A First Look at JMX Web Services Connector

JSR 262 ("Web Services Connector for Java Management Extensions (JMX) Agents") holds much promise an an alternative to the standard remote JMX connector. While the only remote JMX connector required by the JMX Specification (RMI) has been satisfactory for many needs, it has its limitations. RMI is commonly associated with firewall concerns and necessarily requires the JMX client to be implemented in Java. Also, being based on web services is advantageous because of the standardization of web services.

Although work on JSR-262 is still underway, there is already a reference implementation that can be used to gain a more practical perspective on how the JSR enables JMX clients to communicate with a JMX agent via web services. In future blog entries, I hope to blog about additional details related to JSR-262 and its reference implementation such as the association of WS-Management ("Web Services for Management") and the Java-based WS-Management implementation called Wiseman. For now, though, I'll concentrate on trying out one of the Web Services Connector for Java Management Extensions (JMXTM) Agents Reference Implementation Project samples.

The Early Access 3 version of ws-jmx-connector can be downloaded as jsr262-ri.jar and this JAR includes libraries needed for client and server side as well as Javadoc documentation and samples that can be run to try out the web services connector. Most of the necessary dependencies are included in the download (such as wiseman-core.jar), but one significant set of dependencies that must be downloaded separately is the unbundled JAX-WS libraries. The ws-jmx-connector sample documentation states that JAX-WS 2.1.3 should be downloaded, but I downloaded 2.1.4 and had no problems with that version. Once downloaded, the jaxws-ri libraries (all the JARs in the lib directory of the jaxws-ri expanded directory should be copied into the lib directory of the directory expanded from the jsr262-ri.jar. In other words, all contents of the jaxws-ri.jar-expanded lib directory should be copied in to the same-named lib directory of the jsr262-ri.jar expanded directory. If these JAX-WS libraries are not copied into the sample's lib directory, the following error will be seen when trying to run the sample's server.



Without the unbundled JAX-WS libraries copied into the lib directory of the JMX-WS RI lib directory, the client side of the sample will have trouble similar to the server. This is shown in the next screen snapshot.



In both cases (server and client sample code), the error messages provided for the client and for the server clearly point out that the JAX-WS 2.1 bundled with Java SE 6 is not sufficient and that the unbundled JAX-WS 2.1 is needed instead.

While on the subject of Java SE 6 and JAX-WS, this is probably a good time to point out that things are easiest if you use a version of Java SE 6 Update 4 or later. This is because the JAX-WS 2.1 API was included in the rt.jar in that update.

The version of Java used affects which additional libraries besides the jaxws-ri.jar lib contents are needed. Likewise, the version of Ant used to run the samples is significant (at least Ant 1.6 is required). The following screen snapshot demonstrates that I am using a new enough version of Java SE 6 to not need to worry about extra handling associated with J2SE 5 or versions of Java SE 6 earlier than Update 4. The same screen snapshot shows that my Ant version is sufficient and that I have JAVA_HOME and ANT_HOME set properly.



The ws-jmx-connector project's download includes samples that can be run with only minor changes to see the JMX web service support in action. I found that I did need to make some minor changes to get it to work on my Windows-based machine. Specifically, I needed to change the classpath entry separators in the common.properties file included with the samples from a Unix/Linux-friendly colon to a Windows-friendly semicolon. No matter which platform you use, you must change the jdk-install-path property to be set to your JDK's installation directory. If you're using Windows, remember to separate each directory with two backslashes. For example, instead of assigning jdk-install-path to be C:\Program Files\Java\jdk1.6.0_06, make sure that it is C:\\Program Files\\Java\\jdk1.6.0_06. The next screen snapshot shows the types of errors you might see if you are using Windows and neglect changing colons to semicolons or don't add a separate backslash to separate directories in your JDK installation specification.



The ws-jmx-connector reference implementation not only includes client and server samples, but include an HTML-based page documenting how to run these examples. That page contains some of the same details I have already mentioned (such as the need for the unbundled JAX-WS libraries and the need for certain versions of Ant and Java) as well as some additional details not mentioned in this blog entry. The last of the examples discussed in this document is one in which JConsole is used on the client side to monitor the server-side agent via Wiseman and the JMX WS Connector.

To run the JConsole example, one simply need ensure that the proper prerequisites (many of which have been discussed here) have been met and then use Ant to run both the server side and the client side. The next screen snapshot shows what a successful server-side run looks like from the console.



I really like the fact that the server side example provides the JMXServiceURL for the client side to use as a part of its standard output. This can then be easily pasted into the Remote field of JConsole to make the connection. This JConsole connection behavior is shown in the next two screen snapshots. The first snapshot shows the client side console view into running JConsole successfully and the second screen snapshot shows the JMXServiceURL entered into the remote field.





Once we're connected with JConsole via the JMX Web Services connector, we can go to the MBeans tab in JConsole and look at the JAX-WS version and at the "Hello World(s)!" string returned by the server-side JMX agent (used in all of the samples). The next two screen snapshots show these two views.





The Ant tasks provided with the samples hid many of the complexities of running the client side. One of the disadvantages of the Web Services JMX connector (at least in its current form) is the large number of classes needed on the classpath. Similarly, having to worry about different versions of JAX-WS than that which is provided with Java SE 6 adds a little extra effort that would be nice not to have to expend.

It sounds like Java SE 7 will likely include JSR-262 and I would hope that this would relieve at least some of the extra effort (especially the JAX-WS mismatch) currently required. For developers needing another standardized remote JMX connector mechanism free of firewall issues and/or needing to develop JMX clients in a language other than Java, the JMX Web Services Connector should be just the thing they're looking for.