javax/management/package.html

	package.html revision 700
0N/A<html>
0N/A    <head>
0N/A        <title>javax.management package</title>
0N/A        <!--
0N/ACopyright 1999-2006 Sun Microsystems, Inc.  All Rights Reserved.
0N/ADO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A
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
0N/Apublished by the Free Software Foundation.  Sun designates this
0N/Aparticular file as subject to the "Classpath" exception as provided
0N/Aby Sun in the LICENSE file that accompanied this code.
0N/A
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/A
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.
0N/A
0N/APlease contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0N/ACA 95054 USA or visit www.sun.com if you need additional information or
0N/Ahave any questions.
0N/A        -->
0N/A    </head>
0N/A    <body bgcolor="white">
0N/A        <p>Provides the core classes for the Java Management Extensions.</p>
0N/A
0N/A        <p>The Java Management Extensions
0N/A            (JMX<sup><font size="-1">TM</font></sup>) API is a standard
0N/A        API for management and monitoring.  Typical uses include:</p>
0N/A
0N/A        <ul>
0N/A            <li>consulting and changing application configuration</li>
0N/A
0N/A            <li>accumulating statistics about application behavior and
0N/A            making them available</li>
0N/A
0N/A            <li>notifying of state changes and erroneous conditions.</li>
0N/A        </ul>
0N/A
0N/A        <p>The JMX API can also be used as part of a solution for
0N/A        managing systems, networks, and so on.</p>
0N/A
0N/A        <p>The API includes remote access, so a remote management
0N/A            program can interact with a running application for these
0N/A        purposes.</p>
0N/A
0N/A        <h2>MBeans</h2>
0N/A
0N/A        <p>The fundamental notion of the JMX API is the <em>MBean</em>.
0N/A            An MBean is a named <em>managed object</em> representing a
0N/A            resource.  It has a <em>management interface</em> consisting
0N/A        of:</p>
0N/A
0N/A        <ul>
0N/A            <li>named and typed attributes that can be read and/or
0N/A            written</li>
0N/A
0N/A            <li>named and typed operations that can be invoked</li>
0N/A
0N/A            <li>typed notifications that can be emitted by the MBean.</li>
0N/A        </ul>
0N/A
0N/A        <p>For example, an MBean representing an application's
0N/A            configuration could have attributes representing the different
0N/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
0N/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
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
0N/A
0N/A        <h3>Standard MBeans</h3>
0N/A
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>

        <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 id="stdannot">Defining Standard MBeans with annotations</h3>

        <p>As an alternative to creating an interface such as
            <code>ConfigurationMBean</code> and a class that implements it,
            you can write just the class, and use annotations to pick out the
            public methods that will make up the management interface. For
            example, the following class has the same management interface
            as a <code>Configuration</code> class that implements the
        <code>ConfigurationMBean</code> interface above.</p>

        <pre>
    {@link javax.management.MBean @MBean}
    public class Configuration {
        {@link javax.management.ManagedAttribute @ManagedAttribute}
        public int getCacheSize() {...}
        &#64;ManagedAttribute
        public void setCacheSize(int size) {...}

        &#64;ManagedAttribute
        public long getLastChangedTime() {...}

        {@link javax.management.ManagedOperation @ManagedOperation}
        public void save() {...}
        ...
    }
        </pre>

        <p>This approach simplifies development, but it does have two
            potential drawbacks.  First, if you run the Javadoc tool on
            this class, the documentation of the management interface may
            be mixed in with the documentation of non-management methods
            in the class.  Second, you cannot make a proxy
            as described <a href="#proxy">below</a> if you do not have an
        interface like <code>ConfigurationMBean</code>.</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>

        <p>You can define MXBeans using annotations as described
            in the <a href="#stdannot">previous section</a>, but
            using the <code>&#64;MXBean</code> annotation instead of
        <code>&#64;MBean</code>.</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 and resource injection</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>

        <p>If the only reason to implement <code>MBeanRegistration</code> is to
            discover the <code>MBeanServer</code> and <code>ObjectName</code>, <a
                href="MBeanRegistration.html#injection">resource injection</a> may be
        more convenient.</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>If an MBean is to emit notifications, it must do one of two things.</p>

        <ul>
            <li>It can implement the interface {@link
                javax.management.NotificationEmitter NotificationEmitter} (or
                its parent {@link javax.management.NotificationBroadcaster
                NotificationBroadcaster}), usually by subclassing
                {@link javax.management.NotificationBroadcasterSupport
                NotificationBroadcasterSupport} or delegating to an instance of
            that class.</li>
            <li>It can use <a href="MBeanRegistration.html#injection">resource
                injection</a> to obtain a {@link javax.management.SendNotification
                SendNotification} object that it can use to send
            notifications.</li>
        </ul>

        <p>The two classes below illustrate these two techniques:</p>

        <pre>
    // Implementing NotificationEmitter (via NotificationBroadcasterSupport)
    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>;
        }
    }

    // Getting a SendNotification through resource injection
    public class Configuration implements ConfigurationMBean {
        <b>&#64;Resource</b>
        private volatile SendNotification sender;
        ...
        private void updated() {
            Notification n = new Notification(...);
            <b>sender.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 2.0.  Previous
      versions were 1.0, 1.1, 1.2, and 1.4.  (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.  The only
      exception is the unlikely one where a pre-2.0 client used
      the string {@code //} in the domain part of an {@link
      javax.management.ObjectName ObjectName}.</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 method {@link
      javax.management.JMX#getSpecificationVersion
      JMX.getSpecificationVersion} can be used to determine the
      server version to check if required features are
      available.</p>

    <h4 id="interop-1.4">If the remote MBean Server is 1.4</h4>

    <ul>

      <li><p>You cannot use {@link
          javax.management.QueryNotificationFilter
          QueryNotificationFilter} in {@link
          javax.management.MBeanServerConnection#addNotificationListener
          addNotificationListener} since this class did not exist
          in 1.4.</p>

      <li><p>In an attribute in a query, you cannot access values
          inside complex types using dot syntax, for example
          {@link javax.management.Query#attr Query.attr}{@code
          ("HeapMemoryUsage.used")}.</p>

      <li><p>The packages {@link javax.management.event} and
          {@link javax.management.namespace} did not exist in 1.4,
          so you cannot remotely create instances of the MBeans
          they define.</p>

      <li><p>Even if the remote MBean Server is 2.0, you cannot in
          general suppose that {@link
          javax.management.event.EventClient EventClient} or
          {@link javax.management.ClientContext ClientContext}
          will work there without first checking. If the remote
          MBean Server is 1.4 then those checks will return false.
          An attempt to use these features without checking will
          fail in the same way as for a remote 2.0 that is not
          configured to support them.</p>
    </ul>

    <h4 id="interop-1.2">If the remote MBean Server is 1.2</h4>

    <p><b>In addition to the above</b>,</p>

    <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>