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 public MBeanInfo getMBeanInfo (); 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.

               
      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);
            }
         }
      }