Eamonn McManus's Blog

Adding Descriptors to MBeans in Mustang

Descriptors allow you to give additional information about MBeans to management clients. For example, a Descriptor on an MBean attribute might say what units it is measured in, or what its minimum and maximum possible values are. As of Mustang (Java SE 6), Descriptors are a basic part of the JMX API and are available in all types of MBeans. Here's the easiest way to use them.

Mustang makes it very convenient to add information to an MBean. You can use annotations in a Standard MBean to define the Descriptor contents. For example, with this definition...

@Documented
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Units {
    @DescriptorKey("units")
    String value();
}

...you can define an annotation @Units that you can then use like this...

public interface CacheMBean {
    @Units("whatsits")
    public int getUsed();
}

You can just cut-and-paste the @-infested text that defines @Units from the DescriptorKey documentation, so you don't need to remember all the details. Of course, as soon as you've defined @Units once you can use it in any number of MBeans.

As usual with Standard MBeans, you can make an MBean by defining a class Cache that implements CacheMBean and registering it in the MBean Server something like this...

MBeanServer mbeanServer = ManagementFactory.getPlatformMBeanServer();
ObjectName name = new ObjectName("com.example.domain:type=Cache,name=\"Whatever\"");
Cache cache = ...whatever...;
mbeanServer.registerMBean(name, cache);

Now you can see the units of the Used attribute defined by the getUsed() method in the interface...

MBeanInfo mbeanInfo = mbeanServer.getMBeanInfo(name);
for (MBeanAttributeInfo a : mbeanInfo.getAttributes()) {
    Descriptor d = a.getDescriptor();
    System.out.println("Attribute " + a.getName() + " has units " +
		       d.getFieldValue("units"));
}

...and as expected this will print...

Attribute Used has units whatsits

If the Descriptor doesn't contain a value for "units", then the getFieldValue() method will return null. The MBeanAttributeInfo.getDescriptor() method never returns null, though it might return an empty Descriptor.

You can imagine that a management console such as jconsole might use this kind of code to add a label to a graph of the Used attribute. The as-yet fanciful picture here shows the units, minValue, and maxValue items that have been added to the Descriptor for Used, and the graph that a console might produce of the Used value over time. The label of the graph and the minimum and maximum values come from the Descriptor items.

This picture comes from my session at this year's JavaOne. Sessions are now online for free!

If you're unable to migrate to Mustang just yet, I have a later blog entry describing how to use descriptors with Tiger and earlier versions of the J2SE platform.

Comments

• Supplying units is definitely a good thing. You might want to look at the JSR 275 and the dead body of JSR 108. I can't help but think that units will eventually become a standard part of Java. Hopefully that will happen without many incompatible versions.

  See also:

  JSR 108

  JSR 275

  JSR 108 on SourceForge

  JScience

  Posted by: coxcu on October 26, 2005 at 09:42 AM

• This question is not related to this post, but I was wondering what the plans are for JMX with respect to WSDM (and specifically MUWS)? How is JSR-262 progressing (I notice you are spec lead Eamonn)?

  
  

  Posted by: rgreig on October 31, 2005 at 02:14 AM

• rgreig, a good discussion of WSDM and JMX technology is in the article JMX and WSDM: overlapping technologies?. The authors are members of the JSR 262 Expert Group. JSR 262 will not completely address the question of how to link WSDM to JMX instrumentation, notably because there is a competing standard WS-Management and it is not clear how to reconcile the two. Nevertheless, we do expect to address some of the same problems in JSR 262, for example relating to deployment.

  We have draft schemas and much of an implementation of JSR 262 at this stage and hope to publish an early draft in the not too distant future.

  Posted by: emcmanus on November 03, 2005 at 07:46 AM

This work is licensed under a Creative Commons License.