JMX Support

The main focus of Jolokia is to allow easy access to JMX MBeans from everywhere. MBeans can be provided by the JVM itself, by an application server or an application. See MBeans and metadata for more details.

Each MBean is registered at a specific MBeanServer. Multiple MBeanServers can co-exist in a single JVM. The so called PlatformMBeanServer is always present and is created by the JVM during startup. Especially application servers often create additional MBeanServers for various purposes. The details are presented in How to create more MBeanServers?

When accessing an MBean remotely via JSR-160 Connector Server, the MBeanServer holding the requested MBean is the one attached to the connector. Jolokia being a JMX protocol adaptor (see Architecture) merges all MBeanServers it can find in the JVM to give a single view on all MBeans. The merging algorithm is described in MBeanServer merging.

For application specific MBeans, Jolokia provides an own, so called Jolokia MBeanServer which is treated specially by the Jolokia agent. The Jolokia MBeanServer and its features are explained in Jolokia MBeanServer.

Developing application specific MBeans is easy, especially if Standard MBeans are used. However, for Spring users there is even a easier, more declarative way for turning POJOs into MBeans. On top of this Jolokia provides an easy, declarative way for firing up a Jolokia JVM agent merely by including some Jolokia specific Spring configuration. This is described in Spring Support.

Here’s the overview of how Jolokia fits into the picture of JMX architecture in a single JVM and what is the place for the Jolokia MBeanServer and @JsonMBean:

jolokia mbeanserver

Platform MBeanServer: This is the main MBeanServer where MBeans like java.lang:type=Runtime are registered.
MBeanServer: We can have more MBeanServers created using javax.management.MBeanServerFactory.newMBeanServer()
Connector Server: JSR-160 connector attached to an MBeanServer to allow remote access to the MBeans registered there. Each Connector Server is attached to exactly one MBeanServers and more connectors can be attached to a single MBeanServer (including Platform MBeanServer).
Jolokia MBeanServer: Also created using MBeanServerFactory.newMBeanServer() but never attached to a JSR-160 Connector. This means that MBeans registered in this MBeanServer will never be accessible remotely using JSR-160 Connector.
Jolokia JMX Protocol Adaptor: An agent component that allows remote access, but operates on a unified view of all discovered MBeanServers. So it’s not a JMX Connector Server. See Architecture.
Unified View: When accessing MBeans using Jolokia Protocol Adapter (the Agent), we can access all MBeans registered in all discovered MBeanServers. There’s an order defined in which the MBeanServers are checked.
@JsonMBean: Special kind of MBean - when an MBean (standard, dynamic, open, model) is registered in the Jolokia MBeanServer (and not elsewhere), Jolokia registers additional Dynamic MBean in the Platform MBeanServer. THe original and the dynamic one are related. See below for more details.

Jolokia MBeanServer

The Jolokia MBeanServer can be easily created and used with a locator:

MBeanServer jolokiaServer = JolokiaMBeanServerUtil.getJolokiaMBeanServer();

Internally, javax.management.MBeanServerFactory.newMBeanServer() is called, so it’s not returned when calling javax.management.MBeanServerFactory.findMBeanServer().

This MBeanServer is treated specially by a Jolokia Agent:

Every MBean registered at the Jolokia MBeanServer will never show up remotely via JSR-160. The Jolokia MBeanServer is never exposed over JSR-160.
Each Jolokia MBeanServer registered MBean will shadow any MBean with the same ObjectName in any other MBeanServer present. See below for more details.
The Jolokia MBeanServer is also responsible for managing so called JSON MBeans. These are MBeans annotated with @JsonMBean on the class level. JSON MBean are explained in @JsonMBean.

MBeanServer merging

Jolokia tries hard to detect as many MBeanServers as available in a JVM. Beside the always present Platform MBeanServer, many application servers create own MBeanServer(s) which not always can be found using standard mechanisms. Therefore Jolokia comes with so called ServerDetectors for many known brands of applications server. These server detectors know how to find MBeanServer by application server specific means.

