Javascript Client Library

Jolokia's Javascript client library allows for easy access to the Jolokia agent from within Javascript scripts. It encapsulates the JSON/HTTP access within a simple object layer.

The Javascript client binding provides the following features:

  • Synchronous and asynchronous operations
  • Support for JSONP for accessing servers other than the one serving the Javscript file
  • Support for all Jolokia features like bulk requests or JMX proxy calls
  • Simple access methods like get_attribute or exec in addition to a generic request method.

Documentation for the Javascript library can be found in the reference manual in the chapter Javascript Client Library.

Installation

The Jolokia Javascript library can be downloaded from the download page. It is divided into two scripts: jolokia.js contains the basic Jolokia object definition which provides the generic request() method. jolokia-simple.js adds to this definition methods for a simplified access, which are easier to use but less powerful. In addition these libs require jQuery and, if the target brosers don't support native JSON serialization, json2.js. A typical setup in an HTML page using the library looks like:

<head>
  <script type="text/javascript" src="jquery-1.7.2.js"></script>
  <script type="text/javascript" src="json2.js"></script>
  <script type="text/javascript" src="jolokia.js"></script>
  <script type="text/javascript" src="jolokia-simple.js"></script>
</head>

For production setup, the minified versions (e.g. jolokia-min.js) are recommended since the original are blown up with inline documentation.

Example

The following simple example shows how to fetch the used Heap Memory from a Jolokia agent:

  // Create a new jolokia client accessing the agent on the same
  // Host which serves this document:
  var j4p = new Jolokia("/jolokia");

  // Request the memory information asynchronously and print it on
  // the console
  j4p.request(
     {
        type: "read",
        mbean: "java.lang:type=Memory",
        attribute: "HeapMemoryUsage"
     },
     {
        success: function(response) {
            console.log(JSON.stringify(response));
            console.log("Heap-Memory used: " + response.value.used);
        }
     });

  // Same as above, but synchronously and with the simple API:
  console.log("Heap-Memory used:" +
              j4p.getAttribute("java.lang.type=Memory","HeapMemoryUsage","used"));

Jolokia as Cubism source

Cubism is a d3.js plugin for plotting time series data. It can be easily be used with Jolokia for periodically reading JMX attributes and plotting them in the browser.

More details on the Jolokia-Cubism integration along with some demo can be found on an extra page.

Testing

This library comes with a test webapplication for integration testing this library from within a browser. The submodule test-app creates a WAR artifact which can be deployed in a servlet container. The Jolokia agent is contained and reachable under the URL /jolokia. The unit tests can be found at

jolokia-test.html QUnit tests for the base library
jolokia-simple-test.html QUnit tests for the simple API
jolokia-all-test.html All the tests above combined

This test-app is also configured for Jetty, so a

mvn jetty:run-exploded

will startup a Jetty and deploy this test application.

In order to simplify development of unit-test a shell script makeLinks.sh is included which can be used in unix like OSs to create symbolic links to the Javascript files in the source directories. A typical workflow looks like:

  • Initialize:
    mvn clean install
    sh makeLinks.sh
    mvn jetty:run-exploded
  • Edit and save the Javascript files (e.g. jolokia.js or jolokia-test.js)
  • Reload the test HTML files in the browser