KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > management > DescriptorKey


1 /*
2  * @(#)DescriptorKey.java 1.5 06/05/02
3  *
4  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.management;
9
10 import java.lang.annotation.*;
11
12 /**
13  * <p>Meta-annotation that describes how an annotation element relates
14  * to a field in a {@link Descriptor}. This can be the Descriptor for
15  * an MBean, or for an attribute, operation, or constructor in an
16  * MBean, or for a parameter of an operation or constructor.</p>
17  *
18  * <p>Consider this annotation for example:</p>
19  *
20  * <pre>
21  * &#64;Documented
22  * &#64;Target(ElementType.METHOD)
23  * &#64;Retention(RetentionPolicy.RUNTIME)
24  * public &#64;interface Units {
25  * <b>&#64;DescriptorKey("units")</b>
26  * String value();
27  * }
28  * </pre>
29  *
30  * <p>and this use of the annotation:</p>
31  *
32  * <pre>
33  * public interface CacheControlMBean {
34  * <b>&#64;Units("bytes")</b>
35  * public long getCacheSize();
36  * }
37  * </pre>
38  *
39  * <p>When a Standard MBean is made from the {@code CacheControlMBean},
40  * the usual rules mean that it will have an attribute called
41  * {@code CacheSize} of type {@code long}. The {@code @Units}
42  * attribute, given the above definition, will ensure that the
43  * {@link MBeanAttributeInfo} for this attribute will have a
44  * {@code Descriptor} that has a field called {@code units} with
45  * corresponding value {@code bytes}.</p>
46  *
47  * <p>Similarly, if the annotation looks like this:</p>
48  *
49  * <pre>
50  * &#64;Documented
51  * &#64;Target(ElementType.METHOD)
52  * &#64;Retention(RetentionPolicy.RUNTIME)
53  * public &#64;interface Units {
54  * <b>&#64;DescriptorKey("units")</b>
55  * String value();
56  *
57  * <b>&#64;DescriptorKey("descriptionResourceKey")</b>
58  * String resourceKey() default "";
59  *
60  * <b>&#64;DescriptorKey("descriptionResourceBundleBaseName")</b>
61  * String resourceBundleBaseName() default "";
62  * }
63  * </pre>
64  *
65  * <p>and it is used like this:</p>
66  *
67  * <pre>
68  * public interface CacheControlMBean {
69  * <b>&#64;Units("bytes",
70  * resourceKey="bytes.key",
71  * resourceBundleBaseName="com.example.foo.MBeanResources")</b>
72  * public long getCacheSize();
73  * }
74  * </pre>
75  *
76  * <p>then the resulting {@code Descriptor} will contain the following
77  * fields:</p>
78  *
79  * <table border="2">
80  * <tr><th>Name</th><th>Value</th></tr>
81  * <tr><td>units</td><td>"bytes"</td></tr>
82  * <tr><td>descriptionResourceKey</td><td>"bytes.key"</td></tr>
83  * <tr><td>descriptionResourceBundleBaseName</td>
84  * <td>"com.example.foo.MBeanResources"</td></tr>
85  * </table>
86  *
87  * <p>An annotation such as {@code @Units} can be applied to:</p>
88  *
89  * <ul>
90  * <li>a Standard MBean or MXBean interface;
91  * <li>a method in such an interface;
92  * <li>a parameter of a method in a Standard MBean or MXBean interface
93  * when that method is an operation (not a getter or setter for an attribute);
94  * <li>a public constructor in the class that implements a Standard MBean
95  * or MXBean;
96  * <li>a parameter in such a constructor.
97  * </ul>
98  *
99  * <p>Other uses of the annotation are ignored.</p>
100  *
101  * <p>Interface annotations are checked only on the exact interface
102  * that defines the management interface of a Standard MBean or an
103  * MXBean, not on its parent interfaces. Method annotations are
104  * checked only in the most specific interface in which the method
105  * appears; in other words, if a child interface overrides a method
106  * from a parent interface, only {@code @DescriptorKey} annotations in
107  * the method in the child interface are considered.
108  *
109  * <p>The Descriptor fields contributed in this way by different
110  * annotations on the same program element must be consistent. That
111  * is, two different annotations, or two members of the same
112  * annotation, must not define a different value for the same
113  * Descriptor field. Fields from annotations on a getter method must
114  * also be consistent with fields from annotations on the
115  * corresponding setter method.</p>
116  *
117  * <p>The Descriptor resulting from these annotations will be merged
118  * with any Descriptor fields provided by the implementation, such as
119  * the <a HREF="Descriptor.html#immutableInfo">{@code
120  * immutableInfo}</a> field for an MBean. The fields from the annotations
121  * must be consistent with these fields provided by the implementation.</p>
122  *
123  * <p>An annotation element to be converted into a descriptor field
124  * can be of any type allowed by the Java language, except an annotation
125  * or an array of annotations. The value of the field is derived from
126  * the value of the annotation element as follows:</p>
127  *
128  * <table border="2">
129  * <tr><th>Annotation element</th><th>Descriptor field</th></tr>
130  * <tr><td>Primitive value ({@code 5}, {@code false}, etc)</td>
131  * <td>Wrapped value ({@code Integer.valueOf(5)},
132  * {@code Boolean.FALSE}, etc)</td></tr>
133  * <tr><td>Class constant (e.g. {@code Thread.class})</td>
134  * <td>Class name from {@link Class#getName()}
135  * (e.g. {@code "java.lang.Thread"})</td></tr>
136  * <tr><td>Enum constant (e.g. {@link ElementType#FIELD})</td>
137  * <td>Constant name from {@link Enum#name()}
138  * (e.g. {@code "FIELD"})</td></tr>
139  * <tr><td>Array of class constants or enum constants</td>
140  * <td>String array derived by applying these rules to each
141  * element</td></tr>
142  * <tr><td>Value of any other type<br>
143  * ({@code String}, {@code String[]}, {@code int[]}, etc)</td>
144  * <td>The same value</td></tr>
145  * </table>
146  *
147  * @since 1.6
148  */
149 @Documented
150 @Retention(RetentionPolicy.RUNTIME)
151 @Target(ElementType.METHOD)
152 public @interface DescriptorKey {
153     String JavaDoc value();
154 }
155
156
Popular Tags