Package javax.management

Provides the core classes for the Java Management Extensions.

The Java Management Extensions (JMX^TM) API is a standard API for management and monitoring. Typical uses include:

• consulting and changing application configuration
• accumulating statistics about application behavior and making them available
• notifying of state changes and erroneous conditions.

The JMX API can also be used as part of a solution for managing systems, networks, and so on.

The API includes remote access, so a remote management program can interact with a running application for these purposes.

MBeans

The fundamental notion of the JMX API is the MBean. An MBean is a named managed object representing a resource. It has a management interface which must be public and consist of:

• named and typed attributes that can be read and/or written
• named and typed operations that can be invoked
• typed notifications that can be emitted by the MBean.

For example, an MBean representing an application's configuration could have attributes representing the different configuration items. Reading the CacheSize attribute would return the current value of that item. Writing it would update the item, potentially changing the behavior of the running application. An operation such as save could store the current configuration persistently. A notification such as ConfigurationChangedNotification could be sent every time the configuration is changed.

In the standard usage of the JMX API, MBeans are implemented as Java objects. However, as explained below, these objects are not usually referenced directly.

Standard MBeans

To make MBean implementation simple, the JMX API includes the notion of Standard MBeans. A Standard MBean is one whose attributes and operations are deduced from a Java interface using certain naming patterns, similar to those used by JavaBeans^TM. For example, consider an interface like this:

public interface ConfigurationMBean {
         public int getCacheSize();
         public void setCacheSize(int size);
         public long getLastChangedTime();
         public void save();
    }

The methods getCacheSize and setCacheSize define a read-write attribute of type int called CacheSize (with an initial capital, unlike the JavaBeans convention).

The method getLastChangedTime defines an attribute of type long called LastChangedTime. This is a read-only attribute, since there is no method setLastChangedTime.

The method save defines an operation called save. It is not an attribute, since its name does not begin with get, set, or is.

The exact naming patterns for Standard MBeans are detailed in the JMX Specification.

There are two ways to make a Java object that is an MBean with this management interface. One is for the object to be of a class that has exactly the same name as the Java interface but without the MBean suffix. So in the example the object would be of the class Configuration, in the same Java package as ConfigurationMBean. The second way is to use the StandardMBean class.

MXBeans

An MXBean is a variant of Standard MBean where complex types are mapped to a standard set of types defined in the javax.management.openmbean package. MXBeans are appropriate if you would otherwise need to reference application-specific classes in your MBean interface. They are described in detail in the specification for MXBean.

Dynamic MBeans

A Dynamic MBean is an MBean that defines its management interface at run-time. For example, a configuration MBean could determine the names and types of the attributes it exposes by parsing an XML file.

Any Java object of a class that implements the DynamicMBean interface is a Dynamic MBean.

Open MBeans

An Open MBean is a kind of Dynamic MBean where the types of attributes and of operation parameters and return values are built using a small set of predefined Java classes. Open MBeans facilitate operation with remote management programs that do not necessarily have access to application-specific types, including non-Java programs. Open MBeans are defined by the package javax.management.openmbean.

Model MBeans

A Model MBean is a kind of Dynamic MBean that acts as a bridge between the management interface and the underlying managed resource. Both the management interface and the managed resource are specified as Java objects. The same Model MBean implementation can be reused many times with different management interfaces and managed resources, and it can provide common functionality such as persistence and caching. Model MBeans are defined by the package javax.management.modelmbean.

MBean Server

To be useful, an MBean must be registered in an MBean Server. An MBean Server is a repository of MBeans. Usually the only access to the MBeans is through the MBean Server. In other words, code no longer accesses the Java object implementing the MBean directly, but instead accesses the MBean by name through the MBean Server. Each MBean has a unique name within the MBean Server, defined by the ObjectName class.

An MBean Server is an object implementing the interface MBeanServer. The most convenient MBean Server to use is the Platform MBean Server. This is a single MBean Server that can be shared by different managed components running within the same Java Virtual Machine. The Platform MBean Server is accessed with the method ManagementFactory.getPlatformMBeanServer().

Application code can also create a new MBean Server, or access already-created MBean Servers, using the MBeanServerFactory class.

Creating MBeans in the MBean Server

