MMBI: JMX Model MBean Instrumentor

The JMX Model MBean Instrumentor is a Pure Java module for automatic instrumentation of objects of arbitrary classes as JMX Model MBeans. Simply by passing an object to the JMX Instrumentor, appropriate JMX ModelMBeanInfo will be created and the object registered as an MBean.

That way, the developer needs not to bother instrumenting objects as MBeans anymore, this can be done by the JMX Instrumentor automatically on the fly.

The JMX Model MBean Instrumentor project will provide two packages:

1. The Reflection Inspector, which recursively traverses the reflection tree of an arbitrary class and calls handlers when discovering the class'es attributes, methods, and constructors.
2. The JMX Model MBean Instrumentor, providing handler methods for the Reflection Inspector which generate the JMX ModelMBeanInfo for the class members detected by the Reflection Inspector. Furthermore, a JMX annotation is provided which is capable of specifying more detailed information than can be gained by reflection. The JMX Model MBean Instrumentor is aware of this annotation and includes the information provided into the generated JMX ModelMBeanInfo.

Since the JMX Model MBean Instrumentor is written in Pure Java 1.5, and is platform independent. Since it confirms with the JMX standard, it does not depend on the JMX implementation used (e.g. it works fine with JConsole).

Package org.jsesoft.ri

The package org.jsesoft.ri provides for class inspection by Java reflection. The class ReflectionInspector traverses the reflection tree of the inspectee and calls handler function for all fields, constructors, methods, and annotations found.

Package org.jsesoft.mmbi

The org.jsesoft.mmbi package provides the class org.jsesoft.mmbi.ModelMBeanInstrumentor which uses the ReflectionInspector creating ModelMBeanInfo for the inspectee of arbitrary class from both, reflection information (including JavaBeans BeanInfo) and the JMX annotation (below).

The org.jsesoft.mmbi package comes with an annotation for customizing the JMX instrumentation produced by ReflectionInspector with the ModelMBeanInstrumentor. The annotation interface org.jsesoft.mmbi.JMX provides accessors for all the fields which can be specified in Model MBean descriptors.

Finally, org.jsesoft.mmbi offers an experimental annotation adding JMX notification instrumentation produced by the ModelMBeanInstrumentor. The annotation interface JMXNotification provides accessors for all the notification fields which can be specified in Model MBean descriptors.

Usage example

A sample managed resource

 1: public class SampleResource
 2: {
 3:     private boolean controlled;
 4:     public boolean isControlled()
 5:     {
 6:         return controlled;
 7:     }
 8:     public void setControlled( boolean value )
 9:     {
10:         controlled = value;
11:     }
12: }

The instrumentation code

 1: SampleResource resource = new SampleResource();
 2: ModelMBeanInstrumentor instrumentor =
 3:   new ModelMBeanInstrumentor(resource, NotificationBroadcasterSupport.class);
 4: NamedModelMBean mbean = instrumentor.instrument( "mmbi-managed" );
 5: for( int count = 0; (count < 60) || (resource.isControlled()); count++ ) {
 6:   Thread.sleep( 1000 );
 7: }
 8: ManagementFactory.getPlatformMBeanServer().unregisterMBean( mbean.getName() );

1. Create a sample managed resource (can be of arbitrary class).
2. Create the instrumentor for the resource.
3. Set the resources superclass as sentinel class (where inspection stops).
4. Create a Model MBean for the managed resource:
   • Let the instrumentor instrument the managed resource as a Model MBean. The Model MBean is of class NamedModelMBean provided by MMBI.
   • and register at the Platform MBean Server it with the nickname "mmbi-managed". Now you can manage it already!
5. The sample resource has a getter-method isControlled() which indicates that the lifetime of the resource is controlled (managed) from the outside (e.g. with JConsole).
6. Give the manager a chance to take control (sleep 60 secs.).
7. If done, unregister the Model MBean.

public class SampleResourceBeanInfo
    extends SimpleBeanInfo
{
    protected Class beanClass = SampleResource.class;

    @Override
    public MethodDescriptor[] getMethodDescriptors()
    {
        try {
            ParameterDescriptor controlled =
                new ParameterDescriptor();
            controlled.setName("controlled");
            ParameterDescriptor[] setControlParams =
                { controlled };
            Class[] setControlledArgs = { boolean.class };
            MethodDescriptor setControlled =
                new MethodDescriptor(
                beanClass.getMethod("setControlled", setControlledArgs ),
                setControlParams );
            setControlled.setShortDescription("controlled (managed) from the outside?");
            MethodDescriptor[] methodDescriptors =
                { setControlled };
            return methodDescriptors;
        } catch( Exception exception ) {
            exception.printStackTrace();
            return null;
        }
    }

}

 1: public class SampleResource
 2: {
 3:     private boolean controlled;
 4:     public boolean isControlled()
 5:     {
 6:         return controlled;
 7:     }
 8:     public void setControlled( @JMX( name="controlled" ) boolean value )
 9:     {
10:         controlled = value;
11:     }
12: }