| <html> |
| <head> |
| <title>javax.management package</title> |
| <!-- |
| Copyright (c) 1999, 2006, Oracle and/or its affiliates. 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. Oracle designates this |
| particular file as subject to the "Classpath" exception as provided |
| by Oracle 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}.</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</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> |
| |
| |
| <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 delegating to an instance of |
| that class. Here is an example:</p> |
| |
| <pre> |
| 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>; |
| } |
| } |
| </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 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 |
| 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.</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 |
| javax.management.MBeanServerDelegateMBean#getSpecificationVersion |
| SpecificationVersion} attribute of the {@code |
| MBeanServerDelegate}.</p> |
| |
| <h4 id="interop-1.2">If the remote MBean Server is 1.2</h4> |
| |
| <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> |
