Chapter   2

Essentials of the JMX API

This chapter introduces the fundamental notion of the Java Management Extensions (JMX) API, namely managed beans, or MBeans.

An MBean is a managed Java object, similar to a JavaBean^TM, that follows the design patterns set forth in the instrumentation level of the JMX specification. An MBean can represent a device, an application, or any resource that needs to be managed. MBeans expose a management interface: a set of readable and/or writable attributes and a set of invokable operations, along with a self-description. The management interface does not change throughout the life of an MBean instance. MBeans can also emit notifications when certain defined events occur.

The JMX specification defines four types of MBean: standard MBeans, dynamic MBeans, open MBeans and model MBeans. The examples in this chapter demonstrate the simplest type of MBean, namely standard MBeans.

2.1 Standard MBeans

A standard MBean is defined by writing a Java interface called SomethingMBean and a Java class called Something that implements that interface. Every method in the interface defines either an attribute or an operation in the MBean. By default every method defines an operation. Attributes and operations are simply methods which follow certain design patterns. A standard MBean is composed of the MBean interface which lists the methods for all exposed attributes and operations, and the class which implements this interface and provides the functionality of the instrumented resource.

The following sections dissect an example standard MBean, and a simple JMX agent that manages the MBean. The code samples are taken from the directory work_dir/jmx_examples/Essential/com/example/mbeans.

2.1.1 MBean Interface

An example of a very basic MBean interface, named HelloMBean, is shown in CODE EXAMPLE 2-1.

 
package com.example.mbeans; 
 
public interface HelloMBean { 
 
    public void sayHello(); 
    public int add(int x, int y); 
 
    public String getName(); 
 
    public int getCacheSize(); 
    public void setCacheSize(int size); 
} 
 

As stated previously, by convention an MBean interface takes the name of the Java class that implements it, with the suffix MBean added. So, in this case, the interface is called HelloMBean. The Hello class that implements this interface is described in Section 2.1.2 "MBean Implementation".

According to the JMX specification, an MBean interface consists of named and typed attributes that are readable and possibly writable, and named and typed operations that can be invoked by the applications that are managed by the MBean. The HelloMBean interface shown in CODE EXAMPLE 2-1, declares two operations: the Java methods add() and sayHello().

Of the two attributes that are declared by HelloMbean, Name is a read-only string, and CacheSize is an integer that can be both read and written. Getter and setter methods are declared, to allow the managed application to access and possibly change the attribute values. As defined by the JMX specification, a getter is any public method whose name begins with get and which does not return void. A getter enables a manager to read the value of the attribute, whose type is that of the returned object. A setter is any public method whose name begins with set and which takes a single parameter. A setter enables a manager to write a new value in the attribute, whose type is the same as that of the parameter.

The implementation of these operations and attributes is shown in the following section.

2.1.2 MBean Implementation

The Hello class shown in CODE EXAMPLE 2-2 implements HelloMBean.

 
package com.example.mbeans; 
 
public class Hello implements HelloMBean { 
    public void sayHello() { 
	System.out.println("hello, world"); 
    } 
 
    public int add(int x, int y) { 
	return x + y; 
    } 
 
    public String getName() { 
	return this.name; 
    } 
 
 
    public int getCacheSize() { 
	return this.cacheSize; 
    } 
 
    public synchronized void setCacheSize(int size) { 
	this.cacheSize = size; 
 
	System.out.println("Cache size now " + this.cacheSize); 
    } 
 
    private final String name = "Reginald"; 
    private int cacheSize = DEFAULT_CACHE_SIZE; 
    private static final int DEFAULT_CACHE_SIZE = 200; 
} 
 

The straightforward Java class Hello provides the definitions of the operations and attributes declared by HelloMBean. As you can see, the sayHello() and add() operations are extremely simple, but real-life operations can be as simple or as sophisticated as you like.

