Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Standard Ed. 5.0
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package javax.management

Provides the core classes for the Java Management Extensions.

See:
Description

Interface Summary
Descriptor | This interface represents the behavioral metadata set for a JMX Element.
DescriptorAccess | This interface is used to gain access to descriptors of the Descriptor class which are associated with a JMX component, i.e.
DynamicMBean | Defines the methods that should be implemented by a Dynamic MBean (MBean that exposes a dynamic management interface).
MBeanRegistration | Can be implemented by an MBean in order to carry out operations before and after being registered or unregistered from the MBean server.
MBeanServer | This is the interface for MBean manipulation on the agent side.
MBeanServerConnection | This interface represents a way to talk to an MBean server, whether local or remote.
MBeanServerDelegateMBean | Defines the management interface of an object of class MBeanServerDelegate.
NotificationBroadcaster | Interface implemented by an MBean that emits Notifications.
NotificationEmitter | Interface implemented by an MBean that emits Notifications.
NotificationFilter | To be implemented by a any class acting as a notification filter.
NotificationListener | Should be implemented by an object that wants to receive notifications.
PersistentMBean | This class is the interface to be implemented by MBeans that are meant to be persistent.
QueryExp | Represents relational constraints that can be used in database query "where clauses".
ValueExp | Represents values that can be passed as arguments to relational expressions.

Class Summary
Attribute | Represents an MBean attribute by associating its name with its value.
AttributeChangeNotification | Provides definitions of the attribute change notifications sent by MBeans.
AttributeChangeNotificationFilter | This class implements of the `NotificationFilter` interface for the `attribute change notification`.
AttributeList | Represents a list of values for attributes of an MBean.
AttributeValueExp | Represents attributes used as arguments to relational constraints.
DefaultLoaderRepository | Deprecated. Use `MBeanServer.getClassLoaderRepository()` instead.
MBeanAttributeInfo | Describes an MBean attribute exposed for management.
MBeanConstructorInfo | Describes a constructor exposed by an MBean.
MBeanFeatureInfo | Provides general information for an MBean descriptor object.
MBeanInfo | Describes the management interface exposed by an MBean; that is, the set of attributes and operations which are available for management operations.
MBeanNotificationInfo | The `MBeanNotificationInfo` class is used to describe the characteristics of the different notification instances emitted by an MBean, for a given Java class of notification.
MBeanOperationInfo | Describes a management operation exposed by an MBean.
MBeanParameterInfo | Describes an argument of an operation exposed by an MBean.
MBeanPermission | Permission controlling access to MBeanServer operations.
MBeanServerBuilder | This class represents a builder that creates a default `MBeanServer` implementation.
MBeanServerDelegate | Represents the MBean server from the management point of view.
MBeanServerFactory | Provides MBean server references.
MBeanServerInvocationHandler | `InvocationHandler` that forwards methods in an MBean's management interface through the MBean server to the MBean.
MBeanServerNotification | Represents a notification emitted by the MBean server through the MBeanServerDelegate MBean.
MBeanServerPermission | A Permission to perform actions related to MBeanServers.
MBeanTrustPermission | This permission represents "trust" in a signer or codebase.
Notification | The Notification class represents a notification emitted by an MBean.
NotificationBroadcasterSupport | Provides an implementation of `NotificationEmitter` interface.
NotificationFilterSupport | Provides an implementation of the `NotificationFilter` interface.
ObjectInstance | Used to represent the object name of an MBean and its class name.
ObjectName | Represents the object name of an MBean, or a pattern that can match the names of several MBeans.
Query | Constructs query object constraints.
QueryEval | Allows a query to be performed in the context of a specific MBean server.
StandardMBean | An MBean whose management interface is determined by reflection on a Java interface.
StringValueExp | Represents strings that are arguments to relational constraints.

Exception Summary
AttributeNotFoundException | The specified attribute does not exist or cannot be retrieved.
BadAttributeValueExpException | Thrown when an invalid MBean attribute is passed to a query constructing method.
BadBinaryOpValueExpException | Thrown when an invalid expression is passed to a method for constructing a query.
BadStringOperationException | Thrown when an invalid string operation is passed to a method for constructing a query.
InstanceAlreadyExistsException | The MBean is already registered in the repository.
InstanceNotFoundException | The specified MBean does not exist in the repository.
IntrospectionException | An exception occurred during the introspection of an MBean.
InvalidApplicationException | Thrown when an attempt is made to apply either of the following: A subquery expression to an MBean or a qualified attribute expression to an MBean of the wrong class.
InvalidAttributeValueException | The value specified is not valid for the attribute.
JMException | Exceptions thrown by JMX implementations.
JMRuntimeException | Runtime exceptions emitted by JMX implementations.
ListenerNotFoundException | The specified MBean listener does not exist in the repository.
MalformedObjectNameException | The format of the string does not correspond to a valid ObjectName.
MBeanException | Represents "user defined" exceptions thrown by MBean methods in the agent.
MBeanRegistrationException | Wraps exceptions thrown by the preRegister(), preDeregister() methods of the `MBeanRegistration` interface.
NotCompliantMBeanException | Exception which occurs when trying to register an object in the MBean server that is not a JMX compliant MBean.
OperationsException | Represents exceptions thrown in the MBean server when performing operations on MBeans.
ReflectionException | Represents exceptions thrown in the MBean server when using the java.lang.reflect classes to invoke methods on MBeans.
RuntimeErrorException | When a `java.lang.Error` occurs in the agent it should be caught and re-thrown as a `RuntimeErrorException`.
RuntimeMBeanException | Represents runtime exceptions thrown by MBean methods in the agent.
RuntimeOperationsException | Represents runtime exceptions thrown in the agent when performing operations on MBeans.
ServiceNotFoundException | Represents exceptions raised when a requested service is not supported.

## Package javax.management Description

Provides the core classes for the Java Management Extensions.

The Java Management Extensions (JMXTM) 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 consisting 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 JavaBeansTM. 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.

### 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`. As of J2SE 1.5, a Platform MBean Server is available. 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 = (ConfigurationMBean)
            MBeanServerInvocationHandler.newProxyInstance(mbs,
                                                          name,
                                                          ConfigurationMBean.class,
                                                          false);
        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.

## 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 by delegating to an instance of that class.

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.

## Package Specification

- Specification of the JMX API, version 1.2

Since:
  1.5

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Standard Ed. 5.0
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.