javax/management/package.html

0N/A<html>
700N/A    <head>
700N/A        <title>javax.management package</title>
700N/A        <!--
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/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
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/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
2365N/APlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2365N/Aor visit www.oracle.com if you need additional information or have any
2365N/Aquestions.
700N/A        -->
700N/A    </head>
700N/A    <body bgcolor="white">
700N/A        <p>Provides the core classes for the Java Management Extensions.</p>
0N/A
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>
0N/A
700N/A        <ul>
700N/A            <li>consulting and changing application configuration</li>
0N/A
700N/A            <li>accumulating statistics about application behavior and
700N/A            making them available</li>
0N/A
700N/A            <li>notifying of state changes and erroneous conditions.</li>
700N/A        </ul>
0N/A
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>
0N/A
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        purposes.</p>
0N/A
700N/A        <h2>MBeans</h2>
0N/A
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
700N/A        of:</p>
0N/A
406N/A        <ul>
406N/A            <li>named and typed attributes that can be read and/or
406N/A            written</li>
0N/A
406N/A            <li>named and typed operations that can be invoked</li>
406N/A
406N/A            <li>typed notifications that can be emitted by the MBean.</li>
406N/A        </ul>
0N/A
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>
0N/A
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>
0N/A
0N/A
406N/A        <h3>Standard MBeans</h3>
0N/A
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
406N/A        <pre>
0N/A    public interface ConfigurationMBean {
700N/A         public int getCacheSize();
700N/A         public void setCacheSize(int size);
700N/A         public long getLastChangedTime();
700N/A         public void save();
0N/A    }
700N/A        </pre>
0N/A
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>
0N/A
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>
0N/A
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        <code>is</code>.</p>
0N/A
700N/A        <p>The exact naming patterns for Standard MBeans are detailed in
700N/A        the <a href="#spec">JMX Specification</a>.</p>
0N/A
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
700N/A            {@link javax.management.StandardMBean StandardMBean}
700N/A        class.</p>
0N/A
0N/A
406N/A        <h3>MXBeans</h3>
0N/A
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            {@link javax.management.openmbean} package.  MXBeans are appropriate
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        in the specification for {@link javax.management.MXBean MXBean}.</p>
406N/A
0N/A
406N/A        <h3>Dynamic MBeans</h3>
0N/A
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
406N/A        <p>Any Java object of a class that implements the {@link
406N/A            javax.management.DynamicMBean DynamicMBean} interface is a
406N/A        Dynamic MBean.</p>
0N/A
0N/A
406N/A        <h3>Open MBeans</h3>
406N/A
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            the package <a href="openmbean/package-summary.html"><code>
406N/A        javax.management.openmbean</code></a>.</p>
406N/A
0N/A
406N/A        <h3>Model MBeans</h3>
406N/A
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            <a href="modelmbean/package-summary.html"><code>
406N/A        javax.management.modelmbean</code></a>.</p>
0N/A
0N/A
406N/A        <h2>MBean Server</h2>
0N/A
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        javax.management.ObjectName ObjectName} class.</p>
0N/A
406N/A        <p>An MBean Server is an object implementing the interface
406N/A            {@link javax.management.MBeanServer MBeanServer}.
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        java.lang.management.ManagementFactory#getPlatformMBeanServer()}.</p>
0N/A
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        javax.management.MBeanServerFactory MBeanServerFactory} class.</p>
0N/A
0N/A
406N/A        <h3>Creating MBeans in the MBean Server</h3>
406N/A
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            javax.management.MBeanServer#registerMBean registerMBean}
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            of the {@link javax.management.MBeanServer#createMBean(String,
406N/A        javax.management.ObjectName) createMBean} methods.</p>
0N/A
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>
0N/A
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            javax.management.MBeanRegistration MBeanRegistration}
406N/A        interface.</p>
406N/A
406N/A
406N/A        <h3>Accessing MBeans in the MBean Server</h3>
406N/A
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>
406N/A
406N/A        <pre>
0N/A    int cacheSize = mbs.getAttribute(name, "CacheSize");
0N/A    {@link javax.management.Attribute Attribute} newCacheSize =
700N/A         new Attribute("CacheSize", new Integer(2000));
0N/A    mbs.setAttribute(name, newCacheSize);
0N/A    mbs.invoke(name, "save", new Object[0], new Class[0]);
700N/A        </pre>
0N/A
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
700N/A        <pre>
0N/A    ConfigurationMBean conf =
0N/A        {@link javax.management.JMX#newMBeanProxy
0N/A            JMX.newMBeanProxy}(mbs, name, ConfigurationMBean.class);
0N/A    int cacheSize = conf.getCacheSize();
0N/A    conf.setCacheSize(2000);
0N/A    conf.save();
700N/A        </pre>
0N/A
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>
0N/A
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            javax.management.ObjectName ObjectName} class and constraints
700N/A            are constructed using the {@link javax.management.Query Query}
700N/A            class.  The methods {@link
700N/A            javax.management.MBeanServer#queryNames queryNames} and {@link
700N/A            javax.management.MBeanServer#queryMBeans queryMBeans} then
700N/A        perform the query.</p>
0N/A
0N/A
1790N/A        <h3>MBean lifecycle</h3>
0N/A
406N/A        <p>An MBean can implement the {@link javax.management.MBeanRegistration
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            javax.management.MBeanRegistration#preRegister preRegister} method
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        Server.</p>
0N/A
0N/A
406N/A        <h2>Notifications</h2>
406N/A
406N/A        <p>A <em>notification</em> is an instance of the {@link
406N/A            javax.management.Notification Notification} class or a
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>
406N/A
1790N/A        <p>An MBean that will emit notifications must implement the
1790N/A            {@link javax.management.NotificationBroadcaster
1790N/A            NotificationBroadcaster} or {@link
1790N/A            javax.management.NotificationEmitter NotificationEmitter}
1790N/A            interface.  Usually, it does this by subclassing
1790N/A            {@link javax.management.NotificationBroadcasterSupport
1790N/A            NotificationBroadcasterSupport} or delegating to an instance of
1790N/A        that class. Here is an example:</p>
406N/A
406N/A        <pre>
406N/A    public class Configuration <b>extends NotificationBroadcasterSupport</b>
406N/A            implements ConfigurationMBean {
406N/A        ...
406N/A        private void updated() {
406N/A            Notification n = new Notification(...);
406N/A            <b>{@link javax.management.NotificationBroadcasterSupport#sendNotification
406N/A            sendNotification}(n)</b>;
406N/A        }
406N/A    }
406N/A        </pre>
406N/A
406N/A
406N/A        <p>Notifications can be received by a <em>listener</em>, which
406N/A            is an object that implements the {@link
406N/A            javax.management.NotificationListener NotificationListener}
406N/A            interface.  You can add a listener to an MBean with the method
406N/A            {@link
406N/A            javax.management.MBeanServer#addNotificationListener(ObjectName,
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            that implements the {@link javax.management.NotificationFilter
406N/A        NotificationFilter} interface.</p>
0N/A
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            {@link javax.management.NotificationListener
406N/A            NotificationListener} and the method {@link
406N/A            javax.management.MBeanServer#addNotificationListener(ObjectName,
406N/A        ObjectName, NotificationFilter, Object)} is used to listen.</p>
406N/A
406N/A
406N/A        <h2>Remote Access to MBeans</h2>
0N/A
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            <a href="remote/package-summary.html"><code>
406N/A        javax.management.remote</code></a> defines connectors.</p>
406N/A
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>
406N/A
700N/A    <h3 id="interop">Interoperability between versions of the JMX
700N/A      specification</h3>
700N/A
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        onwards.</p>
700N/A
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>
700N/A
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            javax.management.MBeanServerDelegateMBean#getSpecificationVersion
1790N/A            SpecificationVersion} attribute of the {@code
1790N/A        MBeanServerDelegate}.</p>
700N/A
1790N/A        <h4 id="interop-1.2">If the remote MBean Server is 1.2</h4>
700N/A
700N/A    <ul>
700N/A
1790N/A            <li><p>You cannot use wildcards in a key property of an
1790N/A                {@link javax.management.ObjectName ObjectName}, for
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>
700N/A
1790N/A            <li><p>You cannot use {@link
1790N/A                javax.management.Query#isInstanceOf Query.isInstanceOf}
1790N/A            in a query.</p>
700N/A
1790N/A            <li><p>You cannot use dot syntax such as {@code
1790N/A                HeapMemoryUsage.used} in the {@linkplain
1790N/A                javax.management.monitor.Monitor#setObservedAttribute
1790N/A                observed attribute} of a monitor, as described in the
1790N/A                documentation for the {@link javax.management.monitor}
1790N/A            package.</p>
700N/A
1790N/A        </ul>
700N/A
406N/A        <p id="spec">
406N/A        @see <a href="{@docRoot}/technotes/guides/jmx/index.html">
4230N/A        Java Platform documentation on JMX technology</a>
406N/A        in particular the
406N/A        <a href="{@docRoot}/technotes/guides/jmx/JMX_1_4_specification.pdf">
406N/A        JMX Specification, version 1.4(pdf).</a>
406N/A
406N/A        @since 1.5
0N/A
0N/A    </body>
0N/A</html>