/* * Copyright (c) 2005, 2008, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation.  Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ 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 Javadocimport 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 its name ends with {@code    MXBean}, as in {@code SomethingMXBean}.  The following interfaces    are MXBean interfaces:</p>     <pre>    public interface WhatsitMXBean {}     &#64;MXBean    public interface Whatsit1Interface {}     &#64;MXBean(true)    public interface Whatsit2Interface {}    </pre>     <p>The following interfaces are not MXBean interfaces:</p>     <pre>    public interface Whatsit3Interface{}     &#64;MXBean(false)    public interface MisleadingMXBean {}    </pre>     <h3 id="MXBean-spec">MXBean specification</a></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">      <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">      <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>&#64;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">      <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">      <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">      <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">      <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">      <tr>        <th>Java type <em>J</em></th>        <th><em>opentype(J)</em></th>        <th><em>opendata(J)</em></th>      </tr>      <tbody cellvalign="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>

Lines 1–500 of 1178. Load more