/*

 * Copyright 2005-2008 Sun Microsystems, Inc.  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.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.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.Inherited;

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.MXBeanMapping;

import javax.management.openmbean.MXBeanMappingClass;

import javax.management.openmbean.MXBeanMappingFactory;

import javax.management.openmbean.MXBeanMappingFactoryClass;

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 a class or interface explicitly as being an MXBean,

    or as not being an MXBean.  By default, an

    interface is an MXBean interface if its name ends with {@code

    MXBean}, as in {@code SomethingMXBean}.  A class is never an MXBean by

    default.</p>

    <p>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>

    public interface Whatsit3Interface{}

    @MXBean(false)

    public interface MisleadingMXBean {}

    </pre>

    <p>A class can be annotated with {@code @MXBean} to indicate that it

    is an MXBean.  In this case, its methods should have <code>&#64;{@link

    ManagedAttribute}</code> or <code>&#64;{@link ManagedOperation}</code>

    annotations, as described for <code>&#64;{@link MBean}</code>.</p>

    <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">

      <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>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>In addition to the default type mapping rules, you can specify

      custom type mappings, as described <a

      href="#custom">below</a>.</p>

    <p>The following table summarizes the default 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>

          <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>