You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1189 lines
48 KiB
1189 lines
48 KiB
/*
|
|
* Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
|
|
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*/
|
|
|
|
package javax.management;
|
|
|
|
import java.lang.annotation.Documented;
|
|
import java.lang.annotation.ElementType;
|
|
import java.lang.annotation.Retention;
|
|
import java.lang.annotation.RetentionPolicy;
|
|
import java.lang.annotation.Target;
|
|
|
|
// remaining imports are for Javadoc
|
|
import java.io.InvalidObjectException;
|
|
import java.lang.management.MemoryUsage;
|
|
import java.lang.reflect.UndeclaredThrowableException;
|
|
import java.util.Arrays;
|
|
import java.util.List;
|
|
import javax.management.openmbean.ArrayType;
|
|
import javax.management.openmbean.CompositeData;
|
|
import javax.management.openmbean.CompositeDataInvocationHandler;
|
|
import javax.management.openmbean.CompositeDataSupport;
|
|
import javax.management.openmbean.CompositeDataView;
|
|
import javax.management.openmbean.CompositeType;
|
|
import javax.management.openmbean.OpenDataException;
|
|
import javax.management.openmbean.OpenMBeanInfo;
|
|
import javax.management.openmbean.OpenType;
|
|
import javax.management.openmbean.SimpleType;
|
|
import javax.management.openmbean.TabularData;
|
|
import javax.management.openmbean.TabularDataSupport;
|
|
import javax.management.openmbean.TabularType;
|
|
|
|
/**
|
|
<p>Annotation to mark an interface explicitly as being an MXBean
|
|
interface, or as not being an MXBean interface. By default, an
|
|
interface is an MXBean interface if it is public and its name ends
|
|
with {@code MXBean}, as in {@code SomethingMXBean}. The following
|
|
interfaces are MXBean interfaces:</p>
|
|
|
|
<pre>
|
|
public interface WhatsitMXBean {}
|
|
|
|
@MXBean
|
|
public interface Whatsit1Interface {}
|
|
|
|
@MXBean(true)
|
|
public interface Whatsit2Interface {}
|
|
</pre>
|
|
|
|
<p>The following interfaces are not MXBean interfaces:</p>
|
|
|
|
<pre>
|
|
interface NonPublicInterfaceNotMXBean{}
|
|
|
|
public interface Whatsit3Interface{}
|
|
|
|
@MXBean(false)
|
|
public interface MisleadingMXBean {}
|
|
</pre>
|
|
|
|
<h3 id="MXBean-spec">MXBean specification</h3>
|
|
|
|
<p>The MXBean concept provides a simple way to code an MBean
|
|
that only references a predefined set of types, the ones defined
|
|
by {@link javax.management.openmbean}. In this way, you can be
|
|
sure that your MBean will be usable by any client, including
|
|
remote clients, without any requirement that the client have
|
|
access to <em>model-specific classes</em> representing the types
|
|
of your MBeans.</p>
|
|
|
|
<p>The concepts are easier to understand by comparison with the
|
|
Standard MBean concept. Here is how a managed object might be
|
|
represented as a Standard MBean, and as an MXBean:</p>
|
|
|
|
<table border="1" cellpadding="5" summary="Standard Bean vs. MXBean">
|
|
<tr>
|
|
<th>Standard MBean</th><th>MXBean</th>
|
|
</tr>
|
|
<tr>
|
|
<td><pre>
|
|
public interface MemoryPool<b>MBean</b> {
|
|
String getName();
|
|
MemoryUsage getUsage();
|
|
// ...
|
|
}
|
|
</pre></td>
|
|
<td><pre>
|
|
public interface MemoryPool<b>MXBean</b> {
|
|
String getName();
|
|
MemoryUsage getUsage();
|
|
// ...
|
|
}
|
|
</pre></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>As you can see, the definitions are very similar. The only
|
|
difference is that the convention for naming the interface is to use
|
|
<code><em>Something</em>MXBean</code> for MXBeans, rather than
|
|
<code><em>Something</em>MBean</code> for Standard MBeans.</p>
|
|
|
|
<p>In this managed object, there is an attribute called
|
|
<code>Usage</code> of type {@link MemoryUsage}. The point of an
|
|
attribute like this is that it gives a coherent snapshot of a set
|
|
of data items. For example, it might include the current amount
|
|
of used memory in the memory pool, and the current maximum of the
|
|
memory pool. If these were separate items, obtained with separate
|
|
{@link MBeanServer#getAttribute getAttribute} calls, then we could
|
|
get values seen at different times that were not consistent. We
|
|
might get a <code>used</code> value that was greater than the
|
|
<code>max</code> value.</p>
|
|
|
|
<p>So, we might define <code>MemoryUsage</code> like this:</p>
|
|
|
|
<table border="1" cellpadding="5" summary="Standard Bean vs. MXBean">
|
|
<tr>
|
|
<th>Standard MBean</th><th>MXBean</th>
|
|
</tr>
|
|
<tr>
|
|
<td><pre>
|
|
public class MemoryUsage <b>implements Serializable</b> {
|
|
// standard JavaBean conventions with getters
|
|
|
|
public MemoryUsage(long init, long used,
|
|
long committed, long max) {...}
|
|
long getInit() {...}
|
|
long getUsed() {...}
|
|
long getCommitted() {...}
|
|
long getMax() {...}
|
|
}
|
|
</pre></td>
|
|
<td><pre>
|
|
public class MemoryUsage {
|
|
// standard JavaBean conventions with getters
|
|
<b>@ConstructorProperties({"init", "used", "committed", "max"})</b>
|
|
public MemoryUsage(long init, long used,
|
|
long committed, long max) {...}
|
|
long getInit() {...}
|
|
long getUsed() {...}
|
|
long getCommitted() {...}
|
|
long getMax() {...}
|
|
}
|
|
</pre></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The definitions are the same in the two cases, except
|
|
that with the MXBean, <code>MemoryUsage</code> no longer needs to
|
|
be marked <code>Serializable</code> (though it can be). On
|
|
the other hand, we have added a {@code @ConstructorProperties} annotation
|
|
to link the constructor parameters to the corresponding getters.
|
|
We will see more about this below.</p>
|
|
|
|
<p><code>MemoryUsage</code> is a <em>model-specific class</em>.
|
|
With Standard MBeans, a client of the MBean Server cannot access the
|
|
<code>Usage</code> attribute if it does not know the class
|
|
<code>MemoryUsage</code>. Suppose the client is a generic console
|
|
based on JMX technology. Then the console would have to be
|
|
configured with the model-specific classes of every application it
|
|
might connect to. The problem is even worse for clients that are
|
|
not written in the Java language. Then there may not be any way
|
|
to tell the client what a <code>MemoryUsage</code> looks like.</p>
|
|
|
|
<p>This is where MXBeans differ from Standard MBeans. Although we
|
|
define the management interface in almost exactly the same way,
|
|
the MXBean framework <em>converts</em> model-specific classes into
|
|
standard classes from the Java platform. Using arrays and the
|
|
{@link javax.management.openmbean.CompositeData CompositeData} and
|
|
{@link javax.management.openmbean.TabularData TabularData} classes
|
|
from the standard {@link javax.management.openmbean} package, it
|
|
is possible to build data structures of arbitrary complexity
|
|
using only standard classes.</p>
|
|
|
|
<p>This becomes clearer if we compare what the clients of the two
|
|
models might look like:</p>
|
|
|
|
<table border="1" cellpadding="5" summary="Standard Bean vs. MXBean">
|
|
<tr>
|
|
<th>Standard MBean</th><th>MXBean</th>
|
|
</tr>
|
|
<tr>
|
|
<td><pre>
|
|
String name = (String)
|
|
mbeanServer.{@link MBeanServer#getAttribute
|
|
getAttribute}(objectName, "Name");
|
|
<b>MemoryUsage</b> usage = (<b>MemoryUsage</b>)
|
|
mbeanServer.getAttribute(objectName, "Usage");
|
|
<b>long used = usage.getUsed();</b>
|
|
</pre></td>
|
|
<td><pre>
|
|
String name = (String)
|
|
mbeanServer.{@link MBeanServer#getAttribute
|
|
getAttribute}(objectName, "Name");
|
|
<b>{@link CompositeData}</b> usage = (<b>CompositeData</b>)
|
|
mbeanServer.getAttribute(objectName, "Usage");
|
|
<b>long used = (Long) usage.{@link CompositeData#get get}("used");</b>
|
|
</pre></td>
|
|
</table>
|
|
|
|
<p>For attributes with simple types like <code>String</code>, the
|
|
code is the same. But for attributes with complex types, the
|
|
Standard MBean code requires the client to know the model-specific
|
|
class <code>MemoryUsage</code>, while the MXBean code requires no
|
|
non-standard classes.</p>
|
|
|
|
<p>The client code shown here is slightly more complicated for the
|
|
MXBean client. But, if the client does in fact know the model,
|
|
here the interface <code>MemoryPoolMXBean</code> and the
|
|
class <code>MemoryUsage</code>, then it can construct a
|
|
<em>proxy</em>. This is the recommended way to interact with
|
|
managed objects when you know the model beforehand, regardless
|
|
of whether you are using Standard MBeans or MXBeans:</p>
|
|
|
|
<table border="1" cellpadding="5" summary="Standard Bean vs. MXBean">
|
|
<tr>
|
|
<th>Standard MBean</th><th>MXBean</th>
|
|
</tr>
|
|
<tr>
|
|
<td><pre>
|
|
MemoryPool<b>MBean</b> proxy =
|
|
JMX.<b>{@link JMX#newMBeanProxy(MBeanServerConnection, ObjectName,
|
|
Class) newMBeanProxy}</b>(
|
|
mbeanServer,
|
|
objectName,
|
|
MemoryPool<b>MBean</b>.class);
|
|
String name = proxy.getName();
|
|
MemoryUsage usage = proxy.getUsage();
|
|
long used = usage.getUsed();
|
|
</pre></td>
|
|
<td><pre>
|
|
MemoryPool<b>MXBean</b> proxy =
|
|
JMX.<b>{@link JMX#newMXBeanProxy(MBeanServerConnection, ObjectName,
|
|
Class) newMXBeanProxy}</b>(
|
|
mbeanServer,
|
|
objectName,
|
|
MemoryPool<b>MXBean</b>.class);
|
|
String name = proxy.getName();
|
|
MemoryUsage usage = proxy.getUsage();
|
|
long used = usage.getUsed();
|
|
</pre></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Implementing the MemoryPool object works similarly for both
|
|
Standard MBeans and MXBeans.</p>
|
|
|
|
<table border="1" cellpadding="5" summary="Standard Bean vs. MXBean">
|
|
<tr>
|
|
<th>Standard MBean</th><th>MXBean</th>
|
|
</tr>
|
|
<tr>
|
|
<td><pre>
|
|
public class MemoryPool
|
|
implements MemoryPool<b>MBean</b> {
|
|
public String getName() {...}
|
|
public MemoryUsage getUsage() {...}
|
|
// ...
|
|
}
|
|
</pre></td>
|
|
<td><pre>
|
|
public class MemoryPool
|
|
implements MemoryPool<b>MXBean</b> {
|
|
public String getName() {...}
|
|
public MemoryUsage getUsage() {...}
|
|
// ...
|
|
}
|
|
</pre></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Registering the MBean in the MBean Server works in the same way
|
|
in both cases:</p>
|
|
|
|
<table border="1" cellpadding="5" summary="Standard Bean vs. MXBean">
|
|
<tr>
|
|
<th>Standard MBean</th><th>MXBean</th>
|
|
</tr>
|
|
<tr>
|
|
<td><pre>
|
|
{
|
|
MemoryPool<b>MBean</b> pool = new MemoryPool();
|
|
mbeanServer.{@link MBeanServer#registerMBean
|
|
registerMBean}(pool, objectName);
|
|
}
|
|
</pre></td>
|
|
<td><pre>
|
|
{
|
|
MemoryPool<b>MXBean</b> pool = new MemoryPool();
|
|
mbeanServer.{@link MBeanServer#registerMBean
|
|
registerMBean}(pool, objectName);
|
|
}
|
|
</pre></td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<h2 id="mxbean-def">Definition of an MXBean</h2>
|
|
|
|
<p>An MXBean is a kind of MBean. An MXBean object can be
|
|
registered directly in the MBean Server, or it can be used as an
|
|
argument to {@link StandardMBean} and the resultant MBean
|
|
registered in the MBean Server.</p>
|
|
|
|
<p>When an object is registered in the MBean Server using the
|
|
{@code registerMBean} or {@code createMBean} methods of the
|
|
{@link MBeanServer} interface, the object's class is examined
|
|
to determine what type of MBean it is:</p>
|
|
|
|
<ul>
|
|
<li>If the class implements the interface {@link DynamicMBean}
|
|
then the MBean is a Dynamic MBean. Note that the class
|
|
{@code StandardMBean} implements this interface, so this
|
|
case applies to a Standard MBean or MXBean created using
|
|
the class {@code StandardMBean}.</li>
|
|
|
|
<li>Otherwise, if the class matches the Standard MBean naming
|
|
conventions, then the MBean is a Standard MBean.</li>
|
|
|
|
<li>Otherwise, it may be an MXBean. The set of interfaces
|
|
implemented by the object is examined for interfaces that:
|
|
|
|
<ul>
|
|
<li>have a class name <code><em>S</em>MXBean</code> where
|
|
<code><em>S</em></code> is any non-empty string, and
|
|
do not have an annotation {@code @MXBean(false)}; and/or</li>
|
|
<li>have an annotation {@code @MXBean(true)}
|
|
or just {@code @MXBean}.</li>
|
|
</ul>
|
|
|
|
If there is exactly one such interface, or if there is one
|
|
such interface that is a subinterface of all the others, then
|
|
the object is an MXBean. The interface in question is the
|
|
<em>MXBean interface</em>. In the example above, the MXBean
|
|
interface is {@code MemoryPoolMXBean}.
|
|
|
|
<li>If none of these conditions is met, the MBean is invalid and
|
|
the attempt to register it will generate {@link
|
|
NotCompliantMBeanException}.
|
|
</ul>
|
|
|
|
<p>Every Java type that appears as the parameter or return type of a
|
|
method in an MXBean interface must be <em>convertible</em> using
|
|
the rules below. Additionally, parameters must be
|
|
<em>reconstructible</em> as defined below.</p>
|
|
|
|
<p>An attempt to construct an MXBean that does not conform to the
|
|
above rules will produce an exception.</p>
|
|
|
|
|
|
<h2 id="naming-conv">Naming conventions</h2>
|
|
|
|
<p>The same naming conventions are applied to the methods in an
|
|
MXBean as in a Standard MBean:</p>
|
|
|
|
<ol>
|
|
<li>A method <code><em>T</em> get<em>N</em>()</code>, where
|
|
<code><em>T</em></code> is a Java type (not <code>void</code>)
|
|
and <code><em>N</em></code> is a non-empty string, specifies
|
|
that there is a readable attribute called
|
|
<code><em>N</em></code>. The Java type and Open type of the
|
|
attribute are determined by the mapping rules below.
|
|
The method {@code final Class getClass()} inherited from {@code
|
|
Object} is ignored when looking for getters.</li>
|
|
|
|
<li>A method <code>boolean is<em>N</em>()</code> specifies that
|
|
there is a readable attribute called <code><em>N</em></code>
|
|
with Java type <code>boolean</code> and Open type
|
|
<code>SimpleType.Boolean</code>.</li>
|
|
|
|
<li>A method <code>void set<em>N</em>(<em>T</em> x)</code>
|
|
specifies that there is a writeable attribute called
|
|
<code><em>N</em></code>. The Java type and Open type of the
|
|
attribute are determined by the mapping rules below. (Of
|
|
course, the name <code>x</code> of the parameter is
|
|
irrelevant.)</li>
|
|
|
|
<li>Every other method specifies that there is an operation with
|
|
the same name as the method. The Java type and Open type of the
|
|
return value and of each parameter are determined by the mapping
|
|
rules below.</li>
|
|
</ol>
|
|
|
|
<p>The rules for <code>get<em>N</em></code> and
|
|
<code>is<em>N</em></code> collectively define the notion of a
|
|
<em>getter</em>. The rule for <code>set<em>N</em></code> defines
|
|
the notion of a <em>setter</em>.</p>
|
|
|
|
<p>It is an error for there to be two getters with the same name, or
|
|
two setters with the same name. If there is a getter and a setter
|
|
for the same name, then the type <code><em>T</em></code> in both
|
|
must be the same. In this case the attribute is read/write. If
|
|
there is only a getter or only a setter, the attribute is
|
|
read-only or write-only respectively.</p>
|
|
|
|
|
|
<h2 id="mapping-rules">Type mapping rules</h2>
|
|
|
|
<p>An MXBean is a kind of Open MBean, as defined by the {@link
|
|
javax.management.openmbean} package. This means that the types of
|
|
attributes, operation parameters, and operation return values must
|
|
all be describable using <em>Open Types</em>, that is the four
|
|
standard subclasses of {@link javax.management.openmbean.OpenType}.
|
|
MXBeans achieve this by mapping Java types into Open Types.</p>
|
|
|
|
<p>For every Java type <em>J</em>, the MXBean mapping is described
|
|
by the following information:</p>
|
|
|
|
<ul>
|
|
<li>The corresponding Open Type, <em>opentype(J)</em>. This is
|
|
an instance of a subclass of {@link
|
|
javax.management.openmbean.OpenType}.</li>
|
|
<li>The <em>mapped</em> Java type, <em>opendata(J)</em>, which is
|
|
always the same for any given <em>opentype(J)</em>. This is a Java
|
|
class.</li>
|
|
<li>How a value is converted from type <em>J</em> to type
|
|
<em>opendata(J)</em>.</li>
|
|
<li>How a value is converted from type <em>opendata(J)</em> to
|
|
type <em>J</em>, if it can be.</li>
|
|
</ul>
|
|
|
|
<p>For example, for the Java type {@code List<String>}:</p>
|
|
|
|
<ul>
|
|
<li>The Open Type, <em>opentype(</em>{@code
|
|
List<String>}<em>)</em>, is {@link ArrayType}<code>(1, </code>{@link
|
|
SimpleType#STRING}<code>)</code>, representing a 1-dimensional
|
|
array of <code>String</code>s.</li>
|
|
<li>The mapped Java type, <em>opendata(</em>{@code
|
|
List<String>}<em>)</em>, is {@code String[]}.</li>
|
|
<li>A {@code List<String>} can be converted to a {@code String[]}
|
|
using {@link List#toArray(Object[]) List.toArray(new
|
|
String[0])}.</li>
|
|
<li>A {@code String[]} can be converted to a {@code List<String>}
|
|
using {@link Arrays#asList Arrays.asList}.</li>
|
|
</ul>
|
|
|
|
<p>If no mapping rules exist to derive <em>opentype(J)</em> from
|
|
<em>J</em>, then <em>J</em> cannot be the type of a method
|
|
parameter or return value in an MXBean interface.</p>
|
|
|
|
<p id="reconstructible-def">If there is a way to convert
|
|
<em>opendata(J)</em> back to <em>J</em> then we say that <em>J</em> is
|
|
<em>reconstructible</em>. All method parameters in an MXBean
|
|
interface must be reconstructible, because when the MXBean
|
|
framework is invoking a method it will need to convert those
|
|
parameters from <em>opendata(J)</em> to <em>J</em>. In a proxy
|
|
generated by {@link JMX#newMXBeanProxy(MBeanServerConnection,
|
|
ObjectName, Class) JMX.newMXBeanProxy}, it is the return values
|
|
of the methods in the MXBean interface that must be
|
|
reconstructible.</p>
|
|
|
|
<p>Null values are allowed for all Java types and Open Types,
|
|
except primitive Java types where they are not possible. When
|
|
converting from type <em>J</em> to type <em>opendata(J)</em> or
|
|
from type <em>opendata(J)</em> to type <em>J</em>, a null value is
|
|
mapped to a null value.</p>
|
|
|
|
<p>The following table summarizes the type mapping rules.</p>
|
|
|
|
<table border="1" cellpadding="5" summary="Type Mapping Rules">
|
|
<tr>
|
|
<th>Java type <em>J</em></th>
|
|
<th><em>opentype(J)</em></th>
|
|
<th><em>opendata(J)</em></th>
|
|
</tr>
|
|
<tbody valign="top">
|
|
<tr>
|
|
<td>{@code int}, {@code boolean}, etc<br>
|
|
(the 8 primitive Java types)</td>
|
|
<td>{@code SimpleType.INTEGER},<br>
|
|
{@code SimpleType.BOOLEAN}, etc</td>
|
|
<td>{@code Integer}, {@code Boolean}, etc<br>
|
|
(the corresponding boxed types)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>{@code Integer}, {@code ObjectName}, etc<br>
|
|
(the types covered by {@link SimpleType})</td>
|
|
<td>the corresponding {@code SimpleType}</td>
|
|
<td><em>J</em>, the same type</td>
|
|
</tr>
|
|
<tr>
|
|
<td>{@code int[]} etc<br>
|
|
(a one-dimensional array with<br>
|
|
primitive element type)</td>
|
|
<td>{@code ArrayType.getPrimitiveArrayType(int[].class)} etc</td>
|
|
<td><em>J</em>, the same type</td>
|
|
<tr>
|
|
<td><em>E</em>{@code []}<br>
|
|
(an array with non-primitive element type <em>E</em>;
|
|
this includes {@code int[][]}, where <em>E</em> is {@code int[]})</td>
|
|
<td>{@code ArrayType.getArrayType(}<em>opentype(E)</em>{@code )}</td>
|
|
<td><em>opendata(E)</em>{@code []}</td>
|
|
</tr>
|
|
<tr>
|
|
<td>{@code List<}<em>E</em>{@code >}<br>
|
|
{@code Set<}<em>E</em>{@code >}<br>
|
|
{@code SortedSet<}<em>E</em>{@code >} (see below)</td>
|
|
<td>same as for <em>E</em>{@code []}</td>
|
|
<td>same as for <em>E</em>{@code []}</td>
|
|
</tr>
|
|
<tr>
|
|
<td>An enumeration <em>E</em><br>
|
|
(declared in Java as {@code enum }<em>E</em>
|
|
{@code {...}})</td>
|
|
<td>{@code SimpleType.STRING}</td>
|
|
<td>{@code String}</td>
|
|
</tr>
|
|
<tr>
|
|
<td>{@code Map<}<em>K</em>,<em>V</em>{@code >}<br>
|
|
{@code SortedMap<}<em>K</em>,<em>V</em>{@code >}</td>
|
|
<td>{@link TabularType}<br>
|
|
(see below)</td>
|
|
<td>{@link TabularData}<br>
|
|
(see below)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>An MXBean interface</td>
|
|
<td>{@code SimpleType.OBJECTNAME}<br>
|
|
(see below)</td>
|
|
<td>{@link ObjectName}<br>
|
|
(see below)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Any other type</td>
|
|
<td>{@link CompositeType},
|
|
if possible<br>
|
|
(see below)</td>
|
|
<td>{@link CompositeData}</td>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>The following sections give further details of these rules.</p>
|
|
|
|
|
|
<h3>Mappings for primitive types</h3>
|
|
|
|
<p>The 8 primitive Java types
|
|
({@code boolean}, {@code byte}, {@code short}, {@code int}, {@code
|
|
long}, {@code float}, {@code double}, {@code char}) are mapped to the
|
|
corresponding boxed types from {@code java.lang}, namely {@code
|
|
Boolean}, {@code Byte}, etc. The Open Type is the corresponding
|
|
{@code SimpleType}. Thus, <em>opentype(</em>{@code
|
|
long}<em>)</em> is {@code SimpleType.LONG}, and
|
|
<em>opendata(</em>{@code long}<em>)</em> is {@code
|
|
java.lang.Long}.</p>
|
|
|
|
<p>An array of primitive type such as {@code long[]} can be represented
|
|
directly as an Open Type. Thus, <em>openType(</em>{@code
|
|
long[]}<em>)</em> is {@code
|
|
ArrayType.getPrimitiveArrayType(long[].class)}, and
|
|
<em>opendata(</em>{@code long[]}<em>)</em> is {@code
|
|
long[]}.</p>
|
|
|
|
<p>In practice, the difference between a plain {@code int} and {@code
|
|
Integer}, etc, does not show up because operations in the JMX API
|
|
are always on Java objects, not primitives. However, the
|
|
difference <em>does</em> show up with arrays.</p>
|
|
|
|
|
|
<h3>Mappings for collections ({@code List<}<em>E</em>{@code >} etc)</h3>
|
|
|
|
<p>A {@code List<}<em>E</em>{@code >} or {@code
|
|
Set<}<em>E</em>{@code >}, such as {@code List<String>} or {@code
|
|
Set<ObjectName>}, is mapped in the same way as an array of the
|
|
same element type, such as {@code String[]} or {@code
|
|
ObjectName[]}.</p>
|
|
|
|
<p>A {@code SortedSet<}<em>E</em>{@code >} is also mapped in the
|
|
same way as an <em>E</em>{@code []}, but it is only convertible if
|
|
<em>E</em> is a class or interface that implements {@link
|
|
java.lang.Comparable}. Thus, a {@code SortedSet<String>} or
|
|
{@code SortedSet<Integer>} is convertible, but a {@code
|
|
SortedSet<int[]>} or {@code SortedSet<List<String>>} is not. The
|
|
conversion of a {@code SortedSet} instance will fail with an
|
|
{@code IllegalArgumentException} if it has a
|
|
non-null {@link java.util.SortedSet#comparator()
|
|
comparator()}.</p>
|
|
|
|
<p>A {@code List<}<em>E</em>{@code >} is reconstructed as a
|
|
{@code java.util.ArrayList<}<em>E</em>{@code >};
|
|
a {@code Set<}<em>E</em>{@code >} as a
|
|
{@code java.util.HashSet<}<em>E</em>{@code >};
|
|
a {@code SortedSet<}<em>E</em>{@code >} as a
|
|
{@code java.util.TreeSet<}<em>E</em>{@code >}.</p>
|
|
|
|
|
|
<h3>Mappings for maps ({@code Map<}<em>K</em>,<em>V</em>{@code >} etc)</h3>
|
|
|
|
<p>A {@code Map<}<em>K</em>,<em>V</em>{@code >} or {@code
|
|
SortedMap<}<em>K</em>,<em>V</em>{@code >}, for example {@code
|
|
Map<String,ObjectName>}, has Open Type {@link TabularType} and is mapped
|
|
to a {@link TabularData}.
|
|
The {@code TabularType} has two items called {@code key} and
|
|
{@code value}. The Open Type of {@code key} is
|
|
<em>opentype(K)</em>, and the Open Type of {@code value} is
|
|
<em>opentype(V)</em>. The index of the {@code TabularType} is the
|
|
single item {@code key}.</p>
|
|
|
|
<p>For example, the {@code TabularType} for a {@code
|
|
Map<String,ObjectName>} might be constructed with code like
|
|
this:</p>
|
|
|
|
<pre>
|
|
String typeName =
|
|
"java.util.Map<java.lang.String, javax.management.ObjectName>";
|
|
String[] keyValue =
|
|
new String[] {"key", "value"};
|
|
OpenType[] openTypes =
|
|
new OpenType[] {SimpleType.STRING, SimpleType.OBJECTNAME};
|
|
CompositeType rowType =
|
|
new CompositeType(typeName, typeName, keyValue, keyValue, openTypes);
|
|
TabularType tabularType =
|
|
new TabularType(typeName, typeName, rowType, new String[] {"key"});
|
|
</pre>
|
|
|
|
<p>The {@code typeName} here is determined by the <a href="#type-names">
|
|
type name rules</a> detailed below.
|
|
|
|
<p>A {@code SortedMap<}<em>K</em>,<em>V</em>{@code >} is mapped in the
|
|
same way, but it is only convertible if
|
|
<em>K</em> is a class or interface that implements {@link
|
|
java.lang.Comparable}. Thus, a {@code SortedMap<String,int[]>}
|
|
is convertible, but a
|
|
{@code SortedMap<int[],String>} is not. The conversion of a
|
|
{@code SortedMap} instance will fail with an {@code
|
|
IllegalArgumentException} if it has a non-null {@link
|
|
java.util.SortedMap#comparator() comparator()}.</p>
|
|
|
|
<p>A {@code Map<}<em>K</em>,<em>V</em>{@code >} is reconstructed as
|
|
a {@code java.util.HashMap<}<em>K</em>,<em>V</em>{@code >};
|
|
a {@code SortedMap<}<em>K</em>,<em>V</em>{@code >} as
|
|
a {@code java.util.TreeMap<}<em>K</em>,<em>V</em>{@code >}.</p>
|
|
|
|
<p>{@code TabularData} is an interface. The concrete class that is
|
|
used to represent a {@code Map<}<em>K</em>,<em>V</em>{@code >} as
|
|
Open Data is {@link TabularDataSupport},
|
|
or another class implementing {@code
|
|
TabularData} that serializes as {@code TabularDataSupport}.</p>
|
|
|
|
|
|
<h3 id="mxbean-map">Mappings for MXBean interfaces</h3>
|
|
|
|
<p>An MXBean interface, or a type referenced within an MXBean
|
|
interface, can reference another MXBean interface, <em>J</em>.
|
|
Then <em>opentype(J)</em> is {@code SimpleType.OBJECTNAME} and
|
|
<em>opendata(J)</em> is {@code ObjectName}.</p>
|
|
|
|
<p>For example, suppose you have two MXBean interfaces like this:</p>
|
|
|
|
<pre>
|
|
public interface ProductMXBean {
|
|
public ModuleMXBean[] getModules();
|
|
}
|
|
|
|
public interface ModuleMXBean {
|
|
public ProductMXBean getProduct();
|
|
}
|
|
</pre>
|
|
|
|
<p>The object implementing the {@code ModuleMXBean} interface
|
|
returns from its {@code getProduct} method an object
|
|
implementing the {@code ProductMXBean} interface. The
|
|
{@code ModuleMXBean} object and the returned {@code
|
|
ProductMXBean} objects must both be registered as MXBeans in the
|
|
same MBean Server.</p>
|
|
|
|
<p>The method {@code ModuleMXBean.getProduct()} defines an
|
|
attribute called {@code Product}. The Open Type for this
|
|
attribute is {@code SimpleType.OBJECTNAME}, and the corresponding
|
|
{@code ObjectName} value will be the name under which the
|
|
referenced {@code ProductMXBean} is registered in the MBean
|
|
Server.</p>
|
|
|
|
<p>If you make an MXBean proxy for a {@code ModuleMXBean} and
|
|
call its {@code getProduct()} method, the proxy will map the
|
|
{@code ObjectName} back into a {@code ProductMXBean} by making
|
|
another MXBean proxy. More formally, when a proxy made with
|
|
{@link JMX#newMXBeanProxy(MBeanServerConnection, ObjectName,
|
|
Class)
|
|
JMX.newMXBeanProxy(mbeanServerConnection, objectNameX,
|
|
interfaceX)} needs to map {@code objectNameY} back into {@code
|
|
interfaceY}, another MXBean interface, it does so with {@code
|
|
JMX.newMXBeanProxy(mbeanServerConnection, objectNameY,
|
|
interfaceY)}. The implementation may return a proxy that was
|
|
previously created by a call to {@code JMX.newMXBeanProxy}
|
|
with the same parameters, or it may create a new proxy.</p>
|
|
|
|
<p>The reverse mapping is illustrated by the following change to the
|
|
{@code ModuleMXBean} interface:</p>
|
|
|
|
<pre>
|
|
public interface ModuleMXBean {
|
|
public ProductMXBean getProduct();
|
|
public void setProduct(ProductMXBean c);
|
|
}
|
|
</pre>
|
|
|
|
<p>The presence of the {@code setProduct} method now means that the
|
|
{@code Product} attribute is read/write. As before, the value
|
|
of this attribute is an {@code ObjectName}. When the attribute is
|
|
set, the {@code ObjectName} must be converted into the
|
|
{@code ProductMXBean} object that the {@code setProduct} method
|
|
expects. This object will be an MXBean proxy for the given
|
|
{@code ObjectName} in the same MBean Server.</p>
|
|
|
|
<p>If you make an MXBean proxy for a {@code ModuleMXBean} and
|
|
call its {@code setProduct} method, the proxy will map its
|
|
{@code ProductMXBean} argument back into an {@code ObjectName}.
|
|
This will only work if the argument is in fact another proxy,
|
|
for a {@code ProductMXBean} in the same {@code
|
|
MBeanServerConnection}. The proxy can have been returned from
|
|
another proxy (like {@code ModuleMXBean.getProduct()} which
|
|
returns a proxy for a {@code ProductMXBean}); or it can have
|
|
been created by {@link
|
|
JMX#newMXBeanProxy(MBeanServerConnection, ObjectName, Class)
|
|
JMX.newMXBeanProxy}; or it can have been created using {@link
|
|
java.lang.reflect.Proxy Proxy} with an invocation handler that
|
|
is {@link MBeanServerInvocationHandler} or a subclass.</p>
|
|
|
|
<p>If the same MXBean were registered under two different
|
|
{@code ObjectName}s, a reference to that MXBean from another
|
|
MXBean would be ambiguous. Therefore, if an MXBean object is
|
|
already registered in an MBean Server and an attempt is made to
|
|
register it in the same MBean Server under another name, the
|
|
result is an {@link InstanceAlreadyExistsException}. Registering
|
|
the same MBean object under more than one name is discouraged in
|
|
general, notably because it does not work well for MBeans that are
|
|
{@link NotificationBroadcaster}s.</p>
|
|
|
|
<h3 id="composite-map">Mappings for other types</h3>
|
|
|
|
<p>Given a Java class or interface <em>J</em> that does not match the other
|
|
rules in the table above, the MXBean framework will attempt to map
|
|
it to a {@link CompositeType} as follows. The type name of this
|
|
{@code CompositeType} is determined by the <a href="#type-names">
|
|
type name rules</a> below.</p>
|
|
|
|
<p>The class is examined for getters using the conventions
|
|
<a href="#naming-conv">above</a>. (Getters must be public
|
|
instance methods.) If there are no getters, or if
|
|
any getter has a type that is not convertible, then <em>J</em> is
|
|
not convertible.</p>
|
|
|
|
<p>If there is at least one getter and every getter has a
|
|
convertible type, then <em>opentype(J)</em> is a {@code
|
|
CompositeType} with one item for every getter. If the getter is
|
|
|
|
<blockquote>
|
|
<code><em>T</em> get<em>Name</em>()</code>
|
|
</blockquote>
|
|
|
|
then the item in the {@code CompositeType} is called {@code name}
|
|
and has type <em>opentype(T)</em>. For example, if the item is
|
|
|
|
<blockquote>
|
|
<code>String getOwner()</code>
|
|
</blockquote>
|
|
|
|
then the item is called {@code owner} and has Open Type {@code
|
|
SimpleType.STRING}. If the getter is
|
|
|
|
<blockquote>
|
|
<code>boolean is<em>Name</em>()</code>
|
|
</blockquote>
|
|
|
|
then the item in the {@code CompositeType} is called {@code name}
|
|
and has type {@code SimpleType.BOOLEAN}.
|
|
|
|
<p>Notice that the first character (or code point) is converted to
|
|
lower case. This follows the Java Beans convention, which for
|
|
historical reasons is different from the Standard MBean
|
|
convention. In a Standard MBean or MXBean interface, a method
|
|
{@code getOwner} defines an attribute called {@code Owner}, while
|
|
in a Java Bean or mapped {@code CompositeType}, a method {@code
|
|
getOwner} defines a property or item called {@code owner}.</p>
|
|
|
|
<p>If two methods produce the same item name (for example, {@code
|
|
getOwner} and {@code isOwner}, or {@code getOwner} and {@code
|
|
getowner}) then the type is not convertible.</p>
|
|
|
|
<p>When the Open Type is {@code CompositeType}, the corresponding
|
|
mapped Java type (<em>opendata(J)</em>) is {@link
|
|
CompositeData}. The mapping from an instance of <em>J</em> to a
|
|
{@code CompositeData} corresponding to the {@code CompositeType}
|
|
just described is done as follows. First, if <em>J</em>
|
|
implements the interface {@link CompositeDataView}, then that
|
|
interface's {@link CompositeDataView#toCompositeData
|
|
toCompositeData} method is called to do the conversion.
|
|
Otherwise, the {@code CompositeData} is constructed by calling
|
|
the getter for each item and converting it to the corresponding
|
|
Open Data type. Thus, a getter such as</p>
|
|
|
|
<blockquote>
|
|
{@code List<String> getNames()}
|
|
</blockquote>
|
|
|
|
<p>will have been mapped to an item with name "{@code names}" and
|
|
Open Type {@code ArrayType(1, SimpleType.STRING)}. The conversion
|
|
to {@code CompositeData} will call {@code getNames()} and convert
|
|
the resultant {@code List<String>} into a {@code String[]} for the
|
|
item "{@code names}".</p>
|
|
|
|
<p>{@code CompositeData} is an interface. The concrete class that is
|
|
used to represent a type as Open Data is {@link
|
|
CompositeDataSupport}, or another class implementing {@code
|
|
CompositeData} that serializes as {@code
|
|
CompositeDataSupport}.</p>
|
|
|
|
|
|
<h4>Reconstructing an instance of Java type <em>J</em> from
|
|
a {@code CompositeData}</h4>
|
|
|
|
<p>If <em>opendata(J)</em> is {@code CompositeData} for a Java type
|
|
<em>J</em>, then either an instance of <em>J</em> can be
|
|
reconstructed from a {@code CompositeData}, or <em>J</em> is not
|
|
reconstructible. If any item in the {@code CompositeData} is not
|
|
reconstructible, then <em>J</em> is not reconstructible either.</p>
|
|
|
|
<p>For any given <em>J</em>, the following rules are consulted to
|
|
determine how to reconstruct instances of <em>J</em> from
|
|
{@code CompositeData}. The first applicable rule in the list is
|
|
the one that will be used.</p>
|
|
|
|
<ol>
|
|
|
|
<li><p>If <em>J</em> has a method<br>
|
|
{@code public static }<em>J </em>{@code from(CompositeData cd)}<br>
|
|
then that method is called to reconstruct an instance of
|
|
<em>J</em>.</p></li>
|
|
|
|
<li><p>Otherwise, if <em>J</em> has at least one public
|
|
constructor with a {@link java.beans.ConstructorProperties
|
|
ConstructorProperties} annotation, then one
|
|
of those constructors (not necessarily always the same one)
|
|
will be called to reconstruct an instance of <em>J</em>.
|
|
Every such annotation must list as many strings as the
|
|
constructor has parameters; each string must name a property
|
|
corresponding to a getter of <em>J</em>; and the type of this
|
|
getter must be the same as the corresponding constructor
|
|
parameter. It is not an error for there to be getters that
|
|
are not mentioned in the {@code ConstructorProperties} annotation
|
|
(these may correspond to information that is not needed to
|
|
reconstruct the object).</p>
|
|
|
|
<p>An instance of <em>J</em> is reconstructed by calling a
|
|
constructor with the appropriate reconstructed items from the
|
|
{@code CompositeData}. The constructor to be called will be
|
|
determined at runtime based on the items actually present in
|
|
the {@code CompositeData}, given that this {@code
|
|
CompositeData} might come from an earlier version of
|
|
<em>J</em> where not all the items were present. A
|
|
constructor is <em>applicable</em> if all the properties named
|
|
in its {@code ConstructorProperties} annotation are present as items
|
|
in the {@code CompositeData}. If no constructor is
|
|
applicable, then the attempt to reconstruct <em>J</em> fails.</p>
|
|
|
|
<p>For any possible combination of properties, it must be the
|
|
case that either (a) there are no applicable constructors, or
|
|
(b) there is exactly one applicable constructor, or (c) one of
|
|
the applicable constructors names a proper superset of the
|
|
properties named by each other applicable constructor. (In
|
|
other words, there should never be ambiguity over which
|
|
constructor to choose.) If this condition is not true, then
|
|
<em>J</em> is not reconstructible.</p></li>
|
|
|
|
<li><p>Otherwise, if <em>J</em> has a public no-arg constructor, and
|
|
for every getter in <em>J</em> with type
|
|
<em>T</em> and name <em>N</em> there is a corresponding setter
|
|
with the same name and type, then an instance of <em>J</em> is
|
|
constructed with the no-arg constructor and the setters are
|
|
called with the reconstructed items from the {@code CompositeData}
|
|
to restore the values. For example, if there is a method<br>
|
|
{@code public List<String> getNames()}<br>
|
|
then there must also be a method<br>
|
|
{@code public void setNames(List<String> names)}<br>
|
|
for this rule to apply.</p>
|
|
|
|
<p>If the {@code CompositeData} came from an earlier version of
|
|
<em>J</em>, some items might not be present. In this case,
|
|
the corresponding setters will not be called.</p></li>
|
|
|
|
<li><p>Otherwise, if <em>J</em> is an interface that has no methods
|
|
other than getters, an instance of <em>J</em> is constructed
|
|
using a {@link java.lang.reflect.Proxy} with a {@link
|
|
CompositeDataInvocationHandler} backed by the {@code
|
|
CompositeData} being converted.</p></li>
|
|
|
|
<li><p>Otherwise, <em>J</em> is not reconstructible.</p></li>
|
|
</ol>
|
|
|
|
<p>Rule 2 is not applicable to subset Profiles of Java SE that do not
|
|
include the {@code java.beans} package. When targeting a runtime that does
|
|
not include the {@code java.beans} package, and where there is a mismatch
|
|
between the compile-time and runtime environment whereby <em>J</em> is
|
|
compiled with a public constructor and the {@code ConstructorProperties}
|
|
annotation, then <em>J</em> is not reconstructible unless another rule
|
|
applies.</p>
|
|
|
|
<p>Here are examples showing different ways to code a type {@code
|
|
NamedNumber} that consists of an {@code int} and a {@code
|
|
String}. In each case, the {@code CompositeType} looks like this:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
{@link CompositeType}(
|
|
"NamedNumber", // typeName
|
|
"NamedNumber", // description
|
|
new String[] {"number", "name"}, // itemNames
|
|
new String[] {"number", "name"}, // itemDescriptions
|
|
new OpenType[] {SimpleType.INTEGER,
|
|
SimpleType.STRING} // itemTypes
|
|
);
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<ol>
|
|
<li>Static {@code from} method:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
public class NamedNumber {
|
|
public int getNumber() {return number;}
|
|
public String getName() {return name;}
|
|
private NamedNumber(int number, String name) {
|
|
this.number = number;
|
|
this.name = name;
|
|
}
|
|
<b>public static NamedNumber from(CompositeData cd)</b> {
|
|
return new NamedNumber((Integer) cd.get("number"),
|
|
(String) cd.get("name"));
|
|
}
|
|
private final int number;
|
|
private final String name;
|
|
}
|
|
</pre>
|
|
</blockquote>
|
|
</li>
|
|
|
|
<li>Public constructor with <code>@ConstructorProperties</code> annotation:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
public class NamedNumber {
|
|
public int getNumber() {return number;}
|
|
public String getName() {return name;}
|
|
<b>@ConstructorProperties({"number", "name"})
|
|
public NamedNumber(int number, String name)</b> {
|
|
this.number = number;
|
|
this.name = name;
|
|
}
|
|
private final int number;
|
|
private final String name;
|
|
}
|
|
</pre>
|
|
</blockquote>
|
|
</li>
|
|
|
|
<li>Setter for every getter:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
public class NamedNumber {
|
|
public int getNumber() {return number;}
|
|
public void <b>setNumber</b>(int number) {this.number = number;}
|
|
public String getName() {return name;}
|
|
public void <b>setName</b>(String name) {this.name = name;}
|
|
<b>public NamedNumber()</b> {}
|
|
private int number;
|
|
private String name;
|
|
}
|
|
</pre>
|
|
</blockquote>
|
|
</li>
|
|
|
|
<li>Interface with only getters:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
public interface NamedNumber {
|
|
public int getNumber();
|
|
public String getName();
|
|
}
|
|
</pre>
|
|
</blockquote>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>It is usually better for classes that simply represent a
|
|
collection of data to be <em>immutable</em>. An instance of an
|
|
immutable class cannot be changed after it has been constructed.
|
|
Notice that {@code CompositeData} itself is immutable.
|
|
Immutability has many advantages, notably with regard to
|
|
thread-safety and security. So the approach using setters should
|
|
generally be avoided if possible.</p>
|
|
|
|
|
|
<h3>Recursive types</h3>
|
|
|
|
<p>Recursive (self-referential) types cannot be used in MXBean
|
|
interfaces. This is a consequence of the immutability of {@link
|
|
CompositeType}. For example, the following type could not be the
|
|
type of an attribute, because it refers to itself:</p>
|
|
|
|
<pre>
|
|
public interface <b>Node</b> {
|
|
public String getName();
|
|
public int getPriority();
|
|
public <b>Node</b> getNext();
|
|
}
|
|
</pre>
|
|
|
|
<p>It is always possible to rewrite recursive types like this so
|
|
they are no longer recursive. Doing so may require introducing
|
|
new types. For example:</p>
|
|
|
|
<pre>
|
|
public interface <b>NodeList</b> {
|
|
public List<Node> getNodes();
|
|
}
|
|
|
|
public interface Node {
|
|
public String getName();
|
|
public int getPriority();
|
|
}
|
|
</pre>
|
|
|
|
<h3>MBeanInfo contents for an MXBean</h3>
|
|
|
|
<p>An MXBean is a type of Open MBean. However, for compatibility
|
|
reasons, its {@link MBeanInfo} is not an {@link OpenMBeanInfo}.
|
|
In particular, when the type of an attribute, parameter, or
|
|
operation return value is a primitive type such as {@code int},
|
|
or is {@code void} (for a return type), then the attribute,
|
|
parameter, or operation will be represented respectively by an
|
|
{@link MBeanAttributeInfo}, {@link MBeanParameterInfo}, or
|
|
{@link MBeanOperationInfo} whose {@code getType()} or {@code
|
|
getReturnType()} returns the primitive name ("{@code int}" etc).
|
|
This is so even though the mapping rules above specify that the
|
|
<em>opendata</em> mapping is the wrapped type ({@code Integer}
|
|
etc).</p>
|
|
|
|
<p>The array of public constructors returned by {@link
|
|
MBeanInfo#getConstructors()} for an MXBean that is directly
|
|
registered in the MBean Server will contain all of the public
|
|
constructors of that MXBean. If the class of the MXBean is not
|
|
public then its constructors are not considered public either.
|
|
The list returned for an MXBean that is constructed using the
|
|
{@link StandardMBean} class is derived in the same way as for
|
|
Standard MBeans. Regardless of how the MXBean was constructed,
|
|
its constructor parameters are not subject to MXBean mapping
|
|
rules and do not have a corresponding {@code OpenType}.</p>
|
|
|
|
<p>The array of notification types returned by {@link
|
|
MBeanInfo#getNotifications()} for an MXBean that is directly
|
|
registered in the MBean Server will be empty if the MXBean does
|
|
not implement the {@link NotificationBroadcaster} interface.
|
|
Otherwise, it will be the result of calling {@link
|
|
NotificationBroadcaster#getNotificationInfo()} at the time the MXBean
|
|
was registered. Even if the result of this method changes
|
|
subsequently, the result of {@code MBeanInfo.getNotifications()}
|
|
will not. The list returned for an MXBean that is constructed
|
|
using the {@link StandardMBean} or {@link StandardEmitterMBean}
|
|
class is derived in the same way as for Standard MBeans.</p>
|
|
|
|
<p>The {@link Descriptor} for all of the
|
|
{@code MBeanAttributeInfo}, {@code MBeanParameterInfo}, and
|
|
{@code MBeanOperationInfo} objects contained in the {@code MBeanInfo}
|
|
will have a field {@code openType} whose value is the {@link OpenType}
|
|
specified by the mapping rules above. So even when {@code getType()}
|
|
is "{@code int}", {@code getDescriptor().getField("openType")} will
|
|
be {@link SimpleType#INTEGER}.</p>
|
|
|
|
<p>The {@code Descriptor} for each of these objects will also have a
|
|
field {@code originalType} that is a string representing the Java type
|
|
that appeared in the MXBean interface. The format of this string
|
|
is described in the section <a href="#type-names">Type Names</a>
|
|
below.</p>
|
|
|
|
<p>The {@code Descriptor} for the {@code MBeanInfo} will have a field
|
|
{@code mxbean} whose value is the string "{@code true}".</p>
|
|
|
|
|
|
<h3 id="type-names">Type Names</h3>
|
|
|
|
<p>Sometimes the unmapped type <em>T</em> of a method parameter or
|
|
return value in an MXBean must be represented as a string. If
|
|
<em>T</em> is a non-generic type, this string is the value
|
|
returned by {@link Class#getName()}. Otherwise it is the value of
|
|
<em>genericstring(T)</em>, defined as follows:
|
|
|
|
<ul>
|
|
|
|
<li>If <em>T</em> is a non-generic non-array type,
|
|
<em>genericstring(T)</em> is the value returned by {@link
|
|
Class#getName()}, for example {@code "int"} or {@code
|
|
"java.lang.String"}.
|
|
|
|
<li>If <em>T</em> is an array <em>E[]</em>,
|
|
<em>genericstring(T)</em> is <em>genericstring(E)</em> followed
|
|
by {@code "[]"}. For example, <em>genericstring({@code int[]})</em>
|
|
is {@code "int[]"}, and <em>genericstring({@code
|
|
List<String>[][]})</em> is {@code
|
|
"java.util.List<java.lang.String>[][]"}.
|
|
|
|
<li>Otherwise, <em>T</em> is a parameterized type such as {@code
|
|
List<String>} and <em>genericstring(T)</em> consists of the
|
|
following: the fully-qualified name of the parameterized type as
|
|
returned by {@code Class.getName()}; a left angle bracket ({@code
|
|
"<"}); <em>genericstring(A)</em> where <em>A</em> is the first
|
|
type parameter; if there is a second type parameter <em>B</em>
|
|
then {@code ", "} (a comma and a single space) followed by
|
|
<em>genericstring(B)</em>; a right angle bracket ({@code ">"}).
|
|
|
|
</ul>
|
|
|
|
<p>Note that if a method returns {@code int[]}, this will be
|
|
represented by the string {@code "[I"} returned by {@code
|
|
Class.getName()}, but if a method returns {@code List<int[]>},
|
|
this will be represented by the string {@code
|
|
"java.util.List<int[]>"}.
|
|
|
|
<h3>Exceptions</h3>
|
|
|
|
<p>A problem with mapping <em>from</em> Java types <em>to</em>
|
|
Open types is signaled with an {@link OpenDataException}. This
|
|
can happen when an MXBean interface is being analyzed, for
|
|
example if it references a type like {@link java.util.Random
|
|
java.util.Random} that has no getters. Or it can happen when an
|
|
instance is being converted (a return value from a method in an
|
|
MXBean or a parameter to a method in an MXBean proxy), for
|
|
example when converting from {@code SortedSet<String>} to {@code
|
|
String[]} if the {@code SortedSet} has a non-null {@code
|
|
Comparator}.</p>
|
|
|
|
<p>A problem with mapping <em>to</em> Java types <em>from</em>
|
|
Open types is signaled with an {@link InvalidObjectException}.
|
|
This can happen when an MXBean interface is being analyzed, for
|
|
example if it references a type that is not
|
|
<em>reconstructible</em> according to the rules above, in a
|
|
context where a reconstructible type is required. Or it can
|
|
happen when an instance is being converted (a parameter to a
|
|
method in an MXBean or a return value from a method in an MXBean
|
|
proxy), for example from a String to an Enum if there is no Enum
|
|
constant with that name.</p>
|
|
|
|
<p>Depending on the context, the {@code OpenDataException} or
|
|
{@code InvalidObjectException} may be wrapped in another
|
|
exception such as {@link RuntimeMBeanException} or {@link
|
|
UndeclaredThrowableException}. For every thrown exception,
|
|
the condition <em>C</em> will be true: "<em>e</em> is {@code
|
|
OpenDataException} or {@code InvalidObjectException} (as
|
|
appropriate), or <em>C</em> is true of <em>e</em>.{@link
|
|
Throwable#getCause() getCause()}".</p>
|
|
|
|
@since 1.6
|
|
*/
|
|
|
|
@Documented
|
|
@Retention(RetentionPolicy.RUNTIME)
|
|
@Target(ElementType.TYPE)
|
|
public @interface MXBean {
|
|
/**
|
|
True if the annotated interface is an MXBean interface.
|
|
@return true if the annotated interface is an MXBean interface.
|
|
*/
|
|
boolean value() default true;
|
|
}
|