![]() |
|||
![]() |
![]() ![]() |
![]() |
![]() ![]() |
![]() |
![]() ![]() |
![]() |
| ||
Chapter 21Legacy Protocol ConnectorsProtocol connectors provide a point-to-point connection between a Java dynamic management agent and a management application. Each of the connectors relies on a specific communication protocol, but the API that is available to the management application is identical for all connectors and is entirely protocol-independent. A connector consists of a connector server component registered in the agent and a connector client object instance in the management application. The connector client exposes a remote version of the MBean server interface. Each connector client represents one agent to which the manager wants to connect. The connector server replies to requests from any number of connections and fulfills them through its MBean server. Once the connection is established, the remoteness of the agent is transparent to the management application, except for any communication delays. From Java Dynamic Management Kit (Java DMK) 5.1 onwards, remote connections are established via the remote method invocation (RMI) and JMX messaging protocol (JMXMP) connectors defined by Java Management Extensions (JMX) Remote API. However, for reasons of backwards compatibility, the connectors used in previous versions of Java DMK are retained as legacy features of the product. All the connectors rely on the Java serialization package to transmit data as Java objects between client and server components. Therefore, all objects needed in the exchange of management requests and responses must be instances of a serializable class. However, the data encoding and sequencing are proprietary, and the raw data of the message contents in the underlying protocol are not exposed by the connectors. All the legacy connectors provided with Java DMK implement a heartbeat mechanism to detect automatically when a connection is lost. This enables the manager to be notified when the communication is interrupted and when it is restored. If the connection is not reestablished, the connector automatically frees the resources that were associated with the lost connection. The code samples in this chapter are taken from the files in the legacy/SimpleClients and legacy/HeartBeat directories located in the main examplesDir (see Directories and Classpath in the Preface). This chapter covers the following topics:
21.1 Legacy Connector ServersJava DMK 5.0 introduced the concept of multihome interfaces. This enables you to work in an environment in which multiple network protocols can be used at different times by the legacy connector servers. The Java DMK legacy connector servers on the server side do not need to have specified local interfaces. By default, the connector server listens on all local interfaces. There is a legacy connector server for each of the protocols supported in the previous versions of Java DMK: RMI, hypertext transfer protocol (HTTP) and secure HTTP (HTTPS). Support for these protocols is retained in Java DMK 5.1 for reasons of backwards compatibility. All the legacy connectors inherit from the CommunicatorServer class that is the superclass for all the legacy protocol adaptors and connector servers. This class defines the methods needed to control the port and communication settings that are common to all. Each connector server class then provides specific controls, such as the service name for RMI and authentication information for HTTP. This example covers the legacy RMI connector server, and the HTTP authentication mechanism is described in Chapter 23, Legacy Connector Security. A connector server listens for incoming requests from its corresponding connector client, decodes that request and encodes the reply. Several connector clients can establish connections with the same connector server, and the connector server can handle multiple requests simultaneously. There only needs to be one connector server MBean per protocol to which the agent needs to respond. However, several connector servers for the same protocol can coexist in an agent for processing requests on different ports. 21.1.1 Instantiating a Legacy RMI Connector ServerThe legacy RMI connector server is an MBean, so we instantiate its class and register it in the MBean server. This operation could also be performed remotely, for example if a management application wants to access an agent through an alternative protocol. The code extract shown in Example 21-1 is taken from the BaseAgent class in the examplesDir/current/BaseAgent directory. Example 21-1 Instantiating the Legacy RMI Connector Server
Other constructors for the legacy RmiConnectorServer class have parameters for specifying the port and the RMI service name that the connector server will use. The default constructor assigns port 1099 and name=RmiConnectorServer, as given by the static variables RMI_CONNECTOR_PORT and RMI_CONNECTOR_SERVER, respectively, of the ServiceName class. Both attributes can also be accessed through the getter and setter methods of the legacy RmiConnectorServer class. Each legacy connector uses different parameters that are specific to its protocol. For example, the HTTP connector does not need a service name. The default values for all parameters are given by the static variables of the ServiceName class. Registering a connector server as an MBean implies that its MBean server will handle the remote requests that it receives. However, you can specify a different object for fulfilling management requests through the setMBeanServer method that the RmiConnectorServer class inherits from the CommunicatorServer class. For security reasons, this method is not exposed in the legacy RMI connector server MBean, so it must be called from the agent application. Registering the connector server as an MBean is optional. For example, you might not want it exposed for management. In this case, you must use the setMBeanServer method to specify an object that implements the MBeanServer interface so that it can fulfill management requests. A user can select a local server interface for a legacy RMI connector server using the RMI property java.rmi.server.hostname. 21.1.2 Connector StatesLike all communicator servers, the legacy RMI connector server has a connection state that is identified by the static variables of the CommunicatorServer class:
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 21-2 Starting the RMI Connector Server
Instead of blocking the application thread, you can 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 8.3 Attribute Change Notifications). Listeners in the agent can then asynchronously detect when the state changes from STARTING to ONLINE. Note - During the STARTING state, the legacy 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 version 1.4 of the Java platform, creating a second registry in the same Java virtual machine (JVM) 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 legacy 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 interrupts all requests that are pending and closes 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 can be notified by a heartbeat notification (see 21.3 Legacy 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 enables you to change the port on which management requests are 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 that is specific to the RMI connector server. These methods are also exposed in the MBean interface, along with start and stop, enabling a remote management application to configure the connector server through a different connection. 21.2 Legacy Connector ClientsThe manager application interacts with a connector client to access an agent through an established connection. Through its implementation of the RemoteMBeanServer interface, a legacy connector client provides methods to handle the connection and access the agent. This interface specifies nearly all of the same methods as the MBeanServer interface, meaning that an agent is fully manageable from a remote application. Through the connector, the management application sends management requests to the MBeans located in a remote agent. Components of the management application access remote MBeans by calling the methods of the connector client for getting and setting attributes and calling operations on the MBeans. The connector client then returns the result, providing a complete abstraction of the communication layer. By default, a legacy connector client uses the default host name, InetAddress.getLocalHost().getHostName() | ||
| ||
![]() |