Showing the changes to java/pkg/java/lang/management/package.html (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,248 @@ | ||
| 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 | +</pre></blockquote> | |
| 234 | + | |
| 235 | +<p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor | |
| 236 | +or method in any class or interface in this package will cause a {@link | |
| 237 | +java.lang.NullPointerException NullPointerException} to be thrown. | |
| 238 | + | |
| 239 | +<p> The java.lang.management API is thread-safe. | |
| 240 | + | |
| 241 | +@see <a href="../../../javax/management/package-summary.html"> | |
| 242 | + JMX Specification.</a> | |
| 243 | + | |
| 244 | +@author Mandy Chung | |
| 245 | +@since 1.5 | |
| 246 | + | |
| 247 | +</body> | |
| 248 | +</html> | |