1/* 2 * Copyright (c) 2002, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package javax.management.remote; 27 28import java.io.Closeable; 29import java.io.IOException; 30import java.util.Map; 31import javax.management.ListenerNotFoundException; 32import javax.management.MBeanServerConnection; 33import javax.management.NotificationFilter; 34import javax.management.NotificationListener; 35import javax.security.auth.Subject; 36 37/** 38 * <p>The client end of a JMX API connector. An object of this type can 39 * be used to establish a connection to a connector server.</p> 40 * 41 * <p>A newly-created object of this type is unconnected. Its {@link 42 * #connect connect} method must be called before it can be used. 43 * However, objects created by {@link 44 * JMXConnectorFactory#connect(JMXServiceURL, Map) 45 * JMXConnectorFactory.connect} are already connected.</p> 46 * 47 * @since 1.5 48 */ 49public interface JMXConnector extends Closeable { 50 /** 51 * <p>Name of the attribute that specifies the credentials to send 52 * to the connector server during connection. The value 53 * associated with this attribute, if any, is a serializable 54 * object of an appropriate type for the server's {@link 55 * JMXAuthenticator}. 56 */ 57 public static final String CREDENTIALS = 58 "jmx.remote.credentials"; 59 60 /** 61 * <p>Establishes the connection to the connector server. This 62 * method is equivalent to {@link #connect(Map) 63 * connect(null)}.</p> 64 * 65 * @exception IOException if the connection could not be made 66 * because of a communication problem. 67 * 68 * @exception SecurityException if the connection could not be 69 * made for security reasons. 70 */ 71 public void connect() throws IOException; 72 73 /** 74 * <p>Establishes the connection to the connector server.</p> 75 * 76 * <p>If <code>connect</code> has already been called successfully 77 * on this object, calling it again has no effect. If, however, 78 * {@link #close} was called after <code>connect</code>, the new 79 * <code>connect</code> will throw an <code>IOException</code>. 80 * 81 * <p>Otherwise, either <code>connect</code> has never been called 82 * on this object, or it has been called but produced an 83 * exception. Then calling <code>connect</code> will attempt to 84 * establish a connection to the connector server.</p> 85 * 86 * @param env the properties of the connection. Properties in 87 * this map override properties in the map specified when the 88 * <code>JMXConnector</code> was created, if any. This parameter 89 * can be null, which is equivalent to an empty map. 90 * 91 * @exception IOException if the connection could not be made 92 * because of a communication problem. 93 * 94 * @exception SecurityException if the connection could not be 95 * made for security reasons. 96 */ 97 public void connect(Map<String,?> env) throws IOException; 98 99 /** 100 * <p>Returns an <code>MBeanServerConnection</code> object 101 * representing a remote MBean server. For a given 102 * <code>JMXConnector</code>, two successful calls to this method 103 * will usually return the same <code>MBeanServerConnection</code> 104 * object, though this is not required.</p> 105 * 106 * <p>For each method in the returned 107 * <code>MBeanServerConnection</code>, calling the method causes 108 * the corresponding method to be called in the remote MBean 109 * server. The value returned by the MBean server method is the 110 * value returned to the client. If the MBean server method 111 * produces an <code>Exception</code>, the same 112 * <code>Exception</code> is seen by the client. If the MBean 113 * server method, or the attempt to call it, produces an 114 * <code>Error</code>, the <code>Error</code> is wrapped in a 115 * {@link JMXServerErrorException}, which is seen by the 116 * client.</p> 117 * 118 * <p>Calling this method is equivalent to calling 119 * {@link #getMBeanServerConnection(Subject) getMBeanServerConnection(null)} 120 * meaning that no delegation subject is specified and that all the 121 * operations called on the <code>MBeanServerConnection</code> must 122 * use the authenticated subject, if any.</p> 123 * 124 * @return an object that implements the 125 * <code>MBeanServerConnection</code> interface by forwarding its 126 * methods to the remote MBean server. 127 * 128 * @exception IOException if a valid 129 * <code>MBeanServerConnection</code> cannot be created, for 130 * instance because the connection to the remote MBean server has 131 * not yet been established (with the {@link #connect(Map) 132 * connect} method), or it has been closed, or it has broken. 133 */ 134 public MBeanServerConnection getMBeanServerConnection() 135 throws IOException; 136 137 /** 138 * <p>Returns an <code>MBeanServerConnection</code> object representing 139 * a remote MBean server on which operations are performed on behalf of 140 * the supplied delegation subject. For a given <code>JMXConnector</code> 141 * and <code>Subject</code>, two successful calls to this method will 142 * usually return the same <code>MBeanServerConnection</code> object, 143 * though this is not required.</p> 144 * 145 * <p>For each method in the returned 146 * <code>MBeanServerConnection</code>, calling the method causes 147 * the corresponding method to be called in the remote MBean 148 * server on behalf of the given delegation subject instead of the 149 * authenticated subject. The value returned by the MBean server 150 * method is the value returned to the client. If the MBean server 151 * method produces an <code>Exception</code>, the same 152 * <code>Exception</code> is seen by the client. If the MBean 153 * server method, or the attempt to call it, produces an 154 * <code>Error</code>, the <code>Error</code> is wrapped in a 155 * {@link JMXServerErrorException}, which is seen by the 156 * client.</p> 157 * 158 * @param delegationSubject the <code>Subject</code> on behalf of 159 * which requests will be performed. Can be null, in which case 160 * requests will be performed on behalf of the authenticated 161 * Subject, if any. 162 * 163 * @return an object that implements the <code>MBeanServerConnection</code> 164 * interface by forwarding its methods to the remote MBean server on behalf 165 * of a given delegation subject. 166 * 167 * @exception IOException if a valid <code>MBeanServerConnection</code> 168 * cannot be created, for instance because the connection to the remote 169 * MBean server has not yet been established (with the {@link #connect(Map) 170 * connect} method), or it has been closed, or it has broken. 171 */ 172 public MBeanServerConnection getMBeanServerConnection( 173 Subject delegationSubject) 174 throws IOException; 175 176 /** 177 * <p>Closes the client connection to its server. Any ongoing or new 178 * request using the MBeanServerConnection returned by {@link 179 * #getMBeanServerConnection()} will get an 180 * <code>IOException</code>.</p> 181 * 182 * <p>If <code>close</code> has already been called successfully 183 * on this object, calling it again has no effect. If 184 * <code>close</code> has never been called, or if it was called 185 * but produced an exception, an attempt will be made to close the 186 * connection. This attempt can succeed, in which case 187 * <code>close</code> will return normally, or it can generate an 188 * exception.</p> 189 * 190 * <p>Closing a connection is a potentially slow operation. For 191 * example, if the server has crashed, the close operation might 192 * have to wait for a network protocol timeout. Callers that do 193 * not want to block in a close operation should do it in a 194 * separate thread.</p> 195 * 196 * @exception IOException if the connection cannot be closed 197 * cleanly. If this exception is thrown, it is not known whether 198 * the server end of the connection has been cleanly closed. 199 */ 200 public void close() throws IOException; 201 202 /** 203 * <p>Adds a listener to be informed of changes in connection 204 * status. The listener will receive notifications of type {@link 205 * JMXConnectionNotification}. An implementation can send other 206 * types of notifications too.</p> 207 * 208 * <p>Any number of listeners can be added with this method. The 209 * same listener can be added more than once with the same or 210 * different values for the filter and handback. There is no 211 * special treatment of a duplicate entry. For example, if a 212 * listener is registered twice with no filter, then its 213 * <code>handleNotification</code> method will be called twice for 214 * each notification.</p> 215 * 216 * @param listener a listener to receive connection status 217 * notifications. 218 * @param filter a filter to select which notifications are to be 219 * delivered to the listener, or null if all notifications are to 220 * be delivered. 221 * @param handback an object to be given to the listener along 222 * with each notification. Can be null. 223 * 224 * @exception NullPointerException if <code>listener</code> is 225 * null. 226 * 227 * @see #removeConnectionNotificationListener 228 * @see javax.management.NotificationBroadcaster#addNotificationListener 229 */ 230 public void 231 addConnectionNotificationListener(NotificationListener listener, 232 NotificationFilter filter, 233 Object handback); 234 235 /** 236 * <p>Removes a listener from the list to be informed of changes 237 * in status. The listener must previously have been added. If 238 * there is more than one matching listener, all are removed.</p> 239 * 240 * @param listener a listener to receive connection status 241 * notifications. 242 * 243 * @exception NullPointerException if <code>listener</code> is 244 * null. 245 * 246 * @exception ListenerNotFoundException if the listener is not 247 * registered with this <code>JMXConnector</code>. 248 * 249 * @see #removeConnectionNotificationListener(NotificationListener, 250 * NotificationFilter, Object) 251 * @see #addConnectionNotificationListener 252 * @see javax.management.NotificationEmitter#removeNotificationListener 253 */ 254 public void 255 removeConnectionNotificationListener(NotificationListener listener) 256 throws ListenerNotFoundException; 257 258 /** 259 * <p>Removes a listener from the list to be informed of changes 260 * in status. The listener must previously have been added with 261 * the same three parameters. If there is more than one matching 262 * listener, only one is removed.</p> 263 * 264 * @param l a listener to receive connection status notifications. 265 * @param f a filter to select which notifications are to be 266 * delivered to the listener. Can be null. 267 * @param handback an object to be given to the listener along 268 * with each notification. Can be null. 269 * 270 * @exception ListenerNotFoundException if the listener is not 271 * registered with this <code>JMXConnector</code>, or is not 272 * registered with the given filter and handback. 273 * 274 * @see #removeConnectionNotificationListener(NotificationListener) 275 * @see #addConnectionNotificationListener 276 * @see javax.management.NotificationEmitter#removeNotificationListener 277 */ 278 public void removeConnectionNotificationListener(NotificationListener l, 279 NotificationFilter f, 280 Object handback) 281 throws ListenerNotFoundException; 282 283 /** 284 * <p>Gets this connection's ID from the connector server. For a 285 * given connector server, every connection will have a unique id 286 * which does not change during the lifetime of the 287 * connection.</p> 288 * 289 * @return the unique ID of this connection. This is the same as 290 * the ID that the connector server includes in its {@link 291 * JMXConnectionNotification}s. The {@link 292 * javax.management.remote package description} describes the 293 * conventions for connection IDs. 294 * 295 * @exception IOException if the connection ID cannot be obtained, 296 * for instance because the connection is closed or broken. 297 */ 298 public String getConnectionId() throws IOException; 299} 300