1 <html>
2 <head>
3 <title>javax.management package</title>
4 <!--
5 Copyright (c) 1999, 2017, 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) 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. For example, consider an interface like this:</p>
91
92 <pre>
93 public interface ConfigurationMBean {
94 public int getCacheSize();
95 public void setCacheSize(int size);
96 public long getLastChangedTime();
97 public void save();
98 }
99 </pre>
100
101 <p>The methods <code>getCacheSize</code> and
102 <code>setCacheSize</code> define a read-write attribute of
103 type <code>int</code> called <code>CacheSize</code> (with an
104 initial capital, unlike the JavaBeans convention).</p>
105
106 <p>The method <code>getLastChangedTime</code> defines an
107 attribute of type <code>long</code> called
108 <code>LastChangedTime</code>. This is a read-only attribute,
109 since there is no method <code>setLastChangedTime</code>.</p>
110
111 <p>The method <code>save</code> defines an operation called
112 <code>save</code>. It is not an attribute, since its name
113 does not begin with <code>get</code>, <code>set</code>, or
114 <code>is</code>.</p>
115
116 <p>The exact naming patterns for Standard MBeans are detailed in
117 the <a href="#spec">JMX Specification</a>.</p>
118
119 <p>There are two ways to make a Java object that is an MBean
120 with this management interface. One is for the object to be
121 of a class that has exactly the same name as the Java
122 interface but without the <code>MBean</code> suffix. So in
123 the example the object would be of the class
124 <code>Configuration</code>, in the same Java package as
125 <code>ConfigurationMBean</code>. The second way is to use the
126 {@link javax.management.StandardMBean StandardMBean}
127 class.</p>
128
129
130 <h3>MXBeans</h3>
131
132 <p>An <em>MXBean</em> is a variant of Standard MBean where complex
133 types are mapped to a standard set of types defined in the
134 {@link javax.management.openmbean} package. MXBeans are appropriate
135 if you would otherwise need to reference application-specific
136 classes in your MBean interface. They are described in detail
137 in the specification for {@link javax.management.MXBean MXBean}.</p>
138
139
140 <h3>Dynamic MBeans</h3>
141
142 <p>A <em>Dynamic MBean</em> is an MBean that defines its
143 management interface at run-time. For example, a configuration
144 MBean could determine the names and types of the attributes it
145 exposes by parsing an XML file.</p>
146
147 <p>Any Java object of a class that implements the {@link
148 javax.management.DynamicMBean DynamicMBean} interface is a
149 Dynamic MBean.</p>
150
151
152 <h3>Open MBeans</h3>
153
154 <p>An <em>Open MBean</em> is a kind of Dynamic MBean where the
155 types of attributes and of operation parameters and return
156 values are built using a small set of predefined Java classes.
157 Open MBeans facilitate operation with remote management programs
158 that do not necessarily have access to application-specific
159 types, including non-Java programs. Open MBeans are defined by
160 the package <a href="openmbean/package-summary.html"><code>
161 javax.management.openmbean</code></a>.</p>
162
163
164 <h3>Model MBeans</h3>
165
166 <p>A <em>Model MBean</em> is a kind of Dynamic MBean that acts
167 as a bridge between the management interface and the
168 underlying managed resource. Both the management interface and
169 the managed resource are specified as Java objects. The same
170 Model MBean implementation can be reused many times with
171 different management interfaces and managed resources, and it can
172 provide common functionality such as persistence and caching.
173 Model MBeans are defined by the package
174 <a href="modelmbean/package-summary.html"><code>
175 javax.management.modelmbean</code></a>.</p>
176
177
178 <h2>MBean Server</h2>
179
180 <p>To be useful, an MBean must be registered in an <em>MBean
181 Server</em>. An MBean Server is a repository of MBeans.
182 Usually the only access to the MBeans is through the MBean
183 Server. In other words, code no longer accesses the Java
184 object implementing the MBean directly, but instead accesses
185 the MBean by name through the MBean Server. Each MBean has a
186 unique name within the MBean Server, defined by the {@link
187 javax.management.ObjectName ObjectName} class.</p>
188
189 <p>An MBean Server is an object implementing the interface
190 {@link javax.management.MBeanServer MBeanServer}.
191 The most convenient MBean Server to use is the
192 <em>Platform MBean Server</em>. This is a
193 single MBean Server that can be shared by different managed
194 components running within the same Java Virtual Machine. The
195 Platform MBean Server is accessed with the method {@link
196 java.lang.management.ManagementFactory#getPlatformMBeanServer()}.</p>
197
198 <p>Application code can also create a new MBean Server, or
199 access already-created MBean Servers, using the {@link
200 javax.management.MBeanServerFactory MBeanServerFactory} class.</p>
201
202
203 <h3>Creating MBeans in the MBean Server</h3>
204
205 <p>There are two ways to create an MBean. One is to construct a
206 Java object that will be the MBean, then use the {@link
207 javax.management.MBeanServer#registerMBean registerMBean}
208 method to register it in the MBean Server. The other is to
209 create and register the MBean in a single operation using one
210 of the {@link javax.management.MBeanServer#createMBean(String,
211 javax.management.ObjectName) createMBean} methods.</p>
212
213 <p>The <code>registerMBean</code> method is simpler for local
214 use, but cannot be used remotely. The
215 <code>createMBean</code> method can be used remotely, but
216 sometimes requires attention to class loading issues.</p>
217
218 <p>An MBean can perform actions when it is registered in or
219 unregistered from an MBean Server if it implements the {@link
220 javax.management.MBeanRegistration MBeanRegistration}
221 interface.</p>
222
223
224 <h3>Accessing MBeans in the MBean Server</h3>
225
226 <p>Given an <code>ObjectName</code> <code>name</code> and an
227 <code>MBeanServer</code> <code>mbs</code>, you can access
228 attributes and operations as in this example:</p>
229
230 <pre>
231 int cacheSize = mbs.getAttribute(name, "CacheSize");
232 {@link javax.management.Attribute Attribute} newCacheSize =
233 new Attribute("CacheSize", new Integer(2000));
234 mbs.setAttribute(name, newCacheSize);
235 mbs.invoke(name, "save", new Object[0], new Class[0]);
236 </pre>
237
238 <p id="proxy">Alternatively, if you have a Java interface that
239 corresponds to the management interface for the MBean, you can use an
240 <em>MBean proxy</em> like this:</p>
241
242 <pre>
243 ConfigurationMBean conf =
244 {@link javax.management.JMX#newMBeanProxy
245 JMX.newMBeanProxy}(mbs, name, ConfigurationMBean.class);
246 int cacheSize = conf.getCacheSize();
247 conf.setCacheSize(2000);
248 conf.save();
249 </pre>
250
251 <p>Using an MBean proxy is just a convenience. The second
252 example ends up calling the same <code>MBeanServer</code>
253 operations as the first one.</p>
254
255 <p>An MBean Server can be queried for MBeans whose names match
256 certain patterns and/or whose attributes meet certain
257 constraints. Name patterns are constructed using the {@link
258 javax.management.ObjectName ObjectName} class and constraints
259 are constructed using the {@link javax.management.Query Query}
260 class. The methods {@link
261 javax.management.MBeanServer#queryNames queryNames} and {@link
262 javax.management.MBeanServer#queryMBeans queryMBeans} then
263 perform the query.</p>
264
265
266 <h3>MBean lifecycle</h3>
267
268 <p>An MBean can implement the {@link javax.management.MBeanRegistration
269 MBeanRegistration} interface in order to be told when it is registered
270 and unregistered in the MBean Server. Additionally, the {@link
271 javax.management.MBeanRegistration#preRegister preRegister} method
272 allows the MBean to get a reference to the <code>MBeanServer</code>
273 object and to get its <code>ObjectName</code> within the MBean
274 Server.</p>
275
276
277 <h2>Notifications</h2>
278
279 <p>A <em>notification</em> is an instance of the {@link
280 javax.management.Notification Notification} class or a
281 subclass. In addition to its Java class, it has a
282 <em>type</em> string that can distinguish it from other
283 notifications of the same class.</p>
284
285 <p>An MBean that will emit notifications must implement the
286 {@link javax.management.NotificationBroadcaster
287 NotificationBroadcaster} or {@link
288 javax.management.NotificationEmitter NotificationEmitter}
289 interface. Usually, it does this by subclassing
290 {@link javax.management.NotificationBroadcasterSupport
291 NotificationBroadcasterSupport} or delegating to an instance of
292 that class. Here is an example:</p>
293
294 <pre>
295 public class Configuration <b>extends NotificationBroadcasterSupport</b>
296 implements ConfigurationMBean {
297 ...
298 private void updated() {
299 Notification n = new Notification(...);
300 <b>{@link javax.management.NotificationBroadcasterSupport#sendNotification
301 sendNotification}(n)</b>;
302 }
303 }
304 </pre>
305
306
307 <p>Notifications can be received by a <em>listener</em>, which
308 is an object that implements the {@link
309 javax.management.NotificationListener NotificationListener}
310 interface. You can add a listener to an MBean with the method
311 {@link
312 javax.management.MBeanServer#addNotificationListener(ObjectName,
313 NotificationListener, NotificationFilter, Object)}.
314 You can optionally supply a <em>filter</em> to this method, to
315 select only notifications of interest. A filter is an object
316 that implements the {@link javax.management.NotificationFilter
317 NotificationFilter} interface.</p>
318
319 <p>An MBean can be a listener for notifications emitted by other
320 MBeans in the same MBean Server. In this case, it implements
321 {@link javax.management.NotificationListener
322 NotificationListener} and the method {@link
323 javax.management.MBeanServer#addNotificationListener(ObjectName,
324 ObjectName, NotificationFilter, Object)} is used to listen.</p>
325
326
327 <h2>Remote Access to MBeans</h2>
328
329 <p>An MBean Server can be accessed remotely through a
330 <em>connector</em>. A connector allows a remote Java
331 application to access an MBean Server in essentially the same
332 way as a local one. The package
333 <a href="remote/package-summary.html"><code>
334 javax.management.remote</code></a> defines connectors.</p>
335
336 <p>The JMX specification also defines the notion of an
337 <em>adaptor</em>. An adaptor translates between requests in a
338 protocol such as SNMP or HTML and accesses to an MBean Server.
339 So for example an SNMP GET operation might result in a
340 <code>getAttribute</code> on the MBean Server.</p>
341
342 <h3 id="interop">Interoperability between versions of the JMX
343 specification</h3>
344
345 <p>When a client connects to a server using the JMX Remote
346 API, it is possible that they do not have the same version
347 of the JMX specification. The version of the JMX
348 specification described here is version 1.4. Previous
349 versions were 1.0, 1.1, and 1.2. (There was no 1.3.)
350 The standard JMX Remote API is defined to work with version
351 1.2 onwards, so in standards-based deployment the only
352 interoperability questions that arise concern version 1.2
353 onwards.</p>
354
355 <p>Every version of the JMX specification continues to
356 implement the features of previous versions. So when the
357 client is running an earlier version than the server, there
358 should not be any interoperability concerns.</p>
359
360 <p>When the client is running a later version than the server,
361 certain newer features may not be available, as detailed in
362 the next sections. The client can determine the server's
363 version by examining the {@link
364 javax.management.MBeanServerDelegateMBean#getSpecificationVersion
365 SpecificationVersion} attribute of the {@code
366 MBeanServerDelegate}.</p>
367
368 <h4 id="interop-1.2">If the remote MBean Server is 1.2</h4>
369
370 <ul>
371
372 <li><p>You cannot use wildcards in a key property of an
373 {@link javax.management.ObjectName ObjectName}, for
374 example {@code domain:type=Foo,name=*}. Wildcards that
375 match whole properties are still allowed, for example
376 {@code *:*} or {@code *:type=Foo,*}.</p>
377
378 <li><p>You cannot use {@link
379 javax.management.Query#isInstanceOf Query.isInstanceOf}
380 in a query.</p>
381
382 <li><p>You cannot use dot syntax such as {@code
383 HeapMemoryUsage.used} in the {@linkplain
384 javax.management.monitor.Monitor#setObservedAttribute
385 observed attribute} of a monitor, as described in the
386 documentation for the {@link javax.management.monitor}
387 package.</p>
388
389 </ul>
390
391 <p id="spec">
392 @see <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
393 JMX Specification, version 1.4</a>
394
395 @since 1.5
396
397 </body>
398 </html>