Chapter 1 Standard MBeans

A standard MBean is the simplest and fastest way to instrument a resource from scratch: 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 resource.

The code samples in this chapter are from the files in the StandardMBean example directory located in the main examplesDir/current (see “Directories and Classpath” in the Preface).

This chapter covers the following topics:

• 1.1 Exposing the MBean Interface demonstrates the design patterns for attributes and operations and gives some general rules for writing the MBean interface.

• 1.2 Implementing an MBean shows how the MBean interface is related to the code for the manageable resource.

• 1.3 Running the Standard MBean Example demonstrates the runtime behavior of a standard MBean.

1.1 Exposing the MBean Interface

To expose the MBean interface, first determine the management interface of your resource, that is the information needed to manage it. This information is expressed as attributes and operations. An attribute is a value of any type that a manager can get or set remotely. An operation is a method with any signature and any return type that the manager can invoke remotely.

Attributes and operations are conceptually equivalent to properties and actions on JavaBeans objects. However, their translation into Java code is entirely different to accommodate the management functionality.

As specified by the Java Management Extensions (JMX) instrumentation, all attributes and operations are explicitly listed in an MBean interface. This is a Java interface that defines the full management interface of an MBean. This interface must have the same name as the class that implements it, followed by the MBean suffix. Because the interface and its implementation are usually in different files, two files make up a standard MBean.

For example, the class SimpleStandard (in the file SimpleStandard.java) has its management interface defined in the interface SimpleStandardMBean (in the file SimpleStandardMBean.java).

Example 1–1 SimpleStandardMBean Interface

public interface SimpleStandardMBean {

    public String getState() ;
    
    public void setState(String s) ;
    
    public Integer getNbChanges() ;
    
    public void reset() ;
}

Only public methods in the MBean interface are taken into consideration for the management interface. When present, non-public methods should be grouped separately, to make the code clearer for human readers.

1.1.1 MBean Attributes

Attributes are conceptual variables that are exposed for management through getter and setter methods in the MBean interface:

• A getter is any public method whose name begins with get and which does not return void; it enables a manager to read the value of the attribute, whose type is that of the returned object.

• A public method whose name begins with is and which returns a boolean or Boolean is also a getter, though a boolean attribute can have only one getter (it must be one form or the other).

• A setter is any public method whose name begins with set and which takes a single parameter; it enables a manager to write a new value in the attribute, whose type is that of the parameter.

Attribute types can be arrays of objects, but individual array elements cannot be accessed individually through the getters and setters. Use operations to access the array elements, as described in the next section. The following code example demonstrates an attribute with an array type:

public String[] getMessages();
public void setMessages(String[] msgArray);

The name of the attribute is the literal part of the method name following get, is, or set. This name is case sensitive in all Java Dynamic Management Kit (Java DMK) objects that manipulate attribute names. Using these patterns, we can determine the attributes exposed in Example 1–1:

• State is a readable and writable attribute of type String

• NbChanges is a read-only attribute of type Integer

The specification of the design patterns for attributes implies the following rules:

• Attributes can be read-only, write-only, or readable and writable.

• Attribute names cannot be overloaded. For any given attribute name there can be at most one setter and one getter, and if both are defined, they must use the same type.

1.1.2 MBean Operations

Operations are methods that management applications can call remotely on a resource. They can be defined with any number of parameters of any type and can return any type.

The design patterns for operations are simple. Any public method defined in the MBean interface that is not an attribute getter or setter is an operation. For this reason, getters and setters are usually declared first in the Java code, so that all operations are grouped afterwards. The name of an operation is the name of the corresponding method.

The SimpleStandardMBean in Example 1–1 defines one operation, reset, which takes no parameters and returns nothing.

While the following methods define valid operations (and not attributes), to avoid confusion with attributes, these types of names should not be used:

public void getFoo();
public Integer getBar(Float p);
public void setFoo(Integer one, Integer two);
public String isReady();

For performance reasons, you might want to define operations for accessing individual elements of an array type attribute. In this case, use unambiguous operation names:

public String singleGetMessage(int index);
public void singleSetMessage(int index, String msg);

