Java tutorial
/* * Copyright (c) 2002, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.management.remote; import java.io.Closeable; import java.io.IOException; import java.util.Map; import javax.management.ListenerNotFoundException; import javax.management.MBeanServerConnection; import javax.management.NotificationFilter; import javax.management.NotificationListener; import javax.security.auth.Subject; /** * <p>The client end of a JMX API connector. An object of this type can * be used to establish a connection to a connector server.</p> * * <p>A newly-created object of this type is unconnected. Its {@link * #connect connect} method must be called before it can be used. * However, objects created by {@link * JMXConnectorFactory#connect(JMXServiceURL, Map) * JMXConnectorFactory.connect} are already connected.</p> * * @since 1.5 */ public interface JMXConnector extends Closeable { /** * <p>Name of the attribute that specifies the credentials to send * to the connector server during connection. The value * associated with this attribute, if any, is a serializable * object of an appropriate type for the server's {@link * JMXAuthenticator}. */ public static final String CREDENTIALS = "jmx.remote.credentials"; /** * <p>Establishes the connection to the connector server. This * method is equivalent to {@link #connect(Map) * connect(null)}.</p> * * @exception IOException if the connection could not be made * because of a communication problem. * * @exception SecurityException if the connection could not be * made for security reasons. */ public void connect() throws IOException; /** * <p>Establishes the connection to the connector server.</p> * * <p>If <code>connect</code> has already been called successfully * on this object, calling it again has no effect. If, however, * {@link #close} was called after <code>connect</code>, the new * <code>connect</code> will throw an <code>IOException</code>. * * <p>Otherwise, either <code>connect</code> has never been called * on this object, or it has been called but produced an * exception. Then calling <code>connect</code> will attempt to * establish a connection to the connector server.</p> * * @param env the properties of the connection. Properties in * this map override properties in the map specified when the * <code>JMXConnector</code> was created, if any. This parameter * can be null, which is equivalent to an empty map. * * @exception IOException if the connection could not be made * because of a communication problem. * * @exception SecurityException if the connection could not be * made for security reasons. */ public void connect(Map<String, ?> env) throws IOException; /** * <p>Returns an <code>MBeanServerConnection</code> object * representing a remote MBean server. For a given * <code>JMXConnector</code>, two successful calls to this method * will usually return the same <code>MBeanServerConnection</code> * object, though this is not required.</p> * * <p>For each method in the returned * <code>MBeanServerConnection</code>, calling the method causes * the corresponding method to be called in the remote MBean * server. The value returned by the MBean server method is the * value returned to the client. If the MBean server method * produces an <code>Exception</code>, the same * <code>Exception</code> is seen by the client. If the MBean * server method, or the attempt to call it, produces an * <code>Error</code>, the <code>Error</code> is wrapped in a * {@link JMXServerErrorException}, which is seen by the * client.</p> * * <p>Calling this method is equivalent to calling * {@link #getMBeanServerConnection(Subject) getMBeanServerConnection(null)} * meaning that no delegation subject is specified and that all the * operations called on the <code>MBeanServerConnection</code> must * use the authenticated subject, if any.</p> * * @return an object that implements the * <code>MBeanServerConnection</code> interface by forwarding its * methods to the remote MBean server. * * @exception IOException if a valid * <code>MBeanServerConnection</code> cannot be created, for * instance because the connection to the remote MBean server has * not yet been established (with the {@link #connect(Map) * connect} method), or it has been closed, or it has broken. */ public MBeanServerConnection getMBeanServerConnection() throws IOException; /** * <p>Returns an <code>MBeanServerConnection</code> object representing * a remote MBean server on which operations are performed on behalf of * the supplied delegation subject. For a given <code>JMXConnector</code> * and <code>Subject</code>, two successful calls to this method will * usually return the same <code>MBeanServerConnection</code> object, * though this is not required.</p> * * <p>For each method in the returned * <code>MBeanServerConnection</code>, calling the method causes * the corresponding method to be called in the remote MBean * server on behalf of the given delegation subject instead of the * authenticated subject. The value returned by the MBean server * method is the value returned to the client. If the MBean server * method produces an <code>Exception</code>, the same * <code>Exception</code> is seen by the client. If the MBean * server method, or the attempt to call it, produces an * <code>Error</code>, the <code>Error</code> is wrapped in a * {@link JMXServerErrorException}, which is seen by the * client.</p> * * @param delegationSubject the <code>Subject</code> on behalf of * which requests will be performed. Can be null, in which case * requests will be performed on behalf of the authenticated * Subject, if any. * * @return an object that implements the <code>MBeanServerConnection</code> * interface by forwarding its methods to the remote MBean server on behalf * of a given delegation subject. * * @exception IOException if a valid <code>MBeanServerConnection</code> * cannot be created, for instance because the connection to the remote * MBean server has not yet been established (with the {@link #connect(Map) * connect} method), or it has been closed, or it has broken. */ public MBeanServerConnection getMBeanServerConnection(Subject delegationSubject) throws IOException; /** * <p>Closes the client connection to its server. Any ongoing or new * request using the MBeanServerConnection returned by {@link * #getMBeanServerConnection()} will get an * <code>IOException</code>.</p> * * <p>If <code>close</code> has already been called successfully * on this object, calling it again has no effect. If * <code>close</code> has never been called, or if it was called * but produced an exception, an attempt will be made to close the * connection. This attempt can succeed, in which case * <code>close</code> will return normally, or it can generate an * exception.</p> * * <p>Closing a connection is a potentially slow operation. For * example, if the server has crashed, the close operation might * have to wait for a network protocol timeout. Callers that do * not want to block in a close operation should do it in a * separate thread.</p> * * @exception IOException if the connection cannot be closed * cleanly. If this exception is thrown, it is not known whether * the server end of the connection has been cleanly closed. */ public void close() throws IOException; /** * <p>Adds a listener to be informed of changes in connection * status. The listener will receive notifications of type {@link * JMXConnectionNotification}. An implementation can send other * types of notifications too.</p> * * <p>Any number of listeners can be added with this method. The * same listener can be added more than once with the same or * different values for the filter and handback. There is no * special treatment of a duplicate entry. For example, if a * listener is registered twice with no filter, then its * <code>handleNotification</code> method will be called twice for * each notification.</p> * * @param listener a listener to receive connection status * notifications. * @param filter a filter to select which notifications are to be * delivered to the listener, or null if all notifications are to * be delivered. * @param handback an object to be given to the listener along * with each notification. Can be null. * * @exception NullPointerException if <code>listener</code> is * null. * * @see #removeConnectionNotificationListener * @see javax.management.NotificationBroadcaster#addNotificationListener */ public void addConnectionNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback); /** * <p>Removes a listener from the list to be informed of changes * in status. The listener must previously have been added. If * there is more than one matching listener, all are removed.</p> * * @param listener a listener to receive connection status * notifications. * * @exception NullPointerException if <code>listener</code> is * null. * * @exception ListenerNotFoundException if the listener is not * registered with this <code>JMXConnector</code>. * * @see #removeConnectionNotificationListener(NotificationListener, * NotificationFilter, Object) * @see #addConnectionNotificationListener * @see javax.management.NotificationEmitter#removeNotificationListener */ public void removeConnectionNotificationListener(NotificationListener listener) throws ListenerNotFoundException; /** * <p>Removes a listener from the list to be informed of changes * in status. The listener must previously have been added with * the same three parameters. If there is more than one matching * listener, only one is removed.</p> * * @param l a listener to receive connection status notifications. * @param f a filter to select which notifications are to be * delivered to the listener. Can be null. * @param handback an object to be given to the listener along * with each notification. Can be null. * * @exception ListenerNotFoundException if the listener is not * registered with this <code>JMXConnector</code>, or is not * registered with the given filter and handback. * * @see #removeConnectionNotificationListener(NotificationListener) * @see #addConnectionNotificationListener * @see javax.management.NotificationEmitter#removeNotificationListener */ public void removeConnectionNotificationListener(NotificationListener l, NotificationFilter f, Object handback) throws ListenerNotFoundException; /** * <p>Gets this connection's ID from the connector server. For a * given connector server, every connection will have a unique id * which does not change during the lifetime of the * connection.</p> * * @return the unique ID of this connection. This is the same as * the ID that the connector server includes in its {@link * JMXConnectionNotification}s. The {@link * javax.management.remote package description} describes the * conventions for connection IDs. * * @exception IOException if the connection ID cannot be obtained, * for instance because the connection is closed or broken. */ public String getConnectionId() throws IOException; }