javax.management.remote.rmi
class RMIConnectorServer

java.lang.Object javax.management.NotificationBroadcasterSupport javax.management.remote.JMXConnectorServer javax.management.remote.rmi.RMIConnectorServer

All Implemented Interfaces:

MBeanRegistration, NotificationEmitter, JMXAddressable, JMXConnectorServerMBean

public class RMIConnectorServer
extends JMXConnectorServer

A JMX API connector server that creates RMI-based connections from remote clients. Usually, such connector servers are made using {@link javax.management.remote.JMXConnectorServerFactory JMXConnectorServerFactory}. However, specialized applications can use this class directly, for example with an {@link RMIServerImpl} object.

JNDI_REBIND_ATTRIBUTE

public static final String JNDI_REBIND_ATTRIBUTE

Name of the attribute that specifies whether the {@link RMIServer} stub that represents an RMI connector server should override an existing stub at the same address. The value associated with this attribute, if any, should be a string that is equal, ignoring case, to "true" or "false". The default value is false.

RMI_CLIENT_SOCKET_FACTORY_ATTRIBUTE

public static final String RMI_CLIENT_SOCKET_FACTORY_ATTRIBUTE

Name of the attribute that specifies the {@link RMIClientSocketFactory} for the RMI objects created in conjunction with this connector. The value associated with this attribute must be of type RMIClientSocketFactory and can only be specified in the Map argument supplied when creating a connector server.

RMI_SERVER_SOCKET_FACTORY_ATTRIBUTE

public static final String RMI_SERVER_SOCKET_FACTORY_ATTRIBUTE

Name of the attribute that specifies the {@link RMIServerSocketFactory} for the RMI objects created in conjunction with this connector. The value associated with this attribute must be of type RMIServerSocketFactory and can only be specified in the Map argument supplied when creating a connector server.

RMIConnectorServer

public RMIConnectorServer(JMXServiceURL url,
                          Map environment)
                   throws IOException

