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:
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.
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:
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'.