J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 2002-2007 Sun Microsystems, Inc. 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. Sun designates this |
| 8 | * particular file as subject to the "Classpath" exception as provided |
| 9 | * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 22 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 23 | * have any questions. |
| 24 | */ |
| 25 | |
| 26 | package javax.management.remote; |
| 27 | |
| 28 | import java.io.Closeable; |
| 29 | import java.io.IOException; |
| 30 | import java.util.Map; |
| 31 | import javax.management.ListenerNotFoundException; |
| 32 | import javax.management.MBeanServerConnection; |
| 33 | import javax.management.NotificationFilter; |
| 34 | import javax.management.NotificationListener; |
| 35 | import 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 | */ |
| 49 | public 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>.<p> |
| 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 | } |