Index

Controlling the Java Service Wrapper using JMX

The Java Service Wrapper provides a pair of Java Management Extensions (JMX) MBean interfaces (J2SE 5.0 JMX, JavaSE6 JMX) 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 tool "JConsole" (J2SE 5.0 JConsole) (JavaSE6 JConsole). See the above link for details, but JConsole makes it easy to connect to properly configured JVMs, 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 (J2SE 5.0) (JavaSE6) system property when launching the JVM. This can be done using the Wrapper by specifying a JVM parameter with the wrapper.java.additional.<n> property as follows.

Example: (a JVM parameter)
wrapper.java.additional.1=-Dcom.sun.management.jmxremote

The Java Service Wrapper currently provides 2 MBean interfaces.

The primary MBean interface, 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 interface, 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.

Example: (a JVM parameter)
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 Method 1 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 Java Service Wrapper provides two such classes WrapperManager and WrapperManagerTesting in the org.tanukisoftware.wrapper.jmx package.

The first class, WrapperManager, provides several functions to restart and stop the JVM as well as providing other information about the Java Service Wrapper. The second class, WrapperManagerTesting, 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:

Example: (java-service-wrapper-service.xml)
<?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 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 MBeans will present you with a set of attributes and actions provided by the MBean.

JBoss 6.*

Please make sure you have done all steps as described above.

JBoss with version 6 is utilizing internally a MBeanServer Factory based on org.jboss.system.server.jmx.MBeanServerBuilderImpl, however this one is incompatible to the default JVM MBeanServerBuilder (javax.management.MBeanServerBuilder). Usually this wouldn't be a problem as JBoss when running stand-alone it sets the Platform MBeanService and all subsequent MBeans will be created from its MBeanServerBuilder. However when the Wrapper starts, it will register its MBeans and hence the JVM doesn't have a MBeanServer at this time yet, it will create a MBeanServer using the JVM's default MBeanServer. When JBoss starts, it tries to register its MBeans to the MBeanServer, however because of the incompatibility with the default JVM's MBeanServer, JBoss will fail to register any MBean.

In order to use the MBeans of the Wrapper and make it possible for JBoss to register its MBeans, the JVM needs to get instructed to not use the default Factory but the one used by JBoss, which is in fact just an extension of the default. In order to do so you need to set the following properties:

wrapper.java.classpath.N=%JBOSS_HOME%/lib/jboss-logmanager.jar

wrapper.java.additional.N=-Djboss.platform.mbeanserver
wrapper.java.additional.N=-Djavax.management.builder.initial=org.jboss.system.server.jmx.MBeanServerBuilderImpl
wrapper.java.additional.N=-Djava.util.logging.manager=org.jboss.logmanager.LogManager
wrapper.java.additional.N=-Dorg.jboss.logging.Logger.pluginClass=org.jboss.logging.logmanager.LoggerPluginImpl

Please make sure N is a number, which hasn't been assigned.

In detail the above properties mean, that JBoss should use the platform MBeanServer to register MBeans (-Djboss.platform.mbeanserver). The JVM should use org.jboss.system.server.jmx.MBeanServerBuilderImpl as MBeanServer Factory (-Djavax.management.builder.initial=org.jboss.system.server.jmx.MBeanServerBuilderImpl). Hence to that, the Log Manager of the JVM and JBoss have to be redefined. As this Log Manager is not on the classpath, it also needs to get added there.

After this steps have been done, the Wrapper should be able to run JBoss 6.* without any problems and able to register it's MBeans side-by-side with JBoss.

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 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, Oracle 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 (J2SE 1.4) (J2SE 5.0) (JavaSE6) (JavaSE7) class. The following MLET tags can be used to register the MBeans provided with the Wrapper. Notice that they are not really XML.

MLET tags:
<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 Oracle's "Java Management Extensions (JMX) Home Page".

(Java Management Extensions(JMX) Documentation: J2SE 5.0 / JavaSE6)