bbac59f218
6750008: Add JMX.getSpecificationVersion(MBeanServerConnection) and document interop 6750472: Add a way to convert a CompositeData into a Map 6752563: Allow CompositeDataSupport to have zero items Small JMX RFEs Reviewed-by: dfuchs
507 lines
22 KiB
HTML
507 lines
22 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 id="stdannot">Defining Standard MBeans with annotations</h3>
|
|
|
|
<p>As an alternative to creating an interface such as
|
|
<code>ConfigurationMBean</code> and a class that implements it,
|
|
you can write just the class, and use annotations to pick out the
|
|
public methods that will make up the management interface. For
|
|
example, the following class has the same management interface
|
|
as a <code>Configuration</code> class that implements the
|
|
<code>ConfigurationMBean</code> interface above.</p>
|
|
|
|
<pre>
|
|
{@link javax.management.MBean @MBean}
|
|
public class Configuration {
|
|
{@link javax.management.ManagedAttribute @ManagedAttribute}
|
|
public int getCacheSize() {...}
|
|
@ManagedAttribute
|
|
public void setCacheSize(int size) {...}
|
|
|
|
@ManagedAttribute
|
|
public long getLastChangedTime() {...}
|
|
|
|
{@link javax.management.ManagedOperation @ManagedOperation}
|
|
public void save() {...}
|
|
...
|
|
}
|
|
</pre>
|
|
|
|
<p>This approach simplifies development, but it does have two
|
|
potential drawbacks. First, if you run the Javadoc tool on
|
|
this class, the documentation of the management interface may
|
|
be mixed in with the documentation of non-management methods
|
|
in the class. Second, you cannot make a proxy
|
|
as described <a href="#proxy">below</a> if you do not have an
|
|
interface like <code>ConfigurationMBean</code>.</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}.</p>
|
|
|
|
<p>You can define MXBeans using annotations as described
|
|
in the <a href="#stdannot">previous section</a>, but
|
|
using the <code>@MXBean</code> annotation instead of
|
|
<code>@MBean</code>.</p>
|
|
|
|
|
|
<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 id="proxy">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>
|
|
|
|
|
|
<h3>MBean lifecycle and resource injection</h3>
|
|
|
|
<p>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 <code>MBeanServer</code>
|
|
object and to get its <code>ObjectName</code> within the MBean
|
|
Server.</p>
|
|
|
|
<p>If the only reason to implement <code>MBeanRegistration</code> is to
|
|
discover the <code>MBeanServer</code> and <code>ObjectName</code>, <a
|
|
href="MBeanRegistration.html#injection">resource injection</a> may be
|
|
more convenient.</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>If an MBean is to emit notifications, it must do one of two things.</p>
|
|
|
|
<ul>
|
|
<li>It can implement the interface {@link
|
|
javax.management.NotificationEmitter NotificationEmitter} (or
|
|
its parent {@link javax.management.NotificationBroadcaster
|
|
NotificationBroadcaster}), usually by subclassing
|
|
{@link javax.management.NotificationBroadcasterSupport
|
|
NotificationBroadcasterSupport} or delegating to an instance of
|
|
that class.</li>
|
|
<li>It can use <a href="MBeanRegistration.html#injection">resource
|
|
injection</a> to obtain a {@link javax.management.SendNotification
|
|
SendNotification} object that it can use to send
|
|
notifications.</li>
|
|
</ul>
|
|
|
|
<p>The two classes below illustrate these two techniques:</p>
|
|
|
|
<pre>
|
|
// Implementing NotificationEmitter (via NotificationBroadcasterSupport)
|
|
public class Configuration <b>extends NotificationBroadcasterSupport</b>
|
|
implements ConfigurationMBean {
|
|
...
|
|
private void updated() {
|
|
Notification n = new Notification(...);
|
|
<b>{@link javax.management.NotificationBroadcasterSupport#sendNotification
|
|
sendNotification}(n)</b>;
|
|
}
|
|
}
|
|
|
|
// Getting a SendNotification through resource injection
|
|
public class Configuration implements ConfigurationMBean {
|
|
<b>@Resource</b>
|
|
private volatile SendNotification sender;
|
|
...
|
|
private void updated() {
|
|
Notification n = new Notification(...);
|
|
<b>sender.sendNotification(n)</b>;
|
|
}
|
|
}
|
|
</pre>
|
|
|
|
|
|
<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>
|
|
|
|
<h3 id="interop">Interoperability between versions of the JMX
|
|
specification</h3>
|
|
|
|
<p>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 2.0. Previous
|
|
versions were 1.0, 1.1, 1.2, and 1.4. (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.</p>
|
|
|
|
<p>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. The only
|
|
exception is the unlikely one where a pre-2.0 client used
|
|
the string {@code //} in the domain part of an {@link
|
|
javax.management.ObjectName ObjectName}.</p>
|
|
|
|
<p>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 method {@link
|
|
javax.management.JMX#getSpecificationVersion
|
|
JMX.getSpecificationVersion} can be used to determine the
|
|
server version to check if required features are
|
|
available.</p>
|
|
|
|
<h4 id="interop-1.4">If the remote MBean Server is 1.4</h4>
|
|
|
|
<ul>
|
|
|
|
<li><p>You cannot use {@link
|
|
javax.management.QueryNotificationFilter
|
|
QueryNotificationFilter} in {@link
|
|
javax.management.MBeanServerConnection#addNotificationListener
|
|
addNotificationListener} since this class did not exist
|
|
in 1.4.</p>
|
|
|
|
<li><p>In an attribute in a query, you cannot access values
|
|
inside complex types using dot syntax, for example
|
|
{@link javax.management.Query#attr Query.attr}{@code
|
|
("HeapMemoryUsage.used")}.</p>
|
|
|
|
<li><p>The packages {@link javax.management.event} and
|
|
{@link javax.management.namespace} did not exist in 1.4,
|
|
so you cannot remotely create instances of the MBeans
|
|
they define.</p>
|
|
|
|
<li><p>Even if the remote MBean Server is 2.0, you cannot in
|
|
general suppose that {@link
|
|
javax.management.event.EventClient EventClient} or
|
|
{@link javax.management.ClientContext ClientContext}
|
|
will work there without first checking. If the remote
|
|
MBean Server is 1.4 then those checks will return false.
|
|
An attempt to use these features without checking will
|
|
fail in the same way as for a remote 2.0 that is not
|
|
configured to support them.</p>
|
|
</ul>
|
|
|
|
<h4 id="interop-1.2">If the remote MBean Server is 1.2</h4>
|
|
|
|
<p><b>In addition to the above</b>,</p>
|
|
|
|
<ul>
|
|
|
|
<li><p>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,*}.</p>
|
|
|
|
<li><p>You cannot use {@link
|
|
javax.management.Query#isInstanceOf Query.isInstanceOf}
|
|
in a query.</p>
|
|
|
|
<li><p>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.</p>
|
|
|
|
</ul>
|
|
|
|
<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>
|