Basic Introduction to JMX

1. Introduction

The Java Management Extensions (JMX) framework was introduced in Java 1.5 and has found widespread acceptance in the Java developers community since its inception.

It provides an easily configurable, scalable, reliable and more or less friendly infrastructure for managing Java application either locally or remotely. The framework introduces the concept of MBeans for real time management of applications.

This article is a beginner’s step by step guide to create and setup a basic MBean and manage it through JConsole.

2. JMX Architecture

JMX architecture follows a three layered approach:

1. Instrumentation layer: MBeans registered with the JMX agent through which resources are managed
2. JMX agent layer: the core component (MbeanServer) which maintains registry of managed MBeans and provides an interface to access them
3. Remote management layer: usually client side tool like JConsole

3. Creating an MBean Class

While creating MBeans, there is a particular design pattern which we must conform to. The model MBean class MUST implements an interface with the following name: “model class name” plus MBean.

So let’s define our MBean interface and the class implementing it:

public interface GameMBean {

    public void playFootball(String clubName);

    public String getPlayerName();

    public void setPlayerName(String playerName);

}
public class Game implements GameMBean {

    private String playerName;

    @Override
    public void playFootball(String clubName) {
        System.out.println(
          this.playerName + " playing football for " + clubName);
    }

    @Override
    public String getPlayerName() {
        System.out.println("Return playerName " + this.playerName);
        return playerName;
    }

    @Override
    public void setPlayerName(String playerName) {
        System.out.println("Set playerName to value " + playerName);
        this.playerName = playerName;
    }
}

The Game class overrides a method  playFootball() of the parent interface. Apart from this, the class has a member variable playerName and getter/setter for it.

Note that getter/setter are also declared in the parent interface.

4. Instrumenting with the JMX Agent

JMX agents are the entities running either locally or remotely which provide the management access to the MBeans registered with them.

Let’s use PlatformMbeanServer – the core component of JMX agent and register the Game MBean with it.

We’ll use another entity – ObjectName – to register the Game class instance with the PlatformMbeanServer; this is a String consisting of two parts:

• domain: can be an arbitrary String, but according to MBean naming conventions, it should have Java package name (avoids naming conflicts)
• key: a list of  “key=value” pairs separated by comma

In this example, here’s our ObjectName: “com.baledung.tutorial:type=basic,name=game”.

We’ll get the MBeanServer from the factory class java.lang.management.ManagementFactory:

MBeanServer server = ManagementFactory.getPlatformMBeanServer();

And we’ll register the model MBean class using its custom ObjectName:

ObjectName objectName = null;
try {
    objectName = new ObjectName("com.baeldung.tutorial:type=basic,name=game");
} catch (MalformedObjectNameException e) {
    e.printStackTrace();
}

Finally, just to be able to test it – we’ll add a while loop to prevent the application from terminating before we can access the MBean through JConsole:

while (true) {
}

5. Accessing the MBean

5.1. Connecting from the Client Side

1. Start the application in the Eclipse
2. Start Jconsole (located in the bin folder of the JDK installation directory of your machine)
3. Connection -> new Connection -> select the local Java process of this tutorial -> Connect  ->Insecure SSl connection warning -> Continue with insecure connection
4. After connection is established, click on the top right MBeans tab of the View pane
5. List of registered MBeans will be appear in left column
6. Click com.baeldung.tutorial -> basic -> game
7. Under game, there will be two rows, one each for attributes and operations

Here’s a quick look at the JConsole part of the process:

5.2. Managing the MBean

The basics of MBean management are simple:

• Attributes can read or written
• Methods can be invoked and arguments can be supplied to them or values returned from them

Let’s see what that means for the Game MBean in practice:

• attribute: type a new value for the attribute playerName – for example “Messi” and click Refresh button
  

       The Following log will appear in the Eclipse console:

       Set playerName to value Messi

• operations: type a value for the String argument of method playFootBall() – for example “Barcelona” and click on the method button. A window alert for successful invocation will appear

The following log will appear in the eclipse console:

       Messi playing football for Barcelona

6. Conclusion

This tutorial touched upon the basics of setting up a JMX enabled application by use of MBeans. Also, it discussed about using a typical client side tool like JConsole to manage the instrumented MBean.

The domain of JMX technology is very wide in scope and reach. This tutorial can be considered a beginner’s step towards that.

Source code of this tutorial can be found over on Github.