MX4J's JSR 160 JMXConnectors and JMXConnectorServers

The SOAP JSR 160 connector

Thanks to the fact that JSR 160 allows complete pluggability of the communication protocol between JMXConnector and JMXConnectorServer, it is possible to add easily new protocol providers.
However, since these protocol providers are not defined by the JSR 160 specification, they are likely to be not interoperable between different JSR 160 implementations.
This means that - for example - it is safe to have the JSR 160 Sun Reference Implementation on server side and MX4J on client side, or viceversa, only when the the protocol used is RMI or IIOP.
MX4J implements a JSR 160 JMXConnector and JMXConnectorServer that use SOAP to communicate. The SOAP toolkit used by MX4J is Axis 1.1.
When the SOAP protocol is used, other JSR 160 implementations will fail because they don't implement the SOAP provider, or they don't implement it in a interoperable way with MX4J.
By placing MX4J on both client and server side, you can leverage the functionalities offered by MX4J: in this case you can use SOAP to communicate from client to server and viceversa.

Refer to the examples shipped with the MX4J distribution, mx4j.examples.tools.remote.soap.Server and mx4j.examples.tools.remote.soap.Client to follow the instructions below.

Starting successfully a SOAPConnectorServer requires Axis 1.1 and a servlet 2.3 compliant web container. In this example the web container will be the Jetty web container.
Starting a standalone SOAPConnectorServer will perform several operations:

  • Start a Jetty server on the port specified by the JMXServiceURL
  • Deploy to Jetty the Axis servlet, and mapping it to the path specified by the JMXServiceURL
  • Deploy to Axis the webservice that represent the remote MBeanServer

On server side, the SOAPConnectorServer ignores the host part of the JMXServiceURL, since it starts the web container on the local host.
It is therefore recommended to start the SOAPConnectorServer passing null as host name, to allow the real host name to be retrieved and used (as stated by the JMXServiceURL specification). Also, it is recommended that URL path of the JMXServiceURL not be the empty string.

On client side, differently from the rmi, iiop and local providers, the host part of the JMXServiceURL is not ignored; it is used to connect to the server side.
It is very important that the host name of the JMXServiceURL on the server and the host name of the JMXServiceURL on the client be exactly the same. If they differ (for example one is the IP address and the other is the host name), then a message saying that the SOAPConnectorServer cannot be found will be displayed.

It is possible to start several SOAPConnectorServers in the same JVM, with the constraint that they must all have different URL path in their JMXServiceURLs. In this case only one instance of Jetty will be used (and multiple servlet-mappings mapped to the same Axis servlet).

Example 3.17. Starting the SOAPConnectorServer

               
// Use null as host
JMXServiceURL url = new JMXServiceURL("soap", null, 8080, "/jmxconnector");

MBeanServer server = ...;

JMXConnectorServer cntorServer = JMXConnectorServerFactory.newJMXConnectorServer(url, null, server);

// This method call will:
// 1. Start Jetty on port 8080
// 2. Deploy to Jetty the Axis servlet with servlet-mapping /jmxconnector/*
// 3. Deploy to Axis the web service that represent the remote MBeanServer
cntorServer.start();
               
            

Example 3.18. Connecting to the SOAPConnectorServer

               
// Remember to specify the host name if not in-VM
JMXServiceURL url = new JMXServiceURL("soap", null, 8080, "/jmxconnector");

// Connect !
JMXConnector cntor = JMXConnectorFactory.connect(url);

// Invoke some operation
MBeanServerConnection connection = cntor.getMBeanServerConnection();
Integer count = connection.getMBeanCount();
               
            

When you want to use a SOAPConnectorServer from within a running web application, it is possible to tell to the SOAPConnectorServer not to start another web container, by passing the property SOAPConnectorServer.USE_EXTERNAL_WEB_CONTAINER with the value Boolean.TRUE to the environment map passed to JMXConnectorServerFactory.
In this case, the external web container must already have Axis deployed and mapped to a certain path.
For example, the default installation of Axis maps the Axis servlet to the path /axis/services/*.
The JMXServiceURL to use in this case should be:

service:jmx:soap://host:8080/axis/services

As further example, you can take a look at the index.jsp page inside the mx4j-soap.war bundled with the MX4J distribution to see how a SOAPConnectorServer can be started from within a web application.

The HESSIAN and BURLAP JSR 160 connectors

MX4J implements other two JMXConnectors and JMXConnectorServers that use open source (Apache license) Caucho protocols Hessian and Burlap.
Similarly to the SOAP JMXConnector and JMXConnectorServer, Hessian's and Burlap's JMXConnector and JMXConnectorServer use HTTP as transport protocol.

Starting successfully a [Hessian|Burlap]ConnectorServer requires the hessian/burlap library (hessian-3.0.8.jar) and a servlet 2.3 compliant web container, like for example, the Jetty web container.
Starting a standalone [Hessian|Burlap]ConnectorServer will perform several operations:

  • Start a Jetty server on the port specified by the JMXServiceURL
  • Deploy to Jetty an MX4J's customized [Hessian|Burlap] servlet, and mapping it to the path specified by the JMXServiceURL

Follow the advices given for the SOAPConnectorServer in choosing the JMXServiceURL on server side and on client side.

Example 3.19. Starting the HessianConnectorServer

               
// Use null as host
JMXServiceURL url = new JMXServiceURL("hessian", null, 8080, "/hessian");

MBeanServer server = ...;

JMXConnectorServer cntorServer = JMXConnectorServerFactory.newJMXConnectorServer(url, null, server);

// This method call will:
// 1. Start Jetty on port 8080
// 2. Deploy to Jetty the MX4J's Hessian servlet with servlet-mapping /hessian/*
cntorServer.start();
               
            

Example 3.20. Connecting to the HessianConnectorServer

               
// Remember to specify the host name if not in-VM
JMXServiceURL url = new JMXServiceURL("hessian", null, 8080, "/hessian");

// Connect !
JMXConnector cntor = JMXConnectorFactory.connect(url);

// Invoke some operation
MBeanServerConnection connection = cntor.getMBeanServerConnection();
Integer count = connection.getMBeanCount();
               
            

To use the Burlap protocol instead of the Hessian protocol, just replace the protocol (and optionally the path), from 'hessian' to 'burlap'.