test

Java Dynamic Management Kit 5.0 Tutorial

Chapter 4 Open MBeans

Open MBeans are dynamic MBeans, with specific constraints on their data types, that allow management applications and their human administrators to understand and use new managed objects as they are discovered at runtime. Open MBeans provide a flexible means of instrumenting resources which need to be open to a wide range of applications compliant with the Java Management Extensions (JMX) specification.

To provide its own description to management applications, an open MBean must be a dynamic MBean, with the same behavior and functionality as a dynamic MBean. Thus it implements the DynamicMBean interface and no corresponding open MBean interface is required. The open functionality of open MBeans is obtained by providing descriptively rich metadata and by using exclusively certain predefined data types in the management interface.

Because open MBeans build their data types from a predefined set of Java classes, a management application can manage an agent that uses open MBeans, without having to load Java classes specific to that agent. Furthermore, a JMX connector or adaptor only needs to be able to transport classes from the predefined set, not arbitrary Java classes. This means, for example, that a connector could use eXtensible Markup Language (XML) as its transport by defining an XML schema that covers the MBean server operations and the predefined open MBean data types. It also means that a management application could run in a language other than Java.

The code samples in this chapter are taken from the files in the OpenMBean and OpenMBean2 example directories located in the main examplesDir (see “Directories and Classpath” in the Preface).

This chapter covers the following topics:

Open MBean Data Types

Open MBeans refer exclusively to a limited, predefined set of data types, which can be combined into compound types.

Supported Data Types

All open MBean attributes, method return values, and method arguments must be limited to the set of open MBean data types listed in this section. This set is defined as: the wrapper objects that correspond to the Java primitive types (such as Integer, Long, Boolean), String, CompositeData, TabularData, and ObjectName.

In addition, any array of the open MBean data types may be used in open MBeans. A special class, javax.management.openmbean.ArrayType is used to represent the definition of single or multi-dimensional arrays in open MBeans.

The following list specifies all data types that are allowed as scalars or as any-dimensional arrays in open MBeans:

In addition the following type may be used, but only as the return type of an operation:

Type Descriptor Classes

Open types are descriptor classes that describe the open MBean data types. To be able to manipulate the open MBean data types, management applications must be able to identify them. While primitive types are given by their wrapper class names, and arrays can be represented in a standard way, the complex data types need more structure than a flat string to represent their contents. Therefore open MBeans rely on description classes for all the open MBean data types, including special structures for describing complex data.

The abstract OpenType class is the superclass for the following specialized open type classes:

The CompositeType, TabularType, and ArrayType classes are recursive, that is, they can contain instances of other open types.

Open Data Instances

All of the wrapper classes for the primitive types are defined and implemented in all Java virtual machines, as is java.lang.String. The ObjectName class is provided by the implementation of the JMX specification. You can use the CompositeData and TabularData interfaces to define aggregates of the open MBean data types and provide a mechanism for expressing complex data objects in a consistent manner.

All open data instances corresponding to the open MBean types defined in Supported Data Types, except CompositeData and TabularData instances, are available through the classes of the JDK or JMX specification.

CompositeData and TabularData Instances

The CompositeData and TabularData interfaces represent complex data types. The JMX specification now includes a default implementation of these interfaces, using the CompositeDataSupport and TabularDataSupport classes respectively.

The CompositeData and TabularData interfaces and implementations provide some semantic structure to build aggregates from the open MBean data types. An implementation of the CompositeData interface is equivalent to a map with a predefined list of keys: values are retrieved by giving the name of the desired data item. Other terms commonly used for this sort of data type are record or struct.

An instance of a TabularData object contains a set of CompositeData instances. Each CompositeData instance in a TabularData instance is indexed by a unique key derived from its values, as described in TabularDataSupport Class.

A CompositeData object is immutable once instantiated: you cannot add an item to it and you cannot change the value of an existing item. TabularData instances are modifiable: rows can be added or removed from existing instances.

CompositeDataSupport Class

A CompositeData object associates string keys with the values of each data item. The CompositeDataSupport class defines an immutable map with an arbitrary number of entries, called data items, which can be of any type. To comply with the design patterns for open MBeans, all data items must have a type among the set of open MBean data types, including other CompositeData types.

When instantiating the CompositeDataSupport class, you must provide the description of the composite data object in a CompositeType object (see Type Descriptor Classes). All the items provided through the constructor must match this description. Because the composite object is immutable, all items must be provided at instantiation time, and therefore the constructor can verify that the items match the description. The getOpenType method returns this description so that other objects which interact with a CompositeData object can know its structure.

