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 interface for monitoring and management of the
31 Java virtual machine as well as the operating system on which the
32 Java virtual machine is running. It allows both local and remote
33 monitoring and management of the running Java virtual machine.
34
35 <h4>Platform MXBeans</h4>
36
37 This package defines the management interface of the following
38 components:
39
40 <blockquote>
41 <table cellspacing=1 summary="Description of the MBeans">
42 <tr>
43 <th><p align="left">Management Interface</p></th>
44 <th><p align="left">Description</p></th>
45 </tr>
46 <tr>
47 <td> <tt>{@link java.lang.management.ClassLoadingMXBean}</tt> </td>
48 <td> Class loading system of the Java virtual machine.</td>
49 </tr>
50 <tr>
51 <td> <tt>{@link java.lang.management.CompilationMXBean}</tt> </td>
52 <td> Compilation system of the Java virtual machine.</td>
53 </tr>
54 <tr>
55 <td> <tt>{@link java.lang.management.MemoryMXBean}</tt> </td>
56 <td> Memory system of the Java virtual machine.</td>
57 </tr>
58 <tr>
59 <td> <tt>{@link java.lang.management.ThreadMXBean}</tt> </td>
60 <td> Threads system of the Java virtual machine.</td>
61 </tr>
62 <tr>
63 <td> <tt>{@link java.lang.management.RuntimeMXBean}</tt> </td>
64 <td> Runtime system of the Java virtual machine.</td>
65 </tr>
66 <tr>
67 <td> <tt>{@link java.lang.management.OperatingSystemMXBean}</tt> </td>
68 <td> Operating system on which the Java virtual machine is running.</td>
69 </tr>
70 <tr>
71 <td> <tt>{@link java.lang.management.GarbageCollectorMXBean}</tt> </td>
72 <td> Garbage collector in the Java virtual machine.</td>
73 </tr>
74 <tr>
75 <td> <tt>{@link java.lang.management.MemoryManagerMXBean}</tt> </td>
76 <td> Memory manager in the Java virtual machine.</td>
77 </tr>
78 <tr>
79 <td> <tt>{@link java.lang.management.MemoryPoolMXBean}</tt> </td>
80 <td> Memory pool in the Java virtual machine.</td>
81 </tr>
82 </table>
83 </blockquote>
84
85 <p>
86 A platform MXBean is a <i>managed bean</i> that defines the management
87 interface for one component for the platform and is specified in the
88 <a href="ManagementFactory.html#MXBean">
89 ManagementFactory</a> class.
90
91 <p>An application can monitor the instrumentation of the
92 Java virtual machine and manage certain characteristics in
93 the following ways:
94 <ul>
95 <li><i>Direct access to an MXBean interface</i>
96 <ol type="a">
97 <li>Get the MXBean instance through the static factory method
98 and access the MXBean interface locally of the running
99 virtual machine.</li>
100 <li>Construct an MXBean proxy instance that
101 forwards the method calls to a given
102 {@link javax.management.MBeanServer MBeanServer}
103 by calling
104 {@link java.lang.management.ManagementFactory#newPlatformMXBeanProxy
105 ManagementFactory.newPlatformMXBeanProxy}.
106 A proxy is typically constructed to remotely access
107 an MXBean of another running virtual machine.</li>
108 </ol></li>
109 <li><i>Indirect access via {@link javax.management.MBeanServer MBeanServer}
110 interface</i>
111 <ol type="a">
112 <li>Go through the
113 {@link java.lang.management.ManagementFactory#getPlatformMBeanServer
114 platform MBeanServer} to access MXBeans locally or
115 a specific <tt>MBeanServerConnection</tt> to access
116 MXBeans remotely.
117 The attributes and operations of an MXBean use only
118 <em>JMX open types</em> which include basic data types,
119 {@link javax.management.openmbean.CompositeData CompositeData},
120 and {@link javax.management.openmbean.TabularData TabularData}
121 defined in {@link javax.management.openmbean.OpenType OpenType}.
122 </li>
123 </ol></li>
124 </ul>
125
126 Below shows a few <a href="#examples">examples</a> of different
127 ways to access MXBeans.
128
129 <h4>ManagementFactory</h4>
130
131 The {@link java.lang.management.ManagementFactory} class is the management
132 factory class for the Java platform. This class provides a set of
133 static factory methods to obtain the MXBeans for the Java platform
134 to allow an application to access the MXBeans directly.
135
136 <p>A <em>platform MBeanServer</em> can be accessed with the
137 {@link java.lang.management.ManagementFactory#getPlatformMBeanServer
138 getPlatformMBeanServer} method. On the first call to this method,
139 it creates the platform MBeanServer and registers all platform MXBeans
140 including platform MXBeans defined in other packages such as
141 {@link java.util.logging.LoggingMXBean}.
142 Each platform MXBean is registered with a unique name defined in the
143 {@link java.lang.management.ManagementFactory ManagementFactory} class
144 for constructing {@link javax.management.ObjectName ObjectName}.
145 This is a single MBeanServer that can be shared by different managed
146 components running within the same Java virtual machine.
147
148 <h4>Interoperability</h4>
149
150 A management application and a platform MBeanServer of a running
151 virtual machine can interoperate
152 without requiring classes used by the platform MXBean interfaces.
153 The data types being transmitted between the JMX connector
154 server and the connector client are JMX
155 {@link javax.management.openmbean.OpenType open types} and
156 this allows interoperation across versions.
157
158 <p>A data type used by the MXBean interfaces are mapped to
159 an open type when being accessed via MBeanServer interface.
160 The data type mapping is specified in the
161 {@link java.lang.management.ManagementFactory ManagementFactory} class.
162
163 <h4><a name="examples">Ways to Access MXBeans</a></h4>
164
165 There are three different ways to access the management interfaces.
166
167 <p>
168 <ol>
169 <li>Call the methods in the MXBean directly within the same
170 Java virtual machine.
171 <blockquote><pre>
172 RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();
173
174 // Get the standard attribute "VmVendor"
175 String vendor = mxbean.getVmVendor();
176
177 </pre>
178 </blockquote>
179 </li>
180
181 <li>Go through a <tt>MBeanServerConnection</tt> connecting
182 to the <tt>platform MBeanServer</tt> of a running virtual machine.</li>
183 <blockquote><pre>
184 MBeanServerConnection mbs;
185
186 // Connect to a running JVM (or itself) and get MBeanServerConnection
187 // that has the JVM MXBeans registered in it
188 ...
189
190 try {
191 // Assuming the RuntimeMXBean has been registered in mbs
192 ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);
193
194 // Get standard attribute "VmVendor"
195 String vendor = (String) mbs.getAttribute(oname, "VmVendor");
196 } catch (....) {
197 // Catch the exceptions thrown by ObjectName constructor
198 // and MBeanServer.getAttribute method
199 ...
200 }
201
202 </pre></blockquote>
203
204 <li>Use MXBean proxy.</li>
205 <blockquote><pre>
206 MBeanServerConnection mbs;
207
208 // Connect to a running JVM (or itself) and get MBeanServerConnection
209 // that has the JVM MBeans registered in it
210 ...
211
212 // Get a MBean proxy for RuntimeMXBean interface
213 RuntimeMXBean proxy =
214 ManagementFactory.newPlatformMXBeanProxy(mbs,
215 ManagementFactory.RUNTIME_MXBEAN_NAME,
216 RuntimeMXBean.class);
217 // Get standard attribute "VmVendor"
218 String vendor = proxy.getVmVendor();
219 </pre></blockquote>
220 </ol>
221
222
223 <h4><a name="extension">Platform Extension</a></h4>
224
225 A Java virtual machine implementation may add its platform extension to
226 the management interface by defining platform-dependent
227 interfaces that extend the standard management interfaces to include
228 platform-specific metrics and management operations.
229 The static factory methods in the <tt>ManagementFactory</tt> class will
230 return the MBeans with the platform extension.
231
232 <p>
233 It is recommended to name the platform-specific attributes with
234 a vendor-specific prefix such as the vendor's name to
235 avoid collisions of the attribute name between the future extension
236 to the standard management interface and the platform extension.
237 If the future extension to the standard management interface defines
238 a new attribute for a management interface and the attribute name
239 is happened to be same as some vendor-specific attribute's name,
240 the applications accessing that vendor-specific attribute would have
241 to be modified to cope with versioning and compatibility issues.
242
243 <p>Below is an example showing how to access a platform-specific
244 attribute from Sun's implementation of the <tt>RuntimeMXBean</tt>.
245
246 <p>
247 1) Direct access to the Sun-specific MXBean interface
248 <blockquote><pre>
249 com.sun.management.RuntimeMXBean mxbean =
250 (com.sun.management.RuntimeMXBean) ManagementFactory.getRuntimeMXBean();
251
252 // Get the standard attribute "VmVendor"
253 String vendor = mxbean.getVmVendor();
254
255 // Get the platform-specific attribute "Bar"
256 BarType bar = mxbean.getBar();
257
258 </pre>
259 </blockquote>
260
261 <p>
262 2) Access the Sun-specific MXBean interface via <tt>MBeanServer</tt>
263
264 <blockquote><pre>
265 MBeanServerConnection mbs;
266
267 // Connect to a running JVM (or itself) and get MBeanServerConnection
268 // that has the JVM MXBeans registered in it
269 ...
270
271 try {
272 // Assuming the RuntimeMXBean has been registered in mbs
273 ObjectName oname = new ObjectName(ManagementFactory.RUNTIME_MXBEAN_NAME);
274
275 // Get standard attribute "VmVendor"
276 String vendor = (String) mbs.getAttribute(oname, "VmVendor");
277
278 // Check if this MXBean contains Sun's extension
279 if (mbs.isInstanceOf(oname, "com.sun.management.RuntimeMXBean")) {
280 // Get platform-specific attribute "Bar"
281 BarType bar = (String) mbs.getAttribute(oname, "Bar");
282 }
283 } catch (....) {
284 // Catch the exceptions thrown by ObjectName constructor
285 // and MBeanServer methods
286 ...
287 }
288
289 </pre></blockquote>
290
291 <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
292 or method in any class or interface in this package will cause a {@link
293 java.lang.NullPointerException NullPointerException} to be thrown.
294
295 <p> The java.lang.management API is thread-safe.
296
297 @see <a href="../../../javax/management/package-summary.html">
298 JMX Specification.</a>
299
300 @author Mandy Chung
301 @since 1.5
302
303 </body>
304 </html>