1. /*

  2.  * @(#)JMXConnectorServerMBean.java	1.25 04/05/05

  3.  * 

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. 

  9. package javax.management.remote;

  10. 

  11. import java.io.IOException;

  12. import java.util.Map;

  13. 

  14. import javax.management.MBeanServer;

  15. 

  16. /**

  17.  * <p>MBean interface for connector servers.  A JMX API connector server

  18.  * is attached to an MBean server, and establishes connections to that

  19.  * MBean server for remote clients.</p>

  20.  *

  21.  * <p>A newly-created connector server is <em>inactive</em>, and does

  22.  * not yet listen for connections.  Only when its {@link #start start}

  23.  * method has been called does it start listening for connections.</p>

  24.  *

  25.  * @since 1.5

  26.  * @since.unbundled 1.0

  27.  */

  28. public interface JMXConnectorServerMBean {

  29.     /**

  30.      * <p>Activates the connector server, that is, starts listening for

  31.      * client connections.  Calling this method when the connector

  32.      * server is already active has no effect.  Calling this method

  33.      * when the connector server has been stopped will generate an

  34.      * {@link IOException}.</p>

  35.      *

  36.      * @exception IOException if it is not possible to start listening

  37.      * or if the connector server has been stopped.

  38.      *

  39.      * @exception IllegalStateException if the connector server has

  40.      * not been attached to an MBean server.

  41.      */

  42.     public void start() throws IOException;

  43. 

  44.     /**

  45.      * <p>Deactivates the connector server, that is, stops listening for

  46.      * client connections.  Calling this method will also close all

  47.      * client connections that were made by this server.  After this

  48.      * method returns, whether normally or with an exception, the

  49.      * connector server will not create any new client

  50.      * connections.</p>

  51.      *

  52.      * <p>Once a connector server has been stopped, it cannot be started

  53.      * again.</p>

  54.      *

  55.      * <p>Calling this method when the connector server has already

  56.      * been stopped has no effect.  Calling this method when the

  57.      * connector server has not yet been started will disable the

  58.      * connector server object permanently.</p>

  59.      *

  60.      * <p>If closing a client connection produces an exception, that

  61.      * exception is not thrown from this method.  A {@link

  62.      * JMXConnectionNotification} with type {@link

  63.      * JMXConnectionNotification#FAILED} is emitted from this MBean

  64.      * with the connection ID of the connection that could not be

  65.      * closed.</p>

  66.      *

  67.      * <p>Closing a connector server is a potentially slow operation.

  68.      * For example, if a client machine with an open connection has

  69.      * crashed, the close operation might have to wait for a network

  70.      * protocol timeout.  Callers that do not want to block in a close

  71.      * operation should do it in a separate thread.</p>

  72.      *

  73.      * @exception IOException if the server cannot be closed cleanly.

  74.      * When this exception is thrown, the server has already attempted

  75.      * to close all client connections.  All client connections are

  76.      * closed except possibly those that generated exceptions when the

  77.      * server attempted to close them.

  78.      */

  79.     public void stop() throws IOException;

  80. 

  81.     /**

  82.      * <p>Determines whether the connector server is active.  A connector

  83.      * server starts being active when its {@link #start start} method

  84.      * returns successfully and remains active until either its

  85.      * {@link #stop stop} method is called or the connector server

  86.      * fails.</p>

  87.      *

  88.      * @return true if the connector server is active.

  89.      */

  90.     public boolean isActive();

  91. 

  92.     /**

  93.      * <p>Adds an object that intercepts requests for the MBean server

  94.      * that arrive through this connector server.  This object will be

  95.      * supplied as the <code>MBeanServer</code> for any new connection

  96.      * created by this connector server.  Existing connections are

  97.      * unaffected.</p>

  98.      *

  99.      * <p>If this connector server is already associated with an

  100.      * <code>MBeanServer</code> object, then that object is given to

  101.      * {@link MBeanServerForwarder#setMBeanServer

  102.      * mbsf.setMBeanServer}.  If doing so produces an exception, this

  103.      * method throws the same exception without any other effect.</p>

  104.      *

  105.      * <p>If this connector is not already associated with an

  106.      * <code>MBeanServer</code> object, or if the

  107.      * <code>mbsf.setMBeanServer</code> call just mentioned succeeds,

  108.      * then <code>mbsf</code> becomes this connector server's

  109.      * <code>MBeanServer</code>.</p>

  110.      *

  111.      * @param mbsf the new <code>MBeanServerForwarder</code>.

  112.      *

  113.      * @exception IllegalArgumentException if the call to {@link

  114.      * MBeanServerForwarder#setMBeanServer mbsf.setMBeanServer} fails

  115.      * with <code>IllegalArgumentException</code>.  This includes the

  116.      * case where <code>mbsf</code> is null.

  117.      */

  118.     public void setMBeanServerForwarder(MBeanServerForwarder mbsf);

  119. 

  120.     /**

  121.      * <p>The list of IDs for currently-open connections to this

  122.      * connector server.</p>

  123.      *

  124.      * @return a new string array containing the list of IDs.  If

  125.      * there are no currently-open connections, this array will be

  126.      * empty.

  127.      */

  128.     public String[] getConnectionIds();

  129. 

  130.     /**

  131.      * <p>The address of this connector server.</p>

  132.      *

  133.      * @return the address of this connector server, or null if it

  134.      * does not have one.

  135.      */

  136.     public JMXServiceURL getAddress();

  137. 

  138.     /**

  139.      * <p>The attributes for this connector server.</p>

  140.      *

  141.      * @return a read-only map containing the attributes for this

  142.      * connector server.  Attributes whose values are not serializable

  143.      * are omitted from this map.  If there are no serializable

  144.      * attributes, the returned map is empty.

  145.      */

  146.     public Map<String,?> getAttributes();

  147. 

  148.     /**

  149.      * <p>Returns a client stub for this connector server.  A client

  150.      * stub is a serializable object whose {@link

  151.      * JMXConnector#connect(Map) connect} method can be used to make

  152.      * one new connection to this connector server.</p>

  153.      *

  154.      * <p>A given connector need not support the generation of client

  155.      * stubs.  However, the connectors specified by the JMX Remote API do 

  156.      * (JMXMP Connector and RMI Connector).</p>

  157.      *

  158.      * @param env client connection parameters of the same sort that

  159.      * can be provided to {@link JMXConnector#connect(Map)

  160.      * JMXConnector.connect(Map)}.  Can be null, which is equivalent

  161.      * to an empty map.

  162.      *

  163.      * @return a client stub that can be used to make a new connection

  164.      * to this connector server.

  165.      *

  166.      * @exception UnsupportedOperationException if this connector

  167.      * server does not support the generation of client stubs.

  168.      *

  169.      * @exception IllegalStateException if the JMXConnectorServer is

  170.      * not started (see {@link JMXConnectorServerMBean#isActive()}).

  171.      *

  172.      * @exception IOException if a communications problem means that a

  173.      * stub cannot be created.

  174.      *

  175.      */

  176.     public JMXConnector toJMXConnector(Map<String,?> env)

  177. 	throws IOException;

  178. }