diff src/share/classes/javax/management/package.html @ 0:37a05a11f281

Initial load
author duke
date Sat, 01 Dec 2007 00:00:00 +0000
children afa8b71365aa
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/share/classes/javax/management/package.html	Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,329 @@
+<title>javax.management package</title>
+Copyright 1999-2006 Sun Microsystems, Inc.  All Rights Reserved.
+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.
+<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>