JmxBuilder Moves to Groovy Release 1.6

JmxBuilder has been officially added to Groovy! As of version 1.6 RC1, JmxBuilder has been migrated as part of Groovy Core. While the documentation will remain here, all future code release and improvement will be part of Groovy.

Download Groovy 1.6 here - http://groovy.codehaus.org/Download

You can still download the original JmxBuilder 0.5 beta here.

JmxBuilder

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 regular 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.

Features

• Domain Specific Language (DSL) for JMX API using Builder pattern
• Simplified JMX API's programmability
• Maintain the natural Groovy syntax
• Declaratively expose Java/Groovy objects as JMX managed MBeans
• Support class-embedded or explicit descriptors
• Inherent support for JMX's event model
• Seamlessly create JMX event broadcasters
• Attach event listeners as inline closures
• Use Groovy's dynamic nature to easily react to JMX events notifications
• Provides a flexible registration policy for MBean
• No special interfaces or class path restrictions
• Shields developer from complexity of JMX API
• Exposes attribute, constructors, operations, parameters, and notifications
• Simplifies the creation of connector servers and connector clients
• Support for exporting JMX timers

Getting Started

It's easy to start using the JmxBuilder DSL (as long as the jar is on your class path).

Initialize the builder

    def jmxBldr = new JmxBuilder()

You can optionally provide an MBeanServerConnection that the builder will use during its operations

    new JmxBuilder(server)

Exporting an MBean

Let's say you have Java class called RequestController with the following methods

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) { ... }
}

You can export an instance of that class for management to an MBeanServer using

def ctrl = new RequestController()

jmx.export {
    bean(ctrl)
}  

The code above will export an MBean into the MBeanServer for the specified object instance for management. JmxBuilder will do the following

• Generate a default JMX ObjectName
• Export all JMX attributes (in read-only)
• Export all operations

JConsole view of Exported Bean

You can see that JmxBuilder exports all attributes, operations, and constructor information automatically using this shorthand notation. You can customize your targeted attributes and operations description that you want to export (see below).

Export Descriptors

You can control, customize, and describe the information that is exported to the MBeanServer. JmxBuilder lets you describe your export information by declaring your descriptors inline or embedding the descriptors inside the object itself

Overriding the ObjectName

One of the thing you can do is to override the object name to customize your export. This is done as followed:

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

This willl export the MBean using the object name provided. You can use the string representation or an instance of ObjectName here.

See JmxBuilderReference for detail.

Controlling Attribute Export

You can control the description and attribute export using JmxBuilder.

Export with Attributes with Wildcard "*"

You can use a wildcard character to export all attributes associated with the MBean. The snippet below exports all attributes, however, no operations or constructors will be defined nor exported into the MBeanServer.

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

See JmxBuilderReference for more detail on exporting attributes.

Export Attributes by List

The following code snippet provides a list of attributes to export. Only the listed attributes will be exposed for management.

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

This snippet will cause JmxBuilder to export only the attributes listed in key "attributes:" and their associated getter operations.

JConsole View

See JmxBuilderReference for more detail on exporting attributes.

Controlling Operation Export

JmxBuilder lets you describe and export information about operations declared on the underlying bean to be exported as MBean. You can implicitly describe and export all operations (using the wildcard) or specify which operation to export.

Export with Operations with Wildcard "*"

You can use a wildcard character to export all operations declared on the underlying bean to exported. The snippet below exports all operations, however, no attributes or constructors will be defined nor exported into the MBeanServer.

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

JConsole View

You can see that JmxBuilder only exported operations on the MBean (including getter/setters). No attributes were described nor exported.

See JmxBuilderReference for more detail on exporting attributes.

Export Operations by List

You can target operations to export by specifying a comma-separated list of the methods on the underlying bean to export for management.

jmxBldr.export{
    bean(
        target: ctrl, name: "jmx.builder:type=Object3", 
        operations: ["start","stop", "makeRequest"]
    )
}

JConsole View

Notice that only the specified operations are described and export into the MBeanServer.

See JmxBuilderReference for more detail on exporting operations.

Handling Events

Using JmxBuilder, you can intercept listen and react to events emitted on the MBeanServer's event bus. Conversely, JmxBuilder lets you emit your own event on the bus to be consumed by registered listeners.

Attribute Change Events

One basic event that JmxBuilder allows you to listen for is "attribute changes". You can set easily set your listener when you setup the bean for export.

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 *****"
                    }
                }
            ]
        ]
    )
}

The closure specified by key "onChange:" will be invoked whenever the attribute "RequestLimit" on the MBean is updated via the setter associated with the attribute.

JConsole View

Closure Executed

Attribute "RequestLimit" updated to 22, causes the onChange event closure to be called.

See JmxBuilderReference for more detail on event handling.

Operation Call Events

Similary to attribute change events, JmxBuilder supports callback closures for operation invokation. You can easily set up a listener closure that gets executed whenever an MBean operation is invoked.

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

In the snippet above, the closure specified by key "onCall:" will be executed after each invokation of opeartion makeRequest on the MBean.

Closure Executed

See JmxBuilderReference for more detail on event handling.

What's Next

The JmxBuilder DSL is capable of much more. Please review the JmxBuilderReference section for a list of all of the capabilities of the tool.

Feedback

All feedbacks are welcome. If you find a bug, don't hesitate to report it.