There are two ways to create an MBean. One is to construct a Java object that will be the MBean, then use the registerMBean method to register it in the MBean Server. The other is to create and register the MBean in a single operation using one of the createMBean methods.

The registerMBean method is simpler for local use, but cannot be used remotely. The createMBean method can be used remotely, but sometimes requires attention to class loading issues.

An MBean can perform actions when it is registered in or unregistered from an MBean Server if it implements the MBeanRegistration interface.

Accessing MBeans in the MBean Server

Given an ObjectName name and an MBeanServer mbs, you can access attributes and operations as in this example:

int cacheSize = mbs.getAttribute(name, "CacheSize");
    Attribute newCacheSize =
         new Attribute("CacheSize", new Integer(2000));
    mbs.setAttribute(name, newCacheSize);
    mbs.invoke(name, "save", new Object[0], new Class[0]);

Alternatively, if you have a Java interface that corresponds to the management interface for the MBean, you can use an MBean proxy like this:

ConfigurationMBean conf =
        JMX.newMBeanProxy(mbs, name, ConfigurationMBean.class);
    int cacheSize = conf.getCacheSize();
    conf.setCacheSize(2000);
    conf.save();

Using an MBean proxy is just a convenience. The second example ends up calling the same MBeanServer operations as the first one.

An MBean Server can be queried for MBeans whose names match certain patterns and/or whose attributes meet certain constraints. Name patterns are constructed using the ObjectName class and constraints are constructed using the Query class. The methods queryNames and queryMBeans then perform the query.

MBean lifecycle

An MBean can implement the MBeanRegistration interface in order to be told when it is registered and unregistered in the MBean Server. Additionally, the preRegister method allows the MBean to get a reference to the MBeanServer object and to get its ObjectName within the MBean Server.

Notifications

A notification is an instance of the Notification class or a subclass. In addition to its Java class, it has a type string that can distinguish it from other notifications of the same class.

An MBean that will emit notifications must implement the NotificationBroadcaster or NotificationEmitter interface. Usually, it does this by subclassing NotificationBroadcasterSupport or delegating to an instance of that class. Here is an example:

public class Configuration extends NotificationBroadcasterSupport
            implements ConfigurationMBean {
        ...
        private void updated() {
            Notification n = new Notification(...);
            sendNotification(n);
        }
    }

Notifications can be received by a listener, which is an object that implements the NotificationListener interface. You can add a listener to an MBean with the method MBeanServer.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object). You can optionally supply a filter to this method, to select only notifications of interest. A filter is an object that implements the NotificationFilter interface.

An MBean can be a listener for notifications emitted by other MBeans in the same MBean Server. In this case, it implements NotificationListener and the method MBeanServer.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object) is used to listen.

Remote Access to MBeans

An MBean Server can be accessed remotely through a connector. A connector allows a remote Java application to access an MBean Server in essentially the same way as a local one. The package javax.management.remote defines connectors.

The JMX specification also defines the notion of an adaptor. An adaptor translates between requests in a protocol such as SNMP or HTML and accesses to an MBean Server. So for example an SNMP GET operation might result in a getAttribute on the MBean Server.

Interoperability between versions of the JMX specification

When a client connects to a server using the JMX Remote API, it is possible that they do not have the same version of the JMX specification. The version of the JMX specification described here is version 1.4. Previous versions were 1.0, 1.1, and 1.2. (There was no 1.3.) The standard JMX Remote API is defined to work with version 1.2 onwards, so in standards-based deployment the only interoperability questions that arise concern version 1.2 onwards.

Every version of the JMX specification continues to implement the features of previous versions. So when the client is running an earlier version than the server, there should not be any interoperability concerns.

When the client is running a later version than the server, certain newer features may not be available, as detailed in the next sections. The client can determine the server's version by examining the SpecificationVersion attribute of the MBeanServerDelegate.

If the remote MBean Server is 1.2

• You cannot use wildcards in a key property of an ObjectName, for example domain:type=Foo,name=*. Wildcards that match whole properties are still allowed, for example *:* or *:type=Foo,*.

• You cannot use Query.isInstanceOf in a query.

• You cannot use dot syntax such as HeapMemoryUsage.used in the observed attribute of a monitor, as described in the documentation for the javax.management.monitor package.