src/share/classes/java/lang/management/package.html - toolchain/jdk/jdk9_jdk - Git at Google

 <!--
  Copyright (c) 2003, 2006, Oracle and/or its affiliates. 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.  Oracle designates this
  particular file as subject to the "Classpath" exception as provided
  by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  or visit www.oracle.com if you need additional information or have any
  questions.
 -->

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
 <html>
 <body bgcolor="white">

 Provides the management interface for monitoring and management of the
 Java virtual machine as well as the operating system on which the
 Java virtual machine is running.  It allows both local and remote
 monitoring and management of the running Java virtual machine.

 <h4>Platform MXBeans</h4>

 This package defines the management interface of the following
 components:

 <blockquote>
 <table cellspacing=1 summary="Description of the MBeans">
 <tr>
 <th><p align="left">Management Interface</p></th>
 <th><p align="left">Description</p></th>
 </tr>
 <tr>
 <td> <tt>{@link java.lang.management.ClassLoadingMXBean}</tt> </td>
 <td> Class loading system of the Java virtual machine.</td>
 </tr>
 <tr>
 <td> <tt>{@link java.lang.management.CompilationMXBean}</tt> </td>
 <td> Compilation system of the Java virtual machine.</td>
 </tr>
 <tr>
 <td> <tt>{@link java.lang.management.MemoryMXBean}</tt> </td>
 <td> Memory system of the Java virtual machine.</td>
 </tr>
 <tr>
 <td> <tt>{@link java.lang.management.ThreadMXBean}</tt> </td>
 <td> Threads system of the Java virtual machine.</td>
 </tr>
 <tr>
 <td> <tt>{@link java.lang.management.RuntimeMXBean}</tt> </td>
 <td> Runtime system of the Java virtual machine.</td>
 </tr>
 <tr>
 <td> <tt>{@link java.lang.management.OperatingSystemMXBean}</tt> </td>
 <td> Operating system on which the Java virtual machine is running.</td>
 </tr>
 <tr>
 <td> <tt>{@link java.lang.management.GarbageCollectorMXBean}</tt> </td>
 <td> Garbage collector in the Java virtual machine.</td>
 </tr>
 <tr>
 <td> <tt>{@link java.lang.management.MemoryManagerMXBean}</tt> </td>
 <td> Memory manager in the Java virtual machine.</td>
 </tr>
 <tr>
 <td> <tt>{@link java.lang.management.MemoryPoolMXBean}</tt> </td>
 <td> Memory pool in the Java virtual machine.</td>
 </tr>
 </table>
 </blockquote>

 <p>
 A platform MXBean is a <i>managed bean</i> that defines the management
 interface for one component for the platform and is specified in the
 <a href="ManagementFactory.html#MXBean">
 ManagementFactory</a> class.

 <p>An application can monitor the instrumentation of the
 Java virtual machine and manage certain characteristics in
 the following ways:
 <ul>
 <li><i>Direct access to an MXBean interface</i>
     <ol type="a">
     <li>Get the MXBean instance through the static factory method
         and access the MXBean interface locally of the running
         virtual machine.</li>
     <li>Construct an MXBean proxy instance that
         forwards the method calls to a given
         {@link javax.management.MBeanServer MBeanServer}
         by calling
         {@link java.lang.management.ManagementFactory#newPlatformMXBeanProxy
          ManagementFactory.newPlatformMXBeanProxy}.
          A proxy is typically constructed to remotely access
          an MXBean of another running virtual machine.</li>
     </ol></li>
 <li><i>Indirect access via {@link javax.management.MBeanServer MBeanServer}
        interface</i>
     <ol type="a">
     <li>Go through the
         {@link java.lang.management.ManagementFactory#getPlatformMBeanServer
         platform MBeanServer} to access MXBeans locally or
         a specific <tt>MBeanServerConnection</tt> to access
         MXBeans remotely.
         The attributes and operations of an MXBean use only
         <em>JMX open types</em> which include basic data types,
         {@link javax.management.openmbean.CompositeData CompositeData},
         and {@link javax.management.openmbean.TabularData TabularData}
         defined in {@link javax.management.openmbean.OpenType OpenType}.
        </li>
     </ol></li>
 </ul>

 Below shows a few <a href="#examples">examples</a> of different
 ways to access MXBeans.

 <h4>ManagementFactory</h4>

 The {@link java.lang.management.ManagementFactory} class is the management
 factory class for the Java platform.  This class provides a set of
 static factory methods to obtain the MXBeans for the Java platform
 to allow an application to access the MXBeans directly.

 <p>A <em>platform MBeanServer</em> can be accessed with the
 {@link java.lang.management.ManagementFactory#getPlatformMBeanServer
  getPlatformMBeanServer} method.  On the first call to this method,
 it creates the platform MBeanServer and registers all platform MXBeans
 including platform MXBeans defined in other packages such as
 {@link java.util.logging.LoggingMXBean}.
 Each platform MXBean is registered with a unique name defined in the
 {@link java.lang.management.ManagementFactory ManagementFactory} class
 for constructing {@link javax.management.ObjectName ObjectName}.
 This is a single MBeanServer that can be shared by different managed
 components running within the same Java virtual machine.

 <h4>Interoperability</h4>

 A management application and a platform MBeanServer of a running
 virtual machine can interoperate
 without requiring classes used by the platform MXBean interfaces.
 The data types being transmitted between the JMX connector
 server and the connector client are JMX
 {@link javax.management.openmbean.OpenType open types} and
 this allows interoperation across versions.

 <p>A data type used by the MXBean interfaces are mapped to
 an open type when being accessed via MBeanServer interface.
 The data type mapping is specified in the
 {@link java.lang.management.ManagementFactory ManagementFactory} class.

 <h4><a name="examples">Ways to Access MXBeans</a></h4>

 There are three different ways to access the management interfaces.

 <p>
 <ol>
 <li>Call the methods in the MXBean directly within the same
     Java virtual machine.
 <blockquote><pre>
    RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();

    // Get the standard attribute "VmVendor"
    String vendor = mxbean.getVmVendor();

 </pre>
 </blockquote>
 </li>

 <li>Go through a <tt>MBeanServerConnection</tt> connecting
     to the <tt>platform MBeanServer</tt> of a running virtual machine.</li>
 <blockquote><pre>
    MBeanServerConnection mbs;

    // Connect to a running JVM (or itself) and get MBeanServerConnection
    // that has the JVM MXBeans registered in it
    ...

    try {
        // Assuming the RuntimeMXBean has been registered in mbs
        ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);

        // Get standard attribute "VmVendor"
        String vendor = (String) mbs.getAttribute(oname, "VmVendor");
    } catch (....) {
        // Catch the exceptions thrown by ObjectName constructor
        // and MBeanServer.getAttribute method
        ...
    }

 </pre></blockquote>

 <li>Use MXBean proxy.</li>
 <blockquote><pre>
    MBeanServerConnection mbs;

    // Connect to a running JVM (or itself) and get MBeanServerConnection
    // that has the JVM MBeans registered in it
    ...

    // Get a MBean proxy for RuntimeMXBean interface
    RuntimeMXBean proxy =
        ManagementFactory.newPlatformMXBeanProxy(mbs,
                                                 ManagementFactory.RUNTIME_MXBEAN_NAME,
                                                 RuntimeMXBean.class);
    // Get standard attribute "VmVendor"
    String vendor = proxy.getVmVendor();
 </pre></blockquote>
 </ol>


 <h4><a name="extension">Platform Extension</a></h4>

 A Java virtual machine implementation may add its platform extension to
 the management interface by defining platform-dependent
 interfaces that extend the standard management interfaces to include
 platform-specific metrics and management operations.
 The static factory methods in the <tt>ManagementFactory</tt> class will
 return the MBeans with the platform extension.

 <p>
 It is recommended to name the platform-specific attributes with
 a vendor-specific prefix such as the vendor's name to
 avoid collisions of the attribute name between the future extension
 to the standard management interface and the platform extension.
 If the future extension to the standard management interface defines
 a new attribute for a management interface and the attribute name
 is happened to be same as some vendor-specific attribute's name,
 the applications accessing that vendor-specific attribute would have
 to be modified to cope with versioning and compatibility issues.

 <p>Below is an example showing how to access a platform-specific
 attribute from Sun's implementation of the <tt>RuntimeMXBean</tt>.

 <p>
 1) Direct access to the Sun-specific MXBean interface
 <blockquote><pre>
    com.sun.management.RuntimeMXBean mxbean =
        (com.sun.management.RuntimeMXBean) ManagementFactory.getRuntimeMXBean();

    // Get the standard attribute "VmVendor"
    String vendor = mxbean.getVmVendor();

    // Get the platform-specific attribute "Bar"
    BarType bar = mxbean.getBar();

 </pre>
 </blockquote>

 <p>
 2) Access the Sun-specific MXBean interface via <tt>MBeanServer</tt>

 <blockquote><pre>
    MBeanServerConnection mbs;

    // Connect to a running JVM (or itself) and get MBeanServerConnection
    // that has the JVM MXBeans registered in it
    ...

    try {
        // Assuming the RuntimeMXBean has been registered in mbs
        ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);

        // Get standard attribute "VmVendor"
        String vendor = (String) mbs.getAttribute(oname, "VmVendor");

        // Check if this MXBean contains Sun's extension
        if (mbs.isInstanceOf(oname, "com.sun.management.RuntimeMXBean")) {
            // Get platform-specific attribute "Bar"
            BarType bar = (String) mbs.getAttribute(oname, "Bar");
        }
    } catch (....) {
        // Catch the exceptions thrown by ObjectName constructor
        // and MBeanServer methods
        ...
    }

 </pre></blockquote>

 <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
 or method in any class or interface in this package will cause a {@link
 java.lang.NullPointerException NullPointerException} to be thrown.

 <p> The java.lang.management API is thread-safe.

 @see <a href="../../../javax/management/package-summary.html">
      JMX Specification.</a>

 @author  Mandy Chung
 @since   1.5

 </body>
 </html>
	<!--
	Copyright (c) 2003, 2006, Oracle and/or its affiliates. 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. Oracle designates this
	particular file as subject to the "Classpath" exception as provided
	by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	or visit www.oracle.com if you need additional information or have any
	questions.
	-->

	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
	<html>
	<body bgcolor="white">

	Provides the management interface for monitoring and management of the
	Java virtual machine as well as the operating system on which the
	Java virtual machine is running. It allows both local and remote
	monitoring and management of the running Java virtual machine.

	<h4>Platform MXBeans</h4>

	This package defines the management interface of the following
	components:

	<blockquote>
	<table cellspacing=1 summary="Description of the MBeans">
	<tr>
	<th><p align="left">Management Interface</p></th>
	<th><p align="left">Description</p></th>
	</tr>
	<tr>
	<td> <tt>{@link java.lang.management.ClassLoadingMXBean}</tt> </td>
	<td> Class loading system of the Java virtual machine.</td>
	</tr>
	<tr>
	<td> <tt>{@link java.lang.management.CompilationMXBean}</tt> </td>
	<td> Compilation system of the Java virtual machine.</td>
	</tr>
	<tr>
	<td> <tt>{@link java.lang.management.MemoryMXBean}</tt> </td>
	<td> Memory system of the Java virtual machine.</td>
	</tr>
	<tr>
	<td> <tt>{@link java.lang.management.ThreadMXBean}</tt> </td>
	<td> Threads system of the Java virtual machine.</td>
	</tr>
	<tr>
	<td> <tt>{@link java.lang.management.RuntimeMXBean}</tt> </td>
	<td> Runtime system of the Java virtual machine.</td>
	</tr>
	<tr>
	<td> <tt>{@link java.lang.management.OperatingSystemMXBean}</tt> </td>
	<td> Operating system on which the Java virtual machine is running.</td>
	</tr>
	<tr>
	<td> <tt>{@link java.lang.management.GarbageCollectorMXBean}</tt> </td>
	<td> Garbage collector in the Java virtual machine.</td>
	</tr>
	<tr>
	<td> <tt>{@link java.lang.management.MemoryManagerMXBean}</tt> </td>
	<td> Memory manager in the Java virtual machine.</td>
	</tr>
	<tr>
	<td> <tt>{@link java.lang.management.MemoryPoolMXBean}</tt> </td>
	<td> Memory pool in the Java virtual machine.</td>
	</tr>
	</table>
	</blockquote>

	<p>
	A platform MXBean is a <i>managed bean</i> that defines the management
	interface for one component for the platform and is specified in the
	<a href="ManagementFactory.html#MXBean">
	ManagementFactory</a> class.

	<p>An application can monitor the instrumentation of the
	Java virtual machine and manage certain characteristics in
	the following ways:
	<ul>
	<li><i>Direct access to an MXBean interface</i>
	<ol type="a">
	<li>Get the MXBean instance through the static factory method
	and access the MXBean interface locally of the running
	virtual machine.</li>
	<li>Construct an MXBean proxy instance that
	forwards the method calls to a given
	{@link javax.management.MBeanServer MBeanServer}
	by calling
	{@link java.lang.management.ManagementFactory#newPlatformMXBeanProxy
	ManagementFactory.newPlatformMXBeanProxy}.
	A proxy is typically constructed to remotely access
	an MXBean of another running virtual machine.</li>
	</ol></li>
	<li><i>Indirect access via {@link javax.management.MBeanServer MBeanServer}
	interface</i>
	<ol type="a">
	<li>Go through the
	{@link java.lang.management.ManagementFactory#getPlatformMBeanServer
	platform MBeanServer} to access MXBeans locally or
	a specific <tt>MBeanServerConnection</tt> to access
	MXBeans remotely.
	The attributes and operations of an MXBean use only
	<em>JMX open types</em> which include basic data types,
	{@link javax.management.openmbean.CompositeData CompositeData},
	and {@link javax.management.openmbean.TabularData TabularData}
	defined in {@link javax.management.openmbean.OpenType OpenType}.
	</li>
	</ol></li>
	</ul>

	Below shows a few <a href="#examples">examples</a> of different
	ways to access MXBeans.

	<h4>ManagementFactory</h4>

	The {@link java.lang.management.ManagementFactory} class is the management
	factory class for the Java platform. This class provides a set of
	static factory methods to obtain the MXBeans for the Java platform
	to allow an application to access the MXBeans directly.

	<p>A <em>platform MBeanServer</em> can be accessed with the
	{@link java.lang.management.ManagementFactory#getPlatformMBeanServer
	getPlatformMBeanServer} method. On the first call to this method,
	it creates the platform MBeanServer and registers all platform MXBeans
	including platform MXBeans defined in other packages such as
	{@link java.util.logging.LoggingMXBean}.
	Each platform MXBean is registered with a unique name defined in the
	{@link java.lang.management.ManagementFactory ManagementFactory} class
	for constructing {@link javax.management.ObjectName ObjectName}.
	This is a single MBeanServer that can be shared by different managed
	components running within the same Java virtual machine.

	<h4>Interoperability</h4>

	A management application and a platform MBeanServer of a running
	virtual machine can interoperate
	without requiring classes used by the platform MXBean interfaces.
	The data types being transmitted between the JMX connector
	server and the connector client are JMX
	{@link javax.management.openmbean.OpenType open types} and
	this allows interoperation across versions.

	<p>A data type used by the MXBean interfaces are mapped to
	an open type when being accessed via MBeanServer interface.
	The data type mapping is specified in the
	{@link java.lang.management.ManagementFactory ManagementFactory} class.

	<h4><a name="examples">Ways to Access MXBeans</a></h4>

	There are three different ways to access the management interfaces.

	<p>
	<ol>
	<li>Call the methods in the MXBean directly within the same
	Java virtual machine.
	<blockquote><pre>
	RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();

	// Get the standard attribute "VmVendor"
	String vendor = mxbean.getVmVendor();

	</pre>
	</blockquote>
	</li>

	<li>Go through a <tt>MBeanServerConnection</tt> connecting
	to the <tt>platform MBeanServer</tt> of a running virtual machine.</li>
	<blockquote><pre>
	MBeanServerConnection mbs;

	// Connect to a running JVM (or itself) and get MBeanServerConnection
	// that has the JVM MXBeans registered in it
	...

	try {
	// Assuming the RuntimeMXBean has been registered in mbs
	ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);

	// Get standard attribute "VmVendor"
	String vendor = (String) mbs.getAttribute(oname, "VmVendor");
	} catch (....) {
	// Catch the exceptions thrown by ObjectName constructor
	// and MBeanServer.getAttribute method
	...
	}

	</pre></blockquote>

	<li>Use MXBean proxy.</li>
	<blockquote><pre>
	MBeanServerConnection mbs;

	// Connect to a running JVM (or itself) and get MBeanServerConnection
	// that has the JVM MBeans registered in it
	...

	// Get a MBean proxy for RuntimeMXBean interface
	RuntimeMXBean proxy =
	ManagementFactory.newPlatformMXBeanProxy(mbs,
	ManagementFactory.RUNTIME_MXBEAN_NAME,
	RuntimeMXBean.class);
	// Get standard attribute "VmVendor"
	String vendor = proxy.getVmVendor();
	</pre></blockquote>
	</ol>


	<h4><a name="extension">Platform Extension</a></h4>

	A Java virtual machine implementation may add its platform extension to
	the management interface by defining platform-dependent
	interfaces that extend the standard management interfaces to include
	platform-specific metrics and management operations.
	The static factory methods in the <tt>ManagementFactory</tt> class will
	return the MBeans with the platform extension.

	<p>
	It is recommended to name the platform-specific attributes with
	a vendor-specific prefix such as the vendor's name to
	avoid collisions of the attribute name between the future extension
	to the standard management interface and the platform extension.
	If the future extension to the standard management interface defines
	a new attribute for a management interface and the attribute name
	is happened to be same as some vendor-specific attribute's name,
	the applications accessing that vendor-specific attribute would have
	to be modified to cope with versioning and compatibility issues.

	<p>Below is an example showing how to access a platform-specific
	attribute from Sun's implementation of the <tt>RuntimeMXBean</tt>.

	<p>
	1) Direct access to the Sun-specific MXBean interface
	<blockquote><pre>
	com.sun.management.RuntimeMXBean mxbean =
	(com.sun.management.RuntimeMXBean) ManagementFactory.getRuntimeMXBean();

	// Get the standard attribute "VmVendor"
	String vendor = mxbean.getVmVendor();

	// Get the platform-specific attribute "Bar"
	BarType bar = mxbean.getBar();

	</pre>
	</blockquote>

	<p>
	2) Access the Sun-specific MXBean interface via <tt>MBeanServer</tt>

	<blockquote><pre>
	MBeanServerConnection mbs;

	// Connect to a running JVM (or itself) and get MBeanServerConnection
	// that has the JVM MXBeans registered in it
	...

	try {
	// Assuming the RuntimeMXBean has been registered in mbs
	ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);

	// Get standard attribute "VmVendor"
	String vendor = (String) mbs.getAttribute(oname, "VmVendor");

	// Check if this MXBean contains Sun's extension
	if (mbs.isInstanceOf(oname, "com.sun.management.RuntimeMXBean")) {
	// Get platform-specific attribute "Bar"
	BarType bar = (String) mbs.getAttribute(oname, "Bar");
	}
	} catch (....) {
	// Catch the exceptions thrown by ObjectName constructor
	// and MBeanServer methods
	...
	}

	</pre></blockquote>

	<p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
	or method in any class or interface in this package will cause a {@link
	java.lang.NullPointerException NullPointerException} to be thrown.

	<p> The java.lang.management API is thread-safe.

	@see <a href="../../../javax/management/package-summary.html">
	JMX Specification.</a>

	@author Mandy Chung
	@since 1.5

	</body>
	</html>