| author | dholmes |
| Mon, 18 Nov 2019 23:41:06 -0500 | |
| changeset 59132 | 189f47d990b5 |
| parent 55120 | b0513c833960 |
| permissions | -rw-r--r-- |
|
1935
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
1 |
<!-- |
| 55120 | 2 |
Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved. |
|
1935
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
3 |
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
4 |
|
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
5 |
This code is free software; you can redistribute it and/or modify it |
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
6 |
under the terms of the GNU General Public License version 2 only, as |
| 5506 | 7 |
published by the Free Software Foundation. Oracle designates this |
|
1935
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
8 |
particular file as subject to the "Classpath" exception as provided |
| 5506 | 9 |
by Oracle in the LICENSE file that accompanied this code. |
|
1935
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
10 |
|
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
11 |
This code is distributed in the hope that it will be useful, but WITHOUT |
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
12 |
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
13 |
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
14 |
version 2 for more details (a copy is included in the LICENSE file that |
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
15 |
accompanied this code). |
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
16 |
|
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
17 |
You should have received a copy of the GNU General Public License version |
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
18 |
2 along with this work; if not, write to the Free Software Foundation, |
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
19 |
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
20 |
|
| 5506 | 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. |
|
|
1935
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
24 |
--> |
|
4010e03f8c1c
6719182: update legal notice in java/lang/instrument/package.html
darcy
parents:
2
diff
changeset
|
25 |
|
| 2 | 26 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
27 |
<html> |
|
28 |
<body bgcolor="white"> |
|
29 |
||
| 25859 | 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. |
|
| 2 | 34 |
|
| 55120 | 35 |
<h2><a id="MXBean">Platform MXBean</a></h2> |
| 25859 | 36 |
<p> |
37 |
A platform MXBean is a <i>managed bean</i> that |
|
| 45138 | 38 |
conforms to the {@linkplain javax.management JMX}
|
| 25859 | 39 |
Instrumentation Specification and only uses a set of basic data types. |
40 |
Each platform MXBean is a {@link java.lang.management.PlatformManagedObject}
|
|
41 |
with a unique |
|
42 |
{@linkplain java.lang.management.PlatformManagedObject#getObjectName name}.
|
|
| 55120 | 43 |
<h2>ManagementFactory</h2> |
| 2 | 44 |
|
| 25859 | 45 |
<p>The {@link java.lang.management.ManagementFactory} class is the management
|
46 |
factory class for the Java platform. This class provides a set of |
|
47 |
static factory methods to obtain the MXBeans for the Java platform |
|
48 |
to 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, |
|
53 |
it creates the platform MBeanServer and registers all platform MXBeans |
|
54 |
including {@linkplain java.lang.management.PlatformManagedObject
|
|
55 |
platform MXBeans}. |
|
56 |
Each platform MXBean is registered with a unique name defined in |
|
57 |
the specification of the management interface. |
|
58 |
This is a single MBeanServer that can be shared by different managed |
|
59 |
components running within the same Java virtual machine. |
|
60 |
||
| 55120 | 61 |
<h2>Interoperability</h2> |
| 2 | 62 |
|
| 25859 | 63 |
<p>A management application and a platform MBeanServer of a running |
64 |
virtual machine can interoperate |
|
65 |
without requiring classes used by the platform MXBean interfaces. |
|
66 |
The data types being transmitted between the JMX connector |
|
67 |
server and the connector client are JMX |
|
68 |
{@linkplain javax.management.openmbean.OpenType open types} and
|
|
69 |
this allows interoperation across versions. |
|
70 |
A data type used by the MXBean interfaces are mapped to an |
|
71 |
open type when being accessed via MBeanServer interface. |
|
| 52469 | 72 |
See the <a href="{@docRoot}/java.management/javax/management/MXBean.html#MXBean-spec">
|
| 25859 | 73 |
MXBean</a> specification for details. |
74 |
||
| 55120 | 75 |
<h2><a id="examples">Ways to Access MXBeans</a></h2> |
| 2 | 76 |
|
| 25859 | 77 |
<p>An application can monitor the instrumentation of the |
78 |
Java 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); |
|
| 2 | 96 |
|
| 25859 | 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; |
|
| 2 | 105 |
|
| 25859 | 106 |
// Connect to a running JVM (or itself) and get MBeanServerConnection |
107 |
// that has the JVM MBeans registered in it |
|
108 |
... |
|
| 2 | 109 |
|
| 25859 | 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; |
|
| 2 | 145 |
|
| 25859 | 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); |
|
| 2 | 153 |
|
| 25859 | 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> |
|
| 2 | 164 |
|
165 |
||
| 55120 | 166 |
<h2><a id="extension">Platform Extension</a></h2> |
| 2 | 167 |
|
| 25859 | 168 |
<p>A Java virtual machine implementation may add its platform extension to |
169 |
the management interface by defining platform-dependent |
|
170 |
interfaces that extend the standard management interfaces to include |
|
171 |
platform-specific metrics and management operations. |
|
|
32034
05676cfd40b5
8133040: docs: replace <tt> tags (obsolete in html5) for java.management
avstepan
parents:
25859
diff
changeset
|
172 |
The static factory methods in the <code>ManagementFactory</code> class will |
| 25859 | 173 |
return the MXBeans with the platform extension. |
| 2 | 174 |
|
175 |
<p> |
|
| 25859 | 176 |
It is recommended to name the platform-specific attributes with |
177 |
a vendor-specific prefix such as the vendor's name to |
|
178 |
avoid collisions of the attribute name between the future extension |
|
179 |
to the standard management interface and the platform extension. |
|
180 |
If the future extension to the standard management interface defines |
|
181 |
a new attribute for a management interface and the attribute name |
|
182 |
is happened to be same as some vendor-specific attribute's name, |
|
183 |
the applications accessing that vendor-specific attribute would have |
|
184 |
to be modified to cope with versioning and compatibility issues. |
|
| 2 | 185 |
|
| 25859 | 186 |
<p>Below is an example showing how to access an attribute |
187 |
from the platform extension: |
|
| 2 | 188 |
|
| 25859 | 189 |
<p> |
190 |
1) Direct access to the Oracle-specific MXBean interface |
|
| 2 | 191 |
<blockquote> |
| 25859 | 192 |
<pre> |
193 |
List<com.sun.management.GarbageCollectorMXBean> mxbeans = |
|
194 |
ManagementFactory.getPlatformMXBeans(com.sun.management.GarbageCollectorMXBean.class); |
|
| 2 | 195 |
|
| 25859 | 196 |
for (com.sun.management.GarbageCollectorMXBean gc : mxbeans) {
|
197 |
// Get the standard attribute "CollectionCount" |
|
198 |
String count = mxbean.getCollectionCount(); |
|
| 2 | 199 |
|
| 25859 | 200 |
// Get the platform-specific attribute "LastGcInfo" |
201 |
GcInfo gcinfo = gc.getLastGcInfo(); |
|
202 |
... |
|
203 |
} |
|
204 |
</pre> |
|
| 2 | 205 |
</blockquote> |
206 |
||
| 25859 | 207 |
<p> |
|
32034
05676cfd40b5
8133040: docs: replace <tt> tags (obsolete in html5) for java.management
avstepan
parents:
25859
diff
changeset
|
208 |
2) Access the Oracle-specific MXBean interface via <code>MBeanServer</code> |
| 25859 | 209 |
through proxy |
| 2 | 210 |
|
| 25859 | 211 |
<blockquote><pre> |
212 |
MBeanServerConnection mbs; |
|
| 2 | 213 |
|
| 25859 | 214 |
// Connect to a running JVM (or itself) and get MBeanServerConnection |
215 |
// that has the JVM MXBeans registered in it |
|
216 |
... |
|
| 2 | 217 |
|
| 25859 | 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(); |
|
| 2 | 224 |
|
| 25859 | 225 |
// Get the platform-specific attribute "LastGcInfo" |
226 |
GcInfo gcinfo = gc.getLastGcInfo(); |
|
227 |
... |
|
228 |
} |
|
229 |
</pre></blockquote> |
|
| 2 | 230 |
|
|
32034
05676cfd40b5
8133040: docs: replace <tt> tags (obsolete in html5) for java.management
avstepan
parents:
25859
diff
changeset
|
231 |
<p> Unless otherwise noted, passing a <code>null</code> argument to a constructor |
| 25859 | 232 |
or method in any class or interface in this package will cause a {@link
|
233 |
java.lang.NullPointerException NullPointerException} to be thrown. |
|
234 |
||
235 |
<p> The java.lang.management API is thread-safe. |
|
| 2 | 236 |
|
| 45138 | 237 |
@see {@linkplain javax.management JMX Specification}
|
| 2 | 238 |
|
| 25859 | 239 |
@author Mandy Chung |
240 |
@since 1.5 |
|
| 2 | 241 |
|
242 |
</body> |
|
243 |
</html> |