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:
-
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.
-
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.
-
Create a sample managed resource (can be of arbitrary class).
-
Create the instrumentor for the resource.
-
Set the resources superclass as sentinel class (where inspection stops).
-
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!
-
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).
-
Give the manager a chance to take control (sleep 60 secs.).
-
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;
@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;
}
}
}
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 -Dcom.sun.management.jmxremote 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
|