| /* |
| * Copyright (c) 2002, 2007, 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> |
| * |
| * <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; |
| } |
