1/* 2 * Copyright (c) 2005, 2017, 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 26package javax.management; 27 28import 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 class="striped"> 98 * <caption style="display:none">Descriptor Fields</caption> 99 * <thead> 100 * <tr><th scope="col">Name</th><th scope="col">Value</th></tr> 101 * </thead> 102 * <tbody style="text-align:left"> 103 * <tr><th scope="row">units</th><td>"bytes"</td></tr> 104 * <tr><th scope="row">descriptionResourceKey</th><td>"bytes.key"</td></tr> 105 * <tr><th scope="row">descriptionResourceBundleBaseName</th> 106 * <td>"com.example.foo.MBeanResources"</td></tr> 107 * </tbody> 108 * </table> 109 * 110 * <p>An annotation such as {@code @Units} can be applied to:</p> 111 * 112 * <ul> 113 * <li>a Standard MBean or MXBean interface; 114 * <li>a method in such an interface; 115 * <li>a parameter of a method in a Standard MBean or MXBean interface 116 * when that method is an operation (not a getter or setter for an attribute); 117 * <li>a public constructor in the class that implements a Standard MBean 118 * or MXBean; 119 * <li>a parameter in such a constructor. 120 * </ul> 121 * 122 * <p>Other uses of the annotation are ignored.</p> 123 * 124 * <p>Interface annotations are checked only on the exact interface 125 * that defines the management interface of a Standard MBean or an 126 * MXBean, not on its parent interfaces. Method annotations are 127 * checked only in the most specific interface in which the method 128 * appears; in other words, if a child interface overrides a method 129 * from a parent interface, only {@code @DescriptorKey} annotations in 130 * the method in the child interface are considered. 131 * 132 * <p>The Descriptor fields contributed in this way by different 133 * annotations on the same program element must be consistent. That 134 * is, two different annotations, or two members of the same 135 * annotation, must not define a different value for the same 136 * Descriptor field. Fields from annotations on a getter method must 137 * also be consistent with fields from annotations on the 138 * corresponding setter method.</p> 139 * 140 * <p>The Descriptor resulting from these annotations will be merged 141 * with any Descriptor fields provided by the implementation, such as 142 * the <a href="Descriptor.html#immutableInfo">{@code 143 * immutableInfo}</a> field for an MBean. The fields from the annotations 144 * must be consistent with these fields provided by the implementation.</p> 145 * 146 * <p>An annotation element to be converted into a descriptor field 147 * can be of any type allowed by the Java language, except an annotation 148 * or an array of annotations. The value of the field is derived from 149 * the value of the annotation element as follows:</p> 150 * 151 * <table class="striped"> 152 * <caption style="display:none">Descriptor Field Types</caption> 153 * <thead> 154 * <tr><th scope="col">Annotation element</th><th scope="col">Descriptor field</th></tr> 155 * </thead> 156 * <tbody style="text-align:left"> 157 * <tr><th scope="row">Primitive value ({@code 5}, {@code false}, etc)</th> 158 * <td>Wrapped value ({@code Integer.valueOf(5)}, 159 * {@code Boolean.FALSE}, etc)</td></tr> 160 * <tr><th scope="row">Class constant (e.g. {@code Thread.class})</th> 161 * <td>Class name from {@link Class#getName()} 162 * (e.g. {@code "java.lang.Thread"})</td></tr> 163 * <tr><th scope="row">Enum constant (e.g. {@link ElementType#FIELD})</th> 164 * <td>Constant name from {@link Enum#name()} 165 * (e.g. {@code "FIELD"})</td></tr> 166 * <tr><th scope="row">Array of class constants or enum constants</th> 167 * <td>String array derived by applying these rules to each 168 * element</td></tr> 169 * <tr><th scope="row">Value of any other type<br> 170 * ({@code String}, {@code String[]}, {@code int[]}, etc)</th> 171 * <td>The same value</td></tr> 172 * </tbody> 173 * </table> 174 * 175 * @since 1.6 176 */ 177@Documented 178@Retention(RetentionPolicy.RUNTIME) 179@Target(ElementType.METHOD) 180public @interface DescriptorKey { 181 /** 182 * Returns the descriptor key. 183 * @return the descriptor key 184 */ 185 String value(); 186} 187