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<com.sun.management.GarbageCollectorMXBean> 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<com.sun.management.GarbageCollectorMXBean> 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>