JmxBuilder (Groovy DSL for JMX)

JmxBuilder 0.5 (beta) has been released.  After some constructive feedback (see previous post about JmxBuilder in April), I redesigned the DSL to be more robust, compact, and added new features to help export and programmatically manage MBeans at runtime. The new features focus on building JMX agents, Jmx clients, and participate in the JMX event model.  So, here it is:

Full description at http://code.google.com/p/groovy-jmx-builder/

JmxBuilder is a Groovy-based domain specific language for the Java Management Extension (JMX) API. It uses the builder pattern to create an internal DSL that facilitates the exposure of Java and Groovy beans for runtime control and management via the MBean server.The Groovy JMX Builder DSL hides the complexity of creating and exporting management beans via the JMX API and provides a set of natural constructs to interact with the JMX infrastructure.

New Features

• Simplified JMX API's programmability
• Maintain the natural Groovy syntax
• Declaratively expose any Java/Groovy object as JMX managed MBeans
• Support for class-embedded descriptors
• Inherent support for JMX's event model
• Seamlessly create JMX event broadcasters
• Attach event listeners as inline Groovy closures
  
• Exposes attribute, constructors, operations, parameters, and notifications
• Simplifies the creation of connector servers and connector clients
• Support for exporting JMX timers
• Integrates with the existing GroovyMBean class

Exporting an MBean

Suppose you have a class (Java or Groovy) that you want to expose for runtime management:

public class RequestController {
    // constructors
    public RequestCopntroller()
    public RequestController(Map resource)

    // attributes
    public boolean isStarted() { ... }
    public int getRequestCount(){ ... }
    public int getResourceCount() { ... }
    public void setRequestLimit(int limit){ ... }
    public int getRequestLimit() { ... }
    
    // operations
    public void start(){ ... }
    public void stop(){ ... }
    public void putResource(String name, Object resource){ ... }
    public void makeRequest(String res) { ... }
}

Initialize the builder

def jmxBldr = new JmxBuilder()

Export MBean

Once you have builder, you aready to export the object instance as an MBean

def ctrl = new RequestController()
jmxBldr.export {
    bean(ctrl)
}  

Using Descriptors

You can use the descriptors to optionally provide granular description of your bean and provide different level of visility to members of the target MBean.

Override the ObjectName

You can provide JMX ObjectName as a String or an instance of ObjectName.

jmxBldr.export {
    bean(target:ctrl, name:"jmx.builder:type=Object")
} 

Using the wildcard exports all attributes (getters) defined on the underlying backing object.

jmxBldr.export{
    bean(
        target: ctrl, name: "jmx.builder:type=Object", 
        attributes: "*"
    )
}

Export Attribute List
You may export selected attributes by providing a Groovy list of attribute names.

jmxBldr.export{
    bean(
        target: ctrl, name: "jmx.builder:type=Object", 
        attributes: ["Started","RequestCount", "ResourceCount"]
    )
}

JmxBuilder lets you specify attribute-change event listeners as Groovy closures.   This allows you to react to JMX attribute-change events when a value is update through a setter.

jmxBldr.export{
    bean(target:ctrl, name:"jmx.builder:type=Object",
        attributes: [
            "RequestLimit":[reable:true, writable:true,
                onChange:{e -> 
                    if(e.newValue > 10){
                        println "***** Warning, high limit detected *****"
                    }
                }
            ]
        ]
    )
}

View JmxBuilder Reference for detail.

Exporting Operations

Similar descriptors are available to describe and control the level of visibility of operations defined on the backing bean being exported for management.  For sake brevity, I will just show a couple of descriptors. 

You may use the wildcard to export all operations defined on the backing bean for management.

jmxBldr.export{
    bean(
        target: ctrl, name: "jmx.builder:type=Object2", 
        operations: "*"
    )
}

JmxBuilder lets you specify operation-call event listeners as Groovy closures.   This allows you to react to JMX operation invokation events by providing a callback code as Groovy Closure.

jmxBldr.export{
    bean(target:ctrl, name:"jmx.builder:type=Object",
        operations: [
            "makeRequest":[
                onCall:{e -> 
                    println "***** A request was made *****"
                }
            ]
        ]
    )
}

View JmxBuilder Reference for detail.

Conclusion

The sample above provides only a high level view of the features and descriptors provided by the new JmxBuilder tag.  If you use JMX or looking for simple way to script against the JMX API, take a look at JmxBuilder.

http://code.google.com/p/groovy-jmx-builder/