The Java DMK imposes no restrictions on attribute types, operation attribute types, and operation return types. However, the developer must ensure that the corresponding classes are available to all applications manipulating these objects, and that they are compatible with the type of communication used. For example, attribute and operation types must be serializable to be manipulated remotely using the remote method invocation (RMI) or JMX messaging protocol (JMXMP) protocols.

1.2 Implementing an MBean

The second part of an MBean is the class that implements the MBean interface. This class encodes the expected behavior of the manageable resource in its implementation of the attribute and operation methods. The resource does not need to reside entirely in this class. The MBean implementation can rely on other objects.

If the MBean must be instantiated remotely, it must be a concrete class and must expose at least one public constructor so that any other class can create an instance.

Otherwise, the developer is free to implement the management interface in any way, provided that the object has the expected behavior. Here is the sample code that implements our MBean interface.

Example 1–2 SimpleStandard Class

public class SimpleStandard
    extends NotificationBroadcasterSupport
    implements SimpleStandardMBean {

     public String getState() {
        return state;
    }

    public void setState(String s) {
        state = s;
        nbChanges++;
    }

    public Integer getNbChanges() {
        return nbChanges;
    }

    public void reset() {
	         AttributeChangeNotification acn =
	            new AttributeChangeNotification(this,
					                                 0,
					                                 0,
					                                 "NbChanges reset",
					                                 "NbChanges",
					                                 "Integer",
					                                 new Integer(nbChanges),
					                                 new Integer(0));
	         state = "initial state";
          nbChanges = 0;
	         nbResets++;
	         sendNotification(acn);
    }

    // This method is not a getter in the management sense because 
    // it is not exposed in the "SimpleStandardMBean" interface.
    public int getNbResets() {
        return nbResets;
    }

    public MBeanNotificationInfo[] getNotificationInfo() {
        return new MBeanNotificationInfo[] {
	          new MBeanNotificationInfo(
	          new String[] { AttributeChangeNotification.ATTRIBUTE_CHANGE },
	          AttributeChangeNotification.class.getName(),
	          "This notification is emitted when the reset() 
            method is called.")
	        };    
}

As in this example, attributes are usually implemented as internal variables whose value is returned or modified by the getter and setter methods. However, an MBean can implement any access and storage scheme to fit particular management needs, provided getters and setters retain their read and write semantics. Methods in the MBean implementation can have side-effects, but it is up to you to ensure that these are safe and coherent within the full management solution.

We also see here that by calling the MBeanNotificationInfo class, the MBean can send notifications of different types. In this case, the MBean sends notifications about changes in its attributes when the reset() method is called.

As we will see later, management applications never have a direct handle on an MBean. They only have an identification of an instance and the knowledge of the management interface. In this case, the mechanism for exposing attributes through methods in the MBean interface makes it impossible for an application to access the MBean directly. Internal variables and methods, and even public ones, are totally encapsulated and their access is controlled by the programmer through the implementation of the MBean interface.

1.3 Running the Standard MBean Example

The examplesDir/StandardMBean directory contains the SimpleStandard.java and SimpleStandardMBean.java files which make up the MBean. This directory also contains a simple agent application which instantiates this MBean, introspects its management interface, and manipulates its attributes and operations.

To Run the Standard MBean Example

1. Compile all files in this directory with the javac command.

   For example, on the Solaris platform with the Korn shell, type:

   $ cd examplesDir/current/StandardMBean/ $ javac -classpath classpath *.java

2. To run the example, start the agent class which will interact with the SimpleStandard MBean:

   $ java -classpath classpath StandardAgent

3. Press Enter when the application pauses, to step through the example.

   The agent application handles all input and output in this example and gives a view of the MBean at runtime.

We will examine how agents work in Chapter 2, Dynamic MBeans, but this example demonstrates how the MBean interface limits the view of what the MBean exposes for management. Roughly, the agent introspects the MBean interface at runtime to determine what attributes and operations are available. You then see the result of calling the getters, setters, and operations.

Part II also covers the topics of object names and exceptions which you see when running this example.