Table of Contents
MX4J provides some extension to the JMX specification, some transparent with respect to MBeans or applications portability
across JMX implementations, and some that instead ties your MBeans or applications to the MX4J implementation.
This extension is totally transparent with respect to MBeans portability across JMX implementations.
When MBeans are coded as standard MBeans, the JMX Agent is responsible of the creation of the metadata
information for them. Conversely, when coded as dynamic MBeans, the programmer is responsible of the
creation of such metadata information exposed to the JMX Agent through the
<funcdef>public MBeanInfo
getMBeanInfo
</funcdef>
<void></void> method of the
DynamicMBean
interface.
Although the JMX Agent can retrieve information about attributes, operations, constructors and notifications, for standard MBeans it cannot retrieve user information such as attribute description, operation description and parameter names and descriptions, and so on.
These information are important for the user of a management application, that can immediately understand what an operation parameter is for just reading the description associated with that parameter. Same happens with attributes.
MX4J offers the possibility of customize descriptions and parameter's names for attributes, operations, constructors and notifications of standard MBeans. This customization is achieved by implementing a class that follows some lexical patterns, in a way very similar to what happens to standard MBeans and the Java interface that represent their management interface to the JMX Agent.
The MBean programmer should write a class that has the same full qualified name of the MBean class, ends
with "MBeanDescription" and implement the
mx4j.MBeanDescription
interface
or extends the
mx4j.MBeanDescriptionAdapter
class.
For example if you have an MBean whose class is
my.package.MyService
, then you will
have a management interface defined by the
my.package.MyServiceMBean
Java interface,
and you may add a class named
my.package.MyServiceMBeanDescription
that implements
the
mx4j.MBeanDescription
interface and that specifies descriptions and parameter's
names for the MBean (see example below).
The whole mechanism of generating the management interface and the description for standard MBean can be automated using XDoclet (see the section about XDoclet for further details).
When the MyService MBean is used in another JMX implementation, that implementation will not care about the
MBeanDescription class, and thus will ignore the additional information you provided. Your MBean will
work normally, but the other implementation's MBeanServer will not be able to provide description information
to connectors and adaptors.
That's why this extension is transparent: it will not cause your MBeans to stop working in another JMX implementation.
Example 4.1. Specifying description for standard MBeans
public interface MyServiceMBean { public void start(); public void setStatus(int status); } public class MyService implements MyServiceMBean { public MyService(String type) {...} public void start() {...} public void stop() {...} public void setStatus(int status) {...} } public class MyServiceMBeanDescription extends MBeanDescriptionAdapter { public String getConstructorDescription(Constructor ctor) { // Only one constructor return "Creates a new instance of my personal service"; } public String getConstructorParameterName(Constructor ctor, int index) { // Constructor has only one parameter return "type"; } public String getConstructorParameterDescription(Constructor ctor, int index) { // Constructor has only one parameter return "The type of the service. Valid values are 'VOLATILE' or 'PERMANENT'."; } public String getAttributeDescription(String attribute) { // There is only one attribue, 'Status' return "The status of the service. Can be set to ON=1, OFF=0"; } public String getOperationDescription(Method operation) { String name = operation.getName(); if (name.equals("start")) { return "Starts the service. After the service is started its status is ON"; } else if (name.equals("stop")) { return "Stops the service. After the service is stopped its status is OFF"; } else { return super.getOperationDescription(operation); } } }