Summary |  Admin |  Home Page |  Forums |  Tracker |  Bugs |  Support |  Patches |  RFE |  Lists |  Tasks |  Docs |  Maven Docs |  API Docs |  Coverage |  Screenshots |  News |  SVN |  Files | 

MMBI: JMX Model MBean Instrumentor

Title: MMBI: JMX Model MBean Instrumentor.
Author: JSESoft
Company: JSESoft

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: }
Explanation: This simple class adheres to the JavaBeans conventions and thus can automatically instrumented as a Model MBean. It provides an attribute controlled which should be exposed to the outer world (e.g. a JMX manager). It contains no code special to JMX at all!

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() );
Explanation: After executing the first four lines of the code above, the sample managed resource is instrumented and ready for management.
  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.

It's really that easy!

Optional JavaBean BeanInfo code

If you are familiar and used to JavaBeans BeanInfo you can improve the results produced by the instrumentor.

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

    public MethodDescriptor[] getMethodDescriptors()
        try {
            ParameterDescriptor controlled =
                new ParameterDescriptor();
            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 ) {
            return null;

Explanation: This BeanInfo provides a method descriptor for the setControlled() method. This descriptor adds additional information otherwise not available: It provides
  • a name "controlled" for the parameter of setControlled() (Have you realized that this name differs from the one used in the source code?)
  • a short description of the setControlled() method itself
What is done with this informaton is up to the JMX manager used. JConsole displays the parameter name as specified. Descriptions are displayed as finger tips.

Annotating the 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( @JMX( name="controlled" ) boolean value )
 9:     {
10:         controlled = value;
11:     }
12: }
Explanation: This is for the ones who like to keep all in one place. Writing BeanInfo is fairly boring (what about an Inspector generating it?). The same effect as with a separate BeanInfo class can be reached with a simple annotation in the class'es source code:
In the middle of line 8 there is a @JMX annotation giving the parameter a name. Find out yourself how to specify a description for the method.

Have a look at the screenshots to get an idea of how management with the JConsole looks like.

For Java 1.4 only: Don't forget to set the JVM flag if you use the Platform MBean Server as in the example above. Of course you can other servers, too, at the price of registering the MBean yourself.

Copyright: (c) 2005-2010 JSESoft

JSESoft-MMBI uses LOGBack:
Logback: the reliable, generic, fast and flexible logging framework. 

Copyright (C) 1999-2009, All rights reserved. This program and 
the accompanying materials are dual-licensed under either the terms of 
the Eclipse Public License v1.0 as published by the Eclipse Foundation 
or (per the licensee's choosing) under the terms of the GNU Lesser General 
Public License version 2.1 as published by the Free Software Foundation.

mmbi Project Snapshots Screenshots Support This Project Support Logo Host