Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<p><strong>JmxBuilder is a Groovy-based domain specific language for the Java Management Extension (JMX) API</strong>.  It uses the builder pattern (FactoryBuilder) to create an internal DSL that facilitates the exposure of POJO's and Groovy beans as management components via the MBean server.  JmxBuilder hides the complexity of creating and exporting management beans via the JMX API and provides a set of natural Groovy constructs to interact with the JMX infrastructure.</p>

<h1>Instantiating JmxBuilder</h1>

<p>To start using JmxBuilder, simply make sure the jar file is on your class path.  Then you can do the following in your code</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def jmx = new JmxBuilder()
</pre></td></tr></table>
<p><strong>That's it!</strong> You are now ready to use the JmxBuilder.</p>

<p><strong>NOTE:</strong></p>
<ul>
	<li>You can pass in an instance of <strong>your own MBeanServer</strong> to the builder (<strong>JmxBuilder(MBeanServer)</strong>)</li>
	<li>If no MBeanServer is specified, the builder instance will default to the underlying platform MBeanServer.</li>
</ul>

<p>Once you have an instance of JmxBuilder, you are now ready to invoke any of its builder nodes.</p>

<h1>JMX Connectors</h1>

<p>Remote connectivity is a crucial part of the JMX architecture.  JmxBuilder facilitates the creation of connector servers and connector clients with nimimal amount of coding.</p>

<h3>Connector Server</h3>

<p>JmxBuilder.connectoServer() supports the full Connector api syntax and will let you specify properties, override the URL, specify your own host, etc.</p>

<p><strong>Example - Connector Server (see correction below)</strong></p>

<p><em>NOTE: Sadly you are as likely to get something like the following when attempting to run the previous snippet of code (example is incomplete, see below):</em></p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
Caught: java.io.IOException: Cannot bind to URL [rmi://localhost:9000/jmxrmi]: javax.naming.ServiceUnavailableException [Root exception is java.rmi.ConnectException: Connection refused to host: localhost; nested exception is:
    java.net.ConnectException: Connection refused]
 
</pre></td></tr></table>
<p><em>This occurs on Mac and Linux (CentOS 5) with Groovy 1.6 installed. Perhaps there were assumptions made about the configuration of the /etc/hosts file?</em></p>

<p>NOTE: <em>The correct example is shown below.</em></p>

<p><strong>Connector Example (Corrected) - Connector Server</strong></p>

<p>The example above does not create the RMI registry.  So, in order to export, you have to first export the RMI object registry (make sure to import java.rmi.registry.LocateRegistry).</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
import java.rmi.registry.LocateRegistry
...

LocateRegistry.createRegistry(9000)
jmx.connectorServer(port: 9000).start()
</pre></td></tr></table>

<h3>Connector Client</h3>

<p>JmxBuilder.connectorClient() node lets you create JMX connector client object to connect to a JMX MBean Server.</p>

<p><strong>Syntax</strong></p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
jmx.connectorClient (
    protocol:"rmi",
    host:"...",
    port:1099,
    url:"...",
)
</pre></td></tr></table>
<p><strong>Example - Client Connector</strong><br />
Creating a connector client can be done just as easily.  With one line of code, you can create an instance of a JMX Connector Client as shown below.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def client = jmx.connectorClient(port: 9000)
client.connect()
</pre></td></tr></table>
<p>You can then access the MBeanServerConnection associated with the connector using:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
client.getMBeanServerConnection()
</pre></td></tr></table>

<h1>JmxBuilder MBean Export</h1>

<p>You can <strong>export a Java object or a Groovy object</strong> with minimal coding.  JmxBuilder will even find and <strong>export dynamic Groovy methods</strong> injected at runtime.</p>

<h4>Implicit vs Explicit Descriptors</h4>

<p>When using the builder, you can <strong>let JmxBuilder implicitly generate</strong> all of your MBean descriptor info.  This is useful when you want to write minimal code to quickly export your beans.  You can also explicitly declare all descriptor info for the bean.  This gives you total control on how you want to describe every piece of information that you want to export for the underlying bean.</p>

<h3>The JmxBuilder.export() Node</h3>

