Exposing a POJO as a JMX MBean easily with Spring
JMX is a great way to check or change state variables or invoke a method in a (remote) running application via a management GUI such as JConsole. And Spring makes it trivial to expose any POJO as a JMX MBean with only little configuration in a few minutes. The Spring JMX documentation is very good, however there are few points that I struggled with for a while and would therefore like to record here the right solutions.
I needed to monitor a command-line java application using Spring 2.5 on IBM JVM 1.4 1.5 running on a server with a jconsole on Sun JVM 1.6 as the JMX client on my PC.
All the XML snippets are from a Spring application-context.xml. If you haven't used Spring before, read a tutorial on its configuration and dependency injection.
First you declare an instance of the POJO class - the myMBean (for other reasons I've an old-fashioned singleton and use JobPerformanceStats.instance() to access the bean). Next you declare an MBeanExporter with lazy-init="false" and tell it about your bean. (There are also other ways to do it, including auto-discovery.) The bean will be then visible under its key, i.e. "bean:name=MyMBeanName", which JConsole displays as "MyMBeanName".
Notice that the MBeanExporter only works under JVM 1.5+ because it uses the new java.lang.management package. Under 1.4 Spring would fail with
If you are not running in a container that already provides an MBean server, which is my case here, you must tell Spring to start one:
However this protocol isn't supported out of the box and you must include jmxremote_optional.jar, a part of OpenDMK, on the classpath of both the MBean application and the jconsole client to avoid the exception
However there are also some catches you must avoid:
Replace STUBPORT and REGISTRYPORT with suitable numbers and tunnel those two. Notice that the REGISTRYPORT number is same in the connector's serviceUrl and in the RMI registry's port attribute.
WARNING: The configuration above actually doesn't prevent direct access from a remote application. To really force the RMI registry to only listen for connection from the local host we would likely need to set - under Sun JVM without Spring - the system property com.sun.management.jmxremote. Additionally, to force the registry to use the IP 120.0.0.1, we'd need to set java.rmi.server.hostname=localhost (applies to Spring too). See this discussion about forcing local access. I'm not sure how to achieve the same result with Spring while still preserving the ability to specify both the RMI ports. Check also the JavaDoc for Spring's RmiServiceExporter .
Related posts and docs:
Regarding the connection URL, if you have a a connector with the serviceUrl of "service:jmx:rmi://myhost:9999/jndi/rmi://localhost:10099/myconnector" then, from a client, you can use either service:jmx:rmi://myhost:9999/jndi/rmi://your.server.com:10099/myconnector or simply service:jmx:rmi:///jndi/rmi://your.server.com:10099/myconnector because, according to the JMX 1.2 Remote API specification (page 90):
Notice that the IBM JConsole is a bit different, for instance it's missing the Local tab, which is replaced by specifying the command-line option connection=localhost (search the SDK guide for "JConsole monitoring tool Local tab").
You can make it available to JConsole and other JMX agents as follows (though there must be an easier way):
Update: There indeed seems to be a better way of exposing the platform MBeans directly by replacing the Spring's MBeanServerFactoryBean with java.lang.management.ManagementFactory using its factory-method getPlatformMBeanServer. Of course this requires JVM 1.5+.
I needed to monitor a command-line java application using Spring 2.5 on IBM JVM 1.4 1.5 running on a server with a jconsole on Sun JVM 1.6 as the JMX client on my PC.
All the XML snippets are from a Spring application-context.xml. If you haven't used Spring before, read a tutorial on its configuration and dependency injection.
Turning a POJO into an MBean
JMX makes it possible to expose getters, setters and operations taking primitive or complex data types as parameters (though types other then few special ones require the client to have the classes). You tell Spring to expose a POJO as an MBean as follows:
<bean id="myMBean"
class="my.package.JobPerformanceStats"
factory-method="instance" />
<bean class="org.springframework.jmx.export.MBeanExporter" lazy-init="false">
<property name="beans">
<map>
<entry key="bean:name=MyMBeanName" value-ref="myMBean"/>
</map>
</property>
</bean>
First you declare an instance of the POJO class - the myMBean (for other reasons I've an old-fashioned singleton and use JobPerformanceStats.instance() to access the bean). Next you declare an MBeanExporter with lazy-init="false" and tell it about your bean. (There are also other ways to do it, including auto-discovery.) The bean will be then visible under its key, i.e. "bean:name=MyMBeanName", which JConsole displays as "MyMBeanName".
Notice that the MBeanExporter only works under JVM 1.5+ because it uses the new java.lang.management package. Under 1.4 Spring would fail with
By default it will expose all public methods and attributes. You can change that in various ways, for example with the help of an interface.java.lang.NoClassDefFoundError: javax/management/MBeanServerFactory at org.springframework.jmx.support.MBeanServerFactoryBean.createMBeanServer
If you are not running in a container that already provides an MBean server, which is my case here, you must tell Spring to start one:
<bean class="org.springframework.jmx.support.MBeanServerFactoryBean"/>
Enabling remote access
To make the MBean accessible from another machine, you must expose it to the world by declaring a ConnectorServerFactoryBean configured with an appropriate communication mechanism.Remote access over JMXMP
By default the ConnectorServerFactoryBean exposes MBeans over JMXMP with the address service:jmx:jmxmp://localhost:9875 :
<bean class="org.springframework.jmx.support.ConnectorServerFactoryBean" />
However this protocol isn't supported out of the box and you must include jmxremote_optional.jar, a part of OpenDMK, on the classpath of both the MBean application and the jconsole client to avoid the exception
org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'org.springframework.jmx.support.ConnectorServerFactoryBean#0' defined in class path resource [application-context.xml]: Invocation of init method failed; nested exception is java.net.MalformedURLException: Unsupported protocol: jmxmp
Remote access over RMI
Alternatively you can expose the MBeans over RMI, which has no additional dependencies:
<!--
Now expose the server for remote access via RMI
Local access: service:jmx:rmi://localhost/jndi/rmi://localhost:10099/myconnector
Remote access: service:jmx:rmi:///jndi/rmi://your.host:10099/myconnector
or service:jmx:rmi://localhost/jndi/rmi://localhost:10099/myconnector
-->
<bean
class="org.springframework.jmx.support.ConnectorServerFactoryBean"
depends-on="rmiRegistry">
<property name="objectName" value="connector:name=rmi" />
<property name="serviceUrl"
value="service:jmx:rmi://localhost/jndi/rmi://localhost:10099/myconnector" />
</bean>
<bean id="rmiRegistry"
class="org.springframework.remoting.rmi.RmiRegistryFactoryBean">
<property name="port" value="10099" />
</bean>
However there are also some catches you must avoid:
- You must start an RMI registry so that the connector can register the MBean there; it won't start one for you
- You must make sure that the registry is started before the connector tries to use either by declaring it before the connector or by making this dependency explicit with the depends-on attribute
org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'org.springframework.jmx.support.ConnectorServerFactoryBean#0' defined in class path resource [application-context.xml]: Invocation of init method failed; nested exception is java.io.IOException: Cannot bind to URL [rmi://localhost:10099/jmxrmi]: javax.naming.ServiceUnavailableException [Root exception is java.rmi.ConnectException: Connection refused to host: localhost; nested exception is: java.net.ConnectException: Connection refused: connect].
Local MBean server accessed over an SSH tunnel
For increased security you may want to prefer not to expose your MBeans to remote access by making them accessible only from the local machine (127.0.0.1) and use na SSH tunnel so that a remote JConsole can access them as a local application. This is certainly possible but may be difficult because normally JMX goes over RMI, which uses two ports: one for the RMI Registry and another one for the actual service (MBean server here), which is usually chosen randomly at the runtime, and you'd need to tunnel both. Fortunately, Spring makes it possible to configure both the ports:
<bean
class="org.springframework.jmx.support.ConnectorServerFactoryBean"
depends-on="rmiRegistry">
<property name="objectName" value="connector:name=rmi" />
<property name="serviceUrl"
value="service:jmx:rmi://127.0.0.1:STUBPORT/jndi/rmi://localhost:REGISTRYPORT/myconnector" />
</bean>
<bean id="rmiRegistry"
class="org.springframework.remoting.rmi.RmiRegistryFactoryBean">
<property name="port" value="REGISTRYPORT" />
</bean>
Replace STUBPORT and REGISTRYPORT with suitable numbers and tunnel those two. Notice that the REGISTRYPORT number is same in the connector's serviceUrl and in the RMI registry's port attribute.
WARNING: The configuration above actually doesn't prevent direct access from a remote application. To really force the RMI registry to only listen for connection from the local host we would likely need to set - under Sun JVM without Spring - the system property com.sun.management.jmxremote. Additionally, to force the registry to use the IP 120.0.0.1, we'd need to set java.rmi.server.hostname=localhost (applies to Spring too). See this discussion about forcing local access. I'm not sure how to achieve the same result with Spring while still preserving the ability to specify both the RMI ports. Check also the JavaDoc for Spring's RmiServiceExporter .
Related posts and docs:
- Tunneling Debug and JMX for Alfresco (A. uses Spring)- see the second section, SSH Tunneling for JMX
- A custom tunneling RMI agent - uses a configured port instead of a random one
- Monitoring ActiveMQ Using JMX Over SSH
- JMX 1.2 specification and JMX 1.2 Remote API specification; from the JMX spec.: "The MBean server relies on protocol adaptors and connectors to make the agent accessible from management applications outside the agent’s JVM." On the other hand, the Oracle JMX page reads that if you set com.sun.management.jmxremote (as opposed to ...jmxremote.port), you make it possible "to monitor a local Java platform, that is, a JVM running on the same machine" - thus not necessarily from the same JVM.
Connecting with JConsole
Fire up JConsole and type the appropriate remote address, for example service:jmx:rmi:///jndi/rmi://your.server.com:10099/myconnector, if connecting to an application on the remote machine your.server.com accessible via RMI.Regarding the connection URL, if you have a a connector with the serviceUrl of "service:jmx:rmi://myhost:9999/jndi/rmi://localhost:10099/myconnector" then, from a client, you can use either service:jmx:rmi://myhost:9999/jndi/rmi://your.server.com:10099/myconnector or simply service:jmx:rmi:///jndi/rmi://your.server.com:10099/myconnector because, according to the JMX 1.2 Remote API specification (page 90):
... the hostname and port number # (myhost:9999 in the examples) are not used by the client and, if # present, are essentially comments. The connector server address # is actually stored in the serialized stub (/stub/ form) or in the # directory entry (/jndi/ form).
IBM JVM, JConsole and JMX configuration
The IBM JVM 5 SDK guide indicates that the IBM SDK also contains JConsole and recognizes the same JMX-related system properties, namely com.sun.management.jmxremote.* (though "com.sun.management.jmxremote" itself isn't mentioned).Notice that the IBM JConsole is a bit different, for instance it's missing the Local tab, which is replaced by specifying the command-line option connection=localhost (search the SDK guide for "JConsole monitoring tool Local tab").
Further improvements
JVM 1.5: Exposing the MemoryMXBean
Since Java 5.0 there is a couple of useful platform MBeans that provide information about the JVM, including also the java.lang.management.MemoryMXBean, that let you see the heap usage, invoke GC etc.You can make it available to JConsole and other JMX agents as follows (though there must be an easier way):
<bean class="org.springframework.jmx.export.MBeanExporter" lazy-init="false">
<property name="beans">
<map>
<entry key="bean:name=Memory2" value-ref="memProxy"/>
<!-- other exported beans may follow ... -->
</map>
</property>
</bean>
<bean id="memProxy"
class="java.lang.management.ManagementFactory"
factory-method="getMemoryMXBean"
/>
Update: There indeed seems to be a better way of exposing the platform MBeans directly by replacing the Spring's MBeanServerFactoryBean with java.lang.management.ManagementFactory using its factory-method getPlatformMBeanServer. Of course this requires JVM 1.5+.
Improving security with password authentication
Access to your MBeans over RMI may be protected with a password. According to a discussion, authentication is configured on the server connector:<bean class="org.springframework.jmx.support.ConnectorServerFactoryBean" depends-on="rmiRegistry"> <property name="objectName" value="connector:name=rmi" /> <property name="serviceUrl" value="service:jmx:rmi://localhost/jndi/rmi://localhost:10099/myconnector" /> <property name="environment"> <!-- the following is only valid when the sun jmx implementation is used --> <map> <entry key="jmx.remote.x.password.file" value="etc/security/jmxremote.password"/> <entry key="jmx.remote.x.access.file" value="etc/security/jmxremote.access"/> </map> </property> </bean>
The passwd and access files follow the templates that can be found in the JDK/jre/lib/management folder.