lang/management/package.html

0N/A<!--
2362N/A Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
0N/A DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0N/A
0N/A This code is free software; you can redistribute it and/or modify it
0N/A under the terms of the GNU General Public License version 2 only, as
2362N/A published by the Free Software Foundation.  Oracle designates this
0N/A particular file as subject to the "Classpath" exception as provided
2362N/A by Oracle in the LICENSE file that accompanied this code.
0N/A
0N/A This code is distributed in the hope that it will be useful, but WITHOUT
0N/A ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0N/A FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
0N/A version 2 for more details (a copy is included in the LICENSE file that
0N/A accompanied this code).
0N/A
0N/A You should have received a copy of the GNU General Public License version
0N/A 2 along with this work; if not, write to the Free Software Foundation,
0N/A Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0N/A
2362N/A Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2362N/A or visit www.oracle.com if you need additional information or have any
2362N/A questions.
0N/A-->
0N/A
0N/A<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0N/A<html>
0N/A<body bgcolor="white">
0N/A
3887N/AProvides the management interfaces for monitoring and management of the
3887N/AJava virtual machine and other components in the Java runtime.
3887N/AIt allows both local and remote
3887N/Amonitoring and management of the running Java virtual machine.
3887N/A<p>
0N/A
3887N/A<h4><a name="MXBean">Platform MXBean</a></h4>
0N/A<p>
3887N/AA platform MXBean is a <i>managed bean</i> that
3887N/Aconforms to the <a href="/javax/management/package-summary.html">JMX</a>
3887N/AInstrumentation Specification and only uses a set of basic data types.
3887N/AEach platform MXBean is a {@link java.lang.management.PlatformManagedObject}
3887N/Awith a unique
3887N/A{@linkplain java.lang.management.PlatformManagedObject#getObjectName name}.
3887N/A<p>
0N/A<h4>ManagementFactory</h4>
0N/A
3887N/A<p>The {@link java.lang.management.ManagementFactory} class is the management
3887N/Afactory class for the Java platform.  This class provides a set of
0N/Astatic factory methods to obtain the MXBeans for the Java platform
0N/Ato allow an application to access the MXBeans directly.
0N/A
0N/A<p>A <em>platform MBeanServer</em> can be accessed with the
0N/A{@link java.lang.management.ManagementFactory#getPlatformMBeanServer
0N/A getPlatformMBeanServer} method.  On the first call to this method,
3887N/Ait creates the platform MBeanServer and registers all platform MXBeans
3887N/Aincluding {@linkplain java.lang.management.PlatformManagedObject
3887N/Aplatform MXBeans}.
3887N/AEach platform MXBean is registered with a unique name defined in
3887N/Athe specification of the management interface.
3887N/AThis is a single MBeanServer that can be shared by different managed
0N/Acomponents running within the same Java virtual machine.
3887N/A
0N/A<h4>Interoperability</h4>
0N/A
3887N/A<p>A management application and a platform MBeanServer of a running
3887N/Avirtual machine can interoperate
0N/Awithout requiring classes used by the platform MXBean interfaces.
0N/AThe data types being transmitted between the JMX connector
0N/Aserver and the connector client are JMX
3887N/A{@linkplain javax.management.openmbean.OpenType open types} and
0N/Athis allows interoperation across versions.
3887N/AA data type used by the MXBean interfaces are mapped to an
3887N/Aopen type when being accessed via MBeanServer interface.
3887N/ASee the <a href="/javax/management/MXBean.html#MXBean-spec">
3887N/AMXBean</a> specification for details.
0N/A
0N/A<h4><a name="examples">Ways to Access MXBeans</a></h4>
0N/A
3887N/A<p>An application can monitor the instrumentation of the
3887N/AJava virtual machine and the runtime in the following ways:
0N/A<p>
3887N/A<b>1. Direct access to an MXBean interface</b>
3887N/A<p>
3887N/A<ul>
3887N/A<li>Get an MXBean instance locally in the running Java virtual machine:<p>
3887N/A<pre>
0N/A   RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();
0N/A
0N/A   // Get the standard attribute "VmVendor"
0N/A   String vendor = mxbean.getVmVendor();
0N/A</pre>
3887N/A<p>Or by calling the
3887N/A        {@link java.lang.management.ManagementFactory#getPlatformMXBean(Class)
3887N/A               getPlatformMXBean} or
3887N/A        {@link java.lang.management.ManagementFactory#getPlatformMXBeans(Class)
3887N/A               getPlatformMXBeans} method:
3887N/A<pre>
3887N/A   RuntimeMXBean mxbean = ManagementFactory.getPlatformMXBean(RuntimeMXBean.class);
3887N/A
3887N/A   // Get the standard attribute "VmVendor"
3887N/A   String vendor = mxbean.getVmVendor();
3887N/A</pre>
3887N/A<p>
0N/A</li>
3887N/A<li>Construct an MXBean proxy instance that forwards the
3887N/A    method calls to a given MBeanServer:<p>
3887N/A<pre>
3887N/A   MBeanServerConnection mbs;
0N/A
3887N/A   // Connect to a running JVM (or itself) and get MBeanServerConnection
3887N/A   // that has the JVM MBeans registered in it
3887N/A   ...
3887N/A
3887N/A   // Get a MBean proxy for RuntimeMXBean interface
3887N/A   RuntimeMXBean proxy =
3887N/A       {@link java.lang.management.ManagementFactory#getPlatformMXBean(MBeanServerConnection, Class)
3887N/A       ManagementFactory.getPlatformMXBean}(mbs,
3887N/A                                           RuntimeMXBean.class);
3887N/A   // Get standard attribute "VmVendor"
3887N/A   String vendor = proxy.getVmVendor();
3887N/A</pre>
3887N/A<p>A proxy is typically used to access an MXBean
3887N/A   in a remote Java virtual machine.
3887N/A   An alternative way to create an MXBean proxy is:
3887N/A<pre>
3887N/A   RuntimeMXBean proxy =
3887N/A       {@link java.lang.management.ManagementFactory#newPlatformMXBeanProxy
3887N/A              ManagementFactory.newPlatformMXBeanProxy}(mbs,
3887N/A                                                ManagementFactory.RUNTIME_MXBEAN_NAME,
3887N/A                                                RuntimeMXBean.class);
3887N/A</pre>
3887N/A</li>
3887N/A</ul>
3887N/A<p>
3887N/A<b>2. Indirect access to an MXBean interface via MBeanServer</b><p>
3887N/A<ul>
3887N/A<li>Go through the
3887N/A    {@link java.lang.management.ManagementFactory#getPlatformMBeanServer
3887N/A    platform MBeanServer} to access MXBeans locally or
3887N/A    a specific {@code MBeanServerConnection} to access
3887N/A    MXBeans remotely.
3887N/A    The attributes and operations of an MXBean use only
3887N/A    <em>JMX open types</em> which include basic data types,
3887N/A    {@link javax.management.openmbean.CompositeData CompositeData},
3887N/A    and {@link javax.management.openmbean.TabularData TabularData}
3887N/A    defined in {@link javax.management.openmbean.OpenType OpenType}.<p>
3887N/A<pre>
0N/A   MBeanServerConnection mbs;
0N/A
0N/A   // Connect to a running JVM (or itself) and get MBeanServerConnection
0N/A   // that has the JVM MXBeans registered in it
0N/A   ...
0N/A
0N/A   try {
0N/A       // Assuming the RuntimeMXBean has been registered in mbs
0N/A       ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);
3887N/A
0N/A       // Get standard attribute "VmVendor"
0N/A       String vendor = (String) mbs.getAttribute(oname, "VmVendor");
0N/A   } catch (....) {
0N/A       // Catch the exceptions thrown by ObjectName constructor
0N/A       // and MBeanServer.getAttribute method
0N/A       ...
0N/A   }
3887N/A</pre>
3887N/A</li>
3887N/A</ul>
0N/A
0N/A
0N/A<h4><a name="extension">Platform Extension</a></h4>
0N/A
3887N/A<p>A Java virtual machine implementation may add its platform extension to
0N/Athe management interface by defining platform-dependent
0N/Ainterfaces that extend the standard management interfaces to include
3887N/Aplatform-specific metrics and management operations.
0N/AThe static factory methods in the <tt>ManagementFactory</tt> class will
3887N/Areturn the MXBeans with the platform extension.
0N/A
0N/A<p>
0N/AIt is recommended to name the platform-specific attributes with
0N/Aa vendor-specific prefix such as the vendor's name to
0N/Aavoid collisions of the attribute name between the future extension
0N/Ato the standard management interface and the platform extension.
0N/AIf the future extension to the standard management interface defines
0N/Aa new attribute for a management interface and the attribute name
0N/Ais happened to be same as some vendor-specific attribute's name,
0N/Athe applications accessing that vendor-specific attribute would have
0N/Ato be modified to cope with versioning and compatibility issues.
0N/A
3887N/A<p>Below is an example showing how to access an attribute
3887N/Afrom the platform extension:
0N/A
0N/A<p>
3887N/A1) Direct access to the Oracle-specific MXBean interface
3887N/A<blockquote>
3887N/A<pre>
3887N/A   List&lt;com.sun.management.GarbageCollectorMXBean&gt; mxbeans =
3887N/A       ManagementFactory.getPlatformMXBeans(com.sun.management.GarbageCollectorMXBean.class);
0N/A
3887N/A   for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) {
3887N/A       // Get the standard attribute "CollectionCount"
3887N/A       String count = mxbean.getCollectionCount();
0N/A
3887N/A       // Get the platform-specific attribute "LastGcInfo"
3887N/A       GcInfo gcinfo = gc.getLastGcInfo();
3887N/A       ...
3887N/A   }
0N/A</pre>
0N/A</blockquote>
0N/A
0N/A<p>
3887N/A2) Access the Oracle-specific MXBean interface via <tt>MBeanServer</tt>
3887N/A   through proxy
0N/A
0N/A<blockquote><pre>
0N/A   MBeanServerConnection mbs;
0N/A
0N/A   // Connect to a running JVM (or itself) and get MBeanServerConnection
0N/A   // that has the JVM MXBeans registered in it
0N/A   ...
0N/A
3887N/A   List&lt;com.sun.management.GarbageCollectorMXBean&gt; mxbeans =
3887N/A       ManagementFactory.getPlatformMXBeans(mbs, com.sun.management.GarbageCollectorMXBean.class);
0N/A
3887N/A   for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) {
3887N/A       // Get the standard attribute "CollectionCount"
3887N/A       String count = mxbean.getCollectionCount();
3887N/A
3887N/A       // Get the platform-specific attribute "LastGcInfo"
3887N/A       GcInfo gcinfo = gc.getLastGcInfo();
0N/A       ...
0N/A   }
0N/A</pre></blockquote>
0N/A
0N/A<p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
0N/Aor method in any class or interface in this package will cause a {@link
0N/Ajava.lang.NullPointerException NullPointerException} to be thrown.
0N/A
0N/A<p> The java.lang.management API is thread-safe.
0N/A
0N/A@see <a href="/javax/management/package-summary.html">
0N/A     JMX Specification.</a>
0N/A
0N/A@author  Mandy Chung
0N/A@since   1.5
0N/A
0N/A</body>
0N/A</html>