Connector States

Like all communicator servers, the RMI connector server has a connection state which is identified by the static variables of the CommunicatorServer class:

• OFFLINE - Stopped and not responding.

• STARTING - In a transitional state and not yet responding.

• ONLINE - Able to respond to management requests.

• STOPPING - In a transitional state and no longer responding.

All connector servers are OFFLINE after their instantiation, so they must be started explicitly. Then, you must wait for a connector server to come ONLINE before it can respond to connections on its designated port.

Example 8-2 Starting the RMI Connector Server

// Explicitly start the RMI connector server
//
rmiConnector.start();

// waiting for it to leave starting state...
while (rmiConnector.getState() == CommunicatorServer.STARTING) {
    try {
        Thread.sleep( 1000 );
    } catch (InterruptedException e) {
        continue;
    }
}

Instead of blocking the application thread, you may register a listener for attribute change notifications concerning the State attribute of the connector server MBean. All connector servers implement this notification which contains both old and new values of the attribute (see "Attribute Change Notifications"). Listeners in the agent can then asynchronously detect when the state changes from STARTING to ONLINE.

During the STARTING state, the RMI connector server registers its RMI service name with the RMI registry on the local host for its designated port. If no registry exists, one is instantiated for the given port. Due to a limitation of the JDK software, creating a second registry in the same Java VM will fail. As a workaround, before starting an RMI connector server on a new, distinct port number in an agent, you must run the rmiregistry command from a terminal on the same host. This limitation is specific to the RMI connector: the HTTP protocols do not require a registry.

The stop method is used to take a connector server offline. The stop method is also called by the preDeregister method that all connector servers inherit. Stopping a connector server will interrupt all requests that are pending and close all connections that are active. When a connection is closed, all of its resources are cleaned up, including all notification listeners, and the connector client may be notified by a heartbeat notification (see "The Heartbeat Mechanism"). A connection that is closed can no longer be reopened, the connector client must establish a new connection when the connector server is restarted.

The setPort method that all connector servers inherit from the CommunicatorServer class allows you to change the port on which management requests will be expected. You can only change the port when the connector server is offline, so it must be explicitly stopped and then restarted. The same rule applies to the setServiceName method which is specific to the RMI connector server. These methods are also exposed in the MBean interface, along with start and stop, allowing a remote management application to configure the connector server through a different connection.