javax/management/package.html

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