1 /*

     2  * Copyright 2007-2008 Sun Microsystems, Inc.  All Rights Reserved.

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

    27 

    28 import com.sun.jmx.mbeanserver.DefaultMXBeanMappingFactory;

    29 import java.lang.reflect.Type;

    30 

    31 /**

    32  * <p>Defines how types are mapped for a given MXBean or set of MXBeans.

    33  * An {@code MXBeanMappingFactory} can be specified either through the

    34  * {@link MXBeanMappingFactoryClass} annotation, or through the

    35  * {@link javax.management.JMX.MBeanOptions JMX.MBeanOptions} argument to a

    36  * {@link javax.management.StandardMBean StandardMBean} constructor or MXBean

    37  * proxy.</p>

    38  *

    39  * <p>An {@code MXBeanMappingFactory} must return an {@code MXBeanMapping}

    40  * for any Java type that appears in the MXBeans that the factory is being

    41  * used for.  Usually it does that by handling any custom types, and

    42  * forwarding everything else to the {@linkplain #DEFAULT default mapping

    43  * factory}.</p>

    44  *

    45  * <p>Consider the {@code MyLinkedList} example from the {@link MXBeanMapping}

    46  * documentation.  If we are unable to change the {@code MyLinkedList} class

    47  * to add an {@link MXBeanMappingClass} annotation, we could achieve the same

    48  * effect by defining {@code MyLinkedListMappingFactory} as follows:</p>

    49  *

    50  * <pre>

    51  * public class MyLinkedListMappingFactory extends MXBeanMappingFactory {

    52  *     public MyLinkedListMappingFactory() {}

    53  *

    54  *     public MXBeanMapping mappingForType(Type t, MXBeanMappingFactory f)

    55  *     throws OpenDataException {

    56  *         if (t == MyLinkedList.class)

    57  *             return new MyLinkedListMapping(t);

    58  *         else

    59  *             return MXBeanMappingFactory.DEFAULT.mappingForType(t, f);

    60  *     }

    61  * }

    62  * </pre>

    63  *

    64  * <p>The mapping factory handles only the {@code MyLinkedList} class.

    65  * Every other type is forwarded to the default mapping factory.

    66  * This includes types such as {@code MyLinkedList[]} and

    67  * {@code List<MyLinkedList>}; the default mapping factory will recursively

    68  * invoke {@code MyLinkedListMappingFactory} to map the contained

    69  * {@code MyLinkedList} type.</p>

    70  *

    71  * <p>Once we have defined {@code MyLinkedListMappingFactory}, we can use

    72  * it in an MXBean interface like this:</p>

    73  *

    74  * <pre>

    75  * {@literal @MXBeanMappingFactoryClass}(MyLinkedListMappingFactory.class)

    76  * public interface SomethingMXBean {

    77  *     public MyLinkedList getSomething();

    78  * }

    79  * </pre>

    80  *

    81  * <p>Alternatively we can annotate the package that {@code SomethingMXBean}

    82  * appears in, or we can supply the factory to a {@link

    83  * javax.management.StandardMBean StandardMBean} constructor or MXBean

    84  * proxy.</p>

    85  *

    86  * @see <a href="../MXBean.html#custom">MXBean specification, section

    87  * "Custom MXBean type mappings"</a>

    88  */

    89 public abstract class MXBeanMappingFactory {

    90     /**

    91      * <p>Construct an instance of this class.</p>

    92      */

    93     protected MXBeanMappingFactory() {}

    94 

    95     /**

    96      * <p>Mapping factory that applies the default rules for MXBean

    97      * mappings, as described in the <a

    98      * href="../MXBean.html#MXBean-spec">MXBean specification</a>.</p>

    99      */

   100     public static final MXBeanMappingFactory DEFAULT =

   101             new DefaultMXBeanMappingFactory();

   102 

   103     /**

   104      * <p>Determine the appropriate MXBeanMappingFactory to use for the given

   105      * MXBean interface, based on its annotations.  If the interface has an

   106      * {@link MXBeanMappingFactoryClass @MXBeanMappingFactoryClass} annotation,

   107      * that is used to determine the MXBeanMappingFactory.  Otherwise, if the

   108      * package containing the interface has such an annotation, that is used.

   109      * Otherwise the MXBeanMappingFactory is the {@linkplain #DEFAULT default}

   110      * one.</p>

   111      *

   112      * @param intf the MXBean interface for which to determine the

   113      * MXBeanMappingFactory.

   114      *

   115      * @return the MXBeanMappingFactory for the given MXBean interface.

   116      *

   117      * @throws IllegalArgumentException if {@code intf} is null, or if an

   118      * exception occurs while trying constructing an MXBeanMappingFactory

   119      * based on an annotation.  In the second case, the exception will appear

   120      * in the {@linkplain Throwable#getCause() cause chain} of the

   121      * {@code IllegalArgumentException}.

   122      */

   123     public static MXBeanMappingFactory forInterface(Class<?> intf) {

   124         if (intf == null)

   125             throw new IllegalArgumentException("Null interface");

   126         MXBeanMappingFactoryClass annot =

   127                 intf.getAnnotation(MXBeanMappingFactoryClass.class);

   128         if (annot == null) {

   129             Package p = intf.getPackage();

   130             if (p != null)

   131                 annot = p.getAnnotation(MXBeanMappingFactoryClass.class);

   132         }

   133         if (annot == null)

   134             return MXBeanMappingFactory.DEFAULT;

   135         Class<? extends MXBeanMappingFactory> factoryClass = annot.value();

   136         try {

   137             return annot.value().newInstance();

   138         } catch (Exception e) {

   139             throw new IllegalArgumentException(

   140                     "Could not instantiate MXBeanMappingFactory " +

   141                     factoryClass.getName() +

   142                     " from @MXBeanMappingFactoryClass", e);

   143         }

   144     }

   145 

   146     /**

   147      * <p>Return the mapping for the given Java type.  Typically, a

   148      * mapping factory will return mappings for types it handles, and

   149      * forward other types to another mapping factory, most often

   150      * the {@linkplain #DEFAULT default one}.</p>

   151      * @param t the Java type to be mapped.

   152      * @param f the original mapping factory that was consulted to do

   153      * the mapping.  A mapping factory should pass this parameter intact

   154      * if it forwards a type to another mapping factory.  In the example,

   155      * this is how {@code MyLinkedListMappingFactory} works for types

   156      * like {@code MyLinkedList[]} and {@code List<MyLinkedList>}.

   157      * @return the mapping for the given type.

   158      * @throws OpenDataException if this type cannot be mapped.  This

   159      * exception is appropriate if the factory is supposed to handle

   160      * all types of this sort (for example, all linked lists), but

   161      * cannot handle this particular type.

   162      */

   163     public abstract MXBeanMapping mappingForType(Type t, MXBeanMappingFactory f)

   164     throws OpenDataException;

   165 }