Hosted by:
SourceForge
Get Firefox!

JMX Control
JMX Control
Controlling the Java Service Wrapper using JMX

The Java Service Wrapper provides a pair of JMX MBean interfaces which make it possible to control the Wrapper using a JMX interface. This section will describe how to configure your JMX enabled application so that the MBeans provided with the Java Service Wrapper are available.

JConsole

Sun's JDK 5.0 includes the Java Monitoring and Management Console (JConsole) tool. See the above link for details, but JConsole makes it easy to connect to properly configured JVMs and monitor and manage their various functions.

For security reasons, the ability to remotely monitor a JVM is not enabled by default. To enable this functionality it is necessary to define the com.sun.management.jmxremote system property when launching the JVM. This can be done using the wrapper by specifying a JVM parameter as follows. See the wrapper.java.additional.<n> property for details of its usage:

wrapper.java.additional.1=-Dcom.sun.management.jmxremote

The Wrapper currently provides 2 MBean interfaces. The primary MBean, org.tanukisoftware.wrapper.jmx.WrapperManagerMBean, provides basic information about the Wrapper and JVM as well as the ability to stop and restart the JVM as well as trigger a full thread dump. The registration of this MBean is controlled by setting the org.tanukisoftware.wrapper.WrapperManager.mbean system property. It is enabled by default.

The second MBean, org.tanukisoftware.wrapper.jmx.WrapperManagerTestingMBean, makes it possible to trigger various failure states for testing and should not be made enabled outside of a testing environment. The registration of this MBean is controlled by setting the org.tanukisoftware.wrapper.WrapperManager.mbean.testing system property. It is disabled by default.

wrapper.java.additional.1=-Dcom.sun.management.jmxremote
wrapper.java.additional.2=-Dorg.tanukisoftware.wrapper.WrapperManager.mbean=true
wrapper.java.additional.3=-Dorg.tanukisoftware.wrapper.WrapperManager.mbean.testing=false

The registered Wrapper MBeans will show up on the MBean tab of the JConsole interface under the org.tanukisoftware.wrapper package.

JBoss

Registering the Java Service Wrapper's MBean interfaces with JBoss is surprising simple. This assumes that you have already gotten JBoss integrated with the Java Service Wrapper. See the Integration section, in particular the example using JBoss. This explanation assumes that you have installed all of the Wrapper files in the locations described in the JBoss integration example. Particularly the wrapper.jar file is assumed to be located in the ${jboss.home}/lib directory.

JBoss allows you to register as an MBean, any Object which implements an interface whose name is the same as the class, appended by "MBean". The Wrapper provides two such classes in the org.tanukisoftware.wrapper.jmx package. WrapperManager and WrapperManagerTesting. The first provides several functions to restart and stop the JVM as well as providing other information about the Java Service Wrapper. The second class exposes a few methods which can be useful in the testing cycle. They are broken out in case you wish to not include them in a final product release. See the javadocs for more details.

To register both of the above MBeans, create an XML file named java-service-wrapper-service.xml in the ${jboss.home}/server/default/deploy directory. The file should contain the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE server>
<server>
    <classpath archives="wrapper.jar" codebase="../../lib"/>
    
    <mbean code="org.tanukisoftware.wrapper.jmx.WrapperManager"
           name="JavaServiceWrapper:service=WrapperManager"/>
    
    <mbean code="org.tanukisoftware.wrapper.jmx.WrapperManagerTesting"
           name="JavaServiceWrapper:service=WrapperManagerTesting"/>
</server>

Notice that the location of the wrapper.jar jar file is relative to the location of the XML file.

Upon saving the file, JBoss should detect it and register your new MBeans almost immediately. No need to restart JBoss. Pretty Cool.

Now, to actually use the new MBeans, simply point your browser to JBoss's JMX interface at: http://localhost:8080/jmx-console/ You should notice a JavaServiceWrapper Agent with two MBeans, WrapperManager and WrapperManagerTesting. Selecting either beans will present you with a set of attributes and actions provided by the MBean.

MX4J

To do. (This section is incomplete and just a jumble of my notes at this point. Feel free to send in any suggestions for this section)

MX4J

Sun JMX Reference Implementation

To do. (This section is incomplete and just a jumble of my notes at this point. Feel free to send in any suggestions for this section)

Sun's reference implementation is just that, a reference implementation. There are not a fixed set of steps that you can follow to register the the Wrapper's MBeans. Each application tends to have created their own custom way of registering such beans.

Although many applications have defined their own syntax, Sun has defined MLET tags, short for Management Applet, as a means for defining MBeans. Their syntax is described in the javadocs for the javax.management.loading.MLet class. The following MLET tags can be used to register the MBeans provided with the Wrapper. Notice that they are not really XML.

<MLET
    CODE = org.tanukisoftware.wrapper.jmx.WrapperManager
    ARCHIVE = "../lib/wrapper.jar"
    NAME = JavaServiceWrapper:service=WrapperManager>
<MLET
    CODE = org.tanukisoftware.wrapper.jmx.WrapperManagerTesting
    ARCHIVE = "../lib/wrapper.jar"
    NAME = JavaServiceWrapper:service=WrapperManagerTesting>

More information is available on Sun's Java Managagement Extensions (JMX) Home Page.

by Leif Mortenson

last modified: