3516N/ACopyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved. 3516N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3516N/AThis code is free software; you can redistribute it and/or modify it 3516N/Aunder the terms of the GNU General Public License version 2 only, as 3516N/Apublished by the Free Software Foundation. Oracle designates this 3516N/Aparticular file as subject to the "Classpath" exception as provided 3516N/Aby Oracle in the LICENSE file that accompanied this code. 3516N/AThis code is distributed in the hope that it will be useful, but WITHOUT 3516N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 4986N/Aversion 2 for more details (a copy is included in the LICENSE file that 0N/Aaccompanied this code). 4986N/AYou should have received a copy of the GNU General Public License version 4986N/A2 along with this work; if not, write to the Free Software Foundation, 0N/AInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 3516N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A <
p>Provides the core classes for the Java Management Extensions.</
p>
4986N/A <
p>The Java Management Extensions
4986N/A (JMX<
sup><
font size="-1">TM</
font></
sup>) API is a standard
4986N/A API for management and monitoring. Typical uses include:</
p>
3516N/A <
li>consulting and changing application configuration</
li>
4986N/A <
li>accumulating statistics about application behavior and
3516N/A <
li>notifying of state changes and erroneous conditions.</
li>
4986N/A <
p>The JMX API can also be used as part of a solution for
4986N/A managing systems, networks, and so on.</
p>
0N/A <
p>The API includes remote access, so a remote management
4986N/A program can interact with a running application for these
4986N/A <
p>The fundamental notion of the JMX API is the <
em>MBean</
em>.
4986N/A An MBean is a named <
em>managed object</
em> representing a
4986N/A resource. It has a <
em>management interface</
em> consisting
4986N/A <
li>named and typed attributes that can be read
and/
or 0N/A <
li>named and typed operations that can be invoked</
li>
4986N/A <
li>typed notifications that can be emitted by the MBean.</
li>
0N/A <
p>For example, an MBean representing an application's
3516N/A configuration could have attributes representing the different
3516N/A configuration items. Reading the <
code>CacheSize</
code>
0N/A attribute would return the current value of that item.
0N/A Writing it would update the item, potentially changing the
3915N/A behavior of the running application. An operation such as
0N/A <
code>save</
code> could store the current configuration
0N/A persistently. A notification such as
0N/A <
code>ConfigurationChangedNotification</
code> could be sent
0N/A every time the configuration is changed.</
p>
0N/A <
p>In the standard usage of the JMX API, MBeans are implemented
0N/A as Java objects. However, as explained below, these objects are
0N/A not usually referenced directly.</
p>
0N/A <
h3>Standard MBeans</
h3>
0N/A <
p>To make MBean implementation simple, the JMX API includes the
0N/A notion of <
em>Standard MBeans</
em>. A Standard MBean is one
0N/A whose attributes and operations are deduced from a Java
0N/A interface using certain naming patterns, similar to those used
0N/A by JavaBeans<
sup><
font size="-1">TM</
font></
sup>. For
0N/A example, consider an interface like this:</
p>
0N/A public interface ConfigurationMBean {
0N/A public int getCacheSize();
0N/A public void setCacheSize(int size);
0N/A public long getLastChangedTime();
0N/A <
p>The methods <
code>getCacheSize</
code> and
0N/A <
code>setCacheSize</
code> define a read-write attribute of
0N/A type <
code>int</
code> called <
code>CacheSize</
code> (with an
0N/A initial capital, unlike the JavaBeans convention).</
p>
0N/A <
p>The method <
code>getLastChangedTime</
code> defines an
0N/A attribute of type <
code>long</
code> called
0N/A <
code>LastChangedTime</
code>. This is a read-only attribute,
0N/A since there is no method <
code>setLastChangedTime</
code>.</
p>
0N/A <
p>The method <
code>save</
code> defines an operation called
0N/A <
code>save</
code>. It is not an attribute, since its name
0N/A does not begin with <
code>get</
code>, <
code>set</
code>, or
0N/A <
code>is</
code>.</
p>
0N/A <
p>The exact naming patterns for Standard MBeans are detailed in
0N/A the <
a href="#spec">JMX Specification</
a>.</
p>
0N/A <
p>There are two ways to make a Java object that is an MBean
0N/A with this management interface. One is for the object to be
3516N/A of a class that has exactly the same name as the Java
3516N/A interface but without the <
code>MBean</
code> suffix. So in
3516N/A the example the object would be of the class
3516N/A <
code>Configuration</
code>, in the same Java package as
3516N/A <
code>ConfigurationMBean</
code>. The second way is to use the
3516N/A <
p>An <
em>MXBean</
em> is a variant of Standard MBean where complex
3516N/A types are mapped to a standard set of types defined in the
3516N/A if you would otherwise need to reference application-specific
3516N/A classes in your MBean interface. They are described in detail
3516N/A <
p>A <
em>Dynamic MBean</
em> is an MBean that defines its
3516N/A management interface at run-time. For example, a configuration
3516N/A MBean could determine the names and types of the attributes it
3516N/A exposes by parsing an XML file.</
p>
3516N/A <
p>Any Java object of a class that implements the {@link
3516N/A <
p>An <
em>Open MBean</
em> is a kind of Dynamic MBean where the
3516N/A types of attributes and of operation parameters and return
0N/A values are built using a small set of predefined Java classes.
0N/A Open MBeans facilitate operation with remote management programs
0N/A that do not necessarily have access to application-specific
3516N/A types, including non-Java programs. Open MBeans are defined by
3516N/A <
p>A <
em>Model MBean</
em> is a kind of Dynamic MBean that acts
3516N/A as a bridge between the management interface and the
0N/A underlying managed resource. Both the management interface and
3516N/A the managed resource are specified as Java objects. The same
3516N/A Model MBean implementation can be reused many times with
3516N/A different management interfaces and managed resources, and it can
3516N/A provide common functionality such as persistence and caching.
3516N/A Model MBeans are defined by the package
0N/A <
h2>MBean Server</
h2>
3516N/A <
p>To be useful, an MBean must be registered in an <
em>MBean
3516N/A Server</
em>. An MBean Server is a repository of MBeans.
3915N/A 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
<
p>An MBean Server is an object implementing the interface
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
<
p>Application code can also create a new MBean Server, or
access already-created MBean Servers, using the {@link
<
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
method to register it in the MBean Server. The other is to
create and register the MBean in a single operation using one
<
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
<
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>
new Attribute("CacheSize", new Integer(2000));
mbs.invoke(name, "save", new Object[0], new Class[0]);
<
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>
ConfigurationMBean conf =
<
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
class. The methods {@link
MBeanRegistration} interface in order to be told when it is registered
and unregistered in the MBean Server. Additionally, the {@link
allows the MBean to get a reference to the <
code>MBeanServer</
code>
object and to get its <
code>ObjectName</
code> within the MBean
<
p>A <
em>notification</
em> is an instance of the {@link
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
NotificationBroadcaster} or {@link
interface. Usually, it does this by subclassing
NotificationBroadcasterSupport} or delegating to an instance of
that class. Here is an example:</
p>
public class Configuration <
b>extends NotificationBroadcasterSupport</
b>
implements ConfigurationMBean {
Notification n = new Notification(...);
sendNotification}(n)</
b>;
<
p>Notifications can be received by a <
em>listener</
em>, which
is an object that implements the {@link
interface. You can add a listener to an MBean with the method
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
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
NotificationListener} and the method {@link
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
<
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
<
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 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
<
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.</
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 client can determine the server's
version by examining the {@link
SpecificationVersion} attribute of the {@code
MBeanServerDelegate}.</
p>
<
h4 id="interop-1.2">If the remote MBean Server is 1.2</
h4>
<
li><
p>You cannot use wildcards in a key property of an
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
<
li><
p>You cannot use dot syntax such as {@code
observed attribute} of a monitor, as described in the
Java Platform documentation on JMX technology</
a>
JMX Specification, version 1.4(pdf).</
a>