330 lines
13 KiB
HTML
330 lines
13 KiB
HTML
|
<html>
|
||
|
|
<head>
|
||
|
|
<title>javax.management package</title>
|
||
|
|
<!--
|
||
|
|
Copyright 1999-2006 Sun Microsystems, Inc. All Rights Reserved.
|
||
|
|
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
||
|
|
|
||
|
|
This code is free software; you can redistribute it and/or modify it
|
||
|
|
under the terms of the GNU General Public License version 2 only, as
|
||
|
|
published by the Free Software Foundation. Sun designates this
|
||
|
|
particular file as subject to the "Classpath" exception as provided
|
||
|
|
by Sun in the LICENSE file that accompanied this code.
|
||
|
|
|
||
|
|
This code is distributed in the hope that it will be useful, but WITHOUT
|
||
|
|
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
||
|
|
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
||
|
|
version 2 for more details (a copy is included in the LICENSE file that
|
||
|
|
accompanied this code).
|
||
|
|
|
||
|
|
You should have received a copy of the GNU General Public License version
|
||
|
|
2 along with this work; if not, write to the Free Software Foundation,
|
||
|
|
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
||
|
|
|
||
|
|
Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
|
||
|
|
CA 95054 USA or visit www.sun.com if you need additional information or
|
||
|
|
have any questions.
|
||
|
|
-->
|
||
|
|
</head>
|
||
|
|
<body bgcolor="white">
|
||
|
|
<p>Provides the core classes for the Java Management Extensions.</p>
|
||
|
|
|
||
|
|
<p>The Java Management Extensions
|
||
|
|
(JMX<sup><font size="-1">TM</font></sup>) API is a standard
|
||
|
|
API for management and monitoring. Typical uses include:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>consulting and changing application configuration</li>
|
||
|
|
|
||
|
|
<li>accumulating statistics about application behavior and
|
||
|
|
making them available</li>
|
||
|
|
|
||
|
|
<li>notifying of state changes and erroneous conditions.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The JMX API can also be used as part of a solution for
|
||
|
|
managing systems, networks, and so on.</p>
|
||
|
|
|
||
|
|
<p>The API includes remote access, so a remote management
|
||
|
|
program can interact with a running application for these
|
||
|
|
purposes.</p>
|
||
|
|
|
||
|
|
<h2>MBeans</h2>
|
||
|
|
|
||
|
|
<p>The fundamental notion of the JMX API is the <em>MBean</em>.
|
||
|
|
An MBean is a named <em>managed object</em> representing a
|
||
|
|
resource. It has a <em>management interface</em> consisting
|
||
|
|
of:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>named and typed attributes that can be read and/or
|
||
|
|
written</li>
|
||
|
|
|
||
|
|
<li>named and typed operations that can be invoked</li>
|
||
|
|
|
||
|
|
<li>typed notifications that can be emitted by the MBean.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>For example, an MBean representing an application's
|
||
|
|
configuration could have attributes representing the different
|
||
|
|
configuration items. Reading the <code>CacheSize</code>
|
||
|
|
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
|
||
|
|
<code>save</code> could store the current configuration
|
||
|
|
persistently. A notification such as
|
||
|
|
<code>ConfigurationChangedNotification</code> could be sent
|
||
|
|
every time the configuration is changed.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Standard MBeans</h3>
|
||
|
|
|
||
|
|
<p>To make MBean implementation simple, the JMX API includes the
|
||
|
|
notion of <em>Standard MBeans</em>. 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<sup><font size="-1">TM</font></sup>. For
|
||
|
|
example, consider an interface like this:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
public interface ConfigurationMBean {
|
||
|
|
public int getCacheSize();
|
||
|
|
public void setCacheSize(int size);
|
||
|
|
public long getLastChangedTime();
|
||
|
|
public void save();
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>The methods <code>getCacheSize</code> and
|
||
|
|
<code>setCacheSize</code> define a read-write attribute of
|
||
|
|
type <code>int</code> called <code>CacheSize</code> (with an
|
||
|
|
initial capital, unlike the JavaBeans convention).</p>
|
||
|
|
|
||
|
|
<p>The method <code>getLastChangedTime</code> defines an
|
||
|
|
attribute of type <code>long</code> called
|
||
|
|
<code>LastChangedTime</code>. This is a read-only attribute,
|
||
|
|
since there is no method <code>setLastChangedTime</code>.</p>
|
||
|
|
|
||
|
|
<p>The method <code>save</code> defines an operation called
|
||
|
|
<code>save</code>. It is not an attribute, since its name
|
||
|
|
does not begin with <code>get</code>, <code>set</code>, or
|
||
|
|
<code>is</code>.</p>
|
||
|
|
|
||
|
|
<p>The exact naming patterns for Standard MBeans are detailed in
|
||
|
|
the <a href="#spec">JMX Specification</a>.</p>
|
||
|
|
|
||
|
|
<p>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 <code>MBean</code> suffix. So in
|
||
|
|
the example the object would be of the class
|
||
|
|
<code>Configuration</code>, in the same Java package as
|
||
|
|
<code>ConfigurationMBean</code>. The second way is to use the
|
||
|
|
{@link javax.management.StandardMBean StandardMBean}
|
||
|
|
class.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>MXBeans</h3>
|
||
|
|
|
||
|
|
<p>An <em>MXBean</em> 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}.
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Dynamic MBeans</h3>
|
||
|
|
|
||
|
|
<p>A <em>Dynamic MBean</em> 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.</p>
|
||
|
|
|
||
|
|
<p>Any Java object of a class that implements the {@link
|
||
|
|
javax.management.DynamicMBean DynamicMBean} interface is a
|
||
|
|
Dynamic MBean.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Open MBeans</h3>
|
||
|
|
|
||
|
|
<p>An <em>Open MBean</em> 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 <a href="openmbean/package-summary.html"><code>
|
||
|
|
javax.management.openmbean</code></a>.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Model MBeans</h3>
|
||
|
|
|
||
|
|
<p>A <em>Model MBean</em> 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
|
||
|
|
<a href="modelmbean/package-summary.html"><code>
|
||
|
|
javax.management.modelmbean</code></a>.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h2>MBean Server</h2>
|
||
|
|
|
||
|
|
<p>To be useful, an MBean must be registered in an <em>MBean
|
||
|
|
Server</em>. 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.</p>
|
||
|
|
|
||
|
|
<p>An MBean Server is an object implementing the interface
|
||
|
|
{@link javax.management.MBeanServer MBeanServer}.
|
||
|
|
The most convenient MBean Server to use is the
|
||
|
|
<em>Platform MBean Server</em>. 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()}.</p>
|
||
|
|
|
||
|
|
<p>Application code can also create a new MBean Server, or
|
||
|
|
access already-created MBean Servers, using the {@link
|
||
|
|
javax.management.MBeanServerFactory MBeanServerFactory} class.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Creating MBeans in the MBean Server</h3>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>The <code>registerMBean</code> method is simpler for local
|
||
|
|
use, but cannot be used remotely. The
|
||
|
|
<code>createMBean</code> method can be used remotely, but
|
||
|
|
sometimes requires attention to class loading issues.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Accessing MBeans in the MBean Server</h3>
|
||
|
|
|
||
|
|
<p>Given an <code>ObjectName</code> <code>name</code> and an
|
||
|
|
<code>MBeanServer</code> <code>mbs</code>, you can access
|
||
|
|
attributes and operations as in this example:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
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]);
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>Alternatively, if you have a Java interface that corresponds
|
||
|
|
to the management interface for the MBean, you can use an
|
||
|
|
<em>MBean proxy</em> like this:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
ConfigurationMBean conf =
|
||
|
|
{@link javax.management.JMX#newMBeanProxy
|
||
|
|
JMX.newMBeanProxy}(mbs, name, ConfigurationMBean.class);
|
||
|
|
int cacheSize = conf.getCacheSize();
|
||
|
|
conf.setCacheSize(2000);
|
||
|
|
conf.save();
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>Using an MBean proxy is just a convenience. The second
|
||
|
|
example ends up calling the same <code>MBeanServer</code>
|
||
|
|
operations as the first one.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h2>Notifications</h2>
|
||
|
|
|
||
|
|
<p>A <em>notification</em> is an instance of the {@link
|
||
|
|
javax.management.Notification Notification} class or a
|
||
|
|
subclass. In addition to its Java class, it has a
|
||
|
|
<em>type</em> string that can distinguish it from other
|
||
|
|
notifications of the same class.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>Notifications can be received by a <em>listener</em>, 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 <em>filter</em> to this method, to
|
||
|
|
select only notifications of interest. A filter is an object
|
||
|
|
that implements the {@link javax.management.NotificationFilter
|
||
|
|
NotificationFilter} interface.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h2>Remote Access to MBeans</h2>
|
||
|
|
|
||
|
|
<p>An MBean Server can be accessed remotely through a
|
||
|
|
<em>connector</em>. A connector allows a remote Java
|
||
|
|
application to access an MBean Server in essentially the same
|
||
|
|
way as a local one. The package
|
||
|
|
<a href="remote/package-summary.html"><code>
|
||
|
|
javax.management.remote</code></a> defines connectors.</p>
|
||
|
|
|
||
|
|
<p>The JMX specification also defines the notion of an
|
||
|
|
<em>adaptor</em>. 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
|
||
|
|
<code>getAttribute</code> on the MBean Server.</p>
|
||
|
|
|
||
|
|
<p id="spec">
|
||
|
|
@see <a href="{@docRoot}/../technotes/guides/jmx/index.html">
|
||
|
|
Java SE 6 Platform documentation on JMX technology</a>
|
||
|
|
in particular the
|
||
|
|
<a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
|
||
|
|
JMX Specification, version 1.4(pdf).</a>
|
||
|
|
|
||
|
|
@since 1.5
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|