1<!-- 2 Copyright (c) 2003, 2017, 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 30Provides the management interfaces for monitoring and management of the 31Java virtual machine and other components in the Java runtime. 32It allows both local and remote 33monitoring and management of the running Java virtual machine. 34 35<h3><a id="MXBean">Platform MXBean</a></h3> 36<p> 37A platform MXBean is a <i>managed bean</i> that 38conforms to the {@linkplain javax.management JMX} 39Instrumentation Specification and only uses a set of basic data types. 40Each platform MXBean is a {@link java.lang.management.PlatformManagedObject} 41with a unique 42{@linkplain java.lang.management.PlatformManagedObject#getObjectName name}. 43<h3>ManagementFactory</h3> 44 45<p>The {@link java.lang.management.ManagementFactory} class is the management 46factory class for the Java platform. This class provides a set of 47static factory methods to obtain the MXBeans for the Java platform 48to allow an application to access the MXBeans directly. 49 50<p>A <em>platform MBeanServer</em> can be accessed with the 51{@link java.lang.management.ManagementFactory#getPlatformMBeanServer 52 getPlatformMBeanServer} method. On the first call to this method, 53it creates the platform MBeanServer and registers all platform MXBeans 54including {@linkplain java.lang.management.PlatformManagedObject 55platform MXBeans}. 56Each platform MXBean is registered with a unique name defined in 57the specification of the management interface. 58This is a single MBeanServer that can be shared by different managed 59components running within the same Java virtual machine. 60 61<h3>Interoperability</h3> 62 63<p>A management application and a platform MBeanServer of a running 64virtual machine can interoperate 65without requiring classes used by the platform MXBean interfaces. 66The data types being transmitted between the JMX connector 67server and the connector client are JMX 68{@linkplain javax.management.openmbean.OpenType open types} and 69this allows interoperation across versions. 70A data type used by the MXBean interfaces are mapped to an 71open type when being accessed via MBeanServer interface. 72See the <a href="{@docRoot}/javax/management/MXBean.html#MXBean-spec"> 73MXBean</a> specification for details. 74 75<h3><a id="examples">Ways to Access MXBeans</a></h3> 76 77<p>An application can monitor the instrumentation of the 78Java virtual machine and the runtime in the following ways: 79<p> 80<b>1. Direct access to an MXBean interface</b> 81<ul> 82<li>Get an MXBean instance locally in the running Java virtual machine: 83<pre> 84 RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean(); 85 86 // Get the standard attribute "VmVendor" 87 String vendor = mxbean.getVmVendor(); 88</pre> 89<p>Or by calling the 90 {@link java.lang.management.ManagementFactory#getPlatformMXBean(Class) 91 getPlatformMXBean} or 92 {@link java.lang.management.ManagementFactory#getPlatformMXBeans(Class) 93 getPlatformMXBeans} method: 94<pre> 95 RuntimeMXBean mxbean = ManagementFactory.getPlatformMXBean(RuntimeMXBean.class); 96 97 // Get the standard attribute "VmVendor" 98 String vendor = mxbean.getVmVendor(); 99</pre> 100</li> 101<li>Construct an MXBean proxy instance that forwards the 102 method calls to a given MBeanServer: 103<pre> 104 MBeanServerConnection mbs; 105 106 // Connect to a running JVM (or itself) and get MBeanServerConnection 107 // that has the JVM MBeans registered in it 108 ... 109 110 // Get a MBean proxy for RuntimeMXBean interface 111 RuntimeMXBean proxy = 112 {@link java.lang.management.ManagementFactory#getPlatformMXBean(MBeanServerConnection, Class) 113 ManagementFactory.getPlatformMXBean}(mbs, 114 RuntimeMXBean.class); 115 // Get standard attribute "VmVendor" 116 String vendor = proxy.getVmVendor(); 117</pre> 118<p>A proxy is typically used to access an MXBean 119 in a remote Java virtual machine. 120 An alternative way to create an MXBean proxy is: 121<pre> 122 RuntimeMXBean proxy = 123 {@link java.lang.management.ManagementFactory#newPlatformMXBeanProxy 124 ManagementFactory.newPlatformMXBeanProxy}(mbs, 125 ManagementFactory.RUNTIME_MXBEAN_NAME, 126 RuntimeMXBean.class); 127</pre> 128</li> 129</ul> 130<p> 131<b>2. Indirect access to an MXBean interface via MBeanServer</b> 132<ul> 133<li>Go through the 134 {@link java.lang.management.ManagementFactory#getPlatformMBeanServer 135 platform MBeanServer} to access MXBeans locally or 136 a specific {@code MBeanServerConnection} to access 137 MXBeans remotely. 138 The attributes and operations of an MXBean use only 139 <em>JMX open types</em> which include basic data types, 140 {@link javax.management.openmbean.CompositeData CompositeData}, 141 and {@link javax.management.openmbean.TabularData TabularData} 142 defined in {@link javax.management.openmbean.OpenType OpenType}. 143<pre> 144 MBeanServerConnection mbs; 145 146 // Connect to a running JVM (or itself) and get MBeanServerConnection 147 // that has the JVM MXBeans registered in it 148 ... 149 150 try { 151 // Assuming the RuntimeMXBean has been registered in mbs 152 ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME); 153 154 // Get standard attribute "VmVendor" 155 String vendor = (String) mbs.getAttribute(oname, "VmVendor"); 156 } catch (....) { 157 // Catch the exceptions thrown by ObjectName constructor 158 // and MBeanServer.getAttribute method 159 ... 160 } 161</pre> 162</li> 163</ul> 164 165 166<h3><a id="extension">Platform Extension</a></h3> 167 168<p>A Java virtual machine implementation may add its platform extension to 169the management interface by defining platform-dependent 170interfaces that extend the standard management interfaces to include 171platform-specific metrics and management operations. 172The static factory methods in the <code>ManagementFactory</code> class will 173return the MXBeans with the platform extension. 174 175<p> 176It is recommended to name the platform-specific attributes with 177a vendor-specific prefix such as the vendor's name to 178avoid collisions of the attribute name between the future extension 179to the standard management interface and the platform extension. 180If the future extension to the standard management interface defines 181a new attribute for a management interface and the attribute name 182is happened to be same as some vendor-specific attribute's name, 183the applications accessing that vendor-specific attribute would have 184to be modified to cope with versioning and compatibility issues. 185 186<p>Below is an example showing how to access an attribute 187from the platform extension: 188 189<p> 1901) Direct access to the Oracle-specific MXBean interface 191<blockquote> 192<pre> 193 List<com.sun.management.GarbageCollectorMXBean> mxbeans = 194 ManagementFactory.getPlatformMXBeans(com.sun.management.GarbageCollectorMXBean.class); 195 196 for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) { 197 // Get the standard attribute "CollectionCount" 198 String count = mxbean.getCollectionCount(); 199 200 // Get the platform-specific attribute "LastGcInfo" 201 GcInfo gcinfo = gc.getLastGcInfo(); 202 ... 203 } 204</pre> 205</blockquote> 206 207<p> 2082) Access the Oracle-specific MXBean interface via <code>MBeanServer</code> 209 through proxy 210 211<blockquote><pre> 212 MBeanServerConnection mbs; 213 214 // Connect to a running JVM (or itself) and get MBeanServerConnection 215 // that has the JVM MXBeans registered in it 216 ... 217 218 List<com.sun.management.GarbageCollectorMXBean> mxbeans = 219 ManagementFactory.getPlatformMXBeans(mbs, com.sun.management.GarbageCollectorMXBean.class); 220 221 for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) { 222 // Get the standard attribute "CollectionCount" 223 String count = mxbean.getCollectionCount(); 224 225 // Get the platform-specific attribute "LastGcInfo" 226 GcInfo gcinfo = gc.getLastGcInfo(); 227 ... 228 } 229</pre></blockquote> 230 231<p> Unless otherwise noted, passing a <code>null</code> argument to a constructor 232or method in any class or interface in this package will cause a {@link 233java.lang.NullPointerException NullPointerException} to be thrown. 234 235<p> The java.lang.management API is thread-safe. 236 237@see {@linkplain javax.management JMX Specification} 238 239@author Mandy Chung 240@since 1.5 241 242</body> 243</html> 244