|
1 <html> |
|
2 <head> |
|
3 <title>javax.management package</title> |
|
4 <!-- |
|
5 Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. |
|
6 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
7 |
|
8 This code is free software; you can redistribute it and/or modify it |
|
9 under the terms of the GNU General Public License version 2 only, as |
|
10 published by the Free Software Foundation. Oracle designates this |
|
11 particular file as subject to the "Classpath" exception as provided |
|
12 by Oracle in the LICENSE file that accompanied this code. |
|
13 |
|
14 This code is distributed in the hope that it will be useful, but WITHOUT |
|
15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
16 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
17 version 2 for more details (a copy is included in the LICENSE file that |
|
18 accompanied this code). |
|
19 |
|
20 You should have received a copy of the GNU General Public License version |
|
21 2 along with this work; if not, write to the Free Software Foundation, |
|
22 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
23 |
|
24 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
25 or visit www.oracle.com if you need additional information or have any |
|
26 questions. |
|
27 --> |
|
28 </head> |
|
29 <body bgcolor="white"> |
|
30 <p>Provides the core classes for the Java Management Extensions.</p> |
|
31 |
|
32 <p>The Java Management Extensions |
|
33 (JMX<sup><font size="-1">TM</font></sup>) API is a standard |
|
34 API for management and monitoring. Typical uses include:</p> |
|
35 |
|
36 <ul> |
|
37 <li>consulting and changing application configuration</li> |
|
38 |
|
39 <li>accumulating statistics about application behavior and |
|
40 making them available</li> |
|
41 |
|
42 <li>notifying of state changes and erroneous conditions.</li> |
|
43 </ul> |
|
44 |
|
45 <p>The JMX API can also be used as part of a solution for |
|
46 managing systems, networks, and so on.</p> |
|
47 |
|
48 <p>The API includes remote access, so a remote management |
|
49 program can interact with a running application for these |
|
50 purposes.</p> |
|
51 |
|
52 <h2>MBeans</h2> |
|
53 |
|
54 <p>The fundamental notion of the JMX API is the <em>MBean</em>. |
|
55 An MBean is a named <em>managed object</em> representing a |
|
56 resource. It has a <em id="mgIface">management interface</em> |
|
57 which must be <em>public</em> and consist of:</p> |
|
58 |
|
59 <ul> |
|
60 <li>named and typed attributes that can be read and/or |
|
61 written</li> |
|
62 |
|
63 <li>named and typed operations that can be invoked</li> |
|
64 |
|
65 <li>typed notifications that can be emitted by the MBean.</li> |
|
66 </ul> |
|
67 |
|
68 <p>For example, an MBean representing an application's |
|
69 configuration could have attributes representing the different |
|
70 configuration items. Reading the <code>CacheSize</code> |
|
71 attribute would return the current value of that item. |
|
72 Writing it would update the item, potentially changing the |
|
73 behavior of the running application. An operation such as |
|
74 <code>save</code> could store the current configuration |
|
75 persistently. A notification such as |
|
76 <code>ConfigurationChangedNotification</code> could be sent |
|
77 every time the configuration is changed.</p> |
|
78 |
|
79 <p>In the standard usage of the JMX API, MBeans are implemented |
|
80 as Java objects. However, as explained below, these objects are |
|
81 not usually referenced directly.</p> |
|
82 |
|
83 |
|
84 <h3>Standard MBeans</h3> |
|
85 |
|
86 <p>To make MBean implementation simple, the JMX API includes the |
|
87 notion of <em>Standard MBeans</em>. A Standard MBean is one |
|
88 whose attributes and operations are deduced from a Java |
|
89 interface using certain naming patterns, similar to those used |
|
90 by JavaBeans<sup><font size="-1">TM</font></sup>. For |
|
91 example, consider an interface like this:</p> |
|
92 |
|
93 <pre> |
|
94 public interface ConfigurationMBean { |
|
95 public int getCacheSize(); |
|
96 public void setCacheSize(int size); |
|
97 public long getLastChangedTime(); |
|
98 public void save(); |
|
99 } |
|
100 </pre> |
|
101 |
|
102 <p>The methods <code>getCacheSize</code> and |
|
103 <code>setCacheSize</code> define a read-write attribute of |
|
104 type <code>int</code> called <code>CacheSize</code> (with an |
|
105 initial capital, unlike the JavaBeans convention).</p> |
|
106 |
|
107 <p>The method <code>getLastChangedTime</code> defines an |
|
108 attribute of type <code>long</code> called |
|
109 <code>LastChangedTime</code>. This is a read-only attribute, |
|
110 since there is no method <code>setLastChangedTime</code>.</p> |
|
111 |
|
112 <p>The method <code>save</code> defines an operation called |
|
113 <code>save</code>. It is not an attribute, since its name |
|
114 does not begin with <code>get</code>, <code>set</code>, or |
|
115 <code>is</code>.</p> |
|
116 |
|
117 <p>The exact naming patterns for Standard MBeans are detailed in |
|
118 the <a href="#spec">JMX Specification</a>.</p> |
|
119 |
|
120 <p>There are two ways to make a Java object that is an MBean |
|
121 with this management interface. One is for the object to be |
|
122 of a class that has exactly the same name as the Java |
|
123 interface but without the <code>MBean</code> suffix. So in |
|
124 the example the object would be of the class |
|
125 <code>Configuration</code>, in the same Java package as |
|
126 <code>ConfigurationMBean</code>. The second way is to use the |
|
127 {@link javax.management.StandardMBean StandardMBean} |
|
128 class.</p> |
|
129 |
|
130 |
|
131 <h3>MXBeans</h3> |
|
132 |
|
133 <p>An <em>MXBean</em> is a variant of Standard MBean where complex |
|
134 types are mapped to a standard set of types defined in the |
|
135 {@link javax.management.openmbean} package. MXBeans are appropriate |
|
136 if you would otherwise need to reference application-specific |
|
137 classes in your MBean interface. They are described in detail |
|
138 in the specification for {@link javax.management.MXBean MXBean}.</p> |
|
139 |
|
140 |
|
141 <h3>Dynamic MBeans</h3> |
|
142 |
|
143 <p>A <em>Dynamic MBean</em> is an MBean that defines its |
|
144 management interface at run-time. For example, a configuration |
|
145 MBean could determine the names and types of the attributes it |
|
146 exposes by parsing an XML file.</p> |
|
147 |
|
148 <p>Any Java object of a class that implements the {@link |
|
149 javax.management.DynamicMBean DynamicMBean} interface is a |
|
150 Dynamic MBean.</p> |
|
151 |
|
152 |
|
153 <h3>Open MBeans</h3> |
|
154 |
|
155 <p>An <em>Open MBean</em> is a kind of Dynamic MBean where the |
|
156 types of attributes and of operation parameters and return |
|
157 values are built using a small set of predefined Java classes. |
|
158 Open MBeans facilitate operation with remote management programs |
|
159 that do not necessarily have access to application-specific |
|
160 types, including non-Java programs. Open MBeans are defined by |
|
161 the package <a href="openmbean/package-summary.html"><code> |
|
162 javax.management.openmbean</code></a>.</p> |
|
163 |
|
164 |
|
165 <h3>Model MBeans</h3> |
|
166 |
|
167 <p>A <em>Model MBean</em> is a kind of Dynamic MBean that acts |
|
168 as a bridge between the management interface and the |
|
169 underlying managed resource. Both the management interface and |
|
170 the managed resource are specified as Java objects. The same |
|
171 Model MBean implementation can be reused many times with |
|
172 different management interfaces and managed resources, and it can |
|
173 provide common functionality such as persistence and caching. |
|
174 Model MBeans are defined by the package |
|
175 <a href="modelmbean/package-summary.html"><code> |
|
176 javax.management.modelmbean</code></a>.</p> |
|
177 |
|
178 |
|
179 <h2>MBean Server</h2> |
|
180 |
|
181 <p>To be useful, an MBean must be registered in an <em>MBean |
|
182 Server</em>. An MBean Server is a repository of MBeans. |
|
183 Usually the only access to the MBeans is through the MBean |
|
184 Server. In other words, code no longer accesses the Java |
|
185 object implementing the MBean directly, but instead accesses |
|
186 the MBean by name through the MBean Server. Each MBean has a |
|
187 unique name within the MBean Server, defined by the {@link |
|
188 javax.management.ObjectName ObjectName} class.</p> |
|
189 |
|
190 <p>An MBean Server is an object implementing the interface |
|
191 {@link javax.management.MBeanServer MBeanServer}. |
|
192 The most convenient MBean Server to use is the |
|
193 <em>Platform MBean Server</em>. This is a |
|
194 single MBean Server that can be shared by different managed |
|
195 components running within the same Java Virtual Machine. The |
|
196 Platform MBean Server is accessed with the method {@link |
|
197 java.lang.management.ManagementFactory#getPlatformMBeanServer()}.</p> |
|
198 |
|
199 <p>Application code can also create a new MBean Server, or |
|
200 access already-created MBean Servers, using the {@link |
|
201 javax.management.MBeanServerFactory MBeanServerFactory} class.</p> |
|
202 |
|
203 |
|
204 <h3>Creating MBeans in the MBean Server</h3> |
|
205 |
|
206 <p>There are two ways to create an MBean. One is to construct a |
|
207 Java object that will be the MBean, then use the {@link |
|
208 javax.management.MBeanServer#registerMBean registerMBean} |
|
209 method to register it in the MBean Server. The other is to |
|
210 create and register the MBean in a single operation using one |
|
211 of the {@link javax.management.MBeanServer#createMBean(String, |
|
212 javax.management.ObjectName) createMBean} methods.</p> |
|
213 |
|
214 <p>The <code>registerMBean</code> method is simpler for local |
|
215 use, but cannot be used remotely. The |
|
216 <code>createMBean</code> method can be used remotely, but |
|
217 sometimes requires attention to class loading issues.</p> |
|
218 |
|
219 <p>An MBean can perform actions when it is registered in or |
|
220 unregistered from an MBean Server if it implements the {@link |
|
221 javax.management.MBeanRegistration MBeanRegistration} |
|
222 interface.</p> |
|
223 |
|
224 |
|
225 <h3>Accessing MBeans in the MBean Server</h3> |
|
226 |
|
227 <p>Given an <code>ObjectName</code> <code>name</code> and an |
|
228 <code>MBeanServer</code> <code>mbs</code>, you can access |
|
229 attributes and operations as in this example:</p> |
|
230 |
|
231 <pre> |
|
232 int cacheSize = mbs.getAttribute(name, "CacheSize"); |
|
233 {@link javax.management.Attribute Attribute} newCacheSize = |
|
234 new Attribute("CacheSize", new Integer(2000)); |
|
235 mbs.setAttribute(name, newCacheSize); |
|
236 mbs.invoke(name, "save", new Object[0], new Class[0]); |
|
237 </pre> |
|
238 |
|
239 <p id="proxy">Alternatively, if you have a Java interface that |
|
240 corresponds to the management interface for the MBean, you can use an |
|
241 <em>MBean proxy</em> like this:</p> |
|
242 |
|
243 <pre> |
|
244 ConfigurationMBean conf = |
|
245 {@link javax.management.JMX#newMBeanProxy |
|
246 JMX.newMBeanProxy}(mbs, name, ConfigurationMBean.class); |
|
247 int cacheSize = conf.getCacheSize(); |
|
248 conf.setCacheSize(2000); |
|
249 conf.save(); |
|
250 </pre> |
|
251 |
|
252 <p>Using an MBean proxy is just a convenience. The second |
|
253 example ends up calling the same <code>MBeanServer</code> |
|
254 operations as the first one.</p> |
|
255 |
|
256 <p>An MBean Server can be queried for MBeans whose names match |
|
257 certain patterns and/or whose attributes meet certain |
|
258 constraints. Name patterns are constructed using the {@link |
|
259 javax.management.ObjectName ObjectName} class and constraints |
|
260 are constructed using the {@link javax.management.Query Query} |
|
261 class. The methods {@link |
|
262 javax.management.MBeanServer#queryNames queryNames} and {@link |
|
263 javax.management.MBeanServer#queryMBeans queryMBeans} then |
|
264 perform the query.</p> |
|
265 |
|
266 |
|
267 <h3>MBean lifecycle</h3> |
|
268 |
|
269 <p>An MBean can implement the {@link javax.management.MBeanRegistration |
|
270 MBeanRegistration} interface in order to be told when it is registered |
|
271 and unregistered in the MBean Server. Additionally, the {@link |
|
272 javax.management.MBeanRegistration#preRegister preRegister} method |
|
273 allows the MBean to get a reference to the <code>MBeanServer</code> |
|
274 object and to get its <code>ObjectName</code> within the MBean |
|
275 Server.</p> |
|
276 |
|
277 |
|
278 <h2>Notifications</h2> |
|
279 |
|
280 <p>A <em>notification</em> is an instance of the {@link |
|
281 javax.management.Notification Notification} class or a |
|
282 subclass. In addition to its Java class, it has a |
|
283 <em>type</em> string that can distinguish it from other |
|
284 notifications of the same class.</p> |
|
285 |
|
286 <p>An MBean that will emit notifications must implement the |
|
287 {@link javax.management.NotificationBroadcaster |
|
288 NotificationBroadcaster} or {@link |
|
289 javax.management.NotificationEmitter NotificationEmitter} |
|
290 interface. Usually, it does this by subclassing |
|
291 {@link javax.management.NotificationBroadcasterSupport |
|
292 NotificationBroadcasterSupport} or delegating to an instance of |
|
293 that class. Here is an example:</p> |
|
294 |
|
295 <pre> |
|
296 public class Configuration <b>extends NotificationBroadcasterSupport</b> |
|
297 implements ConfigurationMBean { |
|
298 ... |
|
299 private void updated() { |
|
300 Notification n = new Notification(...); |
|
301 <b>{@link javax.management.NotificationBroadcasterSupport#sendNotification |
|
302 sendNotification}(n)</b>; |
|
303 } |
|
304 } |
|
305 </pre> |
|
306 |
|
307 |
|
308 <p>Notifications can be received by a <em>listener</em>, which |
|
309 is an object that implements the {@link |
|
310 javax.management.NotificationListener NotificationListener} |
|
311 interface. You can add a listener to an MBean with the method |
|
312 {@link |
|
313 javax.management.MBeanServer#addNotificationListener(ObjectName, |
|
314 NotificationListener, NotificationFilter, Object)}. |
|
315 You can optionally supply a <em>filter</em> to this method, to |
|
316 select only notifications of interest. A filter is an object |
|
317 that implements the {@link javax.management.NotificationFilter |
|
318 NotificationFilter} interface.</p> |
|
319 |
|
320 <p>An MBean can be a listener for notifications emitted by other |
|
321 MBeans in the same MBean Server. In this case, it implements |
|
322 {@link javax.management.NotificationListener |
|
323 NotificationListener} and the method {@link |
|
324 javax.management.MBeanServer#addNotificationListener(ObjectName, |
|
325 ObjectName, NotificationFilter, Object)} is used to listen.</p> |
|
326 |
|
327 |
|
328 <h2>Remote Access to MBeans</h2> |
|
329 |
|
330 <p>An MBean Server can be accessed remotely through a |
|
331 <em>connector</em>. A connector allows a remote Java |
|
332 application to access an MBean Server in essentially the same |
|
333 way as a local one. The package |
|
334 <a href="remote/package-summary.html"><code> |
|
335 javax.management.remote</code></a> defines connectors.</p> |
|
336 |
|
337 <p>The JMX specification also defines the notion of an |
|
338 <em>adaptor</em>. An adaptor translates between requests in a |
|
339 protocol such as SNMP or HTML and accesses to an MBean Server. |
|
340 So for example an SNMP GET operation might result in a |
|
341 <code>getAttribute</code> on the MBean Server.</p> |
|
342 |
|
343 <h3 id="interop">Interoperability between versions of the JMX |
|
344 specification</h3> |
|
345 |
|
346 <p>When a client connects to a server using the JMX Remote |
|
347 API, it is possible that they do not have the same version |
|
348 of the JMX specification. The version of the JMX |
|
349 specification described here is version 1.4. Previous |
|
350 versions were 1.0, 1.1, and 1.2. (There was no 1.3.) |
|
351 The standard JMX Remote API is defined to work with version |
|
352 1.2 onwards, so in standards-based deployment the only |
|
353 interoperability questions that arise concern version 1.2 |
|
354 onwards.</p> |
|
355 |
|
356 <p>Every version of the JMX specification continues to |
|
357 implement the features of previous versions. So when the |
|
358 client is running an earlier version than the server, there |
|
359 should not be any interoperability concerns.</p> |
|
360 |
|
361 <p>When the client is running a later version than the server, |
|
362 certain newer features may not be available, as detailed in |
|
363 the next sections. The client can determine the server's |
|
364 version by examining the {@link |
|
365 javax.management.MBeanServerDelegateMBean#getSpecificationVersion |
|
366 SpecificationVersion} attribute of the {@code |
|
367 MBeanServerDelegate}.</p> |
|
368 |
|
369 <h4 id="interop-1.2">If the remote MBean Server is 1.2</h4> |
|
370 |
|
371 <ul> |
|
372 |
|
373 <li><p>You cannot use wildcards in a key property of an |
|
374 {@link javax.management.ObjectName ObjectName}, for |
|
375 example {@code domain:type=Foo,name=*}. Wildcards that |
|
376 match whole properties are still allowed, for example |
|
377 {@code *:*} or {@code *:type=Foo,*}.</p> |
|
378 |
|
379 <li><p>You cannot use {@link |
|
380 javax.management.Query#isInstanceOf Query.isInstanceOf} |
|
381 in a query.</p> |
|
382 |
|
383 <li><p>You cannot use dot syntax such as {@code |
|
384 HeapMemoryUsage.used} in the {@linkplain |
|
385 javax.management.monitor.Monitor#setObservedAttribute |
|
386 observed attribute} of a monitor, as described in the |
|
387 documentation for the {@link javax.management.monitor} |
|
388 package.</p> |
|
389 |
|
390 </ul> |
|
391 |
|
392 <p id="spec"> |
|
393 @see <a href="{@docRoot}/../technotes/guides/jmx/index.html"> |
|
394 Java Platform documentation on JMX technology</a> |
|
395 in particular the |
|
396 <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf"> |
|
397 JMX Specification, version 1.4(pdf).</a> |
|
398 |
|
399 @since 1.5 |
|
400 |
|
401 </body> |
|
402 </html> |