Provides the core classes for the Java Management Extensions.
* *The Java Management Extensions * (JMX) API is a standard * API for management and monitoring. Typical uses include:
* *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.
* *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:
* *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.
* * *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. 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
* {@link javax.management.StandardMBean StandardMBean}
* class.
An MXBean is a variant of Standard MBean where complex * types are mapped to a standard set of types defined in the * {@link 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 {@link javax.management.MXBean MXBean}.
* * *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 {@link * javax.management.DynamicMBean DynamicMBean} interface is a * Dynamic MBean.
* * *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.
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.
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 {@link * javax.management.ObjectName ObjectName} class.
* *An MBean Server is an object implementing the interface * {@link javax.management.MBeanServer 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 {@link * java.lang.management.ManagementFactory#getPlatformMBeanServer()}.
* *Application code can also create a new MBean Server, or * access already-created MBean Servers, using the {@link * javax.management.MBeanServerFactory MBeanServerFactory} class.
* * *There are two ways to create an MBean. One is to construct a * Java object that will be the MBean, then use the {@link * javax.management.MBeanServer#registerMBean 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 {@link javax.management.MBeanServer#createMBean(String, * javax.management.ObjectName) 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 {@link * javax.management.MBeanRegistration MBeanRegistration} * interface.
* * *Given an ObjectName name and an
* MBeanServer mbs, you can access
* attributes and operations as in this example:
* int cacheSize = mbs.getAttribute(name, "CacheSize");
* {@link javax.management.Attribute 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 =
* {@link javax.management.JMX#newMBeanProxy
* 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 {@link * javax.management.ObjectName ObjectName} class and constraints * are constructed using the {@link javax.management.Query Query} * class. The methods {@link * javax.management.MBeanServer#queryNames queryNames} and {@link * javax.management.MBeanServer#queryMBeans queryMBeans} then * perform the query.
* * *An MBean can implement the {@link javax.management.MBeanRegistration
* MBeanRegistration} interface in order to be told when it is registered
* and unregistered in the MBean Server. Additionally, the {@link
* javax.management.MBeanRegistration#preRegister preRegister} method
* allows the MBean to get a reference to the MBeanServer
* object and to get its ObjectName within the MBean
* Server.
A notification is an instance of the {@link * javax.management.Notification 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 * {@link javax.management.NotificationBroadcaster * NotificationBroadcaster} or {@link * javax.management.NotificationEmitter NotificationEmitter} * interface. Usually, it does this by subclassing * {@link javax.management.NotificationBroadcasterSupport * 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(...);
* {@link javax.management.NotificationBroadcasterSupport#sendNotification
* sendNotification}(n);
* }
* }
*
*
*
* Notifications can be received by a listener, which * is an object that implements the {@link * javax.management.NotificationListener NotificationListener} * interface. You can add a listener to an MBean with the method * {@link * javax.management.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 {@link javax.management.NotificationFilter * NotificationFilter} interface.
* *An MBean can be a listener for notifications emitted by other * MBeans in the same MBean Server. In this case, it implements * {@link javax.management.NotificationListener * NotificationListener} and the method {@link * javax.management.MBeanServer#addNotificationListener(ObjectName, * ObjectName, NotificationFilter, Object)} is used to listen.
* * *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.
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 {@link * javax.management.MBeanServerDelegateMBean#getSpecificationVersion * SpecificationVersion} attribute of the {@code * MBeanServerDelegate}.
* *You cannot use wildcards in a key property of an * {@link javax.management.ObjectName ObjectName}, for * example {@code domain:type=Foo,name=*}. Wildcards that * match whole properties are still allowed, for example * {@code *:*} or {@code *:type=Foo,*}.
* *You cannot use {@link * javax.management.Query#isInstanceOf Query.isInstanceOf} * in a query.
* *You cannot use dot syntax such as {@code * HeapMemoryUsage.used} in the {@linkplain * javax.management.monitor.Monitor#setObservedAttribute * observed attribute} of a monitor, as described in the * documentation for the {@link javax.management.monitor} * package.
* *