Methods to get the Name attribute and to get and set the cacheSize attribute are also defined. In this example, the Name attribute value never changes, but in a real scenario it might change as the managed resource runs. For example, the attribute might represent statistics such as uptime or memory usage. Here, it is merely the name “Reginald”.

Calling the setCacheSize method allows you to alter the cacheSize attribute from its declared default value of 200. In reality, changing the cacheSize attribute could require other operations to be performed, such as discarding entries or allocating new ones. This example merely prints a message to confirm that the cache size has changed, but more sophisticated operations could be defined in the place of the simple call to println().

With the simple Hello MBean and its interface thus defined, they can now be used to manage the resource they represent, as shown in the following section.

2.1.3 Managing a Resource

As presented in the Java Management Extensions (JMX) Technology Overview, once a resource has been instrumented by MBeans, the management of that resource is performed by a JMX agent.

The core component of a JMX agent is the MBean server, a managed object server in which MBeans are registered (see the API documentation for the MBeanServer interface for details of the MBean server implementation). A JMX agent also includes a set of services to manage MBeans.

CODE EXAMPLE 2-3 presents a basic JMX agent, named Main.

 
package com.example.mbeans; 
 
import java.lang.management.*; 
import javax.management.*; 
 
public class Main { 
 
   public static void main(String[] args) throws Exception { 
 
      MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); 
 
      ObjectName name = new ObjectName("com.example.mbeans:type=Hello"); 
 
      Hello mbean = new Hello(); 
 
      mbs.registerMBean(mbean, name); 
 
      System.out.println("Waiting forever..."); 
      Thread.sleep(Long.MAX_VALUE); 
   } 
} 
 

The JMX agent Main begins by obtaining any MBean server that is running on the platform, by calling the getPlatformMBeanServer() method of the java.lang.management.ManagementFactory class. If there is no MBean server already running on the platform, then getPlatformMBeanServer() creates one automatically by calling the JMX method MBeanServerFactory.createMBeanServer(). The MBeanServer instance obtained by Main is named mbs.

Next, Main defines an object name for the MBean instance it will create. Every JMX MBean must have an object name. The object name is an instance of the JMX class ObjectName, and must conform to the syntax defined by the JMX specification, namely it must comprise a domain, and a list of key-properties (see the API documentation for the ObjectName class for details of this syntax). In the object name defined by Main, name, the domain is com.example.mbeans (the package in which the example MBeans are contained) and the key-property declares that this object is of the type Hello.

An instance of a Hello object is created, named mbean. This Hello object is itself an instance of the MBean Hello that was defined in Section 2.1.2 "MBean Implementation".

The Hello object named mbean is then registered as an MBean in the MBean server mbs with the object name name, by passing the object and the object name into a call to the JMX method MBeanServer.registerMBean().

With the Hello MBean registered in the MBean server, Main will simply wait for management operations to be performed on Hello. In the scope of this example, these management operations are invoking sayHello(), and add(), and getting and setting the attribute values.

2.1.4 Running the Standard MBean Example

Having examined the example classes, you can now run the example. The Java 2 Platform, Standard Edition (J2SE) version 5.0 comes with a management and monitoring console, named JConsole, that is used to interact with the MBean in this example. JConsole is located in J2SE_HOME/bin/jconsole, in which J2SE_HOME is the installation directory of the J2SE platform.

To run the example, follow the steps below, or see the README file:

2.2 Sending Notifications

MBeans can generate notifications, for example to signal a state change, a detected event, or a problem.

For an MBean to generate notifications, it must implement the interface NotificationBroadcaster, or its subinterface NotificationEmitter. All you need to do to send a notification is to construct an instance of the class javax.management.Notification or a subclass (such as AttributeChangedNotification), and pass it to NotificationBroadcasterSupport.sendNotification.

Every notification has a source. The source is the object name of the MBean that emitted the notification.

