1<html> 2 <head> 3 <title>javax.management package</title> 4 <!-- 5Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved. 6DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 7 8This code is free software; you can redistribute it and/or modify it 9under the terms of the GNU General Public License version 2 only, as 10published by the Free Software Foundation. Oracle designates this 11particular file as subject to the "Classpath" exception as provided 12by Oracle in the LICENSE file that accompanied this code. 13 14This code is distributed in the hope that it will be useful, but WITHOUT 15ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 16FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 17version 2 for more details (a copy is included in the LICENSE file that 18accompanied this code). 19 20You should have received a copy of the GNU General Public License version 212 along with this work; if not, write to the Free Software Foundation, 22Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 23 24Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 25or visit www.oracle.com if you need additional information or have any 26questions. 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> 399