Saturday, October 27, 2007

 

Standard MBeans and Documentation

This blog-post assumes that you are a Java Programmer and have used or at least have knowledge of JMX technology. If word JMX is not ringing the bell, and if you are a Java programmer, I strongly suggest you get to know this technology and I'm sure you won't regret that you did. Go here for more info.

JMX technology in Java ecosystem has been playing tremendous role in making the Java components more manageable and maintainable. If you are developing a Java component and are exposing the configuration/management through set of attributes/operations, most probably you would be using

Back to point. If you are using standard MBeans with an interface defining all attributes/operations and an implementation class to provide the functionality, I'm sure you would have noticed that attributes/operations on the JMX agents are not being displayed but just empty.

One would have put in enough effort to document the MBeans interface with all nitty-gritty details but it is would be of no use if it is not being displayed in the JMX agent view.  This is due to fact that JMX  agents are accessing your interfaces at runtime, by then Java compiler would have removed all javadocs and changed the parameter names for operations. However StandardMBeans provide set of hooks, which can show the appropriate documentation on the agent view.

Documentation hooks works by set of getDescription/getParameter methods on StandardMBean class before constructing the MBeanInfo object for your MBean.  Where you can override those method to provide the documentation appropriate for your MBean, which would displayed on the agent view. However it is required to copy the documentation from MBean interface javadocs and programmatically return it. It is laborious and unmaintainable.  Solution being, generate that class which can generate the documentation automatically from the MBean interface javadocs.

To my surprise I didn't find any tool/utility which can generate this java file automatically from the MBean interface and provides the documentation at runtime. So I decided to implement my own and release to public. It is MBeanDoclet.

MBeanDoclet automatically generates a java source file for set of MBeans and provides the same javadoc documentation at runtime. So if you modified the javadoc, it is automatically updated in JMX Agents.

Example worth ten-thousand words. So here is one. For ex., if we have a MBean named TestMBean with some nicely written documentation

package com.brsanthu.mbeandoclet;

/**
 * MBean created to demonstrate the MBean Doclet usage.
 */
public interface TestMBean {
   
    /**
     * This is standard mbean attribute, which does nothing
     * but used only to demonstrate the MBeanDoclet usage.
     */
    public int getSampleAttribute();
   
    /**
     * This is standard mbean operation, which does nothing
     * but used only to demonstrate the MBeanDoclet usage.
     */
    public void sampleOperation();
}
Java2html

Running the MBeanDoclet, generates the following file.

////////////////////////////////////////////////////////////////////////////
//
// CAUTION: This source file is automatically generated by MBeanDoclet.
//          Any modifications would be overwritten nexttime it runs.
//
////////////////////////////////////////////////////////////////////////////

package com.brsanthu.mbeandoclet;

import javax.management.MBeanAttributeInfo;
import javax.management.MBeanInfo;
import javax.management.MBeanOperationInfo;
import javax.management.MBeanParameterInfo;
import javax.management.NotCompliantMBeanException;
import javax.management.StandardMBean;

public class TestMBeanJavadoc extends StandardMBean {

    public TestMBeanJavadoc(Class mbeanInterface) throws NotCompliantMBeanException {
        super(mbeanInterface);
    }

    public TestMBeanJavadoc(Object implementation, Class mbeanInterface)
                    throws NotCompliantMBeanException {
        super(implementation, mbeanInterface);
    }

    @Override
    protected String getDescription(MBeanInfo info) {
    String description = "";

        description = "MBean created to demonstrate the MBean Doclet usage.";

        return description;
    }

    @Override
    protected String getDescription(MBeanAttributeInfo info) {

        String description = "";

        if (false) {
            //This is always false stmt is added to make easier
            //to generate following blocks of else condition.
     

        } else if (info.getName().equals("SampleAttribute")) {
            description = "This is standard mbean attribute, which does nothing" +
 " but used only to demonstrate the MBeanDoclet usage.";


        } else {
          description = super.getDescription(info);
        }

        return description;
    }

    @Override
    protected String getDescription(MBeanOperationInfo info) {
        String description = "";

        if (false) {
            //This is always false statement is added just to make it easier
            //to generate following multiple blocks of else conditions.


        } else if (info.getName().equals("sampleOperation")) {
            description = "This is standard mbean operation, which does nothing" +
 " but used only to demonstrate the MBeanDoclet usage.";


        } else {
          description = super.getDescription(info);
        }

        return description;
    }
}
Java2html

This automatic generated has added lots of value-add to the MBean we have been developing.

If this doclet can be of any useful, you can download here. If you have any questions/issues, mail be brsanthu[at]yahoo[dot]com.


# posted by Santhosh @ 1:09 PM
Comments:
Very interesting!

As you know, I've blogged about achieving the same thing using annotations,
possibly augmented by an annotation
processor to get parameter names.

The advantage of using Javadoc is that the generated HTML looks good and has the same text as the runtime descriptions. If you use annotations, then they show up in the Javadoc, but in a form that is less easy to read. A further advantage to Javadoc is that it works with earlier versions of the Java platform.

The main disadvantages that I see are, first, doc comments can use HTML, but MBeanInfo descriptions aren't expected to contain HTML; second, it makes the build process a bit more complicated; and, third, there is no obvious way to make the descriptions localizable. None of these seems insurmountable.

Rather than generating a subclass of StandardMBean, it might be better to generate a text file (for example XML or Properties), and have just one predefined subclass of StandardMBean that gets the descriptions from such a file. This avoids tricky problems with bootstrapping, where code that references TestMBeanJavadoc will only compile once that class has been generated.

Éamonn McManus -- JMX Spec Lead -- http://weblogs.java.net/blog/emcmanus
# posted by Blogger Eamonn McManus : 5:35 AM
 
People should read this.
# posted by Anonymous Anonymous : 3:28 PM
 
ООО ТРИУМФ производит и поставляет оборудование для систем отопления и теплоснабжения – подогреватели водоводяные ВВП, подогреватели пароводяные пп, бойлеры, грязевики, воздухосборники, а также трубопроводная продукция – фланцы, отводы, переходы.
# posted by Anonymous Anonymous : 7:58 PM
 
Post a Comment



<< Home

This page is powered by Blogger. Isn't yours?