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>