2
|
1 |
/*
|
715
|
2 |
* Copyright 2005-2008 Sun Microsystems, Inc. All Rights Reserved.
|
2
|
3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
4 |
*
|
|
5 |
* This code is free software; you can redistribute it and/or modify it
|
|
6 |
* under the terms of the GNU General Public License version 2 only, as
|
|
7 |
* published by the Free Software Foundation. Sun designates this
|
|
8 |
* particular file as subject to the "Classpath" exception as provided
|
|
9 |
* by Sun in the LICENSE file that accompanied this code.
|
|
10 |
*
|
|
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that
|
|
15 |
* accompanied this code).
|
|
16 |
*
|
|
17 |
* You should have received a copy of the GNU General Public License version
|
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
20 |
*
|
|
21 |
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
|
|
22 |
* CA 95054 USA or visit www.sun.com if you need additional information or
|
|
23 |
* have any questions.
|
|
24 |
*/
|
|
25 |
|
|
26 |
package javax.management;
|
|
27 |
|
|
28 |
import java.lang.annotation.Documented;
|
|
29 |
import java.lang.annotation.ElementType;
|
|
30 |
import java.lang.annotation.Retention;
|
|
31 |
import java.lang.annotation.RetentionPolicy;
|
|
32 |
import java.lang.annotation.Target;
|
|
33 |
|
|
34 |
// remaining imports are for Javadoc
|
|
35 |
import java.beans.ConstructorProperties;
|
|
36 |
import java.io.InvalidObjectException;
|
|
37 |
import java.lang.management.MemoryUsage;
|
|
38 |
import java.lang.reflect.UndeclaredThrowableException;
|
|
39 |
import java.util.Arrays;
|
|
40 |
import java.util.List;
|
|
41 |
import javax.management.openmbean.ArrayType;
|
|
42 |
import javax.management.openmbean.CompositeData;
|
|
43 |
import javax.management.openmbean.CompositeDataInvocationHandler;
|
|
44 |
import javax.management.openmbean.CompositeDataSupport;
|
|
45 |
import javax.management.openmbean.CompositeDataView;
|
|
46 |
import javax.management.openmbean.CompositeType;
|
687
|
47 |
import javax.management.openmbean.MXBeanMapping;
|
|
48 |
import javax.management.openmbean.MXBeanMappingClass;
|
|
49 |
import javax.management.openmbean.MXBeanMappingFactory;
|
|
50 |
import javax.management.openmbean.MXBeanMappingFactoryClass;
|
2
|
51 |
import javax.management.openmbean.OpenDataException;
|
|
52 |
import javax.management.openmbean.OpenMBeanInfo;
|
|
53 |
import javax.management.openmbean.OpenType;
|
|
54 |
import javax.management.openmbean.SimpleType;
|
|
55 |
import javax.management.openmbean.TabularData;
|
|
56 |
import javax.management.openmbean.TabularDataSupport;
|
|
57 |
import javax.management.openmbean.TabularType;
|
|
58 |
|
|
59 |
/**
|
|
60 |
<p>Annotation to mark an interface explicitly as being an MXBean
|
|
61 |
interface, or as not being an MXBean interface. By default, an
|
|
62 |
interface is an MXBean interface if its name ends with {@code
|
|
63 |
MXBean}, as in {@code SomethingMXBean}. The following interfaces
|
|
64 |
are MXBean interfaces:</p>
|
|
65 |
|
|
66 |
<pre>
|
|
67 |
public interface WhatsitMXBean {}
|
|
68 |
|
|
69 |
@MXBean
|
|
70 |
public interface Whatsit1Interface {}
|
|
71 |
|
|
72 |
@MXBean(true)
|
|
73 |
public interface Whatsit2Interface {}
|
|
74 |
</pre>
|
|
75 |
|
|
76 |
<p>The following interfaces are not MXBean interfaces:</p>
|
|
77 |
|
|
78 |
<pre>
|
|
79 |
public interface Whatsit3Interface{}
|
|
80 |
|
|
81 |
@MXBean(false)
|
|
82 |
public interface MisleadingMXBean {}
|
|
83 |
</pre>
|
|
84 |
|
687
|
85 |
<h3 id="MXBean-spec">MXBean specification</h3>
|
2
|
86 |
|
|
87 |
<p>The MXBean concept provides a simple way to code an MBean
|
|
88 |
that only references a predefined set of types, the ones defined
|
|
89 |
by {@link javax.management.openmbean}. In this way, you can be
|
|
90 |
sure that your MBean will be usable by any client, including
|
|
91 |
remote clients, without any requirement that the client have
|
|
92 |
access to <em>model-specific classes</em> representing the types
|
|
93 |
of your MBeans.</p>
|
|
94 |
|
|
95 |
<p>The concepts are easier to understand by comparison with the
|
|
96 |
Standard MBean concept. Here is how a managed object might be
|
|
97 |
represented as a Standard MBean, and as an MXBean:</p>
|
|
98 |
|
|
99 |
<table border="1" cellpadding="5">
|
|
100 |
<tr>
|
|
101 |
<th>Standard MBean</th><th>MXBean</th>
|
|
102 |
</tr>
|
|
103 |
<tr>
|
|
104 |
<td><pre>
|
|
105 |
public interface MemoryPool<b>MBean</b> {
|
|
106 |
String getName();
|
|
107 |
MemoryUsage getUsage();
|
|
108 |
// ...
|
|
109 |
}
|
|
110 |
</pre></td>
|
|
111 |
<td><pre>
|
|
112 |
public interface MemoryPool<b>MXBean</b> {
|
|
113 |
String getName();
|
|
114 |
MemoryUsage getUsage();
|
|
115 |
// ...
|
|
116 |
}
|
|
117 |
</pre></td>
|
|
118 |
</tr>
|
|
119 |
</table>
|
|
120 |
|
|
121 |
<p>As you can see, the definitions are very similar. The only
|
|
122 |
difference is that the convention for naming the interface is to use
|
|
123 |
<code><em>Something</em>MXBean</code> for MXBeans, rather than
|
|
124 |
<code><em>Something</em>MBean</code> for Standard MBeans.</p>
|
|
125 |
|
|
126 |
<p>In this managed object, there is an attribute called
|
|
127 |
<code>Usage</code> of type {@link MemoryUsage}. The point of an
|
|
128 |
attribute like this is that it gives a coherent snapshot of a set
|
|
129 |
of data items. For example, it might include the current amount
|
|
130 |
of used memory in the memory pool, and the current maximum of the
|
|
131 |
memory pool. If these were separate items, obtained with separate
|
|
132 |
{@link MBeanServer#getAttribute getAttribute} calls, then we could
|
|
133 |
get values seen at different times that were not consistent. We
|
|
134 |
might get a <code>used</code> value that was greater than the
|
|
135 |
<code>max</code> value.</p>
|
|
136 |
|
|
137 |
<p>So, we might define <code>MemoryUsage</code> like this:</p>
|
|
138 |
|
|
139 |
<table border="1" cellpadding="5">
|
|
140 |
<tr>
|
|
141 |
<th>Standard MBean</th><th>MXBean</th>
|
|
142 |
</tr>
|
|
143 |
<tr>
|
|
144 |
<td><pre>
|
|
145 |
public class MemoryUsage <b>implements Serializable</b> {
|
|
146 |
// standard JavaBean conventions with getters
|
|
147 |
|
|
148 |
public MemoryUsage(long init, long used,
|
|
149 |
long committed, long max) {...}
|
|
150 |
long getInit() {...}
|
|
151 |
long getUsed() {...}
|
|
152 |
long getCommitted() {...}
|
|
153 |
long getMax() {...}
|
|
154 |
}
|
|
155 |
</pre></td>
|
|
156 |
<td><pre>
|
|
157 |
public class MemoryUsage {
|
|
158 |
// standard JavaBean conventions with getters
|
|
159 |
<b>@ConstructorProperties({"init", "used", "committed", "max"})</b>
|
|
160 |
public MemoryUsage(long init, long used,
|
|
161 |
long committed, long max) {...}
|
|
162 |
long getInit() {...}
|
|
163 |
long getUsed() {...}
|
|
164 |
long getCommitted() {...}
|
|
165 |
long getMax() {...}
|
|
166 |
}
|
|
167 |
</pre></td>
|
|
168 |
</tr>
|
|
169 |
</table>
|
|
170 |
|
|
171 |
<p>The definitions are the same in the two cases, except
|
|
172 |
that with the MXBean, <code>MemoryUsage</code> no longer needs to
|
|
173 |
be marked <code>Serializable</code> (though it can be). On
|
|
174 |
the other hand, we have added a {@code @ConstructorProperties} annotation
|
|
175 |
to link the constructor parameters to the corresponding getters.
|
|
176 |
We will see more about this below.</p>
|
|
177 |
|
|
178 |
<p><code>MemoryUsage</code> is a <em>model-specific class</em>.
|
|
179 |
With Standard MBeans, a client of the MBean Server cannot access the
|
|
180 |
<code>Usage</code> attribute if it does not know the class
|
|
181 |
<code>MemoryUsage</code>. Suppose the client is a generic console
|
|
182 |
based on JMX technology. Then the console would have to be
|
|
183 |
configured with the model-specific classes of every application it
|
|
184 |
might connect to. The problem is even worse for clients that are
|
|
185 |
not written in the Java language. Then there may not be any way
|
|
186 |
to tell the client what a <code>MemoryUsage</code> looks like.</p>
|
|
187 |
|
|
188 |
<p>This is where MXBeans differ from Standard MBeans. Although we
|
|
189 |
define the management interface in almost exactly the same way,
|
|
190 |
the MXBean framework <em>converts</em> model-specific classes into
|
|
191 |
standard classes from the Java platform. Using arrays and the
|
|
192 |
{@link javax.management.openmbean.CompositeData CompositeData} and
|
|
193 |
{@link javax.management.openmbean.TabularData TabularData} classes
|
|
194 |
from the standard {@link javax.management.openmbean} package, it
|
|
195 |
is possible to build data structures of arbitrary complexity
|
|
196 |
using only standard classes.</p>
|
|
197 |
|
|
198 |
<p>This becomes clearer if we compare what the clients of the two
|
|
199 |
models might look like:</p>
|
|
200 |
|
|
201 |
<table border="1" cellpadding="5">
|
|
202 |
<tr>
|
|
203 |
<th>Standard MBean</th><th>MXBean</th>
|
|
204 |
</tr>
|
|
205 |
<tr>
|
|
206 |
<td><pre>
|
|
207 |
String name = (String)
|
|
208 |
mbeanServer.{@link MBeanServer#getAttribute
|
|
209 |
getAttribute}(objectName, "Name");
|
|
210 |
<b>MemoryUsage</b> usage = (<b>MemoryUsage</b>)
|
|
211 |
mbeanServer.getAttribute(objectName, "Usage");
|
|
212 |
<b>long used = usage.getUsed();</b>
|
|
213 |
</pre></td>
|
|
214 |
<td><pre>
|
|
215 |
String name = (String)
|
|
216 |
mbeanServer.{@link MBeanServer#getAttribute
|
|
217 |
getAttribute}(objectName, "Name");
|
|
218 |
<b>{@link CompositeData}</b> usage = (<b>CompositeData</b>)
|
|
219 |
mbeanServer.getAttribute(objectName, "Usage");
|
|
220 |
<b>long used = (Long) usage.{@link CompositeData#get get}("used");</b>
|
|
221 |
</pre></td>
|
|
222 |
</table>
|
|
223 |
|
|
224 |
<p>For attributes with simple types like <code>String</code>, the
|
|
225 |
code is the same. But for attributes with complex types, the
|
|
226 |
Standard MBean code requires the client to know the model-specific
|
|
227 |
class <code>MemoryUsage</code>, while the MXBean code requires no
|
|
228 |
non-standard classes.</p>
|
|
229 |
|
|
230 |
<p>The client code shown here is slightly more complicated for the
|
|
231 |
MXBean client. But, if the client does in fact know the model,
|
|
232 |
here the interface <code>MemoryPoolMXBean</code> and the
|
|
233 |
class <code>MemoryUsage</code>, then it can construct a
|
|
234 |
<em>proxy</em>. This is the recommended way to interact with
|
|
235 |
managed objects when you know the model beforehand, regardless
|
|
236 |
of whether you are using Standard MBeans or MXBeans:</p>
|
|
237 |
|
|
238 |
<table border="1" cellpadding="5">
|
|
239 |
<tr>
|
|
240 |
<th>Standard MBean</th><th>MXBean</th>
|
|
241 |
</tr>
|
|
242 |
<tr>
|
|
243 |
<td><pre>
|
|
244 |
MemoryPool<b>MBean</b> proxy =
|
|
245 |
JMX.<b>{@link JMX#newMBeanProxy(MBeanServerConnection, ObjectName,
|
|
246 |
Class) newMBeanProxy}</b>(
|
|
247 |
mbeanServer,
|
|
248 |
objectName,
|
|
249 |
MemoryPool<b>MBean</b>.class);
|
|
250 |
String name = proxy.getName();
|
|
251 |
MemoryUsage usage = proxy.getUsage();
|
|
252 |
long used = usage.getUsed();
|
|
253 |
</pre></td>
|
|
254 |
<td><pre>
|
|
255 |
MemoryPool<b>MXBean</b> proxy =
|
|
256 |
JMX.<b>{@link JMX#newMXBeanProxy(MBeanServerConnection, ObjectName,
|
|
257 |
Class) newMXBeanProxy}</b>(
|
|
258 |
mbeanServer,
|
|
259 |
objectName,
|
|
260 |
MemoryPool<b>MXBean</b>.class);
|
|
261 |
String name = proxy.getName();
|
|
262 |
MemoryUsage usage = proxy.getUsage();
|
|
263 |
long used = usage.getUsed();
|
|
264 |
</pre></td>
|
|
265 |
</tr>
|
|
266 |
</table>
|
|
267 |
|
|
268 |
<p>Implementing the MemoryPool object works similarly for both
|
|
269 |
Standard MBeans and MXBeans.</p>
|
|
270 |
|
|
271 |
<table border="1" cellpadding="5">
|
|
272 |
<tr>
|
|
273 |
<th>Standard MBean</th><th>MXBean</th>
|
|
274 |
</tr>
|
|
275 |
<tr>
|
|
276 |
<td><pre>
|
|
277 |
public class MemoryPool
|
|
278 |
implements MemoryPool<b>MBean</b> {
|
|
279 |
public String getName() {...}
|
|
280 |
public MemoryUsage getUsage() {...}
|
|
281 |
// ...
|
|
282 |
}
|
|
283 |
</pre></td>
|
|
284 |
<td><pre>
|
|
285 |
public class MemoryPool
|
|
286 |
implements MemoryPool<b>MXBean</b> {
|
|
287 |
public String getName() {...}
|
|
288 |
public MemoryUsage getUsage() {...}
|
|
289 |
// ...
|
|
290 |
}
|
|
291 |
</pre></td>
|
|
292 |
</tr>
|
|
293 |
</table>
|
|
294 |
|
|
295 |
<p>Registering the MBean in the MBean Server works in the same way
|
|
296 |
in both cases:</p>
|
|
297 |
|
|
298 |
<table border="1" cellpadding="5">
|
|
299 |
<tr>
|
|
300 |
<th>Standard MBean</th><th>MXBean</th>
|
|
301 |
</tr>
|
|
302 |
<tr>
|
|
303 |
<td><pre>
|
|
304 |
{
|
|
305 |
MemoryPool<b>MBean</b> pool = new MemoryPool();
|
|
306 |
mbeanServer.{@link MBeanServer#registerMBean
|
|
307 |
registerMBean}(pool, objectName);
|
|
308 |
}
|
|
309 |
</pre></td>
|
|
310 |
<td><pre>
|
|
311 |
{
|
|
312 |
MemoryPool<b>MXBean</b> pool = new MemoryPool();
|
|
313 |
mbeanServer.{@link MBeanServer#registerMBean
|
|
314 |
registerMBean}(pool, objectName);
|
|
315 |
}
|
|
316 |
</pre></td>
|
|
317 |
</tr>
|
|
318 |
</table>
|
|
319 |
|
|
320 |
|
687
|
321 |
<h2 id="mxbean-def">Definition of an MXBean</h2>
|
2
|
322 |
|
|
323 |
<p>An MXBean is a kind of MBean. An MXBean object can be
|
|
324 |
registered directly in the MBean Server, or it can be used as an
|
|
325 |
argument to {@link StandardMBean} and the resultant MBean
|
|
326 |
registered in the MBean Server.</p>
|
|
327 |
|
|
328 |
<p>When an object is registered in the MBean Server using the
|
|
329 |
{@code registerMBean} or {@code createMBean} methods of the
|
|
330 |
{@link MBeanServer} interface, the object's class is examined
|
|
331 |
to determine what type of MBean it is:</p>
|
|
332 |
|
|
333 |
<ul>
|
|
334 |
<li>If the class implements the interface {@link DynamicMBean}
|
|
335 |
then the MBean is a Dynamic MBean. Note that the class
|
|
336 |
{@code StandardMBean} implements this interface, so this
|
|
337 |
case applies to a Standard MBean or MXBean created using
|
|
338 |
the class {@code StandardMBean}.</li>
|
|
339 |
|
|
340 |
<li>Otherwise, if the class matches the Standard MBean naming
|
|
341 |
conventions, then the MBean is a Standard MBean.</li>
|
|
342 |
|
|
343 |
<li>Otherwise, it may be an MXBean. The set of interfaces
|
|
344 |
implemented by the object is examined for interfaces that:
|
|
345 |
|
|
346 |
<ul>
|
|
347 |
<li>have a class name <code><em>S</em>MXBean</code> where
|
|
348 |
<code><em>S</em></code> is any non-empty string, and
|
|
349 |
do not have an annotation {@code @MXBean(false)}; and/or</li>
|
|
350 |
<li>have an annotation {@code @MXBean(true)}
|
|
351 |
or just {@code @MXBean}.</li>
|
|
352 |
</ul>
|
|
353 |
|
|
354 |
If there is exactly one such interface, or if there is one
|
|
355 |
such interface that is a subinterface of all the others, then
|
|
356 |
the object is an MXBean. The interface in question is the
|
|
357 |
<em>MXBean interface</em>. In the example above, the MXBean
|
|
358 |
interface is {@code MemoryPoolMXBean}.
|
|
359 |
|
|
360 |
<li>If none of these conditions is met, the MBean is invalid and
|
|
361 |
the attempt to register it will generate {@link
|
|
362 |
NotCompliantMBeanException}.
|
|
363 |
</ul>
|
|
364 |
|
|
365 |
<p>Every Java type that appears as the parameter or return type of a
|
|
366 |
method in an MXBean interface must be <em>convertible</em> using
|
|
367 |
the rules below. Additionally, parameters must be
|
|
368 |
<em>reconstructible</em> as defined below.</p>
|
|
369 |
|
|
370 |
<p>An attempt to construct an MXBean that does not conform to the
|
|
371 |
above rules will produce an exception.</p>
|
|
372 |
|
|
373 |
|
687
|
374 |
<h2 id="naming-conv">Naming conventions</h2>
|
2
|
375 |
|
|
376 |
<p>The same naming conventions are applied to the methods in an
|
|
377 |
MXBean as in a Standard MBean:</p>
|
|
378 |
|
|
379 |
<ol>
|
|
380 |
<li>A method <code><em>T</em> get<em>N</em>()</code>, where
|
|
381 |
<code><em>T</em></code> is a Java type (not <code>void</code>)
|
|
382 |
and <code><em>N</em></code> is a non-empty string, specifies
|
|
383 |
that there is a readable attribute called
|
|
384 |
<code><em>N</em></code>. The Java type and Open type of the
|
|
385 |
attribute are determined by the mapping rules below.
|
|
386 |
The method {@code final Class getClass()} inherited from {@code
|
|
387 |
Object} is ignored when looking for getters.</li>
|
|
388 |
|
|
389 |
<li>A method <code>boolean is<em>N</em>()</code> specifies that
|
|
390 |
there is a readable attribute called <code><em>N</em></code>
|
|
391 |
with Java type <code>boolean</code> and Open type
|
|
392 |
<code>SimpleType.Boolean</code>.</li>
|
|
393 |
|
|
394 |
<li>A method <code>void set<em>N</em>(<em>T</em> x)</code>
|
|
395 |
specifies that there is a writeable attribute called
|
|
396 |
<code><em>N</em></code>. The Java type and Open type of the
|
|
397 |
attribute are determined by the mapping rules below. (Of
|
|
398 |
course, the name <code>x</code> of the parameter is
|
|
399 |
irrelevant.)</li>
|
|
400 |
|
|
401 |
<li>Every other method specifies that there is an operation with
|
|
402 |
the same name as the method. The Java type and Open type of the
|
|
403 |
return value and of each parameter are determined by the mapping
|
|
404 |
rules below.</li>
|
|
405 |
</ol>
|
|
406 |
|
|
407 |
<p>The rules for <code>get<em>N</em></code> and
|
|
408 |
<code>is<em>N</em></code> collectively define the notion of a
|
|
409 |
<em>getter</em>. The rule for <code>set<em>N</em></code> defines
|
|
410 |
the notion of a <em>setter</em>.</p>
|
|
411 |
|
|
412 |
<p>It is an error for there to be two getters with the same name, or
|
|
413 |
two setters with the same name. If there is a getter and a setter
|
|
414 |
for the same name, then the type <code><em>T</em></code> in both
|
|
415 |
must be the same. In this case the attribute is read/write. If
|
|
416 |
there is only a getter or only a setter, the attribute is
|
|
417 |
read-only or write-only respectively.</p>
|
|
418 |
|
|
419 |
|
687
|
420 |
<h2 id="mapping-rules">Type mapping rules</h2>
|
2
|
421 |
|
|
422 |
<p>An MXBean is a kind of Open MBean, as defined by the {@link
|
|
423 |
javax.management.openmbean} package. This means that the types of
|
|
424 |
attributes, operation parameters, and operation return values must
|
|
425 |
all be describable using <em>Open Types</em>, that is the four
|
|
426 |
standard subclasses of {@link javax.management.openmbean.OpenType}.
|
|
427 |
MXBeans achieve this by mapping Java types into Open Types.</p>
|
|
428 |
|
|
429 |
<p>For every Java type <em>J</em>, the MXBean mapping is described
|
|
430 |
by the following information:</p>
|
|
431 |
|
|
432 |
<ul>
|
|
433 |
<li>The corresponding Open Type, <em>opentype(J)</em>. This is
|
|
434 |
an instance of a subclass of {@link
|
|
435 |
javax.management.openmbean.OpenType}.</li>
|
|
436 |
<li>The <em>mapped</em> Java type, <em>opendata(J)</em>, which is
|
|
437 |
always the same for any given <em>opentype(J)</em>. This is a Java
|
|
438 |
class.</li>
|
|
439 |
<li>How a value is converted from type <em>J</em> to type
|
|
440 |
<em>opendata(J)</em>.</li>
|
|
441 |
<li>How a value is converted from type <em>opendata(J)</em> to
|
|
442 |
type <em>J</em>, if it can be.</li>
|
|
443 |
</ul>
|
|
444 |
|
|
445 |
<p>For example, for the Java type {@code List<String>}:</p>
|
|
446 |
|
|
447 |
<ul>
|
|
448 |
<li>The Open Type, <em>opentype(</em>{@code
|
|
449 |
List<String>}<em>)</em>, is {@link ArrayType}<code>(1, </code>{@link
|
|
450 |
SimpleType#STRING}<code>)</code>, representing a 1-dimensional
|
|
451 |
array of <code>String</code>s.</li>
|
|
452 |
<li>The mapped Java type, <em>opendata(</em>{@code
|
|
453 |
List<String>}<em>)</em>, is {@code String[]}.</li>
|
|
454 |
<li>A {@code List<String>} can be converted to a {@code String[]}
|
|
455 |
using {@link List#toArray(Object[]) List.toArray(new
|
|
456 |
String[0])}.</li>
|
|
457 |
<li>A {@code String[]} can be converted to a {@code List<String>}
|
|
458 |
using {@link Arrays#asList Arrays.asList}.</li>
|
|
459 |
</ul>
|
|
460 |
|
|
461 |
<p>If no mapping rules exist to derive <em>opentype(J)</em> from
|
|
462 |
<em>J</em>, then <em>J</em> cannot be the type of a method
|
|
463 |
parameter or return value in an MXBean interface.</p>
|
|
464 |
|
|
465 |
<p>If there is a way to convert <em>opendata(J)</em> back to
|
|
466 |
<em>J</em> then we say that <em>J</em> is
|
|
467 |
<em>reconstructible</em>. All method parameters in an MXBean
|
|
468 |
interface must be reconstructible, because when the MXBean
|
|
469 |
framework is invoking a method it will need to convert those
|
|
470 |
parameters from <em>opendata(J)</em> to <em>J</em>. In a proxy
|
|
471 |
generated by {@link JMX#newMXBeanProxy(MBeanServerConnection,
|
|
472 |
ObjectName, Class) JMX.newMXBeanProxy}, it is the return values
|
|
473 |
of the methods in the MXBean interface that must be
|
|
474 |
reconstructible.</p>
|
|
475 |
|
|
476 |
<p>Null values are allowed for all Java types and Open Types,
|
|
477 |
except primitive Java types where they are not possible. When
|
|
478 |
converting from type <em>J</em> to type <em>opendata(J)</em> or
|
|
479 |
from type <em>opendata(J)</em> to type <em>J</em>, a null value is
|
|
480 |
mapped to a null value.</p>
|
|
481 |
|
687
|
482 |
<p>In addition to the default type mapping rules, you can specify
|
|
483 |
custom type mappings, as described <a
|
|
484 |
href="#custom">below</a>.</p>
|
|
485 |
|
|
486 |
<p>The following table summarizes the default type mapping rules.</p>
|
2
|
487 |
|
|
488 |
<table border="1" cellpadding="5">
|
|
489 |
<tr>
|
|
490 |
<th>Java type <em>J</em></th>
|
|
491 |
<th><em>opentype(J)</em></th>
|
|
492 |
<th><em>opendata(J)</em></th>
|
|
493 |
</tr>
|
|
494 |
<tbody cellvalign="top">
|
|
495 |
<tr>
|
|
496 |
<td>{@code int}, {@code boolean}, etc<br>
|
|
497 |
(the 8 primitive Java types)</td>
|
|
498 |
<td>{@code SimpleType.INTEGER},<br>
|
|
499 |
{@code SimpleType.BOOLEAN}, etc</td>
|
|
500 |
<td>{@code Integer}, {@code Boolean}, etc<br>
|
|
501 |
(the corresponding boxed types)</td>
|
|
502 |
</tr>
|
|
503 |
<tr>
|
|
504 |
<td>{@code Integer}, {@code ObjectName}, etc<br>
|
|
505 |
(the types covered by {@link SimpleType})</td>
|
|
506 |
<td>the corresponding {@code SimpleType}</td>
|
|
507 |
<td><em>J</em>, the same type</td>
|
|
508 |
</tr>
|
|
509 |
<tr>
|
|
510 |
<td>{@code int[]} etc<br>
|
|
511 |
(a one-dimensional array with<br>
|
|
512 |
primitive element type)</td>
|
|
513 |
<td>{@code ArrayType.getPrimitiveArrayType(int[].class)} etc</td>
|
|
514 |
<td><em>J</em>, the same type</td>
|
|
515 |
<tr>
|
|
516 |
<td><em>E</em>{@code []}<br>
|
|
517 |
(an array with non-primitive element type <em>E</em>;
|
|
518 |
this includes {@code int[][]}, where <em>E</em> is {@code int[]})</td>
|
|
519 |
<td>{@code ArrayType.getArrayType(}<em>opentype(E)</em>{@code )}</td>
|
|
520 |
<td><em>opendata(E)</em>{@code []}</td>
|
|
521 |
</tr>
|
|
522 |
<tr>
|
|
523 |
<td>{@code List<}<em>E</em>{@code >}<br>
|
|
524 |
{@code Set<}<em>E</em>{@code >}<br>
|
|
525 |
{@code SortedSet<}<em>E</em>{@code >} (see below)</td>
|
|
526 |
<td>same as for <em>E</em>{@code []}</td>
|
|
527 |
<td>same as for <em>E</em>{@code []}</td>
|
|
528 |
</tr>
|
|
529 |
<tr>
|
|
530 |
<td>An enumeration <em>E</em><br>
|
|
531 |
(declared in Java as {@code enum }<em>E</em>
|
|
532 |
{@code {...}})</td>
|
|
533 |
<td>{@code SimpleType.STRING}</td>
|
|
534 |
<td>{@code String}</td>
|
|
535 |
</tr>
|
|
536 |
<tr>
|
|
537 |
<td>{@code Map<}<em>K</em>,<em>V</em>{@code >}<br>
|
|
538 |
{@code SortedMap<}<em>K</em>,<em>V</em>{@code >}</td>
|
|
539 |
<td>{@link TabularType}<br>
|
|
540 |
(see below)</td>
|
|
541 |
<td>{@link TabularData}<br>
|
|
542 |
(see below)</td>
|
|
543 |
</tr>
|
|
544 |
<tr>
|
|
545 |
<td>An MXBean interface</td>
|
|
546 |
<td>{@code SimpleType.OBJECTNAME}<br>
|
|
547 |
(see below)</td>
|
|
548 |
<td>{@link ObjectName}<br>
|
|
549 |
(see below)</td>
|
|
550 |
</tr>
|
|
551 |
<tr>
|
|
552 |
<td>Any other type</td>
|
|
553 |
<td>{@link CompositeType},
|
|
554 |
if possible<br>
|
|
555 |
(see below)</td>
|
|
556 |
<td>{@link CompositeData}</td>
|
|
557 |
</tbody>
|
|
558 |
</table>
|
|
559 |
|
|
560 |
<p>The following sections give further details of these rules.</p>
|
|
561 |
|
|
562 |
|
|
563 |
<h3>Mappings for primitive types</h3>
|
|
564 |
|
|
565 |
<p>The 8 primitive Java types
|
|
566 |
({@code boolean}, {@code byte}, {@code short}, {@code int}, {@code
|
|
567 |
long}, {@code float}, {@code double}, {@code char}) are mapped to the
|
|
568 |
corresponding boxed types from {@code java.lang}, namely {@code
|
|
569 |
Boolean}, {@code Byte}, etc. The Open Type is the corresponding
|
|
570 |
{@code SimpleType}. Thus, <em>opentype(</em>{@code
|
|
571 |
long}<em>)</em> is {@code SimpleType.LONG}, and
|
|
572 |
<em>opendata(</em>{@code long}<em>)</em> is {@code
|
|
573 |
java.lang.Long}.</p>
|
|
574 |
|
|
575 |
<p>An array of primitive type such as {@code long[]} can be represented
|
|
576 |
directly as an Open Type. Thus, <em>openType(</em>{@code
|
|
577 |
long[]}<em>)</em> is {@code
|
|
578 |
ArrayType.getPrimitiveArrayType(long[].class)}, and
|
|
579 |
<em>opendata(</em>{@code long[]}<em>)</em> is {@code
|
|
580 |
long[]}.</p>
|
|
581 |
|
|
582 |
<p>In practice, the difference between a plain {@code int} and {@code
|
|
583 |
Integer}, etc, does not show up because operations in the JMX API
|
|
584 |
are always on Java objects, not primitives. However, the
|
|
585 |
difference <em>does</em> show up with arrays.</p>
|
|
586 |
|
|
587 |
|
|
588 |
<h3>Mappings for collections ({@code List<}<em>E</em>{@code >} etc)</h3>
|
|
589 |
|
|
590 |
<p>A {@code List<}<em>E</em>{@code >} or {@code
|
|
591 |
Set<}<em>E</em>{@code >}, such as {@code List<String>} or {@code
|
|
592 |
Set<ObjectName>}, is mapped in the same way as an array of the
|
|
593 |
same element type, such as {@code String[]} or {@code
|
|
594 |
ObjectName[]}.</p>
|
|
595 |
|
|
596 |
<p>A {@code SortedSet<}<em>E</em>{@code >} is also mapped in the
|
|
597 |
same way as an <em>E</em>{@code []}, but it is only convertible if
|
|
598 |
<em>E</em> is a class or interface that implements {@link
|
|
599 |
java.lang.Comparable}. Thus, a {@code SortedSet<String>} or
|
|
600 |
{@code SortedSet<Integer>} is convertible, but a {@code
|
|
601 |
SortedSet<int[]>} or {@code SortedSet<List<String>>} is not. The
|
|
602 |
conversion of a {@code SortedSet} instance will fail with an
|
|
603 |
{@code IllegalArgumentException} if it has a
|
|
604 |
non-null {@link java.util.SortedSet#comparator()
|
|
605 |
comparator()}.</p>
|
|
606 |
|
|
607 |
<p>A {@code List<}<em>E</em>{@code >} is reconstructed as a
|
|
608 |
{@code java.util.ArrayList<}<em>E</em>{@code >};
|
|
609 |
a {@code Set<}<em>E</em>{@code >} as a
|
|
610 |
{@code java.util.HashSet<}<em>E</em>{@code >};
|
|
611 |
a {@code SortedSet<}<em>E</em>{@code >} as a
|
|
612 |
{@code java.util.TreeSet<}<em>E</em>{@code >}.</p>
|
|
613 |
|
|
614 |
|
|
615 |
<h3>Mappings for maps ({@code Map<}<em>K</em>,<em>V</em>{@code >} etc)</h3>
|
|
616 |
|
|
617 |
<p>A {@code Map<}<em>K</em>,<em>V</em>{@code >} or {@code
|
|
618 |
SortedMap<}<em>K</em>,<em>V</em>{@code >}, for example {@code
|
|
619 |
Map<String,ObjectName>}, has Open Type {@link TabularType} and is mapped
|
|
620 |
to a {@link TabularData}.
|
|
621 |
The {@code TabularType} has two items called {@code key} and
|
|
622 |
{@code value}. The Open Type of {@code key} is
|
|
623 |
<em>opentype(K)</em>, and the Open Type of {@code value} is
|
|
624 |
<em>opentype(V)</em>. The index of the {@code TabularType} is the
|
|
625 |
single item {@code key}.</p>
|
|
626 |
|
|
627 |
<p>For example, the {@code TabularType} for a {@code
|
|
628 |
Map<String,ObjectName>} might be constructed with code like
|
|
629 |
this:</p>
|
|
630 |
|
|
631 |
<pre>
|
|
632 |
String typeName =
|
|
633 |
"java.util.Map<java.lang.String, javax.management.ObjectName>";
|
|
634 |
String[] keyValue =
|
|
635 |
new String[] {"key", "value"};
|
|
636 |
OpenType[] openTypes =
|
|
637 |
new OpenType[] {SimpleType.STRING, SimpleType.OBJECTNAME};
|
|
638 |
CompositeType rowType =
|
|
639 |
new CompositeType(typeName, typeName, keyValue, keyValue, openTypes);
|
|
640 |
TabularType tabularType =
|
|
641 |
new TabularType(typeName, typeName, rowType, new String[] {"key"});
|
|
642 |
</pre>
|
|
643 |
|
|
644 |
<p>The {@code typeName} here is determined by the <a href="#type-names">
|
|
645 |
type name rules</a> detailed below.
|
|
646 |
|
|
647 |
<p>A {@code SortedMap<}<em>K</em>,<em>V</em>{@code >} is mapped in the
|
|
648 |
same way, but it is only convertible if
|
|
649 |
<em>K</em> is a class or interface that implements {@link
|
|
650 |
java.lang.Comparable}. Thus, a {@code SortedMap<String,int[]>}
|
|
651 |
is convertible, but a
|
|
652 |
{@code SortedMap<int[],String>} is not. The conversion of a
|
|
653 |
{@code SortedMap} instance will fail with an {@code
|
|
654 |
IllegalArgumentException} if it has a non-null {@link
|
|
655 |
java.util.SortedMap#comparator() comparator()}.</p>
|
|
656 |
|
|
657 |
<p>A {@code Map<}<em>K</em>,<em>V</em>{@code >} is reconstructed as
|
|
658 |
a {@code java.util.HashMap<}<em>K</em>,<em>V</em>{@code >};
|
|
659 |
a {@code SortedMap<}<em>K</em>,<em>V</em>{@code >} as
|
|
660 |
a {@code java.util.TreeMap<}<em>K</em>,<em>V</em>{@code >}.</p>
|
|
661 |
|
|
662 |
<p>{@code TabularData} is an interface. The concrete class that is
|
|
663 |
used to represent a {@code Map<}<em>K</em>,<em>V</em>{@code >} as
|
|
664 |
Open Data is {@link TabularDataSupport},
|
|
665 |
or another class implementing {@code
|
|
666 |
TabularData} that serializes as {@code TabularDataSupport}.</p>
|
|
667 |
|
|
668 |
|
687
|
669 |
<h3 id="mxbean-map">Mappings for MXBean interfaces</h3>
|
2
|
670 |
|
|
671 |
<p>An MXBean interface, or a type referenced within an MXBean
|
|
672 |
interface, can reference another MXBean interface, <em>J</em>.
|
|
673 |
Then <em>opentype(J)</em> is {@code SimpleType.OBJECTNAME} and
|
|
674 |
<em>opendata(J)</em> is {@code ObjectName}.</p>
|
|
675 |
|
|
676 |
<p>For example, suppose you have two MXBean interfaces like this:</p>
|
|
677 |
|
|
678 |
<pre>
|
|
679 |
public interface ProductMXBean {
|
|
680 |
public ModuleMXBean[] getModules();
|
|
681 |
}
|
|
682 |
|
|
683 |
public interface ModuleMXBean {
|
|
684 |
public ProductMXBean getProduct();
|
|
685 |
}
|
|
686 |
</pre>
|
|
687 |
|
|
688 |
<p>The object implementing the {@code ModuleMXBean} interface
|
|
689 |
returns from its {@code getProduct} method an object
|
|
690 |
implementing the {@code ProductMXBean} interface. The
|
|
691 |
{@code ModuleMXBean} object and the returned {@code
|
|
692 |
ProductMXBean} objects must both be registered as MXBeans in the
|
|
693 |
same MBean Server.</p>
|
|
694 |
|
|
695 |
<p>The method {@code ModuleMXBean.getProduct()} defines an
|
|
696 |
attribute called {@code Product}. The Open Type for this
|
|
697 |
attribute is {@code SimpleType.OBJECTNAME}, and the corresponding
|
|
698 |
{@code ObjectName} value will be the name under which the
|
|
699 |
referenced {@code ProductMXBean} is registered in the MBean
|
|
700 |
Server.</p>
|
|
701 |
|
|
702 |
<p>If you make an MXBean proxy for a {@code ModuleMXBean} and
|
|
703 |
call its {@code getProduct()} method, the proxy will map the
|
|
704 |
{@code ObjectName} back into a {@code ProductMXBean} by making
|
|
705 |
another MXBean proxy. More formally, when a proxy made with
|
|
706 |
{@link JMX#newMXBeanProxy(MBeanServerConnection, ObjectName,
|
|
707 |
Class)
|
|
708 |
JMX.newMXBeanProxy(mbeanServerConnection, objectNameX,
|
|
709 |
interfaceX)} needs to map {@code objectNameY} back into {@code
|
|
710 |
interfaceY}, another MXBean interface, it does so with {@code
|
|
711 |
JMX.newMXBeanProxy(mbeanServerConnection, objectNameY,
|
|
712 |
interfaceY)}. The implementation may return a proxy that was
|
|
713 |
previously created by a call to {@code JMX.newMXBeanProxy}
|
|
714 |
with the same parameters, or it may create a new proxy.</p>
|
|
715 |
|
|
716 |
<p>The reverse mapping is illustrated by the following change to the
|
|
717 |
{@code ModuleMXBean} interface:</p>
|
|
718 |
|
|
719 |
<pre>
|
|
720 |
public interface ModuleMXBean {
|
|
721 |
public ProductMXBean getProduct();
|
|
722 |
public void setProduct(ProductMXBean c);
|
|
723 |
}
|
|
724 |
</pre>
|
|
725 |
|
|
726 |
<p>The presence of the {@code setProduct} method now means that the
|
|
727 |
{@code Product} attribute is read/write. As before, the value
|
|
728 |
of this attribute is an {@code ObjectName}. When the attribute is
|
|
729 |
set, the {@code ObjectName} must be converted into the
|
|
730 |
{@code ProductMXBean} object that the {@code setProduct} method
|
|
731 |
expects. This object will be an MXBean proxy for the given
|
|
732 |
{@code ObjectName} in the same MBean Server.</p>
|
|
733 |
|
|
734 |
<p>If you make an MXBean proxy for a {@code ModuleMXBean} and
|
|
735 |
call its {@code setProduct} method, the proxy will map its
|
|
736 |
{@code ProductMXBean} argument back into an {@code ObjectName}.
|
|
737 |
This will only work if the argument is in fact another proxy,
|
|
738 |
for a {@code ProductMXBean} in the same {@code
|
|
739 |
MBeanServerConnection}. The proxy can have been returned from
|
|
740 |
another proxy (like {@code ModuleMXBean.getProduct()} which
|
|
741 |
returns a proxy for a {@code ProductMXBean}); or it can have
|
|
742 |
been created by {@link
|
|
743 |
JMX#newMXBeanProxy(MBeanServerConnection, ObjectName, Class)
|
|
744 |
JMX.newMXBeanProxy}; or it can have been created using {@link
|
|
745 |
java.lang.reflect.Proxy Proxy} with an invocation handler that
|
|
746 |
is {@link MBeanServerInvocationHandler} or a subclass.</p>
|
|
747 |
|
|
748 |
<p>If the same MXBean were registered under two different
|
|
749 |
{@code ObjectName}s, a reference to that MXBean from another
|
|
750 |
MXBean would be ambiguous. Therefore, if an MXBean object is
|
|
751 |
already registered in an MBean Server and an attempt is made to
|
|
752 |
register it in the same MBean Server under another name, the
|
|
753 |
result is an {@link InstanceAlreadyExistsException}. Registering
|
|
754 |
the same MBean object under more than one name is discouraged in
|
|
755 |
general, notably because it does not work well for MBeans that are
|
|
756 |
{@link NotificationBroadcaster}s.</p>
|
|
757 |
|
687
|
758 |
<h3 id="composite-map">Mappings for other types</h3>
|
2
|
759 |
|
|
760 |
<p>Given a Java class or interface <em>J</em> that does not match the other
|
|
761 |
rules in the table above, the MXBean framework will attempt to map
|
|
762 |
it to a {@link CompositeType} as follows. The type name of this
|
|
763 |
{@code CompositeType} is determined by the <a href="#type-names">
|
|
764 |
type name rules</a> below.</p>
|
|
765 |
|
|
766 |
<p>The class is examined for getters using the conventions
|
|
767 |
<a href="#naming-conv">above</a>. (Getters must be public
|
|
768 |
instance methods.) If there are no getters, or if
|
|
769 |
any getter has a type that is not convertible, then <em>J</em> is
|
|
770 |
not convertible.</p>
|
|
771 |
|
|
772 |
<p>If there is at least one getter and every getter has a
|
|
773 |
convertible type, then <em>opentype(J)</em> is a {@code
|
|
774 |
CompositeType} with one item for every getter. If the getter is
|
|
775 |
|
|
776 |
<blockquote>
|
|
777 |
<code><em>T</em> get<em>Name</em>()</code>
|
|
778 |
</blockquote>
|
|
779 |
|
|
780 |
then the item in the {@code CompositeType} is called {@code name}
|
|
781 |
and has type <em>opentype(T)</em>. For example, if the item is
|
|
782 |
|
|
783 |
<blockquote>
|
|
784 |
<code>String getOwner()</code>
|
|
785 |
</blockquote>
|
|
786 |
|
|
787 |
then the item is called {@code owner} and has Open Type {@code
|
|
788 |
SimpleType.STRING}. If the getter is
|
|
789 |
|
|
790 |
<blockquote>
|
|
791 |
<code>boolean is<em>Name</em>()</code>
|
|
792 |
</blockquote>
|
|
793 |
|
|
794 |
then the item in the {@code CompositeType} is called {@code name}
|
|
795 |
and has type {@code SimpleType.BOOLEAN}.</p>
|
|
796 |
|
|
797 |
<p>Notice that the first character (or code point) is converted to
|
|
798 |
lower case. This follows the Java Beans convention, which for
|
|
799 |
historical reasons is different from the Standard MBean
|
|
800 |
convention. In a Standard MBean or MXBean interface, a method
|
|
801 |
{@code getOwner} defines an attribute called {@code Owner}, while
|
|
802 |
in a Java Bean or mapped {@code CompositeType}, a method {@code
|
|
803 |
getOwner} defines a property or item called {@code owner}.</p>
|
|
804 |
|
|
805 |
<p>If two methods produce the same item name (for example, {@code
|
|
806 |
getOwner} and {@code isOwner}, or {@code getOwner} and {@code
|
|
807 |
getowner}) then the type is not convertible.</p>
|
|
808 |
|
|
809 |
<p>When the Open Type is {@code CompositeType}, the corresponding
|
|
810 |
mapped Java type (<em>opendata(J)</em>) is {@link
|
|
811 |
CompositeData}. The mapping from an instance of <em>J</em> to a
|
|
812 |
{@code CompositeData} corresponding to the {@code CompositeType}
|
|
813 |
just described is done as follows. First, if <em>J</em>
|
|
814 |
implements the interface {@link CompositeDataView}, then that
|
|
815 |
interface's {@link CompositeDataView#toCompositeData
|
|
816 |
toCompositeData} method is called to do the conversion.
|
|
817 |
Otherwise, the {@code CompositeData} is constructed by calling
|
|
818 |
the getter for each item and converting it to the corresponding
|
|
819 |
Open Data type. Thus, a getter such as</p>
|
|
820 |
|
|
821 |
<blockquote>
|
|
822 |
{@code List<String> getNames()}
|
|
823 |
</blockquote>
|
|
824 |
|
|
825 |
<p>will have been mapped to an item with name "{@code names}" and
|
|
826 |
Open Type {@code ArrayType(1, SimpleType.STRING)}. The conversion
|
|
827 |
to {@code CompositeData} will call {@code getNames()} and convert
|
|
828 |
the resultant {@code List<String>} into a {@code String[]} for the
|
|
829 |
item "{@code names}".</p>
|
|
830 |
|
|
831 |
<p>{@code CompositeData} is an interface. The concrete class that is
|
|
832 |
used to represent a type as Open Data is {@link
|
|
833 |
CompositeDataSupport}, or another class implementing {@code
|
|
834 |
CompositeData} that serializes as {@code
|
|
835 |
CompositeDataSupport}.</p>
|
|
836 |
|
|
837 |
|
|
838 |
<h4>Reconstructing an instance of Java type <em>J</em> from
|
|
839 |
a {@code CompositeData}</h4>
|
|
840 |
|
|
841 |
<p>If <em>opendata(J)</em> is {@code CompositeData} for a Java type
|
|
842 |
<em>J</em>, then either an instance of <em>J</em> can be
|
|
843 |
reconstructed from a {@code CompositeData}, or <em>J</em> is not
|
|
844 |
reconstructible. If any item in the {@code CompositeData} is not
|
|
845 |
reconstructible, then <em>J</em> is not reconstructible either.</p>
|
|
846 |
|
|
847 |
<p>For any given <em>J</em>, the following rules are consulted to
|
|
848 |
determine how to reconstruct instances of <em>J</em> from
|
|
849 |
{@code CompositeData}. The first applicable rule in the list is
|
|
850 |
the one that will be used.</p>
|
|
851 |
|
|
852 |
<ol>
|
|
853 |
|
|
854 |
<li><p>If <em>J</em> has a method<br>
|
|
855 |
{@code public static }<em>J </em>{@code from(CompositeData cd)}<br>
|
|
856 |
then that method is called to reconstruct an instance of
|
|
857 |
<em>J</em>.</p></li>
|
|
858 |
|
|
859 |
<li><p>Otherwise, if <em>J</em> has at least one public
|
|
860 |
constructor with a {@link ConstructorProperties} annotation, then one
|
|
861 |
of those constructors (not necessarily always the same one)
|
|
862 |
will be called to reconstruct an instance of <em>J</em>.
|
|
863 |
Every such annotation must list as many strings as the
|
|
864 |
constructor has parameters; each string must name a property
|
|
865 |
corresponding to a getter of <em>J</em>; and the type of this
|
|
866 |
getter must be the same as the corresponding constructor
|
|
867 |
parameter. It is not an error for there to be getters that
|
|
868 |
are not mentioned in the {@code ConstructorProperties} annotation
|
|
869 |
(these may correspond to information that is not needed to
|
|
870 |
reconstruct the object).</p>
|
|
871 |
|
|
872 |
<p>An instance of <em>J</em> is reconstructed by calling a
|
|
873 |
constructor with the appropriate reconstructed items from the
|
|
874 |
{@code CompositeData}. The constructor to be called will be
|
|
875 |
determined at runtime based on the items actually present in
|
|
876 |
the {@code CompositeData}, given that this {@code
|
|
877 |
CompositeData} might come from an earlier version of
|
|
878 |
<em>J</em> where not all the items were present. A
|
|
879 |
constructor is <em>applicable</em> if all the properties named
|
|
880 |
in its {@code ConstructorProperties} annotation are present as items
|
|
881 |
in the {@code CompositeData}. If no constructor is
|
|
882 |
applicable, then the attempt to reconstruct <em>J</em> fails.</p>
|
|
883 |
|
|
884 |
<p>For any possible combination of properties, it must be the
|
|
885 |
case that either (a) there are no applicable constructors, or
|
|
886 |
(b) there is exactly one applicable constructor, or (c) one of
|
|
887 |
the applicable constructors names a proper superset of the
|
|
888 |
properties named by each other applicable constructor. (In
|
|
889 |
other words, there should never be ambiguity over which
|
|
890 |
constructor to choose.) If this condition is not true, then
|
|
891 |
<em>J</em> is not reconstructible.</p></li>
|
|
892 |
|
|
893 |
<li><p>Otherwise, if <em>J</em> has a public no-arg constructor, and
|
|
894 |
for every getter in <em>J</em> with type
|
|
895 |
<em>T</em> and name <em>N</em> there is a corresponding setter
|
|
896 |
with the same name and type, then an instance of <em>J</em> is
|
|
897 |
constructed with the no-arg constructor and the setters are
|
|
898 |
called with the reconstructed items from the {@code CompositeData}
|
|
899 |
to restore the values. For example, if there is a method<br>
|
|
900 |
{@code public List<String> getNames()}<br>
|
|
901 |
then there must also be a method<br>
|
|
902 |
{@code public void setNames(List<String> names)}<br>
|
|
903 |
for this rule to apply.</p>
|
|
904 |
|
|
905 |
<p>If the {@code CompositeData} came from an earlier version of
|
|
906 |
<em>J</em>, some items might not be present. In this case,
|
|
907 |
the corresponding setters will not be called.</p></li>
|
|
908 |
|
|
909 |
<li><p>Otherwise, if <em>J</em> is an interface that has no methods
|
|
910 |
other than getters, an instance of <em>J</em> is constructed
|
|
911 |
using a {@link java.lang.reflect.Proxy} with a {@link
|
|
912 |
CompositeDataInvocationHandler} backed by the {@code
|
|
913 |
CompositeData} being converted.</p></li>
|
|
914 |
|
|
915 |
<li><p>Otherwise, <em>J</em> is not reconstructible.</p></li>
|
|
916 |
</ol>
|
|
917 |
|
|
918 |
<p>Here are examples showing different ways to code a type {@code
|
|
919 |
NamedNumber} that consists of an {@code int} and a {@code
|
|
920 |
String}. In each case, the {@code CompositeType} looks like this:</p>
|
|
921 |
|
|
922 |
<blockquote>
|
|
923 |
<pre>
|
|
924 |
{@link CompositeType}(
|
|
925 |
"NamedNumber", // typeName
|
|
926 |
"NamedNumber", // description
|
|
927 |
new String[] {"number", "name"}, // itemNames
|
|
928 |
new String[] {"number", "name"}, // itemDescriptions
|
|
929 |
new OpenType[] {SimpleType.INTEGER,
|
|
930 |
SimpleType.STRING} // itemTypes
|
|
931 |
);
|
|
932 |
</pre>
|
|
933 |
</blockquote>
|
|
934 |
|
|
935 |
<ol>
|
|
936 |
<li>Static {@code from} method:
|
|
937 |
|
|
938 |
<blockquote>
|
|
939 |
<pre>
|
|
940 |
public class NamedNumber {
|
|
941 |
public int getNumber() {return number;}
|
|
942 |
public String getName() {return name;}
|
|
943 |
private NamedNumber(int number, String name) {
|
|
944 |
this.number = number;
|
|
945 |
this.name = name;
|
|
946 |
}
|
|
947 |
<b>public static NamedNumber from(CompositeData cd)</b> {
|
|
948 |
return new NamedNumber((Integer) cd.get("number"),
|
|
949 |
(String) cd.get("name"));
|
|
950 |
}
|
|
951 |
private final int number;
|
|
952 |
private final String name;
|
|
953 |
}
|
|
954 |
</pre>
|
|
955 |
</blockquote>
|
|
956 |
</li>
|
|
957 |
|
|
958 |
<li>Public constructor with <code>@ConstructorProperties</code> annotation:
|
|
959 |
|
|
960 |
<blockquote>
|
|
961 |
<pre>
|
|
962 |
public class NamedNumber {
|
|
963 |
public int getNumber() {return number;}
|
|
964 |
public String getName() {return name;}
|
|
965 |
<b>@ConstructorProperties({"number", "name"})
|
|
966 |
public NamedNumber(int number, String name)</b> {
|
|
967 |
this.number = number;
|
|
968 |
this.name = name;
|
|
969 |
}
|
|
970 |
private final int number;
|
|
971 |
private final String name;
|
|
972 |
}
|
|
973 |
</pre>
|
|
974 |
</blockquote>
|
|
975 |
</li>
|
|
976 |
|
|
977 |
<li>Setter for every getter:
|
|
978 |
|
|
979 |
<blockquote>
|
|
980 |
<pre>
|
|
981 |
public class NamedNumber {
|
|
982 |
public int getNumber() {return number;}
|
|
983 |
public void <b>setNumber</b>(int number) {this.number = number;}
|
|
984 |
public String getName() {return name;}
|
|
985 |
public void <b>setName</b>(String name) {this.name = name;}
|
|
986 |
<b>public NamedNumber()</b> {}
|
|
987 |
private int number;
|
|
988 |
private String name;
|
|
989 |
}
|
|
990 |
</pre>
|
|
991 |
</blockquote>
|
|
992 |
</li>
|
|
993 |
|
|
994 |
<li>Interface with only getters:
|
|
995 |
|
|
996 |
<blockquote>
|
|
997 |
<pre>
|
|
998 |
public interface NamedNumber {
|
|
999 |
public int getNumber();
|
|
1000 |
public String getName();
|
|
1001 |
}
|
|
1002 |
</pre>
|
|
1003 |
</blockquote>
|
|
1004 |
</li>
|
|
1005 |
</ol>
|
|
1006 |
|
|
1007 |
<p>It is usually better for classes that simply represent a
|
|
1008 |
collection of data to be <em>immutable</em>. An instance of an
|
|
1009 |
immutable class cannot be changed after it has been constructed.
|
|
1010 |
Notice that {@code CompositeData} itself is immutable.
|
|
1011 |
Immutability has many advantages, notably with regard to
|
|
1012 |
thread-safety and security. So the approach using setters should
|
|
1013 |
generally be avoided if possible.</p>
|
|
1014 |
|
|
1015 |
|
|
1016 |
<h3>Recursive types</h3>
|
|
1017 |
|
|
1018 |
<p>Recursive (self-referential) types cannot be used in MXBean
|
|
1019 |
interfaces. This is a consequence of the immutability of {@link
|
|
1020 |
CompositeType}. For example, the following type could not be the
|
|
1021 |
type of an attribute, because it refers to itself:</p>
|
|
1022 |
|
|
1023 |
<pre>
|
|
1024 |
public interface <b>Node</b> {
|
|
1025 |
public String getName();
|
|
1026 |
public int getPriority();
|
|
1027 |
public <b>Node</b> getNext();
|
|
1028 |
}
|
|
1029 |
</pre>
|
|
1030 |
|
|
1031 |
<p>It is always possible to rewrite recursive types like this so
|
|
1032 |
they are no longer recursive. Doing so may require introducing
|
|
1033 |
new types. For example:</p>
|
|
1034 |
|
|
1035 |
<pre>
|
|
1036 |
public interface <b>NodeList</b> {
|
|
1037 |
public List<Node> getNodes();
|
|
1038 |
}
|
|
1039 |
|
|
1040 |
public interface Node {
|
|
1041 |
public String getName();
|
|
1042 |
public int getPriority();
|
|
1043 |
}
|
|
1044 |
</pre>
|
|
1045 |
|
687
|
1046 |
<p>Alternatively, you can define a custom mapping for your recursive
|
|
1047 |
type; see the next section.</p>
|
|
1048 |
|
|
1049 |
<h3 id="custom">Custom MXBean type mappings</h3>
|
|
1050 |
|
|
1051 |
<p>You can augment or replace the default type mappings described
|
|
1052 |
above with custom mappings. An example appears in the
|
|
1053 |
documentation for {@link MXBeanMapping}.</p>
|
|
1054 |
|
|
1055 |
<p>If an MXBean uses custom mappings, then an MXBean proxy for
|
|
1056 |
that MXBean must use the same mappings for correct behavior.
|
|
1057 |
This requires more careful synchronization between client and
|
|
1058 |
server than is necessary with the default mappings. For example
|
|
1059 |
it typically requires the client to have the same implementation
|
|
1060 |
of any {@link MXBeanMapping} subclasses as the server. For this
|
|
1061 |
reason, custom mappings should be avoided if possible.</p>
|
|
1062 |
|
|
1063 |
<p>Every MXBean has an associated {@link MXBeanMappingFactory}.
|
|
1064 |
Call this <code><em>f</em></code>. Then every type that appears
|
|
1065 |
in that MXBean has an associated {@link MXBeanMapping}
|
|
1066 |
determined by <code><em>f</em></code>. If the type is
|
|
1067 |
<code><em>J</em></code>, say, then the mapping is {@link
|
|
1068 |
MXBeanMappingFactory#mappingForType
|
|
1069 |
<em>f</em>.mappingForType}<code>(<em>J</em>,
|
|
1070 |
<em>f</em>)</code>.</p>
|
|
1071 |
|
|
1072 |
<p>The {@code MXBeanMappingFactory} <code><em>f</em></code> for an
|
|
1073 |
MXBean is determined as follows.</p>
|
|
1074 |
|
|
1075 |
<ul>
|
|
1076 |
<li><p>If an {@link JMX.MBeanOptions} argument is supplied to
|
|
1077 |
the {@link StandardMBean} constructor that makes an MXBean,
|
|
1078 |
or to the {@link JMX#newMXBeanProxy JMX.newMXBeanProxy}
|
|
1079 |
method, and the {@code MBeanOptions} object defines a non-null
|
|
1080 |
{@code MXBeanMappingFactory}, then that is the value of
|
|
1081 |
<code><em>f</em></code>.</p></li>
|
|
1082 |
|
|
1083 |
<li><p>Otherwise, if the MXBean interface has an {@link
|
|
1084 |
MXBeanMappingFactoryClass} annotation, then that annotation
|
|
1085 |
must identify a subclass of {@code MXBeanMappingFactory}
|
|
1086 |
with a no-argument constructor. Then
|
|
1087 |
<code><em>f</em></code> is the result of calling this
|
|
1088 |
constructor. If the class does not have a no-argument
|
|
1089 |
constructor, or if calling the constructor produces an
|
|
1090 |
exception, then the MXBean is invalid and an attempt to
|
|
1091 |
register it in the MBean Server will produce a {@link
|
|
1092 |
NotCompliantMBeanException}.</p>
|
|
1093 |
|
|
1094 |
<p>This annotation is not inherited from any parent
|
|
1095 |
interfaces. If an MXBean interface has this annotation,
|
|
1096 |
then usually any MXBean subinterfaces must repeat the same
|
|
1097 |
annotation for correct behavior.</p></li>
|
|
1098 |
|
|
1099 |
<li><p>Otherwise, if the package in which the MXBean interface
|
|
1100 |
appears has an {@code MXBeanMappingFactoryClass} annotation,
|
|
1101 |
then <code><em>f</em></code> is determined as if that
|
|
1102 |
annotation appeared on the MXBean interface.</p></li>
|
|
1103 |
|
|
1104 |
<li><p>Otherwise, <code><em>f</em></code> is the default mapping
|
|
1105 |
factory, {@link MXBeanMappingFactory#DEFAULT}.</p></li>
|
|
1106 |
</ul>
|
|
1107 |
|
|
1108 |
<p>The default mapping factory recognizes the {@link
|
|
1109 |
MXBeanMappingClass} annotation on a class or interface. If
|
|
1110 |
<code><em>J</em></code> is a class or interface that has such an
|
|
1111 |
annotation, then the {@code MXBeanMapping} for
|
|
1112 |
<code><em>J</em></code> produced by the default mapping factory
|
|
1113 |
will be determined by the value of the annotation as described
|
|
1114 |
in its {@linkplain MXBeanMappingClass documentation}.</p>
|
|
1115 |
|
2
|
1116 |
<h3>MBeanInfo contents for an MXBean</h3>
|
|
1117 |
|
|
1118 |
<p>An MXBean is a type of Open MBean. However, for compatibility
|
|
1119 |
reasons, its {@link MBeanInfo} is not an {@link OpenMBeanInfo}.
|
|
1120 |
In particular, when the type of an attribute, parameter, or
|
|
1121 |
operation return value is a primitive type such as {@code int},
|
|
1122 |
or is {@code void} (for a return type), then the attribute,
|
|
1123 |
parameter, or operation will be represented respectively by an
|
|
1124 |
{@link MBeanAttributeInfo}, {@link MBeanParameterInfo}, or
|
|
1125 |
{@link MBeanOperationInfo} whose {@code getType()} or {@code
|
|
1126 |
getReturnType()} returns the primitive name ("{@code int}" etc).
|
|
1127 |
This is so even though the mapping rules above specify that the
|
|
1128 |
<em>opendata</em> mapping is the wrapped type ({@code Integer}
|
|
1129 |
etc).</p>
|
|
1130 |
|
|
1131 |
<p>The array of public constructors returned by {@link
|
|
1132 |
MBeanInfo#getConstructors()} for an MXBean that is directly
|
|
1133 |
registered in the MBean Server will contain all of the public
|
|
1134 |
constructors of that MXBean. If the class of the MXBean is not
|
|
1135 |
public then its constructors are not considered public either.
|
|
1136 |
The list returned for an MXBean that is constructed using the
|
|
1137 |
{@link StandardMBean} class is derived in the same way as for
|
|
1138 |
Standard MBeans. Regardless of how the MXBean was constructed,
|
|
1139 |
its constructor parameters are not subject to MXBean mapping
|
|
1140 |
rules and do not have a corresponding {@code OpenType}.</p>
|
|
1141 |
|
|
1142 |
<p>The array of notification types returned by {@link
|
|
1143 |
MBeanInfo#getNotifications()} for an MXBean that is directly
|
|
1144 |
registered in the MBean Server will be empty if the MXBean does
|
|
1145 |
not implement the {@link NotificationBroadcaster} interface.
|
|
1146 |
Otherwise, it will be the result of calling {@link
|
|
1147 |
NotificationBroadcaster#getNotificationInfo()} at the time the MXBean
|
|
1148 |
was registered. Even if the result of this method changes
|
|
1149 |
subsequently, the result of {@code MBeanInfo.getNotifications()}
|
|
1150 |
will not. The list returned for an MXBean that is constructed
|
|
1151 |
using the {@link StandardMBean} or {@link StandardEmitterMBean}
|
|
1152 |
class is derived in the same way as for Standard MBeans.</p>
|
|
1153 |
|
|
1154 |
<p>The {@link Descriptor} for all of the
|
|
1155 |
{@code MBeanAttributeInfo}, {@code MBeanParameterInfo}, and
|
|
1156 |
{@code MBeanOperationInfo} objects contained in the {@code MBeanInfo}
|
|
1157 |
will have a field {@code openType} whose value is the {@link OpenType}
|
|
1158 |
specified by the mapping rules above. So even when {@code getType()}
|
|
1159 |
is "{@code int}", {@code getDescriptor().getField("openType")} will
|
|
1160 |
be {@link SimpleType#INTEGER}.</p>
|
|
1161 |
|
|
1162 |
<p>The {@code Descriptor} for each of these objects will also have a
|
|
1163 |
field {@code originalType} that is a string representing the Java type
|
|
1164 |
that appeared in the MXBean interface. The format of this string
|
|
1165 |
is described in the section <a href="#type-names">Type Names</a>
|
|
1166 |
below.</p>
|
|
1167 |
|
|
1168 |
<p>The {@code Descriptor} for the {@code MBeanInfo} will have a field
|
|
1169 |
{@code mxbean} whose value is the string "{@code true}".</p>
|
|
1170 |
|
|
1171 |
|
687
|
1172 |
<h3 id="type-names">Type Names</h3>
|
2
|
1173 |
|
|
1174 |
<p>Sometimes the unmapped type <em>T</em> of a method parameter or
|
|
1175 |
return value in an MXBean must be represented as a string. If
|
|
1176 |
<em>T</em> is a non-generic type, this string is the value
|
|
1177 |
returned by {@link Class#getName()}. Otherwise it is the value of
|
|
1178 |
<em>genericstring(T)</em>, defined as follows:
|
|
1179 |
|
|
1180 |
<ul>
|
|
1181 |
|
|
1182 |
<li>If <em>T</em> is a non-generic non-array type,
|
|
1183 |
<em>genericstring(T)</em> is the value returned by {@link
|
|
1184 |
Class#getName()}, for example {@code "int"} or {@code
|
|
1185 |
"java.lang.String"}.
|
|
1186 |
|
|
1187 |
<li>If <em>T</em> is an array <em>E[]</em>,
|
|
1188 |
<em>genericstring(T)</em> is <em>genericstring(E)</em> followed
|
|
1189 |
by {@code "[]"}. For example, <em>genericstring({@code int[]})</em>
|
|
1190 |
is {@code "int[]"}, and <em>genericstring({@code
|
|
1191 |
List<String>[][]})</em> is {@code
|
|
1192 |
"java.util.List<java.lang.String>[][]"}.
|
|
1193 |
|
|
1194 |
<li>Otherwise, <em>T</em> is a parameterized type such as {@code
|
|
1195 |
List<String>} and <em>genericstring(T)</em> consists of the
|
|
1196 |
following: the fully-qualified name of the parameterized type as
|
|
1197 |
returned by {@code Class.getName()}; a left angle bracket ({@code
|
|
1198 |
"<"}); <em>genericstring(A)</em> where <em>A</em> is the first
|
|
1199 |
type parameter; if there is a second type parameter <em>B</em>
|
|
1200 |
then {@code ", "} (a comma and a single space) followed by
|
|
1201 |
<em>genericstring(B)</em>; a right angle bracket ({@code ">"}).
|
|
1202 |
|
|
1203 |
</ul>
|
|
1204 |
|
|
1205 |
<p>Note that if a method returns {@code int[]}, this will be
|
|
1206 |
represented by the string {@code "[I"} returned by {@code
|
|
1207 |
Class.getName()}, but if a method returns {@code List<int[]>},
|
|
1208 |
this will be represented by the string {@code
|
|
1209 |
"java.util.List<int[]>"}.
|
|
1210 |
|
|
1211 |
<h3>Exceptions</h3>
|
|
1212 |
|
|
1213 |
<p>A problem with mapping <em>from</em> Java types <em>to</em>
|
|
1214 |
Open types is signaled with an {@link OpenDataException}. This
|
|
1215 |
can happen when an MXBean interface is being analyzed, for
|
|
1216 |
example if it references a type like {@link java.util.Random
|
|
1217 |
java.util.Random} that has no getters. Or it can happen when an
|
|
1218 |
instance is being converted (a return value from a method in an
|
|
1219 |
MXBean or a parameter to a method in an MXBean proxy), for
|
|
1220 |
example when converting from {@code SortedSet<String>} to {@code
|
|
1221 |
String[]} if the {@code SortedSet} has a non-null {@code
|
|
1222 |
Comparator}.</p>
|
|
1223 |
|
|
1224 |
<p>A problem with mapping <em>to</em> Java types <em>from</em>
|
|
1225 |
Open types is signaled with an {@link InvalidObjectException}.
|
|
1226 |
This can happen when an MXBean interface is being analyzed, for
|
|
1227 |
example if it references a type that is not
|
|
1228 |
<em>reconstructible</em> according to the rules above, in a
|
|
1229 |
context where a reconstructible type is required. Or it can
|
|
1230 |
happen when an instance is being converted (a parameter to a
|
|
1231 |
method in an MXBean or a return value from a method in an MXBean
|
|
1232 |
proxy), for example from a String to an Enum if there is no Enum
|
|
1233 |
constant with that name.</p>
|
|
1234 |
|
|
1235 |
<p>Depending on the context, the {@code OpenDataException} or
|
|
1236 |
{@code InvalidObjectException} may be wrapped in another
|
|
1237 |
exception such as {@link RuntimeMBeanException} or {@link
|
|
1238 |
UndeclaredThrowableException}. For every thrown exception,
|
|
1239 |
the condition <em>C</em> will be true: "<em>e</em> is {@code
|
|
1240 |
OpenDataException} or {@code InvalidObjectException} (as
|
|
1241 |
appropriate), or <em>C</em> is true of <em>e</em>.{@link
|
|
1242 |
Throwable#getCause() getCause()}".</p>
|
|
1243 |
|
687
|
1244 |
@see MXBeanMapping
|
|
1245 |
|
2
|
1246 |
@since 1.6
|
|
1247 |
*/
|
|
1248 |
|
|
1249 |
@Documented
|
|
1250 |
@Retention(RetentionPolicy.RUNTIME)
|
|
1251 |
@Target(ElementType.TYPE)
|
|
1252 |
public @interface MXBean {
|
|
1253 |
/**
|
|
1254 |
True if the annotated interface is an MXBean interface.
|
|
1255 |
@return true if the annotated interface is an MXBean interface.
|
|
1256 |
*/
|
|
1257 |
boolean value() default true;
|
|
1258 |
}
|