/* |
|
* Copyright (c) 2002, 2008, 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.IOException; |
|
import java.util.Map; |
|
/** |
|
* <p>MBean interface for connector servers. A JMX API connector server |
|
* is attached to an MBean server, and establishes connections to that |
|
* MBean server for remote clients.</p> |
|
* |
|
* <p>A newly-created connector server is <em>inactive</em>, and does |
|
* not yet listen for connections. Only when its {@link #start start} |
|
* method has been called does it start listening for connections.</p> |
|
* |
|
* @since 1.5 |
|
*/ |
|
public interface JMXConnectorServerMBean { |
|
/** |
|
* <p>Activates the connector server, that is, starts listening for |
|
* client connections. Calling this method when the connector |
|
* server is already active has no effect. Calling this method |
|
* when the connector server has been stopped will generate an |
|
* {@link IOException}.</p> |
|
* |
|
* @exception IOException if it is not possible to start listening |
|
* or if the connector server has been stopped. |
|
* |
|
* @exception IllegalStateException if the connector server has |
|
* not been attached to an MBean server. |
|
*/ |
|
public void start() throws IOException; |
|
/** |
|
* <p>Deactivates the connector server, that is, stops listening for |
|
* client connections. Calling this method will also close all |
|
* client connections that were made by this server. After this |
|
* method returns, whether normally or with an exception, the |
|
* connector server will not create any new client |
|
* connections.</p> |
|
* |
|
* <p>Once a connector server has been stopped, it cannot be started |
|
* again.</p> |
|
* |
|
* <p>Calling this method when the connector server has already |
|
* been stopped has no effect. Calling this method when the |
|
* connector server has not yet been started will disable the |
|
* connector server object permanently.</p> |
|
* |
|
* <p>If closing a client connection produces an exception, that |
|
* exception is not thrown from this method. A {@link |
|
* JMXConnectionNotification} with type {@link |
|
* JMXConnectionNotification#FAILED} is emitted from this MBean |
|
* with the connection ID of the connection that could not be |
|
* closed.</p> |
|
* |
|
* <p>Closing a connector server is a potentially slow operation. |
|
* For example, if a client machine with an open connection 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 server cannot be closed cleanly. |
|
* When this exception is thrown, the server has already attempted |
|
* to close all client connections. All client connections are |
|
* closed except possibly those that generated exceptions when the |
|
* server attempted to close them. |
|
*/ |
|
public void stop() throws IOException; |
|
/** |
|
* <p>Determines whether the connector server is active. A connector |
|
* server starts being active when its {@link #start start} method |
|
* returns successfully and remains active until either its |
|
* {@link #stop stop} method is called or the connector server |
|
* fails.</p> |
|
* |
|
* @return true if the connector server is active. |
|
*/ |
|
public boolean isActive(); |
|
/** |
|
* <p>Inserts an object that intercepts requests for the MBean server |
|
* that arrive through this connector server. This object will be |
|
* supplied as the <code>MBeanServer</code> for any new connection |
|
* created by this connector server. Existing connections are |
|
* unaffected.</p> |
|
* |
|
* <p>This method can be called more than once with different |
|
* {@link MBeanServerForwarder} objects. The result is a chain |
|
* of forwarders. The last forwarder added is the first in the chain. |
|
* In more detail:</p> |
|
* |
|
* <ul> |
|
* <li><p>If this connector server is already associated with an |
|
* <code>MBeanServer</code> object, then that object is given to |
|
* {@link MBeanServerForwarder#setMBeanServer |
|
* mbsf.setMBeanServer}. If doing so produces an exception, this |
|
* method throws the same exception without any other effect.</p> |
|
* |
|
* <li><p>If this connector is not already associated with an |
|
* <code>MBeanServer</code> object, or if the |
|
* <code>mbsf.setMBeanServer</code> call just mentioned succeeds, |
|
* then <code>mbsf</code> becomes this connector server's |
|
* <code>MBeanServer</code>.</p> |
|
* </ul> |
|
* |
|
* @param mbsf the new <code>MBeanServerForwarder</code>. |
|
* |
|
* @exception IllegalArgumentException if the call to {@link |
|
* MBeanServerForwarder#setMBeanServer mbsf.setMBeanServer} fails |
|
* with <code>IllegalArgumentException</code>. This includes the |
|
* case where <code>mbsf</code> is null. |
|
*/ |
|
public void setMBeanServerForwarder(MBeanServerForwarder mbsf); |
|
/** |
|
* <p>The list of IDs for currently-open connections to this |
|
* connector server.</p> |
|
* |
|
* @return a new string array containing the list of IDs. If |
|
* there are no currently-open connections, this array will be |
|
* empty. |
|
*/ |
|
public String[] getConnectionIds(); |
|
/** |
|
* <p>The address of this connector server.</p> |
|
* <p> |
|
* The address returned may not be the exact original {@link JMXServiceURL} |
|
* that was supplied when creating the connector server, since the original |
|
* address may not always be complete. For example the port number may be |
|
* dynamically allocated when starting the connector server. Instead the |
|
* address returned is the actual {@link JMXServiceURL} of the |
|
* {@link JMXConnectorServer}. This is the address that clients supply |
|
* to {@link JMXConnectorFactory#connect(JMXServiceURL)}. |
|
* </p> |
|
* <p>Note that the address returned may be {@code null} if |
|
* the {@code JMXConnectorServer} is not yet {@link #isActive active}. |
|
* </p> |
|
* |
|
* @return the address of this connector server, or null if it |
|
* does not have one. |
|
*/ |
|
public JMXServiceURL getAddress(); |
|
/** |
|
* <p>The attributes for this connector server.</p> |
|
* |
|
* @return a read-only map containing the attributes for this |
|
* connector server. Attributes whose values are not serializable |
|
* are omitted from this map. If there are no serializable |
|
* attributes, the returned map is empty. |
|
*/ |
|
public Map<String,?> getAttributes(); |
|
/** |
|
* <p>Returns a client stub for this connector server. A client |
|
* stub is a serializable object whose {@link |
|
* JMXConnector#connect(Map) connect} method can be used to make |
|
* one new connection to this connector server.</p> |
|
* |
|
* <p>A given connector need not support the generation of client |
|
* stubs. However, the connectors specified by the JMX Remote API do |
|
* (JMXMP Connector and RMI Connector).</p> |
|
* |
|
* @param env client connection parameters of the same sort that |
|
* can be provided to {@link JMXConnector#connect(Map) |
|
* JMXConnector.connect(Map)}. Can be null, which is equivalent |
|
* to an empty map. |
|
* |
|
* @return a client stub that can be used to make a new connection |
|
* to this connector server. |
|
* |
|
* @exception UnsupportedOperationException if this connector |
|
* server does not support the generation of client stubs. |
|
* |
|
* @exception IllegalStateException if the JMXConnectorServer is |
|
* not started (see {@link JMXConnectorServerMBean#isActive()}). |
|
* |
|
* @exception IOException if a communications problem means that a |
|
* stub cannot be created. |
|
* |
|
*/ |
|
public JMXConnector toJMXConnector(Map<String,?> env) |
|
throws IOException; |
|
} |