9.1 Connector Servers

Connector servers on the agent side listen for management requests issued through a corresponding connector client. The connector server transmits these requests to its MBean server and forwards any response back to the management application. The connector server also forwards notifications, when the management application has registered to receive them through its connector client.

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.

9.1.1 Connector Server Factories

The simplest way to create connector servers is to use the JMXConnectorServerFactory constructor defined by JMX Remote API. No instances of this class are ever created, but its single method, newJMXConnectorServer() is called to create instances of the JMXConnectorServer class. New JMXConnectorServer instances are created when newJMXConnectorServer() is passed the following parameters:

A JMXServiceURL, that serves as the address for the connector server; this URL identifies the connector protocol to be implemented, and the machine name and port number (or path or URL) at which this connector server will be bound.
The environment Map for newJMXConnectorServer(); this can be null.
A reference to the MBean server that will be exposed for remote management through this connector server. If null is given at creation time, the MBean server that will be exposed to remote management will be the MBean server in which the connector server is later registered as an MBean.

Note that if you supply an MBean server at creation time, you can optionally register the connector server as an MBean. In that case, the MBean server in which you choose to register the connector server can optionally be the same MBean server as the one that was supplied at creation time. However, if you supply a null value for this parameter, you will need to register the connector server as an MBean in the MBean server that you wish to expose through that connector server.

In the JMXServiceURL, the connector protocol specified can be either RMI or JMXMP. Depending which protocol is specified, the connector server created will be either an instance of the RMIConnectorServer or JMXMPConnectorServer classes. Both of these classes inherit from the JMXConnectorServer class.

9.1.2 RMI Connector Server

The Java DMK RMI connector server supports the standard RMI transports, Java Remote Method Protocol (JRMP) and the Internet Inter-Object Request Broker (ORB) Protocol (IIOP). An example of an RMI connector is provided in the examplesDir that demonstrates an RMI connection between a server and a remote client.

The Server class from the RMI connector example is is shown in Example 9–1.

Example 9–1 RMI Connector Server

public static void main(String[] args) {  
      try {  
          // Instantiate the MBean server  
          //  
          MBeanServer mbs = MBeanServerFactory.createMBeanServer();  
 
          // Create an RMI connector server  
          //  
          JMXServiceURL url = new JMXServiceURL(  
            "service:jmx:rmi:///jndi/rmi://localhost:9999/server");  
          JMXConnectorServer cs =  
               JMXConnectorServerFactory.newJMXConnectorServer(url,  
               null, mbs);  
          cs.start();  
        } catch (Exception e) {  
          e.printStackTrace();  
        }  
   }  
}

Firstly, the Server class creates a new MBean server called mbs by calling the createMBeanServer() method of the MBeanServerFactory class. A call to JMXServiceURL creates a new service URL called url, which serves as an address for the connector server. This service URL defines the following:

The connector will use the default RMI transport, JRMP, denoted by rmi.
The RMI registry in which the RMI connector stub will be stored will be running on port 9999 on the local host, and the server will be registered under the name server. The port 9999 specified in the example is arbitrary; you can use any available port.

Finally, an RMI connector server named cs is created by calling the JMXConnectorServerFactory constructor, with the service URL url, a null environment map, and the MBean server mbs as parameters. The connector server cs is launched by calling the start() method of JMXConnectorServer, whereupon the instance of RMIConnectorServer that is created exports its underlying RMI server stub server to the RMI registry.

9.1.3 JMXMP Connector Server

The JMXMP connector protocol defined by Java DMK 5.1 is based on Java serialization over transmission control protocol (TCP) sockets. The JMXMP protocol is a custom protocol for JMX Remote API, and offers a more complete security solution than the RMI connector, as it can implement both the secure sockets layer (SSL) and the simple authentication and security layer (SASL) technologies. These optional security features are described in Chapter 11, Connector Security.

In the JMXMP connector, communication between server and client happens over a single TCP connection, and every message is a serialized Java object. Communication between server and client is performed in two separate streams, one for each direction, allowing multiple concurrent requests over the connection at any given time.

The JMXMP connector example is contained in the directory examplesDir/current/Connectors/jmxmp.

The code for a JMXMP connector server is shown in Example 9–2.

Example 9–2 JMXMP Connector Server

public class Server { 
 
   public static void main(String[] args) { 
      try { 
         // Instantiate the MBean server 
         // 
         MBeanServer mbs = MBeanServerFactory.createMBeanServer(); 
 
         // Create a JMXMP connector server 
         // 
         JMXServiceURL url = 
              new JMXServiceURL("jmxmp", null, 5555); 
         JMXConnectorServer cs = 
              JMXConnectorServerFactory.newJMXConnectorServer(url, 
              null, mbs); 
         cs.start(); 
       } catch (Exception e) { 
         e.printStackTrace(); 
       } 
    } 
}

Firstly, the Server class creates a new MBean server named mbs by calling the createMBeanServer() method of the MBeanServerFactory class.

A call to JMXServiceURL creates a new service URL called url, which serves as an address for the connector server. This service URL defines the following:

The connector will use the JMXMP protocol, denoted by jmxmp.
No environment map is specified, as denoted by null.
The connector server will listen for client connections on port 5555 on the local host.

Finally, a JMXMP connector server named cs is created by calling the constructor JMXConnectorServerFactory, with the service URL url, the null environment map, and the MBean server mbs as parameters. The connector server cs is launched by calling the start() method of JMXConnectorServer, whereupon JMXMPConnectorServer, which inherits from JMXConnectorServer, starts listening for client connections.