Jolokia is remote JMX with JSON over HTTP. It is fast, simple, polyglot and has unique features. It's JMX on Capsaicin. Jolokia is a JMX-HTTP bridge giving an alternative to JSR-160 connectors. It is an agent based approach with support for many platforms. In addition to basic JMX operations it enhances JMX remoting with unique features like bulk requests or fine grained security policies.

Although there are non-JVM approaches to JMX web clients such as the experimental JMX Web Services Connector, these are the exception rather than the rule. Perhaps the most significant advantage of Jolokia is that it is based on HTTP (rather than traditional RMI used for JMX remote access) and its format is language-independent JSON (which I recently discussed in Groovy 1.8 Introduces Groovy to JSON). Having HTTP as the transport mechanism and JSON as the data format allows Jolokia-based clients to be written in nearly any conceivable language. At the time of this writing, out-of-the-box Jolkia agents are WAR (Java EE web application) Agent, OSGi Agent, JVM JDK6 Agent, and the Mule Agent. I focus on the JVM JDK6 Agent in this post.

The next code listing contains a simple nonsensical class that is intended solely to provide a long-running Java application whose automatically-provided MXBeans can be accessed via Jolokia.

The above class, once compiled, can be run with the Java launcher. However, to employ Jolokia's JVM JDK6 Agent, the JVM Tool Interface (JVMTI) must be used. The JVMTI documentation warns that "JVM TI may not be available in all implementations of the JavaTM virtual machine." The Jolokia documentation is more specific in saying that Oracle's HotSpot JVM is the one for which their particular Agent is supported (because it leverages the HttpServer embedded in HotSpot).

Assuming that the Main.java class shown above is compiled and then packaged into a JAR file called JolokiaDemo.jar, the Java launcher can be run against this JAR file and associate the Jolokia JVM JDK6 Agent with the following command:

The command just shown specifies the Jolokia agent JAR (jolokia-jvm-jdk6-0.90-agent.jar) and specifies two properties with values (host and port). Note that the specified host and port happen to be the defaults, but I included them here explicitly to indicate how they are supplied to the agent. The portion "-javaagent:C:\jolokia-0.90\jolokia-jvm-jdk6-0.90-agent.jar=port=8778,host=localhost" is the JVMTI portion and everything else is "traditional" Java launcher syntax.

Running the java launcher as indicated above leads to output like that shown in the next screen snapshot.

I like that Jolokia reports the URL by which its HTTP-exposed JMX information is available. This makes it easier to ensure that the client connects properly. In "normal" mode, this is about all that is seen as the client interacts with the application. However, I find it useful to enable Jolokia's debugging when getting the client to connect to this exposed application and this is easily done by adding debug=true onto the end of the JVMTI agent specification. An example of this is shown next.

I haven't shown the client yet, but this debug output gives pretty good hints as to what the client is asking for. I found this invaluable as I experimented with the Jolokia requests. Speaking of the client, the next code listing contains a Groovy script for accessing some built-in MXBeans information about this simple thread sleeping class.

The simple script above uses basic Jolokia classes and exceptions to communicate with the Jolokia instrumented Java application. The output from running the above script is shown in the next screen snapshot.

The output proves that the client was able to talk to the simple Java application and acquire information about its memory usage, its thread count, and its operating system architecture. For this exercise, I threw all the required dependencies on the classpath explicitly provided to the Groovy launcher, but there are other ways to handle classpath dependencies in Groovy.

Accessing JMX information via Groovy clients is pretty straightforward thanks to Groovy being a JVM-based language and thanks to its JMX syntactic goodness. In the case of Groovy clients, I probably would not be likely to employ Jolokia. However, the fact that the remote access is via HTTP and that the data is passed back in JSON format means there are numerous possibilities for non-JVM-based clients to access JVM information. Tomasz Nurkiewicz's post Jolokia + Highcharts = JMX for human beings provides a thorough example of doing just this. Nurkiewicz not only covers using JavaScript on the client side, but also provides examples via curl of the JSON format returned by Jolokia.

Jolokia holds significant promise as a mechanism for exposing valuable information held within Java applications and their hosting JVMs to non-Java/non-JVM clients. In this post, I've looked at one very simple example of accessing a Java application's JVM information from a Groovy client using Jolokia.