Makes an RMIConnectorServer. This is equivalent to calling {@link #RMIConnectorServer( JMXServiceURL,Map,RMIServerImpl,MBeanServer) RMIConnectorServer(directoryURL,environment,null,null)}

Parameters:

url - the URL defining how to create the connector server. Cannot be null.

environment - attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.

Throws:

IOException - if the connector server cannot be created for some reason or if it is inevitable that its {@link #start() start} method will fail.

RMIConnectorServer

public RMIConnectorServer(JMXServiceURL url,
                          Map environment,
                          MBeanServer mbeanServer)
                   throws IOException

Makes an RMIConnectorServer for the given MBean server. This is equivalent to calling {@link #RMIConnectorServer( JMXServiceURL,Map,RMIServerImpl,MBeanServer) RMIConnectorServer(directoryURL,environment,null,mbeanServer)}

Parameters:

url - the URL defining how to create the connector server. Cannot be null.

environment - attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.

mbeanServer - the MBean server to which the new connector server is attached, or null if it will be attached by being registered as an MBean in the MBean server.

Throws:

IOException - if the connector server cannot be created for some reason or if it is inevitable that its {@link #start() start} method will fail.

RMIConnectorServer

public RMIConnectorServer(JMXServiceURL url,
                          Map environment,
                          RMIServerImpl rmiServerImpl,
                          MBeanServer mbeanServer)
                   throws IOException

Makes an RMIConnectorServer for the given MBean server.

Parameters:

url - the URL defining how to create the connector server. Cannot be null.

environment - attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.

rmiServerImpl - An implementation of the RMIServer interface, consistent with the protocol type specified in url. If this parameter is non null, the protocol type specified by url is not constrained, and is assumed to be valid. Otherwise, only "rmi" and "iiop" will be recognized.

mbeanServer - the MBean server to which the new connector server is attached, or null if it will be attached by being registered as an MBean in the MBean server.

Throws:

IOException - if the connector server cannot be created for some reason or if it is inevitable that its {@link #start() start} method will fail.

connectionClosed

protected void connectionClosed(String connectionId,
                                String message,
                                Object userData)

Overrides:

connectionClosed in class JMXConnectorServer

Parameters:

connectionId

message

userData

connectionFailed

protected void connectionFailed(String connectionId,
                                String message,
                                Object userData)

Overrides:

connectionFailed in class JMXConnectorServer

Parameters:

connectionId

message

userData

connectionOpened

protected void connectionOpened(String connectionId,
                                String message,
                                Object userData)

Overrides:

connectionOpened in class JMXConnectorServer

Parameters:

connectionId

message

userData

getAddress

public JMXServiceURL getAddress()

getAttributes

public Map getAttributes()

isActive

public synchronized boolean isActive()

setMBeanServerForwarder

public synchronized void setMBeanServerForwarder(MBeanServerForwarder mbsf)

Overrides:

setMBeanServerForwarder in class JMXConnectorServer

Parameters:

mbsf

start

public synchronized void start()
                        throws IOException

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 IOException.

The behavior of this method when called for the first time depends on the parameters that were supplied at construction, as described below.

First, an object of a subclass of {@link RMIServerImpl} is required, to export the connector server through RMI:

• If an RMIServerImpl was supplied to the constructor, it is used.
• Otherwise, if the protocol part of the JMXServiceURL supplied to the constructor was iiop, an object of type {@link RMIIIOPServerImpl} is created.
• Otherwise, if the JMXServiceURL was null, or its protocol part was rmi, an object of type {@link RMIJRMPServerImpl} is created.
• Otherwise, the implementation can create an implementation-specific {@link RMIServerImpl} or it can throw {@link MalformedURLException}.

If the given address includes a JNDI directory URL as specified in the package documentation for {@link javax.management.remote.rmi}, then this RMIConnectorServer will bootstrap by binding the RMIServerImpl to the given address.

If the URL path part of the JMXServiceURL was empty or a single slash (/), then the RMI object will not be bound to a directory. Instead, a reference to it will be encoded in the URL path of the RMIConnectorServer address (returned by {@link #getAddress()}). The encodings for rmi and iiop are described in the package documentation for {@link javax.management.remote.rmi}.

The behavior when the URL path is neither empty nor a JNDI directory URL, or when the protocol is neither rmi nor iiop, is implementation defined, and may include throwing {@link MalformedURLException} when the connector server is created or when it is started.

Throws:

IOException - if the connector server cannot be started.

stop

public void stop()
          throws IOException

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.

Once a connector server has been stopped, it cannot be started again.

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.

If closing a client connection produces an exception, that exception is not thrown from this method. A {@link JMXConnectionNotification} is emitted from this MBean with the connection ID of the connection that could not be closed.

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.

This method calls the method {@link RMIServerImpl#close() close} on the connector server's RMIServerImpl object.

If the RMIServerImpl was bound to a JNDI directory by the {@link #start() start} method, it is unbound from the directory by this method.

Throws:

IOException - if the server cannot be closed cleanly, or if the RMIServerImpl cannot be unbound from the directory. When this exception is thrown, the server has already attempted to close all client connections, if appropriate; to call {@link RMIServerImpl#close()}; and to unbind the RMIServerImpl from its directory, if appropriate. All client connections are closed except possibly those that generated exceptions when the server attempted to close them.

toJMXConnector

public JMXConnector toJMXConnector(Map env)
                            throws IOException

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.

Overrides:

toJMXConnector in class JMXConnectorServer

Parameters:

env - client connection parameters of the same sort that could be provided to {@link JMXConnector#connect(Map) JMXConnector.connect(Map)}. Can be null, which is equivalent to an empty map.

Returns:

a client stub that can be used to make a new connection to this connector server.

Throws:

IOException - if a communications problem means that a stub cannot be created.