TabularDataSupport Class

The TabularDataSupport class defines a table structure with an arbitrary number of rows which can be indexed by any number of columns. Each row is a CompositeData object, and all rows must have the same composite data description. The columns of the table are headed by the names of the data items which make up the uniform CompositeData rows. The constructor and the methods for adding rows verify that all rows are described by equal CompositeData instances.

The index consists of a subset of the data items in the common composite data structure. This subset must be a key which uniquely identifies each row of the table. When the table is instantiated, or when a row is added, the methods of this class ensure that the index can uniquely identify all rows. Often the index will be a single column, for instance a column containing unique strings or integers.

Both the composite data description of all rows and the list of items which form the index are given by the table description returned by the getOpenType method. This method defined in the TabularData interface returns the TabularType object which describes the table (see Type Descriptor Classes).

The access methods of the TabularData class take an array of objects representing a key value which indexes one row and returns the CompositeData instance which makes up the designated row. A row of the table can also be removed by providing its key value. All rows of the table can also be retrieved in an enumeration.

Open MBean Metadata Classes

To distinguish open MBeans from other MBeans, the JMX specification provides a set of metadata classes which are used specifically to describe open MBeans.

The following interfaces in the javax.management.openmbean package define the management interface of an open MBean:

For each of these interfaces, a support class provides an implementation. Each of these classes describes a category of components in an open MBean. However, open MBeans do not have a specific metadata object for notifications; they use the MBeanNotificationInfo class.

Open MBeans provide a universal means of exchanging management functionality and consequently their description must be explicit enough for any user to understand. All of the OpenMBean*Info metadata classes inherit the getDescription method which should return a non-empty string. Each component of an open MBean must use this method to provide descriptions that are suitable for displaying in a graphical user interface.

Only the OpenMBeanOperationInfo specifies the getImpact method. Instances of OpenMBeanOperationInfo.getImpact must return one of the following constant values:

The value UNKNOWN cannot be used.

Running the Open MBean Examples

The examples directory provides two examples that demonstrate how to implement and manage an open MBean.

Open MBean Example 1

In the first open MBean example, we implement an open MBean and manage it through a simple JMX agent application. We develop a sample open MBean that uses some of the open data types and correctly exposes its management interface at runtime through the OpenMBean*Info classes. We then develop a simple JMX agent for exercising the open MBean, which involves:

The examplesDir/OpenMBean directory contains the SampleOpenMBean.java file, which is an open MBean, and the OpenAgent.java file which is a simple JMX agent used to interact with the open MBean.

To Run Open MBean Example 1

  1. Compile all files in the examplesDir/OpenMBean directory with the javac command.

    For example, on the Solaris platform, type:


    $ cd examplesDir/OpenMBean/
$ javac -classpath classpath *.java

  2. Run the agent class that interacts with the open MBean:


    $ java -classpath classpath OpenAgent

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

    You interact with the agent through the standard input and output in the window where it was launched. The OpenAgent displays information about each management step and waits for your input before continuing.

Open MBean Example 2

In the second open MBean example, we implement an open MBean and manage it through a simple JMX manager application. Although it is helpful to run the first open MBean example before this example, it is not obligatory.

We develop a sample open MBean that uses some of the open data types and correctly exposes its management interface at runtime through the OpenMBean*Info classes. See the README2.html file in the examplesDir/OpenMBean2/README2 directory for more detailed information on the data structure of this example.

We then develop a simple manager for exercising the open MBean, which involves:

The examplesDir/OpenMBean2 directory contains the following source files:

To Run Open MBean Example 2

  1. Compile all files in the examplesDir/OpenMBean2 directory with the javac command.

    For example, on the Solaris platform, type:


    $ cd examplesDir/OpenMBean2/
$ javac -classpath classpath *.java

  2. Run the agent class that interacts with the open MBean:


    $ java -classpath classpath Agent

  3. Open a second terminal window and change to the OpenMBean2 example directory:

    For example, on the Solaris platform, type:


    $ cd examplesDir/OpenMBean2/

    You can open this second terminal window on another host.

  4. Run the manager class:

    • If you are using a second terminal window on the same host as the agent class, type:


      $ java -classpath classpath Manager

    • If you are using another host, type:


      $ java -classpath classpath Manager hostname

      where hostname is the name or IP address of the host on which the agent is running.

    Interact with the manager through the standard input and output in the window where it was started. The Manager class displays information about each management step and waits for your input before continuing.