| author | ohair |
| Wed, 26 May 2010 20:28:04 -0700 | |
| changeset 5551 | 327690766109 |
| parent 5506 | 202f599c92aa |
| child 9693 | ee89bfc8fa66 |
| permissions | -rw-r--r-- |
| 2 | 1 |
<html> |
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
2 |
<head> |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
3 |
<title>javax.management package</title> |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
4 |
<!-- |
| 5506 | 5 |
Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved. |
| 2 | 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 |
|
| 5506 | 10 |
published by the Free Software Foundation. Oracle designates this |
| 2 | 11 |
particular file as subject to the "Classpath" exception as provided |
| 5506 | 12 |
by Oracle in the LICENSE file that accompanied this code. |
| 2 | 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 |
||
|
5551
327690766109
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5506
diff
changeset
|
24 |
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
327690766109
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5506
diff
changeset
|
25 |
or visit www.oracle.com if you need additional information or have any |
|
327690766109
6956202: Fix a few missed rebranding issues, please contact lines etc.
ohair
parents:
5506
diff
changeset
|
26 |
questions. |
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
27 |
--> |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
28 |
</head> |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
29 |
<body bgcolor="white"> |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
30 |
<p>Provides the core classes for the Java Management Extensions.</p> |
| 2 | 31 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
32 |
<p>The Java Management Extensions |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
33 |
(JMX<sup><font size="-1">TM</font></sup>) API is a standard |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
34 |
API for management and monitoring. Typical uses include:</p> |
| 2 | 35 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
36 |
<ul> |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
37 |
<li>consulting and changing application configuration</li> |
| 2 | 38 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
39 |
<li>accumulating statistics about application behavior and |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
40 |
making them available</li> |
| 2 | 41 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
42 |
<li>notifying of state changes and erroneous conditions.</li> |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
43 |
</ul> |
| 2 | 44 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
45 |
<p>The JMX API can also be used as part of a solution for |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
46 |
managing systems, networks, and so on.</p> |
| 2 | 47 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
48 |
<p>The API includes remote access, so a remote management |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
49 |
program can interact with a running application for these |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
50 |
purposes.</p> |
| 2 | 51 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
52 |
<h2>MBeans</h2> |
| 2 | 53 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
54 |
<p>The fundamental notion of the JMX API is the <em>MBean</em>. |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
55 |
An MBean is a named <em>managed object</em> representing a |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
56 |
resource. It has a <em>management interface</em> consisting |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
57 |
of:</p> |
| 2 | 58 |
|
| 833 | 59 |
<ul> |
60 |
<li>named and typed attributes that can be read and/or |
|
61 |
written</li> |
|
| 2 | 62 |
|
| 833 | 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> |
|
| 2 | 67 |
|
| 833 | 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> |
|
| 2 | 78 |
|
| 833 | 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> |
|
| 2 | 82 |
|
83 |
||
| 833 | 84 |
<h3>Standard MBeans</h3> |
| 2 | 85 |
|
| 833 | 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> |
|
| 2 | 92 |
|
| 833 | 93 |
<pre> |
| 2 | 94 |
public interface ConfigurationMBean {
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
95 |
public int getCacheSize(); |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
96 |
public void setCacheSize(int size); |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
97 |
public long getLastChangedTime(); |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
98 |
public void save(); |
| 2 | 99 |
} |
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
100 |
</pre> |
| 2 | 101 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
102 |
<p>The methods <code>getCacheSize</code> and |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
103 |
<code>setCacheSize</code> define a read-write attribute of |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
104 |
type <code>int</code> called <code>CacheSize</code> (with an |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
105 |
initial capital, unlike the JavaBeans convention).</p> |
| 2 | 106 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
107 |
<p>The method <code>getLastChangedTime</code> defines an |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
108 |
attribute of type <code>long</code> called |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
109 |
<code>LastChangedTime</code>. This is a read-only attribute, |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
110 |
since there is no method <code>setLastChangedTime</code>.</p> |
| 2 | 111 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
112 |
<p>The method <code>save</code> defines an operation called |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
113 |
<code>save</code>. It is not an attribute, since its name |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
114 |
does not begin with <code>get</code>, <code>set</code>, or |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
115 |
<code>is</code>.</p> |
| 2 | 116 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
117 |
<p>The exact naming patterns for Standard MBeans are detailed in |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
118 |
the <a href="#spec">JMX Specification</a>.</p> |
| 2 | 119 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
120 |
<p>There are two ways to make a Java object that is an MBean |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
121 |
with this management interface. One is for the object to be |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
122 |
of a class that has exactly the same name as the Java |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
123 |
interface but without the <code>MBean</code> suffix. So in |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
124 |
the example the object would be of the class |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
125 |
<code>Configuration</code>, in the same Java package as |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
126 |
<code>ConfigurationMBean</code>. The second way is to use the |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
127 |
{@link javax.management.StandardMBean StandardMBean}
|
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
128 |
class.</p> |
| 2 | 129 |
|
130 |
||
| 833 | 131 |
<h3>MXBeans</h3> |
| 2 | 132 |
|
| 833 | 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 |
||
| 2 | 140 |
|
| 833 | 141 |
<h3>Dynamic MBeans</h3> |
| 2 | 142 |
|
| 833 | 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> |
|
| 2 | 151 |
|
152 |
||
| 833 | 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 |
||
| 2 | 164 |
|
| 833 | 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> |
|
| 2 | 177 |
|
178 |
||
| 833 | 179 |
<h2>MBean Server</h2> |
| 2 | 180 |
|
| 833 | 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> |
|
| 2 | 189 |
|
| 833 | 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> |
|
| 2 | 198 |
|
| 833 | 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> |
|
| 2 | 202 |
|
203 |
||
| 833 | 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> |
|
| 2 | 213 |
|
| 833 | 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> |
|
| 2 | 218 |
|
| 833 | 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> |
|
| 2 | 232 |
int cacheSize = mbs.getAttribute(name, "CacheSize"); |
233 |
{@link javax.management.Attribute Attribute} newCacheSize =
|
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
234 |
new Attribute("CacheSize", new Integer(2000));
|
| 2 | 235 |
mbs.setAttribute(name, newCacheSize); |
236 |
mbs.invoke(name, "save", new Object[0], new Class[0]); |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
237 |
</pre> |
| 2 | 238 |
|
| 833 | 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> |
|
| 2 | 242 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
243 |
<pre> |
| 2 | 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(); |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
250 |
</pre> |
| 2 | 251 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
252 |
<p>Using an MBean proxy is just a convenience. The second |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
253 |
example ends up calling the same <code>MBeanServer</code> |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
254 |
operations as the first one.</p> |
| 2 | 255 |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
256 |
<p>An MBean Server can be queried for MBeans whose names match |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
257 |
certain patterns and/or whose attributes meet certain |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
258 |
constraints. Name patterns are constructed using the {@link
|
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
259 |
javax.management.ObjectName ObjectName} class and constraints |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
260 |
are constructed using the {@link javax.management.Query Query}
|
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
261 |
class. The methods {@link
|
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
262 |
javax.management.MBeanServer#queryNames queryNames} and {@link
|
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
263 |
javax.management.MBeanServer#queryMBeans queryMBeans} then |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
264 |
perform the query.</p> |
| 2 | 265 |
|
266 |
||
| 4156 | 267 |
<h3>MBean lifecycle</h3> |
| 2 | 268 |
|
| 833 | 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> |
|
| 2 | 276 |
|
277 |
||
| 833 | 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 |
||
| 4156 | 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> |
|
| 833 | 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> |
|
| 2 | 319 |
|
| 833 | 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> |
|
| 2 | 329 |
|
| 833 | 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 |
||
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
343 |
<h3 id="interop">Interoperability between versions of the JMX |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
344 |
specification</h3> |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
345 |
|
| 4156 | 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> |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
355 |
|
| 4156 | 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> |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
360 |
|
| 4156 | 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> |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
368 |
|
| 4156 | 369 |
<h4 id="interop-1.2">If the remote MBean Server is 1.2</h4> |
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
370 |
|
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
371 |
<ul> |
|
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
372 |
|
| 4156 | 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>
|
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
378 |
|
| 4156 | 379 |
<li><p>You cannot use {@link
|
380 |
javax.management.Query#isInstanceOf Query.isInstanceOf} |
|
381 |
in a query.</p> |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
382 |
|
| 4156 | 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> |
|
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
389 |
|
| 4156 | 390 |
</ul> |
|
1571
421ef5172dd3
6336968: Methods to convert AttributeList to/from Map
emcmanus
parents:
833
diff
changeset
|
391 |
|
| 833 | 392 |
<p id="spec"> |
393 |
@see <a href="{@docRoot}/../technotes/guides/jmx/index.html">
|
|
394 |
Java SE 6 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 |
|
| 2 | 400 |
|
401 |
</body> |
|
402 |
</html> |