<p>The <strong>JmxBuilder.export() node provides a container</strong> where all management entities to be exported to the MBeanServer are placed.  You can place one or more bean() or timer() nodes as children of the export() node.  JmxBuilder will <strong>automatically batch export the entities described</strong> by the nodes to the MBean server for management (see example below).</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def beans = jmx.export {
    bean(new Foo())
    bean(new Bar())
    bean(new SomeBar())
}
</pre></td></tr></table>
<p>In the code snippet above, <strong>JmxBuilder.export() will export three management beans</strong> to the MBean server.</p>

<h3>JmxBuilder.export() Syntax</h3>

<p>JmxBuilder.export() node supports the <strong>registrationPolicy</strong> parameter to specify how JmxBuilder will behave to resolve bean name collision during MBean registration:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
jmx.export(policy:"replace|ignore|error")
or
jmx.export(regPolicy:"replace|ignore|error")
</pre></td></tr></table>
<p><strong>replace</strong> - JmxBuilder.export() will replance any bean already registered with the MBean during export.<br />
<strong>ignore</strong> - The bean being exported will be ignored if the same bean is already registered.<br />
<strong>error</strong> - JmxBuilder.export() throws an error upon bean name collision during registration.</p>

<h3>Integration with GroovyMBean Class</h3>

<p>When you export an MBean to the MBeanServer, <strong>JmxBuilder will return an instance of GroovyMBean</strong> representing the management bean that have been exported by the builder.  Nodes such as <strong>bean()</strong> and <strong>timer()</strong> will return an instances of GroovyMBean when they are invoked.  The <strong>export()</strong> node returns an <strong>array of all of GroovyMBean[]</strong> representing all managed objects exported to the MBean server.</p>

<h3>MBean Registration with JmxBuilder.bean()</h3>

<p>This portion of this reference uses class <strong>RequestController</strong> to illustrate how to use JmxBuilder to export runtime management beans.  The class is for illustration purpose and can be a POJO or a Groovy bean.</p>
<ul>
	<li>RequestController 
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
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) { ... }
    public void makeRequest() { ... }
}
</pre></td></tr></table></li>
</ul>

<h4>Implicit Export</h4>

<p>As mentioned earlier, you can use JmxBuilder's flexible syntax to export any POJO/POGO with no descriptor.  The builder can automatically describe all aspects of the management beans using implicit defaults.  These default values can easily be overridden as we'll see in this in the next section.</p>

<p>The simplest way to export a POJO or POGO is listed below.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
jmx.export {
    bean(new RequestController(resource:"Hello World"))
}
</pre></td></tr></table>
<p><strong>What this does</strong>:</p>
<ul>
	<li>First, the <strong>JmxBuilder.export() node will export</strong> an MBean to the MBeanServer representing <strong>the declared POJO</strong> instance.</li>
	<li>The builder will <strong>generate a default ObjectName</strong> for the MBean and all other MBean descriptor information.</li>
	<li><strong>JmxBuilder will automatically export</strong> all declared <strong>attributes</strong> (MBean getter/setters), <strong>constructors</strong>, and <strong>operations</strong> on the instance.</li>
	<li>The exported <strong>attributes</strong> will have <strong>read-only</strong> visibility.</li>
</ul>

<p>Remember, <strong>JmxBuilder.export() returns an array of GroovyMBean[] objects</strong> for all exported instances.  So, once you call JmxBuilder.export(), <strong>you have immediate access to the underlying MBean proxy</strong> (via GroovyMBean).</p>

<h5>JConsole view of Exported Bean</h5>

<h3>JmxBuilder.bean() Syntax</h3>

