<html>    <head>        <title>javax.management package</title>        <!--Copyright (c) 1999, 2011, 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 itunder the terms of the GNU General Public License version 2 only, aspublished by the Free Software Foundation.  Oracle designates thisparticular file as subject to the "Classpath" exception as providedby Oracle in the LICENSE file that accompanied this code. This code is distributed in the hope that it will be useful, but WITHOUTANY WARRANTY; without even the implied warranty of MERCHANTABILITY orFITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public Licenseversion 2 for more details (a copy is included in the LICENSE file thataccompanied this code). You should have received a copy of the GNU General Public License version2 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USAor visit www.oracle.com if you need additional information or have anyquestions.        -->    </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 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>