--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/javax/management/package.html Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,329 @@
+<html>
+<head>
+<title>javax.management package</title>
+<!--
+Copyright 1999-2006 Sun Microsystems, Inc. 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. Sun designates this
+particular file as subject to the "Classpath" exception as provided
+by Sun 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}.
+
+
+ <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>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>
+
+
+ <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 by delegating to an instance
+ of that class.</p>
+
+ <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>
+
+ <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>