While reference manual contains all the details about Jolokia protocol, configuration, agents, etc., this page highlights some high level concepts and core classes which are required to understand Jolokia goals.

Main feature

The most important feature of Jolokia is to provide a protocol adaptor for accessing MBeanServer instances and managed beans available in single or multiple JVMs.

jolokia architecture

Chapter 5.3 of JMX Specification 1.4 defines two means of remote access to JVM’s MBeanServer instances:

  • connector, which is a way to remotely expose the management interface. For RMI protocol (which is the only mandatory protocol as specified by JMX), it is a remote view of interface. This approach requires active connector server running in the JVM which' MBeanServer instances we want to access remotely.

  • protocol adaptor, where there is no direct remote representation of an MBeanServer. Instead a set of specific protocol operations is mapped to a set of operations on MBeanServer. For HTTP protocol, operations like GET or POST with details specified in HTTP payloads may be used to operate on an MBeanServer. And this is the approach taken by Jolokia.

JMX connectors were originally defined in details in JMX Remote API Specification (JSR-160). JSR-160 was then merged with JMX Specification 1.4 (JSR-3) itself.

Jolokia architecture

Jolokia exposes a protocol adaptor using an agent which effectively translates HTTP protocol messages into operations invoked on an instance of (or in Proxy mode) and their results.

Each kind of Jolokia supported agent uses the same set of support classes.

Jolokia agents

There are 3 kinds of agents supported by Jolokia:

JVM agent

An agent installed using JVM Attach API or Java Instrument API.

WAR agent

An agent started from WAR application with org.jolokia.server.core.http.AgentServlet servlet declared.

OSGi agent

An agent started from a bundle, which registers org.jolokia.server.core.osgi.OsgiAgentServlet using OSGi CMPN Whiteboard Specification for Jakarta™ Servlet.

JVM Agent uses JDK’s own HTTP server. WAR agent just runs inside Servlet container and OSGi agent uses whatever HTTP server is available in the OSGi runtime.

Jolokia support classes

For all the agents, Jolokia uses the same set of classes for two kinds of processing:

  • initialization stage, when Jolokia is configured

  • request processing stage, when Jolokia handles incoming HTTP requests, communicates with and returns HTTP responses after translating the results

Initialization stage

an interface for accessing the configuration


an interface used for logging, delegates to underlying (Servlet, OSGi Logging, stdout) logging mechanism


an interface used to configure and discover services used throughout Jolokia


single access point to access configuration, Jolokia services and register MBeans in platform MBeanServer


is used to detect platofm-specific instances (which may not be detected using

Request processing stage

ACL style interface for restricting remote access


translates HTTP request into JolokiaRequest


represents generic Jolokia request


handles generic JolokiaRequest


is used by backend manager to process JolokiaRequest


is used to process a result JSON from request dispatcher


a service obtained from JolokiaContext. Request dispatcher obtains available handlers from JolokiaContext (and JolokiaServiceManager) and passes the incoming request to each of the handlers.

Available request handlers

Jolokia provides several implementations of org.jolokia.server.core.service.request.RequestHandler:


doesn’t really call any MBean, but simply returns version information of Jolokia agent.


most important handler, which directly calls (actually a merged view of available MBeanServer instances)


calls remote MBeanServer through JSR-160 connector (

operates on beans obtained from Spring’s org.springframework.context.ApplicationContext using name key from target