JMX Annotations

Introduction

The aim of this tutorial is to create two JMX annotations to help define MBean metadata seamlessly.

  • @Description – describes the MBean attribute and operations. By default the JMX API uses the attribute or operation name.
  • @Name – names to the operation parameters. By default the JMX API uses p0 , p1 ,   p2 , …

By default, the JMX API falls short with providing meaningful descriptions and parameter names.  Using the JMX API directly is complicated.  The aim of this tutorial is to provide two annotations that will encapsulate this complexity.

For an introduction to the JMX architecture and how to register MBeans using the standard JMX API, check our Brief Instroduction to JMX tutorial.  Also, if you use the Spring Framework, the JMX Spring tutorial explains how to easily register your Spring beans with the JMX Agent.

The Problem with JMX API

The JMX API goes a long way to easily register MBeans with the JMX Agent. Out of the box, the JMX API registers the MBean with the same attribute and operation names used in the code.

Unfortunately it falls short on providing meaningful descriptions and parameter names. For example, the default parameter names used are p0 , p1 ,   p2 , … which makes it very hard to read in the JConsole. Attempt to provide meaningful descriptions or change the parameter names using the JMX API is very cumbersome.

Missing Param Names in JConsole
Missing Param Names in JConsole

The @Description and @Name annotations that we will introduce in this tutorial encapsulate this JMX API complexity and provide an easy and natural way to define descriptions and parameter names.

@Description and @Name annotations

Now, let’s create the @Description and @Name annotations that will better help document MBeans:

Using these two annotations, a typical MBean management interface can be decorated like this:

And finally, we wrap our MBean with the AnnotatedStandardMXBean class bring up to live our annotations.  The AnnotatedStandardMXBean class encapsulates all the ugliness of the JMX API.

If you fire up the JConsole, you will see our parameter names and description now have the values from our annotations.

MBean Showing Param Names in JConsole
MBean Showing Param Names in JConsole

A detail analysis of the AnnotatedStandardMBean class is provided in the next section.

If you are not too concerned how this magic works, feel free to skip the next section and just copy and paste the AnnotatedStandardMBean implementation.  If you decide to continue reading, be warned, it will get nasty.

AnnotatedStandardMBean

The AnnotatedStandardMBean class encapsulates the logic to interpret the simplicity of our @Description and @Name annotations, and translates it into the ugliness of the JMX API.

The full implementation of AnnotatedStandardMBean can be found here.

If you are not too concerned how this magic works, feel free to skip this section and just use the class provided as is.  If you are however intrigued how to define MBean metadata directly with the JMX API, then by all means keep reading.  But be warned, it is going to get messy…

Constructor

The first thing we’ll notice is that AnnotatedStandardMBean is a subclass of javax.management.StandardMBean .  By subclassing from StandardMBean , we are in fact turning our AnnotatedStandardMBean into a Dynamic MBean.

The constructor of StandardMBean has three parameters: the target MBean, the target management interface, and a flag to indicate whether this is an MXBean.

 Metadata Methods

The StandardMBean provides a series of protected methods that describe the MBean.  We will use these methods to return the descriptions provided in the annotations.

The first method returns the description of the MBean. The second returns the description for attributes (defined with getter/setters).  The third provides description for operations.  The fourth provides descriptions for operation parameters.  The last one defines the name of operation parameters (instead of the above p0, p1, p2…)

MBean description

The following method returns the MBean description as provided in the @Description annotation.

 MBean Attibute description

The method below returns the MBean attribute description as provided by the @Description annotation. First it derives the getter method name used in the MBean interface, and then uses methodByName  to retrieve the java.lang.reflect.Method .  The annotation description value is then retrieved from the Method class.

MBean Operation description

The method below provides the description of an MBean operation.  It uses methodForOperation  to retrieve the java.lang.reflect.Method  from the MBeanOperationInfo.  The annotation description value is then retrieved from the Method class.

MBean Parameter Description

The method below extracts the parameter information from the MBean. Once again, it uses   methodForOperation  to find the Method of the operation, and then uses getParameterAnnotation to return the @Description annotation of the parameter (if any).

MBean Parameter Name

Last but not least, getParameterName returns the name provided in operation parameters by the @Name annotation.  This is the name that will be shown in JConsole instead of p0, p1, p2…

Private Reflection Helpers used

The implementation of getParameterAnnotation is provided below.  Basically this method returns the annotation of a given parameter in the Method .

Below the implementation of methodByName and methodByOperation .   methodByName uses standard reflection to retrieve the java.lang.reflect.Method  from a Class, given a method name and parameters.   methodByOperation is similar, but uses the MBeanOperationInfo instead to describe the method to retrieve.

The two methods below are used to return the class name.  The difference between  classForName and Class.forName  is that the later does not work for primitive values (i.e. int, long, float…)

Bibliography

The following two tabs change content below.

Eduard Manas

Eduard is a senior IT consultant with over 15 years in the financial sector. He is an experienced developer in Java, C#, Python, Wordpress, Tibco EMS/RV, Oracle, Sybase and MySQL.Outside of work, he likes spending time with family, friends, and watching football.

Latest posts by Eduard Manas (see all)

Leave a Reply