Every notification has a sequence number. This number can be used to order notifications coming from the same source when order matters and there is a danger of the notifications being handled in the wrong order. It is all right for the sequence number to be zero, but it is better for it to increment for each notification from a given MBean.

There is an example of a standard MBean that emits notifications in the directory work_dir/jmx_examples/Notification/com/example/mbeans. This example is essentially the same as the example seen in Section 2.1 "Standard MBeans", except that the Hello MBean implements the NotificationBroadcaster interface.

2.2.1 NotificationBroadcaster Interface

As stated above, the only difference between this example and the one presented in Section 2.1 "Standard MBeans" is the fact that the MBean implementation allows for the sending of notifications.

Notifications are activated by implementing the NotificationBroadcaster interface, as shown in CODE EXAMPLE 2-4.

 
package com.example.mbeans; 
 
import javax.management.*; 
 
public class Hello 
        extends NotificationBroadcasterSupport implements HelloMBean { 
 
    public void sayHello() { 
        System.out.println("hello, world"); 
    } 
 
    public int add(int x, int y) { 
        return x + y; 
    } 
 
    public String getName() { 
        return this.name; 
    } 
 
    public int getCacheSize() { 
        return this.cacheSize; 
    } 
 
    public synchronized void setCacheSize(int size) { 
        int oldSize = this.cacheSize; 
        this.cacheSize = size; 
 
        System.out.println("Cache size now " + this.cacheSize); 
 
        Notification n = 
            new AttributeChangeNotification(this, 
					    sequenceNumber++, 
					    System.currentTimeMillis(), 
					    "CacheSize changed", 
					    "CacheSize", 
					    "int", 
					    oldSize, 
					    this.cacheSize); 
 
	sendNotification(n); 
    } 
 
    @Override 
    public MBeanNotificationInfo[] getNotificationInfo() { 
        String[] types = new String[] { 
            AttributeChangeNotification.ATTRIBUTE_CHANGE 
        }; 
        String name = AttributeChangeNotification.class.getName(); 
        String description = "An attribute of this MBean has changed"; 
        MBeanNotificationInfo info = 
            new MBeanNotificationInfo(types, name, description); 
        return new MBeanNotificationInfo[] {info}; 
    } 
 
    private final String name = "Reginald"; 
    private int cacheSize = DEFAULT_CACHE_SIZE; 
    private static final int DEFAULT_CACHE_SIZE = 200; 
 
    private long sequenceNumber = 1; 
} 
 

As you can see in CODE EXAMPLE 2-4, this Hello MBean implementation extends the NotificationBroadcasterSupport class, that itself implements the NotificationEmitter interface.

The operations and attributes are set in the same way as before, with the only exception that the cacheSize attribute’s setter method now defines a new value oldSize, which records the cacheSize attribute’s value prior to the set operation.

The notification is constructed from an instance, n, of the JMX class AttributeChangeNotification, which extends javax.management.Notification. The notification is constructed within the definition of the setCacheSize() method, from the following information, that is passed to AttributeChangeNotification as parameters:

The object name of the source of the notification, namely the Hello MBean, represented simply by this
A sequence number, which in this example is a long named sequenceNumber, that is set at 1 and that increases incrementally
A timestamp
The content of the notification message
The name of the attribute that has changed, in this case cacheSize
The type of attribute that has changed
The old attribute value, in this case oldSize
The new attribute value, in this case this.cacheSize

The notification n is then passed to the NotificationBroadcasterSupport.sendNotification() method.

Finally, the MBeanNotification is defined to describe the characteristics of the different notification instances emitted by the MBean for a given Java class of notification, which in this case is AttributeChangeNotification notifications.

The MBean interface, HelloMBean, and the JMX agent Main are identical to those used in the previous example.

2.2.2 Running the MBean Notfication Example

Having examined the example classes, you can now run the example. This example again uses JConsole to interact with the Hello MBean.To run the example, follow the steps below, or see the README file:

Copyright © 2004 Sun Microsystems, Inc. All rights reserved.