annotate src/share/classes/javax/management/package.html @ 0:37a05a11f281

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