JMX Integration

Java Management Extensions (JMX) is used for managing and monitoring java applications.  This tutorial will provide you with an example as to how you can JMX-enable your MINA based application.

This tutorial is designed to help you get the JMX technology integrated in to your MINA-based application. In this tutorial, we will integrate the MINA-JMX classes into the HTTP server example program.

Version Note This tutorial has been verified on MINA 1.0 and above.

Adding a Service Manager MBean

example\src\main\java\org\apache\mina\example\httpserver\codec\Server.java

Add the following import statements

import java.lang.management.ManagementFactory;
import javax.management.MBeanServer;
import javax.management.ObjectName;
import org.apache.mina.integration.jmx.IoServiceManager;

After the following the line:

IoAcceptor acceptor = new SocketAcceptor();

Add the following code

IoServiceManager serviceManager = new IoServiceManager( acceptor );
serviceManager.startCollectingStats(1000);
MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();
ObjectName name = new ObjectName("mina.example.http.server:type=IoServiceManager");
mbs.registerMBean(serviceManager, name);

The IoServiceManager class implements the IoServiceManagerMBean interface.  The IoServiceManager class will take an IoService object and monitor the work that is being performed.  The work performed will be polled every second, as per the call to serviceManager.startCollectingStats(1000).

The next 3 lines of the code are JMX specific and are used to declare an exposed MBean that is suitable for monitoring by the JMX subsystem.  The String parameter that is passed into the ObjectName constructor can be any name you wish.  Using something that adequately describes your MBean is the preferred. 

Compile the JMX-enhanced HTTP Server.  Nothing special in this step.

Start the HTTP Server 

Java Version Note Depending on the version of Java you are using, your command line arguments may be different.

If you are using Java 5 or earlier:

java -Dcom.sun.management.jmxremote -classpath <CLASSPATH> org.apache.mina.example.httpserver.codec.Server

If you  are using Java 6:

java  -classpath <CLASSPATH> org.apache.mina.example.httpserver.codec.Server

Start JConsole 

Start JConsole using the following command: 

<JDK_HOME>/bin/jconsole

Once you have connected to the JMX enabled HTTP server using JConsole, you will be able to view the exposed beans by clicking on the "MBeans" tab and then expanding the "mina.example.http.server" node in the tree.  By further investigation into the attributes of the MBean, you are able to see the current attributes of this bean.  These attributes and operations listed below are methods that are contained in the interface org.apache.mina.integration.jmx.IoServiceManagerMBean.  The class that defines the methods is org.apache.mina.integration.jmx.IoServiceManager.

Methods for starting the stat collection :

• startCollectingStats : start collecting throughput values for the managed sessions (advice : use a 5000ms value as parameter for polling time)
• stopCollectingStats : stop the polling of the IoService sessions

Below is a list of the attributes filled when the stat collection is started :

• ManagedSessionCount : the number of sessions currently managed by this IoService

• Average value for the managed IoService sessions :
  • AverageByteReadThroughput : average byte reading per seconds for the managed sessions
  • AverageByteWrittenThroughput : average byte writing throughput per seconds
  • AverageMessageReadThroughput : average message decoded per seconds (only if you use a FilterCodec)
  • AverageMessageWrittenThroughput : average message encoded per seconds (only if you use a FilterCodec)

• The total throughput of this IoService sessions :
  • TotalByteReadThroughput : total byte reading per seconds for the managed sessions
  • TotalByteWrittenThroughput : total byte writting per seconds for the managed sessions
  • TotalMessageReadThroughput : total message decoded per seconds (only if you use a FilterCodec)
  • TotalMessageWrittenThoughput : total message encoded per seconds (only if you use a FilterCodec)

Additionally, you may execute any of the operations listed below:

• closeAllSessions : force the closing of all managed sessions

More In-depth information about MINA and JMX

...coming soon