|
javax.management package
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
{@link javax.management.StandardMBean 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
{@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}.
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 {@link
javax.management.DynamicMBean 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 {@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.
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 {@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.
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");
{@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.
Notifications
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 by delegating to an instance
of that class.
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.
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.
@see
Java SE 6 Platform documentation on JMX technology
in particular the
JMX Specification, version 1.4(pdf).
@since 1.5
|