4230N/ACopyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved. 0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/AThis code is free software; you can redistribute it and/or modify it 0N/Aunder the terms of the GNU General Public License version 2 only, as 2362N/Apublished by the Free Software Foundation. Oracle designates this 0N/Aparticular file as subject to the "Classpath" exception as provided 2362N/Aby Oracle in the LICENSE file that accompanied this code. 0N/AThis code is distributed in the hope that it will be useful, but WITHOUT 0N/AANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/AFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/Aversion 2 for more details (a copy is included in the LICENSE file that 0N/Aaccompanied this code). 0N/AYou should have received a copy of the GNU General Public License version 0N/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. 2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 700N/A <
p>Provides the core classes for the Java Management Extensions.</
p>
700N/A <
p>The Java Management Extensions
700N/A (JMX<
sup><
font size="-1">TM</
font></
sup>) API is a standard
700N/A API for management and monitoring. Typical uses include:</
p>
700N/A <
li>consulting and changing application configuration</
li>
700N/A <
li>accumulating statistics about application behavior and
700N/A making them available</
li>
700N/A <
li>notifying of state changes and erroneous conditions.</
li>
700N/A <
p>The JMX API can also be used as part of a solution for
700N/A managing systems, networks, and so on.</
p>
700N/A <
p>The API includes remote access, so a remote management
700N/A program can interact with a running application for these
700N/A <
p>The fundamental notion of the JMX API is the <
em>MBean</
em>.
700N/A An MBean is a named <
em>managed object</
em> representing a
700N/A resource. It has a <
em>management interface</
em> consisting
406N/A <
li>named and typed attributes that can be read
and/
or 406N/A <
li>named and typed operations that can be invoked</
li>
406N/A <
li>typed notifications that can be emitted by the MBean.</
li>
406N/A <
p>For example, an MBean representing an application's
406N/A configuration could have attributes representing the different
406N/A configuration items. Reading the <
code>CacheSize</
code>
406N/A attribute would return the current value of that item.
406N/A Writing it would update the item, potentially changing the
406N/A behavior of the running application. An operation such as
406N/A <
code>save</
code> could store the current configuration
406N/A persistently. A notification such as
406N/A <
code>ConfigurationChangedNotification</
code> could be sent
406N/A every time the configuration is changed.</
p>
406N/A <
p>In the standard usage of the JMX API, MBeans are implemented
406N/A as Java objects. However, as explained below, these objects are
406N/A not usually referenced directly.</
p>
406N/A <
h3>Standard MBeans</
h3>
406N/A <
p>To make MBean implementation simple, the JMX API includes the
406N/A notion of <
em>Standard MBeans</
em>. A Standard MBean is one
406N/A whose attributes and operations are deduced from a Java
406N/A interface using certain naming patterns, similar to those used
406N/A by JavaBeans<
sup><
font size="-1">TM</
font></
sup>. For
406N/A example, consider an interface like this:</
p>
0N/A public interface ConfigurationMBean {
700N/A public int getCacheSize();
700N/A public void setCacheSize(int size);
700N/A public long getLastChangedTime();
700N/A <
p>The methods <
code>getCacheSize</
code> and
700N/A <
code>setCacheSize</
code> define a read-write attribute of
700N/A type <
code>int</
code> called <
code>CacheSize</
code> (with an
700N/A initial capital, unlike the JavaBeans convention).</
p>
700N/A <
p>The method <
code>getLastChangedTime</
code> defines an
700N/A attribute of type <
code>long</
code> called
700N/A <
code>LastChangedTime</
code>. This is a read-only attribute,
700N/A since there is no method <
code>setLastChangedTime</
code>.</
p>
700N/A <
p>The method <
code>save</
code> defines an operation called
700N/A <
code>save</
code>. It is not an attribute, since its name
700N/A does not begin with <
code>get</
code>, <
code>set</
code>, or
700N/A <
p>The exact naming patterns for Standard MBeans are detailed in
700N/A the <
a href="#spec">JMX Specification</
a>.</
p>
700N/A <
p>There are two ways to make a Java object that is an MBean
700N/A with this management interface. One is for the object to be
700N/A of a class that has exactly the same name as the Java
700N/A interface but without the <
code>MBean</
code> suffix. So in
700N/A the example the object would be of the class
700N/A <
code>Configuration</
code>, in the same Java package as
700N/A <
code>ConfigurationMBean</
code>. The second way is to use the
406N/A <
p>An <
em>MXBean</
em> is a variant of Standard MBean where complex
406N/A types are mapped to a standard set of types defined in the
406N/A if you would otherwise need to reference application-specific
406N/A classes in your MBean interface. They are described in detail
406N/A <
h3>Dynamic MBeans</
h3>
406N/A <
p>A <
em>Dynamic MBean</
em> is an MBean that defines its
406N/A management interface at run-time. For example, a configuration
406N/A MBean could determine the names and types of the attributes it
406N/A exposes by parsing an XML file.</
p>
406N/A <
p>Any Java object of a class that implements the {@link
406N/A <
p>An <
em>Open MBean</
em> is a kind of Dynamic MBean where the
406N/A types of attributes and of operation parameters and return
406N/A values are built using a small set of predefined Java classes.
406N/A Open MBeans facilitate operation with remote management programs
406N/A that do not necessarily have access to application-specific
406N/A types, including non-Java programs. Open MBeans are defined by
406N/A <
p>A <
em>Model MBean</
em> is a kind of Dynamic MBean that acts
406N/A as a bridge between the management interface and the
406N/A underlying managed resource. Both the management interface and
406N/A the managed resource are specified as Java objects. The same
406N/A Model MBean implementation can be reused many times with
406N/A different management interfaces and managed resources, and it can
406N/A provide common functionality such as persistence and caching.
406N/A Model MBeans are defined by the package
406N/A <
p>To be useful, an MBean must be registered in an <
em>MBean
406N/A Server</
em>. An MBean Server is a repository of MBeans.
406N/A Usually the only access to the MBeans is through the MBean
406N/A Server. In other words, code no longer accesses the Java
406N/A object implementing the MBean directly, but instead accesses
406N/A the MBean by name through the MBean Server. Each MBean has a
406N/A unique name within the MBean Server, defined by the {@link
406N/A <
p>An MBean Server is an object implementing the interface
406N/A The most convenient MBean Server to use is the
406N/A <
em>Platform MBean Server</
em>. This is a
406N/A single MBean Server that can be shared by different managed
406N/A components running within the same Java Virtual Machine. The
406N/A Platform MBean Server is accessed with the method {@link
406N/A <
p>Application code can also create a new MBean Server, or
406N/A access already-created MBean Servers, using the {@link
406N/A <
h3>Creating MBeans in the MBean Server</
h3>
406N/A <
p>There are two ways to create an MBean. One is to construct a
406N/A Java object that will be the MBean, then use the {@link
406N/A method to register it in the MBean Server. The other is to
406N/A create and register the MBean in a single operation using one
406N/A <
p>The <
code>registerMBean</
code> method is simpler for local
406N/A use, but cannot be used remotely. The
406N/A <
code>createMBean</
code> method can be used remotely, but
406N/A sometimes requires attention to class loading issues.</
p>
406N/A <
p>An MBean can perform actions when it is registered in or
406N/A unregistered from an MBean Server if it implements the {@link
406N/A <
h3>Accessing MBeans in the MBean Server</
h3>
406N/A <
p>Given an <
code>ObjectName</
code> <
code>name</
code> and an
406N/A <
code>MBeanServer</
code> <
code>mbs</
code>, you can access
406N/A attributes and operations as in this example:</
p>
700N/A new Attribute("CacheSize", new Integer(2000));
406N/A <
p id="proxy">Alternatively, if you have a Java interface that
406N/A corresponds to the management interface for the MBean, you can use an
406N/A <
em>MBean proxy</
em> like this:</
p>
0N/A ConfigurationMBean conf =
700N/A <
p>Using an MBean proxy is just a convenience. The second
700N/A example ends up calling the same <
code>MBeanServer</
code>
700N/A operations as the first one.</
p>
700N/A <
p>An MBean Server can be queried for MBeans whose names match
700N/A certain patterns
and/
or whose attributes meet certain
700N/A constraints. Name patterns are constructed using the {@link
700N/A class. The methods {@link
406N/A MBeanRegistration} interface in order to be told when it is registered
406N/A and unregistered in the MBean Server. Additionally, the {@link
406N/A allows the MBean to get a reference to the <
code>MBeanServer</
code>
406N/A object and to get its <
code>ObjectName</
code> within the MBean
406N/A <
p>A <
em>notification</
em> is an instance of the {@link
406N/A subclass. In addition to its Java class, it has a
406N/A <
em>type</
em> string that can distinguish it from other
406N/A notifications of the same class.</
p>
1790N/A <
p>An MBean that will emit notifications must implement the
1790N/A NotificationBroadcaster} or {@link
1790N/A interface. Usually, it does this by subclassing
1790N/A NotificationBroadcasterSupport} or delegating to an instance of
1790N/A that class. Here is an example:</
p>
406N/A public class Configuration <
b>extends NotificationBroadcasterSupport</
b>
406N/A implements ConfigurationMBean {
406N/A private void updated() {
406N/A Notification n = new Notification(...);
406N/A sendNotification}(n)</
b>;
406N/A <
p>Notifications can be received by a <
em>listener</
em>, which
406N/A is an object that implements the {@link
406N/A interface. You can add a listener to an MBean with the method
406N/A NotificationListener, NotificationFilter, Object)}.
406N/A You can optionally supply a <
em>filter</
em> to this method, to
406N/A select only notifications of interest. A filter is an object
406N/A NotificationFilter} interface.</
p>
406N/A <
p>An MBean can be a listener for notifications emitted by other
406N/A MBeans in the same MBean Server. In this case, it implements
406N/A NotificationListener} and the method {@link
406N/A ObjectName, NotificationFilter, Object)} is used to listen.</
p>
406N/A <
h2>Remote Access to MBeans</
h2>
406N/A <
p>An MBean Server can be accessed remotely through a
406N/A <
em>connector</
em>. A connector allows a remote Java
406N/A application to access an MBean Server in essentially the same
406N/A way as a local one. The package
406N/A <
p>The JMX specification also defines the notion of an
406N/A <
em>adaptor</
em>. An adaptor translates between requests in a
406N/A protocol such as SNMP or HTML and accesses to an MBean Server.
406N/A So for example an SNMP GET operation might result in a
406N/A <
code>getAttribute</
code> on the MBean Server.</
p>
700N/A <
h3 id="interop">Interoperability between versions of the JMX
1790N/A <
p>When a client connects to a server using the JMX Remote
1790N/A API, it is possible that they do not have the same version
1790N/A of the JMX specification. The version of the JMX
1790N/A specification described here is version 1.4. Previous
1790N/A versions were 1.0, 1.1, and 1.2. (There was no 1.3.)
1790N/A The standard JMX Remote API is defined to work with version
1790N/A 1.2 onwards, so in standards-based deployment the only
1790N/A interoperability questions that arise concern version 1.2
1790N/A <
p>Every version of the JMX specification continues to
1790N/A implement the features of previous versions. So when the
1790N/A client is running an earlier version than the server, there
1790N/A should not be any interoperability concerns.</
p>
1790N/A <
p>When the client is running a later version than the server,
1790N/A certain newer features may not be available, as detailed in
1790N/A the next sections. The client can determine the server's
1790N/A version by examining the {@link
1790N/A SpecificationVersion} attribute of the {@code
1790N/A <
h4 id="interop-1.2">If the remote MBean Server is 1.2</
h4>
1790N/A <
li><
p>You cannot use wildcards in a key property of an
1790N/A example {@code domain:type=Foo,name=*}. Wildcards that
1790N/A match whole properties are still allowed, for example
1790N/A {@code *:*} or {@code *:type=Foo,*}.</
p>
1790N/A <
li><
p>You cannot use {@link
1790N/A <
li><
p>You cannot use dot syntax such as {@code
1790N/A observed attribute} of a monitor, as described in the
4230N/A Java Platform documentation on JMX technology</
a>
406N/A JMX Specification, version 1.4(pdf).</
a>