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 itself, where 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. When accessing an MBean remotely via JSR-160, the MBeanServer holding the requested MBean must be known before. Jolokia instead merges all MBeanServers it can find to give a single view on all MBeans. The merging algorithm is described in Section 9.1.1, “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 Section 9.1, “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 Section 9.3, “Spring Support”.
The Jolokia MBeanServer can be easily created and used with a locator:
MBeanServer jolokiaServer = JolokiaMBeanServerUtil.getJolokiaMBeanServer();
This server is treated specially by a Jolokia Agent:
@JsonMBeanon the class level. JSON MBean are explained in Section 9.2, “@JsonMBean”
Jolokia tries hard to detect as many MBeanServer as available
in a JVM. Beside the always present
application servers create own MBeanServer which not always
can be found with 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
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.
MBeanServerFactory.findMBeanServer(null)are called if not already tried previously.
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
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).
JMX 1.4 introduced MXBeans
which allows 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
structure with property names as keys and their values in
Jolokia provides an annotation
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
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:
ModelMBeans unde the hood. E.g. Spring JMX uses a ModelMBean for
@JsonMBeancan be easily added, whereas
@MXBeanwouldn't work here.
The Jolokia MBeanServer and the
@JsonMBean annotation are contained in the
A Jolokia agent can be easily integrated into a Spring application
context. A dedicated artefact
jolokia-spring can be used, which
comes with a custom Spring configuration syntax.
For Maven based projects, a simple dependency declaration is sufficient:
<dependency> <groupId>org.jolokia</groupId> <artifactId>jolokia-spring</artifactId> <version>1.1.0</version> </dependency>
With this in place, the following configuration can be used to fire up a Jolokia JVM based agent using the HTTP server which comes with OpenJDK/Oracle JVMs (Version 6 or later).
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jolokia="http://www.jolokia.org/jolokia-spring/schema/config" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.jolokia.org/jolokia-spring/schema/config http://www.jolokia.org/jolokia-spring/schema/config/jolokia-config.xsd "> <jolokia:agent lookupConfig="false" systemPropertiesMode="never"> <jolokia:config autoStart="true" host="0.0.0.0" port="8778" .... /> </jolokia:agent> </beans>
There are two directives available:
<jolokia:agent> declares a Jolokia
server with a configuration as defined in an embedded
<jolokia:agent> has an attribute
lookupConfig. If set to
true, externally defined
<jolokia:config> sections will be
looked up, too and merged with the embedded configuration. A
<jolokia:config> has an
order attribute, which determines the
config merge order: The higher order configs will be merged
later and hence will override conflicting parameters. By
default, external config lookup is disabled.
determines, how system properties with a prefix
jolokia. can be used as configuration
values. There are three modes available:
Table 9.1. System properties modes
||No lookup is done on system properties as all. This is the default mode.|
System properties with a prefix
System properties with a prefix
<jolokia:config> takes as attributes all
the configuration parameters for the JVM agent as described in
Table 3.6, “JVM agent configuration options”. In addition, the is an extra
autoStart which allows for
automatically starting the HTTP server during the initialization
of the application context. By default this is set to
true, so the server starts up automatically
<jolokia:mbean-server> the Jolokia
MBeanServer can be specified. This is especially useful for
adding it to
so that this MBeanServer is used for registering
@JsonMBean. Remember, MBean registered at
the Jolokia MBeanServer never will show up in an JSR-160 client
except when annotated with
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context" xmlns:jolokia="http://www.jolokia.org/jolokia-spring/schema/config" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.jolokia.org/jolokia-spring/schema/config http://www.jolokia.org/jolokia-spring/schema/config/jolokia-config.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd "> <context:mbean-export server="jolokiaServer"/> <jolokia:mbean-server id="jolokiaServer"/> </beans>
There is an even simpler way to startup a Jolokia JVM agent
with a default setup if you use a variant of the
jolokia-spring module with the classifier
plugin. This artefact contains a
predefined Spring configuration for starting up Jolokia with
default values automatically:
<dependency> <groupId>org.jolokia</groupId> <artifactId>jolokia-spring</artifactId> <classifier>plugin</classifier> <version>1.1.0</version> </dependency>
Beside putting this jar into the classpath (along with its
dependencies) the only requirement is, that the Spring
application context needs to pickup
many Spring based containers like the Camel
Maven Plugin do this automatically for you, nothing
has to be configured here. Otherwise this
application context path has to be added manually, but in this case it is
probably easier to use the non-plugin version (without
classifier) and declare the Jolokia server explicitily in an
existing Spring configuration file as described above.
By default, the Jolokia agent starts on port 8778 on every IP-Address of the host without security.
The configuration can be tweaked via system properties as
described in Table 9.1, “System properties modes”. I.e. the plugin
doesn't specify any configuration on its own and uses a
As an alternative, the default settings can be customized by
providing a standalone
<jolokia:config> somewhere in the
Spring application context. An
attribute can be used if multiple config declarations are
present: the higher the order, the higher the priority. But
then again, instead of using the plugin with an external
configuration it is probably better to us an explicite
<jolokia:agent> declaration, since
you have to add to a Spring configuration file anyway.