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