<p>The JmxBuilder.bean() node supports an extensive set of descriptors to describe your bean for management.  The JMX MBeanServer uses these descriptors to expose meta data about the bean exposed for management.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
jmx.export {
    bean(
        target:bean instance,
        name:ObjectName,
        desc:"...",
        attributes:"*",
        attributes:[]
        attributes:[ "AttrubuteName1","AttributeName2",...,"AttributeName_n" ]
        attributes:[
            "AttributeName":"*",
            "AttributeName":[
                desc:"...",
                defaultValue:value,
                writable:true|false,
                editable:true|false,
                onChange:{event-> // event handler}
            ]
        ],

constructors:"*",
        constructors:[
            "Constructor Name":[],
            "Constructor Name":[ "ParamType1","ParamType2,...,ParamType_n" ],
            "Constructor Name":[
                desc:"...",
                params:[
                    "ParamType1":"*",
                    "ParamType2":[desc:"...", name:"..."],...,
                    "ParamType_n":[desc:"...", name:"..."]
                ]
            ]
        ],

operations:"*",
        operations:[ "OperationName1", "OperationName2",...,"OperationNameN" ],
        operations:[
            "OperationName1":"*",
            "OperationName2":[ "type1","type2,"type3" ]
            "OperationName3":[
                desc:"...",
                params:[
                    "ParamType1":"*"
                    "ParamType2":[desc:"...", name:"..."],...,
                    "ParamType_n":[desc:"...", name:"..."]
                ],
                onInvoked:{event-> JmxBuilder.send(event:"", to:"")}
            ]
        ],

listeners:[
            "ListenerName1":[event: "...", from:ObjectName, call:{event->}],
            "ListenerName2":[event: "...", from:ObjectName, call:&amp;methodPointer]
        ]

)
}
</pre></td></tr></table>
<p>Instead of describing the entire node, the following section explore each attribute separately.</p>

<h3>Bean() Node - Specifying MBean ObjectName</h3>

<p>Using the bean() node descriptors, you can specify your own MBean ObjectName.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def ctrl = new RequestController(resource:"Hello World")
def beans = jmx.export {
    bean(target:ctrl, name:"jmx.tutorial:type=Object")
}
</pre></td></tr></table>
<p>The ObjectName can be specified as a String or an instance of the ObjectName.</p>

<h2>Bean() Node - Attribute Export</h2>

<p>JMX attributes are the setters and getters on the underlying bean.  The JmxBuilder.bean() node provides several ways to flexibly describe and export MBean attributes.  You can combine them however you want to achieve any level of attribute visibility.  Let's take a look.</p>

<h4>Export All Attributes with Wildcard &quot;*&quot;</h4>

<p>The following code snippet <strong>will describe and export all attributes</strong> on the bean as read-only. <strong>JmxBuilder will use default values</strong> to describe the attributes that exported for management.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def objName = new ObjectName("jmx.tutorial:type=Object")
def beans = jmx.export {
    bean(target: new RequestController(),
    name: objName,
    attributes: "*")
}
</pre></td></tr></table>

<h4>Export Attribute List</h4>

<p>JmxBuilder will let you specify a list of attributes to export.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def objName = new ObjectName("jmx.tutorial:type=Object")
def beans = jmx.export {
    bean(
        target: new RequestController(),
        name: objName,
        attributes: [ "Resource", "RequestCount" ]
    )
}
</pre></td></tr></table>
<p>In the snippet above, <strong>only the &quot;Resource&quot; and &quot;RequestCount&quot; attributes will be exported</strong>. Again, since no descriptors are provided, <strong>JmxBuilder will use sensible defaults</strong> to describe the exported attributes.</p>

<h4>Export Attribute with Explicit Descriptors</h4>

<p>One of the strengths of JmxBuilder is its flexibility in describing MBean.  With the builder you can describe all aspects of the MBeans attribute that you want to export to the MBeanServer (see syntax above).</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def objName = new ObjectName("jmx.tutorial:type=Object")
def beans = jmx.export {
    bean(
        target: new RequestController(),
        name: objName,
        attributes: [
            "Resource":[desc: "The resource to request.", readable: true, writable: true, defaultValue:"Hello"],
            "RequestCount":"*"
        ]
    )
}
</pre></td></tr></table>
<p>In the snippet above, attribute <strong>&quot;Resource&quot; is fully-described</strong> using all supported descriptors (i.e. desc, readable, writable, defaultValue) for a JMX attribute. However, we use the wildcard to describe attribute <strong>RequestCount</strong> and it will be exported and described using defaults.</p>

<h3>Bean() Node - Constructor Export</h3>

<p>JmxBuilder <strong>supports the explicit description and export of constructors</strong> defined in the underlying bean.  There are several options available when exporting constructors.  You can combine them however you want to achieve the desired level of manageability.</p>

<h4>Export all Constructors with &quot;*&quot;</h4>

<p>You can use the builder's special `&quot;<strong>&quot;` notation to *export all constructors</strong> declared on the underlying bean.  The builder will use default values to describe the MBean constructors.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def objName = new ObjectName("jmx.tutorial:type=Object")
def beans = jmx.export {
    bean(
        target: new RequestController(),
        name: objName,
        constructors: "*"
    )
}
</pre></td></tr></table>

<h4>Export Constructors using Parameter Descriptor</h4>

<p>JmxBuilder lets you <strong>target specific constructor</strong> to export by <strong>describing the parameter signature</strong>.  This is useful when you have several constructors with different parameter signature and you want to export specific constructors.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def objName = new ObjectName("jmx.tutorial:type=Object")
def beans = jmx.export {
    bean(
        target: new RequestController(),
        name: objName,
        constructors:[
            "RequestController":[ "Object" ]
        ]
    )
}
</pre></td></tr></table>
<p>Here, JmxBuilder will <strong>export a constructor that takes one parameter of type &quot;Object&quot;</strong>.  Again, JmxBuilder will use default values to fill in the description of the constructor and the parameters.</p>

<h4>Export Constructor with Explicit Descriptors</h4>

<p>JmxBuilder allows you to <strong>fully-describe</strong> the constructor that you want to target for export (see syntax above).</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def objName = new ObjectName("jmx.tutorial:type=Object")
def beans = jmx.export {
    bean(target: new RequestController(), name: objName,
        constructors:[
            "RequestController":[
                desc:"Constructor takes param",
                params:[ "Object" : [name:"Resource", desc:"Resource for controller"] ]
            ]
        ]
    )
}
</pre></td></tr></table>
<p>In the code above, JmxBuilder will target a constructor that takes one parameter for export to the MBeanServer.  Notice how the constructor can be fully-described using all optional descriptor keys including parameter descriptors.</p>

<h3>Bean() Node - Operation Export</h3>

<p>Similar to constructors, JmxBuilder supports the description and export of MBean operations using a flexible notation (see above for syntax).  You can combine these notations however you want to achieve the level of operation manageability desired.</p>

<h4>Export All Operations with &quot;*&quot;</h4>

<p>You can use the builder's special `&quot;<strong>&quot;` notation to *export all operations</strong> defined on the bean to be exposed for management.  The builder will use default descriptor values for the operations being exported.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def objName = new ObjectName("jmx.tutorial:type=Object")
def beans = jmx.export {
    bean(
        target: new RequestController(),
        name: objName,
        operations: "*"
    )
}
</pre></td></tr></table>
<p>In this snippet, JmxBuilder will <strong>export all bean operations</strong> and will use default values to describe them in the MBeanServer.</p>

<h4>Export Operation List</h4>

<p>JmxBuilder has a shorthand notation that lets you quickly target operations to be exported by providing a list of methods to export.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def objName = new ObjectName("jmx.tutorial:type=Object")
def beans = jmx.export {
    bean(
        target: new RequestController(),
        name: objName,
        operations: [ "start", "stop" ]
    )
}
</pre></td></tr></table>
<p>In the snippet above, the <strong>builder will only export methods start() and stop()</strong>.  All other methods will be ignored.  JmxBuilder will use default descriptor values to describe the operations being exported.</p>

<h4>Export Operations by Signature</h4>

<p>Using JmxBuilder, you can target methods to export for management using the methods's parameter signature.  This is useful when you want to distinguish methods with the same name that you want to export (i.e. stop() instead of stop(boolean)).</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def objName = new ObjectName("jmx.tutorial:type=Object")
def beans = jmx.export {
    bean(
        target: new RequestController(),
        name: objName,
        operations: [
            "makeRequest":[ "String" ]
        ]
    )
}
</pre></td></tr></table>
<p>In the snipet above, JmxBuilder would <strong>select method makeRequest(String)</strong> to be exported instead of the other version makeRequest() which takes no parameter.  In this shorthand context, the signature is specified as a list of type (i.e. &quot;String&quot;).</p>

<h4>Export Operations with Explicit Descriptors</h4>

<p>JmxBuilder supports detailed descriptors for bean operations.  You can supply deep descriptor info about any operation on your bean including a name, description, method parameters, parameter type, and parameter description.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def objName = new ObjectName("jmx.tutorial:type=Object")
def beans = jmx.export {
    bean(target: new RequestController(), name: objName,
        operations: [
            "start": [desc:"Starts request controller"],
            "stop":[desc:"Stops the request controller"],
            "setResource":[params:[ "Object" ]],
            "makeRequest": [
                desc:"Executes the request.",
                params: [
                    "String":[name:"Resource",desc:"The resource to request"]
                ]
            ]

]
    )
}
</pre></td></tr></table>
<p>The snippet above shows all of the ways JmxBuilder allows you to describe an operation targeted for management:</p>
<ul>
	<li>Operations <strong>start() and stop()</strong> are described by the &quot;desc&quot; key (this is enough since there are no params).</li>
	<li>In operation <strong>setResource()</strong> uses of a shorthand version of <strong>params:</strong> to describe the parameters for the method.</li>
	<li><strong>makeRequest()</strong> uses the the extended descriptor syntax to describe all aspects of the operation.</li>
</ul>

<h3>Embedding Descriptor</h3>

<p>JmxBuilder supports the ability to <strong>embed descriptors directly in your Groovy class</strong>.  So, instead of wrapping your description around the declared object (as we've seen here), you can ebmed your JMX descriptors directly in your class.</p>
<ul>
	<li>RequestControllerGroovy *
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
public class RequestController {
    // attributes
    boolean started
    int requestCount
    int resourceCount
    int requestLimit
    Map resources

// operations
    void start(){ ... }
    void stop(){ ... }
    void putResource(String name, Object resource){ ... }
    void makeRequest(String res) { ... }
    void makeRequest() { ... }

static descriptor = [
        name: "jmx.builder:type=EmbeddedObject",
        operations: [ "start", "stop", "putResource" ]
        attributes:"*"
    ]
}

....
// export
jmx.export(
    bean(new RequestControllerGroovy())
)
</pre></td></tr></table></li>
</ul>

<p>There are two things going on in the code above:</p>
<ol>
	<li>Groovy class RequestControllerGroovy is defined and includes a <strong>static descriptor</strong> member.  That member is used to declare a JmxBuilder descriptor to describe member of the class targeted for JMX export.</li>
	<li>The second part of the code shows how to use JmxBuilder to export that class for management.</li>
</ol>

<h3>Timer Export</h3>

<p>JMX standards mandate that the implementation of the API makes available a timer service.  Since JMX is a component-based architecture, timers provide an excellent signaling mechanism to communicate to registered listener components in the MBeanServer.  JmxBuilder supports the creation and export of timers using the same easy syntax we've seen so far.</p>

<h3>Timer Node Syntax</h3>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
timer(
    name:ObjectName,
    event:"...",
    message:"...",
    data:dataValue
    startDate:"now"|dateValue
    period:"99d"|"99h"|"99m"|"99s"|99
    occurences:long
)
</pre></td></tr></table>
<p>The timer() node supports several attributes:</p>
<ul>
	<li><strong>name:</strong> - <a class="confluence-link unresolved" data-content-title="Required" data-linked-resource-default-alias="Required" href="#">Required</a> The qualified JMX ObjectName instance (or String) for the timer.</li>
	<li><strong>event:</strong> - The JMX event type string that will be broadcast with every timing signal (default <strong>&quot;jmx.builder.event&quot;</strong>).</li>
	<li><strong>message:</strong> - An optional string value that can be sent to listneners.</li>
	<li><strong>data:</strong> - An optional object that can be sent to listeners of timing signal.</li>
	<li><strong>startDate:</strong> - When to start timer.  Set of valid values [ &quot;now&quot;, date object ].  Default is &quot;now&quot;</li>
	<li><strong>period:</strong> - A timer's period expressed as either a number of millisecond or time unit (day, hour, minute, second).  See description below.</li>
	<li><strong>occurences:</strong> - A number indicating the number of time to repeat timer.  Default is forever.</li>
</ul>

<h4>Exporting a Timer</h4>

<p>An <strong>alternative way of exporting timers</strong> is within the JmxBuilder.export() node.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def beans = jmx.export {
    timer(name: "jmx.builder:type=Timer1", event: "event.signal", period: "1s")
    timer(name: "jmx.builder:type=Timer2", event: "event.log", period: "1s")
}
beans[0].start()
beans[1].start()
</pre></td></tr></table>

<h4>Timer Period</h4>

<p>The <strong>timer() node supports a flexible notation</strong> for specifying the <strong>timer period values</strong>.  You can specify the time in second, minutes, hour, and day.  The default is millisecond.</p>
<ul>
	<li>timer(<strong>period: 100</strong>)  = 100 millisecond</li>
	<li>timer(<strong>period: &quot;1s&quot;</strong>) = 1 second</li>
	<li>timer(<strong>period: &quot;1m&quot;</strong>) = 1 minute</li>
	<li>timer(<strong>period: &quot;1h&quot;</strong>) = 1 hour</li>
	<li>timer(<strong>period: &quot;1d&quot;</strong>) = 1 day</li>
</ul>

<p>The node will automatically translate.</p>

<h3>JmxBuilder and Events</h3>

<p>An integral part of <strong>JMX</strong> is its <strong>event model</strong>.  Registered management beans can <strong>communicate with each other by broadcasting events</strong> on the MBeanServer's event bus. <strong>JmxBuilder provides several ways to easily listen and react to events</strong> broadcasted on the MBeanServer's event bus.  Developers can <strong>capture any event on the bus or throw their own</strong> to be consumed by other components registered on the MBeanServer.</p>

<h4>Event Handling Closures</h4>

<p>JmxBuilder leverages Groovy's use of closures to provide simple, yet elegant, mean of reacting to JMX events.    JmxBuilder supports two closure signatures:</p>

<h5>Parameterless</h5>

<h5>With Event Parameter</h5>

<h4>Handling Attribute onChange Event</h4>

<p>When describing attributes (see bean() node section above), you can <strong>provide a closure (or method pointer) for callback to be executed when the value of the attribute is updated</strong> on the exported MBean.  This gives developers an opportunity to listen to and react to state changes on the MBean.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
jmx.export {
    bean(
        target: new RequestController(), name: "jmx.tutorial:type=Object",
        attributes: [
            "Resource":[
                readable: true, writable: true,
                onChange:{e ->
                    println e.oldValue
                    println e.newValue
                }
            ]
        ]
    )
}
</pre></td></tr></table>
<p>The sample snippet above shows how to <strong>specify an &quot;onChange&quot; callback closure</strong> when describing MBean attributes.  In this sample code, whenever attribute &quot;Resource&quot; is updated via the exported MBean, the <strong>onChange event will be executed</strong>.</p>

<h4>Attribute onChange Event Object</h4>

<p>When handling the attribute onChange event, the handler closure will receive an event object with the following info:</p>
<ul>
	<li>event.<strong>oldValue</strong> - the previous attribute value before the change event.</li>
	<li>event.<strong>newValue</strong> - the new value of the attribute after the change.</li>
	<li>event.<strong>attribute</strong> - the name of the attribute on which the event occured.</li>
	<li>event.<strong>attributeType</strong> - the data type of the attribute that causes the event.</li>
	<li>event.<strong>sequenceNumber</strong> - a numeric value representing the sequence number of event.</li>
	<li>event.<strong>timeStamp</strong> - a time stamp for the event occurence.</li>
</ul>

<h4>Handling Operation onCall Event</h4>

<p>Similar to mbean attributes, JmxBuilder affords developers the <strong>ability to listen for operation invokation</strong> on an MBean registered in the MBeaServer.  JmxBuilder accepts a <strong>callback closure that will be executed after the MBean method has invoked</strong>.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
class EventHandler {
    void handleStart(e){
        println e
    }
}

def handler = new EventHandler()

def beans = jmx.export {
    bean(target: new RequestController(), name: "jmx.tutorial:type=Object",
        operations: [
            "start": [
                desc:"Starts request controller"
                onCall:handler.&amp;handleStart
            ]
        ]
    )
}
</pre></td></tr></table>
<p>The snippet above <strong>shows how to declare an &quot;onCall&quot; closure to be used as listener</strong> when operation &quot;start()&quot; is invoked on the MBean.  This sample <strong>uses the method pointer syntax</strong> to illustrate the versatility of JmxBuilder.</p>

<h4>Operation onCall Event Object</h4>

<p>When handling the operation onCall event, the callback closure will receive an event object with the following info:</p>
<ul>
	<li>event.<strong>event</strong> - the event type string that was broadcasted.</li>
	<li>event.<strong>source</strong> - The object on which the method was invoked.</li>
	<li>event.<strong>data</strong> - the data type of the attribute that causes the event.</li>
	<li>event.<strong>sequenceNumber</strong> - a numeric value representing the sequence number of event.</li>
	<li>event.<strong>timeStamp</strong> - a time stamp for the event occurence.</li>
</ul>

<h3>Listener MBean</h3>

<p>When you export an MBean with the bean() node, you can define events the MBean can listen and react to. The bean() node provides a &quot;listeners:&quot; attribute that lets you define event listeners that your bean can react to.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def beans = jmx.export {
    timer(name: "jmx.builder:type=Timer", event: "heartbeat", period: "1s").start()
    bean(target: new RequestController(), name: "jmx.tutorial:type=Object",
        operations: "*",
        listeners: [
            heartbeat:[
                from:"jmx.builder:type=Timer",
                call:{e ->
                    println e
                }
            ]
        ]
    )
}
</pre></td></tr></table>
<p>In the sample above, we see the <strong>syntax for adding listeners to an exported MBean</strong>.</p>
<ul>
	<li>Fist, a <strong>timer is exported</strong> and started.</li>
	<li>Then an <strong>MBean is declared that will listen to the timer</strong> event and do something meaningful.</li>
	<li>The <strong>&quot;heartbeat:&quot;</strong> name is arbitrary and has no correlation to the timer declared above.</li>
	<li>The <strong>source</strong> of the event <strong>is specified using the &quot;from:&quot; attribute</strong>.</li>
</ul>

<p>You can also specify an <strong>event type</strong> you are interested in receiving from a broadcaster (since a broadcaster can be emitting multiple events).</p>

<h4>Listening to JMX Events</h4>

<p>In some cases, you will want to create stand-alone event listensers (not attached to exported MBeans).  JmxBuilder provides the Listener() node to let you create JMX listeners that can listen to MBeanServer events.  This is useful when creating JMX client applications to monitor/manage JMX agents on remote JMX MBeanServers.</p>

<h4>Listener Node Syntax</h4>

<p>Here is an example of JmxBuilder's listener node:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
jmx.timer(name: "jmx.builder:type=Timer", period: "1s").start()

jmx.listener(
    from: "jmx.builder:type=Timer",
    call: {e ->
        println "beep..."
    }
)
</pre></td></tr></table>
<p>This example shows how you can use a stand alone listener (outside of an MBean export).  Here, we <strong>export a timer with a 1 second</strong> resolution.  Then, we specify a listener to that timer that will print &quot;beep&quot; every second.</p>

<h3>Emitting JMX Events</h3>

<p>JmxBuilder provides the <strong>tools needed to broadcast your own events</strong> on the MBeanServer's event bus.  There are no restrictions on the event type you can broadcast.  You simply <strong>declare your emitter</strong> and the event type that you want to send, then <strong>broadcast your event</strong> at any time.  Any registered component in the MBeanServer can register themselves to listen to your events.</p>

<h4>Emitter Syntax</h4>

<h4>Declare the Emitter</h4>

<p>As with other nodes in the builder, <strong>you can override all keys in the emitter() node</strong>.  You can specify the <strong>ObjectName</strong> and the <strong>event type</strong>.</p>

<h4>Broadcast Event</h4>

<p>Once you have declared your emitter, you can broadcast your event.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
emitter.send()
</pre></td></tr></table>
<p>The sample above shows the <strong>emitter sending an event</strong>, once it has been declared.  Any JMX component registered in the MBeanServer can register to receive message from this emitter.</p>

<h4>Sending Event Objects</h4>

<p>You can optionally pass data to the receiver when you send the message.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
...
emitter.send("Hello!")
...
</pre></td></tr></table>
<p>If you use an <strong>event listener closure (see above) that accpets a parameter</strong>, you can access that value.</p>