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