Annotation that adds fields to a {@link Descriptor}. This can be the + * Descriptor for an MBean, or for an attribute, operation, or constructor + * in an MBean, or for a parameter of an operation or constructor.
+ * + *Consider this Standard MBean interface, for example:
+ * + *
+ * public interface CacheControlMBean {
+ * @DescriptorFields("units=bytes")
+ * public long getCacheSize();
+ * }
+ *
+ *
+ * When a Standard MBean is made using this interface, the usual rules + * mean that it will have an attribute called {@code CacheSize} of type + * {@code long}. The {@code DescriptorFields} annotation will ensure + * that the {@link MBeanAttributeInfo} for this attribute will have a + * {@code Descriptor} that has a field called {@code units} with + * corresponding value {@code bytes}.
+ * + *Similarly, if the interface looks like this:
+ * + *
+ * public interface CacheControlMBean {
+ * @DescriptorFields({"units=bytes", "since=1.5"})
+ * public long getCacheSize();
+ * }
+ *
+ *
+ * then the resulting {@code Descriptor} will contain the following + * fields:
+ * + *| Name | Value |
|---|---|
| units | "bytes" |
| since | "1.5" |
The {@code @DescriptorFields} annotation can be applied to:
+ * + *Other uses of the annotation will either fail to compile or be + * ignored.
+ * + *Interface annotations are checked only on the exact interface + * that defines the management interface of a Standard MBean or an + * MXBean, not on its parent interfaces. Method annotations are + * checked only in the most specific interface in which the method + * appears; in other words, if a child interface overrides a method + * from a parent interface, only {@code @DescriptorFields} annotations in + * the method in the child interface are considered. + * + *
The Descriptor fields contributed in this way must be consistent + * with each other and with any fields contributed by {@link + * DescriptorKey @DescriptorKey} annotations. That is, two + * different annotations, or two members of the same annotation, must + * not define a different value for the same Descriptor field. Fields + * from annotations on a getter method must also be consistent with + * fields from annotations on the corresponding setter method.
+ * + *The Descriptor resulting from these annotations will be merged + * with any Descriptor fields provided by the implementation, such as + * the {@code + * immutableInfo} field for an MBean. The fields from the annotations + * must be consistent with these fields provided by the implementation.
+ * + *The {@link DescriptorKey @DescriptorKey} annotation provides
+ * another way to use annotations to define Descriptor fields.
+ * @DescriptorKey requires more work but is also more
+ * robust, because there is less risk of mistakes such as misspelling
+ * the name of the field or giving an invalid value.
+ * @DescriptorFields is more convenient but includes
+ * those risks. @DescriptorFields is more
+ * appropriate for occasional use, but for a Descriptor field that you
+ * add in many places, you should consider a purpose-built annotation
+ * using @DescriptorKey.
+ *
+ * @since 1.7
+ */
+@Documented
+@Inherited // for @MBean and @MXBean classes
+@Target({ElementType.CONSTRUCTOR, ElementType.METHOD,
+ ElementType.PARAMETER, ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface DescriptorFields {
+ /**
+ *
The descriptor fields. Each element of the string looks like + * {@code "name=value"}.
+ */ + public String[] value(); +}