Although it is recommended that you use the new RMI and JMXMP connector protocols defined by the JMX Remote API, it is possible for you to continue to use your existing legacy connectors alongside the new ones. This is achieved by wrapping the legacy connector so that it appears in a form that is compatible with the new standard connectors. Wrapping your Java DMK 5.0 RMI and HTTP(S) connectors allows applications created using Java DMK 5.1 to interoperate with existing Java DMK applications. In addition, if you want to use HTTP(S) connectors, you must wrap them.
The JmxConnectorServerFactory and JmxConnectorFactory classes are used to create wrapped legacy Java DMK connector servers and clients. These connector servers and clients expose the same interfaces as standard JMX connectors. For the JmxConnectorServerFactory to create a wrapped connector, you must ensure that the jdmkrt.jar is either in your CLASSPATH environment variable, or in the context of the thread that is used to create the wrapped connector.
Java DMK 5.1 defines a new interface, JdmkLegacyConnector, that is used to obtain the wrapped connectors.
The JdmkLegacyConnector interface specifies a new protocol name for each of the legacy connectors. These protocol names are passed into the JMXServiceURL when it is created, in the same way the RMI connector and JMXMP connectors are identified as rmi and jmxmp respectively in the service URLs. The new protocol names are listed below.
jdmk-http, for the legacy HTTP connector.
jdmk-https, for the legacy HTTPS connector.
jdmk-rmi, for the legacy RMI connector.
The JdmkLegacyConnector also specifies a list of properties to allow the factory to obtain information defined by the user to create the legacy connectors, as follows.
com.sun.jdmk.http.server.authinfo.list, specifying the list of AuthInfo[] for an HTTP or HTTPS server.
com.sun.jdmk.client.localhost, specifying a String object as a local host name for an HTTP, HTTPS or RMI client.
com.sun.jdmk.http.client.authinfo, specifying an AuthInfo[] object for an HTTP or HTTPS client to connect to its server.
com.sun.jdmk.http.server.authinfo.list, a list of AuthInfo for an HTTP or HTTPS connector server.
com.sun.jdmk.http.server.local.address, specifying the local InetAddress the HTTP/HTTPS connector server will bind to.
The creation of wrapped legacy RMI and HTTP connector servers is shown in Example 9–5. The code extracts in this section are taken from the classes in the examplesDir/current/Connectors/wrapping directory.
public class Server { public static void main(String[] args) { try { MBeanServer mbs = MBeanServerFactory.createMBeanServer(); JMXServiceURL httpURL = new JMXServiceURL("jdmk-http", null, 6868); JMXConnectorServer httpCS = JMXConnectorServerFactory.newJMXConnectorServer(httpURL, null, mbs); ObjectName httpON = new ObjectName("legacyWrapper:protocol=jdmk-http,port=6868"); mbs.registerMBean(httpCS, httpON); httpCS.start(); JMXServiceURL rmiURL = new JMXServiceURL("jdmk-rmi", null, 8888, "/myRMI"); JMXConnectorServer rmiCS = JMXConnectorServerFactory.newJMXConnectorServer(rmiURL, null, mbs); ObjectName rmiON = new ObjectName("legacyWrapper:protocol=jdmk-rmi,port=8888"); mbs.registerMBean(rmiCS, rmiON); rmiCS.start(); } catch (Exception e) { e.printStackTrace(); } } }
In Example 9–5, we see that the connector servers are created in a similar way to standard connector servers defined by the JMX Remote API. The only difference is that the connector protocols used to create the JMX service URLs are jdmk-rmi and jmdk-http. For simplicity, this example does not create an HTTPS connector.
As you can see above, the wrapped connector server is registered in the MBean server before it is started. This order of events must always be respected, otherwise the wrapped connector will not work.
public class Client { public static void main(String[] args) { try { JMXServiceURL url = new JMXServiceURL("jdmk-http", null, 6868); connect(url); url = new JMXServiceURL("jdmk-rmi", null, 8888, "/myRMI"); connect(url); } catch (Exception e) { e.printStackTrace(); } System.exit(0); } [...]
As for the creation of the connector servers, in Example 9–6, the legacy connector clients are created by passing the jdmk-http and jdmk-rmi property strings to the JMX service URLs. The rest of the Client example is identical to a standard JMX Remote API connector client.
The following example uses the classes in the examplesDir/current/Connectors/wrapping directory.
Compile the Java classes
$ javac -classpath classpath *.java |
Start the Server
$ java -classpath .:classpath Server & |
You will see confirmation of the creation of the wrapped connector servers, and will be prompted to start the Client.
When prompted, start the Client
$ java -classpath .:classpath Client |
You will see the wrapped HTTP connector client connect to the HTTP server, and perform various MBean operations via the connection. Once the MBean operations have completed, the Client closes the HTTP connection, before opening a connection to the legacy RMI connector server, and performing further MBean operations.
The wrapped legacy connectors do not provide the full functionality of either their JMX Remote API or their Java DMK 5.0 counterparts. The limitations of the wrapped legacy connectors are listed below.
Not all of the methods supported by standard JMXConnector and JMXConnectorServer are supported by the wrapped legacy connectors.
The following are the only methods supported by the wrapped legacy connector clients.
addNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object handback)
removeNotificationListener(ObjectName name, ObjectName listener)
removeNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object handback)
removeNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback)
The wrapped legacy connector servers only support the getConnectionIds() method.
A legacy connector can only use the class loader that was used to created that connector.
Legacy servers do not send out events relating to client connections or failures, but only about state changes: offline, starting, online.
A client can connect to a legacy connector server created by the JMX Remote API factory only after the server has been registered in an MBean server.
A legacy connector client has no way of showing its local port number. Calling Client.getConnectionId() will return:
protocol://host:server_port count |
Where the count is an integer ID that is unique within a Java virtual machine on the client side. For example:
jdmk-http://host_name:6666 1 |
A legacy connector server must be registered as an MBean in the MBean server which is exposed through that connector server, before the server can be started.