|
2
|
1 |
<html>
|
|
|
2 |
<head>
|
|
|
3 |
<title>javax.management package</title>
|
|
|
4 |
<!--
|
|
|
5 |
Copyright 1999-2006 Sun Microsystems, Inc. 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. Sun designates this
|
|
|
11 |
particular file as subject to the "Classpath" exception as provided
|
|
|
12 |
by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
|
|
|
25 |
CA 95054 USA or visit www.sun.com if you need additional information or
|
|
|
26 |
have any 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>management interface</em> consisting
|
|
|
57 |
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}.
|
|
|
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>Alternatively, if you have a Java interface that corresponds
|
|
|
240 |
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 |
<h2>Notifications</h2>
|
|
|
268 |
|
|
|
269 |
<p>A <em>notification</em> is an instance of the {@link
|
|
|
270 |
javax.management.Notification Notification} class or a
|
|
|
271 |
subclass. In addition to its Java class, it has a
|
|
|
272 |
<em>type</em> string that can distinguish it from other
|
|
|
273 |
notifications of the same class.</p>
|
|
|
274 |
|
|
|
275 |
<p>An MBean that will emit notifications must implement the
|
|
|
276 |
{@link javax.management.NotificationBroadcaster
|
|
|
277 |
NotificationBroadcaster} or {@link
|
|
|
278 |
javax.management.NotificationEmitter NotificationEmitter}
|
|
|
279 |
interface. Usually, it does this by subclassing {@link
|
|
|
280 |
javax.management.NotificationBroadcasterSupport
|
|
|
281 |
NotificationBroadcasterSupport} or by delegating to an instance
|
|
|
282 |
of that class.</p>
|
|
|
283 |
|
|
|
284 |
<p>Notifications can be received by a <em>listener</em>, which
|
|
|
285 |
is an object that implements the {@link
|
|
|
286 |
javax.management.NotificationListener NotificationListener}
|
|
|
287 |
interface. You can add a listener to an MBean with the method
|
|
|
288 |
{@link
|
|
|
289 |
javax.management.MBeanServer#addNotificationListener(ObjectName,
|
|
|
290 |
NotificationListener, NotificationFilter, Object)}.
|
|
|
291 |
You can optionally supply a <em>filter</em> to this method, to
|
|
|
292 |
select only notifications of interest. A filter is an object
|
|
|
293 |
that implements the {@link javax.management.NotificationFilter
|
|
|
294 |
NotificationFilter} interface.</p>
|
|
|
295 |
|
|
|
296 |
<p>An MBean can be a listener for notifications emitted by other
|
|
|
297 |
MBeans in the same MBean Server. In this case, it implements
|
|
|
298 |
{@link javax.management.NotificationListener
|
|
|
299 |
NotificationListener} and the method {@link
|
|
|
300 |
javax.management.MBeanServer#addNotificationListener(ObjectName,
|
|
|
301 |
ObjectName, NotificationFilter, Object)} is used to listen.</p>
|
|
|
302 |
|
|
|
303 |
|
|
|
304 |
<h2>Remote Access to MBeans</h2>
|
|
|
305 |
|
|
|
306 |
<p>An MBean Server can be accessed remotely through a
|
|
|
307 |
<em>connector</em>. A connector allows a remote Java
|
|
|
308 |
application to access an MBean Server in essentially the same
|
|
|
309 |
way as a local one. The package
|
|
|
310 |
<a href="remote/package-summary.html"><code>
|
|
|
311 |
javax.management.remote</code></a> defines connectors.</p>
|
|
|
312 |
|
|
|
313 |
<p>The JMX specification also defines the notion of an
|
|
|
314 |
<em>adaptor</em>. An adaptor translates between requests in a
|
|
|
315 |
protocol such as SNMP or HTML and accesses to an MBean Server.
|
|
|
316 |
So for example an SNMP GET operation might result in a
|
|
|
317 |
<code>getAttribute</code> on the MBean Server.</p>
|
|
|
318 |
|
|
|
319 |
<p id="spec">
|
|
|
320 |
@see <a href="{@docRoot}/../technotes/guides/jmx/index.html">
|
|
|
321 |
Java SE 6 Platform documentation on JMX technology</a>
|
|
|
322 |
in particular the
|
|
|
323 |
<a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
|
|
|
324 |
JMX Specification, version 1.4(pdf).</a>
|
|
|
325 |
|
|
|
326 |
@since 1.5
|
|
|
327 |
|
|
|
328 |
</body>
|
|
|
329 |
</html>
|