mmbi2 0.2.0-SNAPSHOT API

Provides JMX Model MBean instrumentation on the fly.

See:
Description

Packages

org.jsesoft.mmbi	Provides JMX Model MBean instrumentation on the fly.
org.jsesoft.mmbi.samples	TODO
org.jsesoft.ri	Provides class inspection by reflection (subclass- and strategy pattern, resp).

Provides JMX Model MBean instrumentation on the fly.

JMX Model Mbean Instrumentor Project Overview

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 of a strategy object when discovering the class'es attributes, methods, and constructors.
2. The JMX Model MBean Instrumentor, which is a strategy for the Reflection Inspector providing handler methods 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, it 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.

The Reflection Inspector offers two methods of exploiting the information provided:

• subclassing the inspector
• attaching a strategy to the inspector

The JUnit test class org.jsesoft.ri.TestReflectionInspector demonstrates both types of usage.

Package org.jsesoft.mmbi

The org.jsesoft.mmbi package provides the class org.jsesoft.mmbi.ModelMBeanInstrumentor which is a strategy for 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: ModelMBeanInstrumentor instrumentor =
 2:   new ModelMBeanInstrumentor(NotificationBroadcasterSupport.class);
 3: SampleResource resource = new SampleResource();
 4: NamedModelMBean mbean = instrumentor.instrument( resource, "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 the instrumentor.
2. Set the resources superclass as sentinel class (where inspection stops).
3. Create a sample managed resource (can be of arbitrary class).
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();
            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;
        }
    }

}

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.

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:

• JSESoft MMBI homepage

Since:

0.1