View Javadoc
1   /*
2    * Copyright (c) 2007, 2008, Oracle and/or its affiliates. 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.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package com.sun.jmx.mbeanserver;
27  
28  import javax.management.openmbean.*;
29  import com.sun.jmx.mbeanserver.MXBeanMapping;
30  import com.sun.jmx.mbeanserver.DefaultMXBeanMappingFactory;
31  import java.lang.reflect.Type;
32  
33  /**
34   * <p>Defines how types are mapped for a given MXBean or set of MXBeans.
35   * An {@code MXBeanMappingFactory} can be specified either through the
36   * {@link MXBeanMappingFactoryClass} annotation, or through the
37   * {@link javax.management.JMX.MBeanOptions JMX.MBeanOptions} argument to a
38   * {@link javax.management.StandardMBean StandardMBean} constructor or MXBean
39   * proxy.</p>
40   *
41   * <p>An {@code MXBeanMappingFactory} must return an {@code MXBeanMapping}
42   * for any Java type that appears in the MXBeans that the factory is being
43   * used for.  Usually it does that by handling any custom types, and
44   * forwarding everything else to the {@linkplain #DEFAULT default mapping
45   * factory}.</p>
46   *
47   * <p>Consider the {@code MyLinkedList} example from the {@link MXBeanMapping}
48   * documentation.  If we are unable to change the {@code MyLinkedList} class
49   * to add an {@link MXBeanMappingClass} annotation, we could achieve the same
50   * effect by defining {@code MyLinkedListMappingFactory} as follows:</p>
51   *
52   * <pre>
53   * public class MyLinkedListMappingFactory extends MXBeanMappingFactory {
54   *     public MyLinkedListMappingFactory() {}
55   *
56   *     public MXBeanMapping mappingForType(Type t, MXBeanMappingFactory f)
57   *     throws OpenDataException {
58   *         if (t == MyLinkedList.class)
59   *             return new MyLinkedListMapping(t);
60   *         else
61   *             return MXBeanMappingFactory.DEFAULT.mappingForType(t, f);
62   *     }
63   * }
64   * </pre>
65   *
66   * <p>The mapping factory handles only the {@code MyLinkedList} class.
67   * Every other type is forwarded to the default mapping factory.
68   * This includes types such as {@code MyLinkedList[]} and
69   * {@code List<MyLinkedList>}; the default mapping factory will recursively
70   * invoke {@code MyLinkedListMappingFactory} to map the contained
71   * {@code MyLinkedList} type.</p>
72   *
73   * <p>Once we have defined {@code MyLinkedListMappingFactory}, we can use
74   * it in an MXBean interface like this:</p>
75   *
76   * <pre>
77   * {@literal @MXBeanMappingFactoryClass}(MyLinkedListMappingFactory.class)
78   * public interface SomethingMXBean {
79   *     public MyLinkedList getSomething();
80   * }
81   * </pre>
82   *
83   * <p>Alternatively we can annotate the package that {@code SomethingMXBean}
84   * appears in, or we can supply the factory to a {@link
85   * javax.management.StandardMBean StandardMBean} constructor or MXBean
86   * proxy.</p>
87   *
88   * @see <a href="../MXBean.html#custom">MXBean specification, section
89   * "Custom MXBean type mappings"</a>
90   */
91  public abstract class MXBeanMappingFactory {
92      /**
93       * <p>Construct an instance of this class.</p>
94       */
95      protected MXBeanMappingFactory() {}
96  
97      /**
98       * <p>Mapping factory that applies the default rules for MXBean
99       * mappings, as described in the <a
100      * href="../MXBean.html#MXBean-spec">MXBean specification</a>.</p>
101      */
102     public static final MXBeanMappingFactory DEFAULT =
103             new DefaultMXBeanMappingFactory();
104 
105     /**
106      * <p>Return the mapping for the given Java type.  Typically, a
107      * mapping factory will return mappings for types it handles, and
108      * forward other types to another mapping factory, most often
109      * the {@linkplain #DEFAULT default one}.</p>
110      * @param t the Java type to be mapped.
111      * @param f the original mapping factory that was consulted to do
112      * the mapping.  A mapping factory should pass this parameter intact
113      * if it forwards a type to another mapping factory.  In the example,
114      * this is how {@code MyLinkedListMappingFactory} works for types
115      * like {@code MyLinkedList[]} and {@code List<MyLinkedList>}.
116      * @return the mapping for the given type.
117      * @throws OpenDataException if this type cannot be mapped.  This
118      * exception is appropriate if the factory is supposed to handle
119      * all types of this sort (for example, all linked lists), but
120      * cannot handle this particular type.
121      */
122     public abstract MXBeanMapping mappingForType(Type t, MXBeanMappingFactory f)
123     throws OpenDataException;
124 }