The set of available of MBeanServers is detected during startup and kept, except for the Jolokia MBeanServer which can kick in and out at any time. For Jolokia operations, all these MBeanServers are tried according the order given below. Jolokia provides a unified view of all MBeanServers.

Jolokia MBeanServer is queried first, if available.
Next every MBeanServer as detected by the server detectors a queried in turn.
All MBeanServers returned by MBeanServerFactory.findMBeanServer(null) (which should return all the MBeanServers created with MBeanServerFactory.createMBeanServer(), but not the ones created by javax.management.MBeanServerFactory.newMBeanServer()) are called if not already tried previously.
Finally, the ManagementFactory.getPlatformMBeanServer() is used (also, if not found in a former step).

All MBeans contained in all detected MBeanServers are merged to give a single view on the set of available MBeans. For MBeans registered with the same name at different MBeanServers, MBeans registered in later MBeanServers are not visible. These hidden MBeans will never be called on read, write or exec operations. Also, for list operations only the meta data of the visible MBeans is returned.

This hiding mechanism is used by @JsonMBean to provide a different view of an MBean for JSR-160 connectors (see below).

@JsonMBean

JMX 1.4 introduced MXBeans which allow for nearly arbitrary data to be translated into so called OpenData which are accessible via JMX. For example, arbitrary Java Beans are translated into a CompositeData structure with property names as keys and their values in OpenData values.

Jolokia provides an annotation @JsonMBean for marking an MBean as a JSON MBean. Such an MBean, if registered at the Jolokia MBeanServer creates a proxy on the PlatformMBeanServer where every complex value gets translated into plain strings in JSON format. This is true for attributes, operation return values and arguments. That way, a JSR-160 based console (like jconsole) can easily access complex data type exposed by custom MBeans. Json MBeans work for Java 6 and newer.

Figure 1. A @JsonMBean in jconsole

As presented in the jconsole attribute view, the type of the attribute is simply java.lang.String even if the original attribute is ComplexTestData bean defined as:

@JsonMBean
public class JsonChecking implements JsonCheckingMBean {

    ComplexTestData data;

    public JsonChecking() {
        data = new ComplexTestData();
    }

    public ComplexTestData getData() {
        return data;
    }
}

public class ComplexTestData {
    private int number;
    private String string;
    private Map<String,Boolean> map;
    private Set<Integer> set;
    private String[] stringArray;
    private List<Boolean> list;
    private Map<String,List<Map<String,String>>> complex;

    ...
}

The actual instance of JsonChecking is registered in the Jolokia MBeanServer and what is registered in the Platform MBeanServer (accessible to jconsole using JSR-160 RMI Connector) is a Dynamic MBean (implementing javax.management.DynamicMBean interface). This dynamic MBean translates the string input (for writing attributes and passing operation arguments) and output (for reading attributes and operation return values) into actual data types required by the original MBean annotated with @JsonMBean.

JsonMBean and MXBean are quite similar as both do a translation from complex data types to a standard format (OpenType for MXBeans, JSON strings for JsonMBean). However, there are also differences:

MXBeans are a standard mechanism which are available on every JVM since 1.5^[1].
Serialization of complex Java Beans is more powerful with JsonMBeans, e.g. Jolokia can detect self (or cyclic) object references. MXBeans will cause an error in this case.
JsonMBeans must be added to the Jolokia MBeanServer to work. MXBeans work with the PlatformMBeanServer, too.
JsonMBean work also with JMX support libraries which use ModelMBean's under the hood. E.g. Spring JMX uses a ModelMBean for @ManagedResource annotated MBeans. @JsonMBean can be easily added, whereas @MXBean wouldn’t work here.

The Jolokia MBeanServer and the @JsonMBean annotation are contained in the Maven module jolokia-support-jmx.

1. For JBoss prior to version 7 there are some slight issues since JBoss used to replace the standard MBeanServer with an own variant. See this discussion for details.