1 <!--
   2  Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
   3  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4 
   5  This code is free software; you can redistribute it and/or modify it
   6  under the terms of the GNU General Public License version 2 only, as
   7  published by the Free Software Foundation.  Oracle designates this
   8  particular file as subject to the "Classpath" exception as provided
   9  by Oracle in the LICENSE file that accompanied this code.
  10 
  11  This code is distributed in the hope that it will be useful, but WITHOUT
  12  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  version 2 for more details (a copy is included in the LICENSE file that
  15  accompanied this code).
  16 
  17  You should have received a copy of the GNU General Public License version
  18  2 along with this work; if not, write to the Free Software Foundation,
  19  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20 
  21  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  or visit www.oracle.com if you need additional information or have any
  23  questions.
  24 -->
  25 
  26 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  27 <html>
  28 <body bgcolor="white">
  29 
  30 Provides the management interfaces for monitoring and management of the 
  31 Java virtual machine and other components in the Java runtime.
  32 It allows both local and remote 
  33 monitoring and management of the running Java virtual machine.  
  34 <p>
  35 
  36 <h4><a name="MXBean">Platform MXBean</a></h4>
  37 <p>
  38 A platform MXBean is a <i>managed bean</i> that
  39 conforms to the <a href="../../../javax/management/package-summary.html">JMX</a>
  40 Instrumentation Specification and only uses a set of basic data types.
  41 Each platform MXBean is a {@link java.lang.management.PlatformManagedObject}
  42 with a unique
  43 {@linkplain java.lang.management.PlatformManagedObject#getObjectName name}.
  44 <p>
  45 <h4>ManagementFactory</h4>
  46 
  47 <p>The {@link java.lang.management.ManagementFactory} class is the management
  48 factory class for the Java platform.  This class provides a set of 
  49 static factory methods to obtain the MXBeans for the Java platform
  50 to allow an application to access the MXBeans directly.
  51 
  52 <p>A <em>platform MBeanServer</em> can be accessed with the
  53 {@link java.lang.management.ManagementFactory#getPlatformMBeanServer
  54  getPlatformMBeanServer} method.  On the first call to this method,
  55 it creates the platform MBeanServer and registers all platform MXBeans 
  56 including {@linkplain java.lang.management.PlatformManagedObject
  57 platform MXBeans}.
  58 Each platform MXBean is registered with a unique name defined in 
  59 the specification of the management interface.
  60 This is a single MBeanServer that can be shared by different managed 
  61 components running within the same Java virtual machine.
  62  
  63 <h4>Interoperability</h4>
  64 
  65 <p>A management application and a platform MBeanServer of a running
  66 virtual machine can interoperate 
  67 without requiring classes used by the platform MXBean interfaces.
  68 The data types being transmitted between the JMX connector
  69 server and the connector client are JMX
  70 {@linkplain javax.management.openmbean.OpenType open types} and
  71 this allows interoperation across versions.
  72 A data type used by the MXBean interfaces are mapped to an 
  73 open type when being accessed via MBeanServer interface.
  74 See the <a href="../../../javax/management/MXBean.html#MXBean-spec">
  75 MXBean</a> specification for details. 
  76 
  77 <h4><a name="examples">Ways to Access MXBeans</a></h4>
  78 
  79 <p>An application can monitor the instrumentation of the 
  80 Java virtual machine and the runtime in the following ways:
  81 <p>
  82 <b>1. Direct access to an MXBean interface</b>
  83 <p>
  84 <ul>
  85 <li>Get an MXBean instance locally in the running Java virtual machine:<p>
  86 <pre>
  87    RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();
  88 
  89    // Get the standard attribute "VmVendor"
  90    String vendor = mxbean.getVmVendor();
  91 </pre>
  92 <p>Or by calling the
  93         {@link java.lang.management.ManagementFactory#getPlatformMXBean(Class)
  94                getPlatformMXBean} or
  95         {@link java.lang.management.ManagementFactory#getPlatformMXBeans(Class)
  96                getPlatformMXBeans} method:
  97 <pre>
  98    RuntimeMXBean mxbean = ManagementFactory.getPlatformMXBean(RuntimeMXBean.class);
  99 
 100    // Get the standard attribute "VmVendor"
 101    String vendor = mxbean.getVmVendor();
 102 </pre>
 103 <p>
 104 </li>
 105 <li>Construct an MXBean proxy instance that forwards the
 106     method calls to a given MBeanServer:<p>
 107 <pre>
 108    MBeanServerConnection mbs;
 109 
 110    // Connect to a running JVM (or itself) and get MBeanServerConnection
 111    // that has the JVM MBeans registered in it
 112    ...
 113 
 114    // Get a MBean proxy for RuntimeMXBean interface
 115    RuntimeMXBean proxy = 
 116        {@link java.lang.management.ManagementFactory#getPlatformMXBean(MBeanServerConnection, Class)
 117        ManagementFactory.getPlatformMXBean}(mbs,
 118                                            RuntimeMXBean.class);
 119    // Get standard attribute "VmVendor" 
 120    String vendor = proxy.getVmVendor();
 121 </pre>
 122 <p>A proxy is typically used to access an MXBean 
 123    in a remote Java virtual machine.
 124    An alternative way to create an MXBean proxy is:
 125 <pre>
 126    RuntimeMXBean proxy = 
 127        {@link java.lang.management.ManagementFactory#newPlatformMXBeanProxy
 128               ManagementFactory.newPlatformMXBeanProxy}(mbs,
 129                                                 ManagementFactory.RUNTIME_MXBEAN_NAME,
 130                                                 RuntimeMXBean.class);
 131 </pre>
 132 </li>
 133 </ul>
 134 <p>
 135 <b>2. Indirect access to an MXBean interface via MBeanServer</b><p>
 136 <ul>
 137 <li>Go through the 
 138     {@link java.lang.management.ManagementFactory#getPlatformMBeanServer
 139     platform MBeanServer} to access MXBeans locally or
 140     a specific {@code MBeanServerConnection} to access
 141     MXBeans remotely.
 142     The attributes and operations of an MXBean use only
 143     <em>JMX open types</em> which include basic data types, 
 144     {@link javax.management.openmbean.CompositeData CompositeData},
 145     and {@link javax.management.openmbean.TabularData TabularData} 
 146     defined in {@link javax.management.openmbean.OpenType OpenType}.<p>
 147 <pre>
 148    MBeanServerConnection mbs;
 149 
 150    // Connect to a running JVM (or itself) and get MBeanServerConnection
 151    // that has the JVM MXBeans registered in it
 152    ...
 153 
 154    try {
 155        // Assuming the RuntimeMXBean has been registered in mbs
 156        ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);
 157     
 158        // Get standard attribute "VmVendor"
 159        String vendor = (String) mbs.getAttribute(oname, "VmVendor");
 160    } catch (....) {
 161        // Catch the exceptions thrown by ObjectName constructor
 162        // and MBeanServer.getAttribute method
 163        ...
 164    }
 165 </pre>
 166 </li>
 167 </ul>
 168 
 169 
 170 <h4><a name="extension">Platform Extension</a></h4>
 171 
 172 <p>A Java virtual machine implementation may add its platform extension to
 173 the management interface by defining platform-dependent
 174 interfaces that extend the standard management interfaces to include
 175 platform-specific metrics and management operations.  
 176 The static factory methods in the <tt>ManagementFactory</tt> class will
 177 return the MXBeans with the platform extension.
 178 
 179 <p>
 180 It is recommended to name the platform-specific attributes with
 181 a vendor-specific prefix such as the vendor's name to
 182 avoid collisions of the attribute name between the future extension
 183 to the standard management interface and the platform extension.
 184 If the future extension to the standard management interface defines
 185 a new attribute for a management interface and the attribute name
 186 is happened to be same as some vendor-specific attribute's name,
 187 the applications accessing that vendor-specific attribute would have
 188 to be modified to cope with versioning and compatibility issues.
 189 
 190 <p>Below is an example showing how to access an attribute 
 191 from the platform extension:
 192 
 193 <p>
 194 1) Direct access to the Oracle-specific MXBean interface
 195 <blockquote>
 196 <pre>
 197    List&lt;com.sun.management.GarbageCollectorMXBean&gt; mxbeans = 
 198        ManagementFactory.getPlatformMXBeans(com.sun.management.GarbageCollectorMXBean.class);
 199 
 200    for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) {
 201        // Get the standard attribute "CollectionCount"
 202        String count = mxbean.getCollectionCount();
 203 
 204        // Get the platform-specific attribute "LastGcInfo"
 205        GcInfo gcinfo = gc.getLastGcInfo();
 206        ...
 207    }
 208 </pre>
 209 </blockquote>
 210 
 211 <p>
 212 2) Access the Oracle-specific MXBean interface via <tt>MBeanServer</tt>
 213    through proxy
 214 
 215 <blockquote><pre>
 216    MBeanServerConnection mbs;
 217 
 218    // Connect to a running JVM (or itself) and get MBeanServerConnection
 219    // that has the JVM MXBeans registered in it
 220    ...
 221 
 222    List&lt;com.sun.management.GarbageCollectorMXBean&gt; mxbeans = 
 223        ManagementFactory.getPlatformMXBeans(mbs, com.sun.management.GarbageCollectorMXBean.class);
 224 
 225    for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) {
 226        // Get the standard attribute "CollectionCount"
 227        String count = mxbean.getCollectionCount();
 228 
 229        // Get the platform-specific attribute "LastGcInfo"
 230        GcInfo gcinfo = gc.getLastGcInfo();
 231        ...
 232    }
 233     
 234 </pre></blockquote>
 235 
 236 <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
 237 or method in any class or interface in this package will cause a {@link
 238 java.lang.NullPointerException NullPointerException} to be thrown.
 239 
 240 <p> The java.lang.management API is thread-safe.
 241 
 242 @see <a href="../../../javax/management/package-summary.html">
 243      JMX Specification.</a>
 244 
 245 @author  Mandy Chung
 246 @since   1.5
 247 
 248 </body>
 249 </html>