modules/ROOT/pages/modules/jmx.adoc

Title: JMX

+++<a name="JMX">++++++</a>+++ #JMX#

This page describes the Aries JMX component.

The Aries JMX component is the Reference Implementation of the  OSGi JMX Management Model Specification, chapter 124 in the  http://www.osgi.org/Download/Release5[OSGi Enterprise Specification].

##Getting Started## To use the Aries JMX component, obtain the following:

* The Aries JMX bundle, e.g.
from Maven Central: http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22org.apache.aries.jmx%22[org.apache.aries.jmx]
* The Aries Util bundle, e.g.
from Maven Central: http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22org.apache.aries.util%22[org.apache.aries.util]

As prescribed by the OSGi JMX specification, to hook it in with an MBean Server the relevant MBean Server needs to be registered in the OSGi Service Registry.

The easiest way to get things to do this is to use the platform mbean server, and register that.
For example create a simple bundle that contains the following Bundle Activator:

....
import java.lang.management.ManagementFactory;
import javax.management.MBeanServer;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

public class Activator implements BundleActivator {
  public void start(BundleContext context) throws Exception {
    MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();
    context.registerService(MBeanServer.class.getName(), mbs, null);
  }

  public void stop(BundleContext context) throws Exception {}
}
....

Then install the Aries JMX Bundle and the Aries Util Bundle and start everything:

 g! lb
 START LEVEL 1
    ID|State      |Level|Name
     0|Active     |    0|System Bundle (4.2.1)
     1|Active     |    1|Apache Felix Bundle Repository (1.6.6)
     2|Active     |    1|Apache Felix Gogo Command (0.12.0)
     3|Active     |    1|Apache Felix Gogo Runtime (0.10.0)
     4|Active     |    1|Apache Felix Gogo Shell (0.10.0)
     5|Active     |    1|My Glue Activator (1.0.0)
     6|Active     |    1|Apache Aries JMX Bundle (1.1.1)
     7|Active     |    1|Apache Aries Util (1.1.0)

Now you can access the OSGi functionality through MBeans, for example via jconsole: image:http://aries.apache.org/images/modules/jmx-screenshot.png[JMX Screenshot]

##Blueprint Integration## TODO

##Whiteboard support## The JMX Whiteboard support bundle allows registration of JMX MBeans through the OSGi service registry.
As a prerequisite the Apache Aries JMX Whiteboard Bundle has to be installed.

Once this is installed, register your services with the `jmx.objectname` service registration property.
This is either a JMX `ObjectName` or a single String.
The value is used as the JMX Object Name to register the MBean.
If the property is of some other type a message is logged and the MBean is still registered if the service implements the `MBeanRegistration` interface and the implmentation provides the actual JMX Object Name to use for the registration.

The name of the service as which the MBean service is registered is ignored by the Whiteboard.

The service object, though, must be a valid JMX MBean: It has to either implement the `DynamicMBean` interface or implement an interface whose name is the object's (simple) class name with the `MBean` suffix.

Additional Service Properties supported:

* `warning.exceptions` (String+): One or more exception class names can be specified in this service property.
If an exception occurs during the MBean registration and the exception is of one of these types mentioned, then this exception is logged as a warning.
Otherwise the exception is logged as an error.