https://projects.eclipse.org/projects/ee4j.orb: GlassFish MBean Annotation Library (Eclipse Foundation)
  • Russell.Gold 
/*
 * Copyright (c) 2005, 2018 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0, which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

package org.glassfish.gmbal;

import java.lang.annotation.*;


This is taken directly from JDK 7 in order to support this feature in
JDK 5.

Meta-annotation that describes how an annotation element relates
to a field in a 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.


(The DescriptorFields annotation provides another way to add fields to a Descriptor. See the documentation for that annotation for a comparison of the two possibilities.)


Consider this annotation for example:


@Documented
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Units {
    @DescriptorKey("units")
    String value();
}



and this use of the annotation:


public interface CacheControlMBean {
    @Units("bytes")
    public long getCacheSize();
}



When a Standard MBean is made from the CacheControlMBean, the usual rules mean that it will have an attribute called CacheSize of type long. The @Units annotation, given the above definition, will ensure that the MBeanAttributeInfo for this attribute will have a Descriptor that has a field called units with corresponding value bytes.


Similarly, if the annotation looks like this:


@Documented
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Units {
    @DescriptorKey("units")
    String value();
    @DescriptorKey("descriptionResourceKey")
    String resourceKey() default "";
    @DescriptorKey("descriptionResourceBundleBaseName")
    String resourceBundleBaseName() default "";
}



and it is used like this:


public interface CacheControlMBean {
    @Units("bytes",
           resourceKey="bytes.key",
           resourceBundleBaseName="com.example.foo.MBeanResources")
    public long getCacheSize();
}



then the resulting Descriptor will contain the following fields:




NameValue


units"bytes"


descriptionResourceKey"bytes.key"


descriptionResourceBundleBaseName
    "com.example.foo.MBeanResources"




An annotation such as @Units can be applied to:


    

  • a Standard MBean or MXBean interface;

  • a method in such an interface;

  • a parameter of a method in a Standard MBean or MXBean interface
when that method is an operation (not a getter or setter for an attribute);

  • a public constructor in the class that implements a Standard MBean
or MXBean;

  • a parameter in such a constructor.



Other uses of the annotation are 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 @DescriptorKey annotations in the method in the child interface are considered. 
The Descriptor fields contributed in this way by different
annotations on the same program element must be consistent with
each other and with any fields contributed by a 
DescriptorFields annotation.  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 
immutableInfo field for an MBean.  The fields from the annotations
must be consistent with these fields provided by the implementation.


An annotation element to be converted into a descriptor field
can be of any type allowed by the Java language, except an annotation
or an array of annotations.  The value of the field is derived from
the value of the annotation element as follows:




Annotation elementDescriptor field


Primitive value (5, false, etc)
    Wrapped value (Integer.valueOf(5), Boolean.FALSE, etc)


Class constant (e.g. Thread.class)
    Class name from Class.getName() (e.g. "java.lang.Thread")


Enum constant (e.g. ElementType.FIELD)
    Constant name from Enum.name() (e.g. "FIELD")


Array of class constants or enum constants
    String array derived by applying these rules to each
        element


Value of any other type
 (String, String[], int[], etc)		
    The same value




Since:1.6
/** This is taken directly from JDK 7 in order to support this feature in
 * JDK 5.
 *
 * <p>Meta-annotation that describes how an annotation element relates
 * to a field in a 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.</p>
 *
 * <p>(The DescriptorFields annotation
 * provides another way to add fields to a {@code Descriptor}.  See
 * the documentation for that annotation for a comparison of the
 * two possibilities.)</p>
 *
 * <p>Consider this annotation for example:</p>
 *
 * <pre>
 * &#64;Documented
 * &#64;Target(ElementType.METHOD)
 * &#64;Retention(RetentionPolicy.RUNTIME)
 * public &#64;interface Units {
 *     <b>&#64;DescriptorKey("units")</b>
 *     String value();
 * }
 * </pre>
 *
 * <p>and this use of the annotation:</p>
 *
 * <pre>
 * public interface CacheControlMBean {
 *     <b>&#64;Units("bytes")</b>
 *     public long getCacheSize();
 * }
 * </pre>
 *
 * <p>When a Standard MBean is made from the {@code CacheControlMBean},
 * the usual rules mean that it will have an attribute called
 * {@code CacheSize} of type {@code long}.  The {@code @Units}
 * annotation, given the above definition, will ensure that the
 * MBeanAttributeInfo for this attribute will have a
 * {@code Descriptor} that has a field called {@code units} with
 * corresponding value {@code bytes}.</p>
 *
 * <p>Similarly, if the annotation looks like this:</p>
 *
 * <pre>
 * &#64;Documented
 * &#64;Target(ElementType.METHOD)
 * &#64;Retention(RetentionPolicy.RUNTIME)
 * public &#64;interface Units {
 *     <b>&#64;DescriptorKey("units")</b>
 *     String value();
 *
 *     <b>&#64;DescriptorKey("descriptionResourceKey")</b>
 *     String resourceKey() default "";
 *
 *     <b>&#64;DescriptorKey("descriptionResourceBundleBaseName")</b>
 *     String resourceBundleBaseName() default "";
 * }
 * </pre>
 *
 * <p>and it is used like this:</p>
 *
 * <pre>
 * public interface CacheControlMBean {
 *     <b>&#64;Units("bytes",
 *            resourceKey="bytes.key",
 *            resourceBundleBaseName="com.example.foo.MBeanResources")</b>
 *     public long getCacheSize();
 * }
 * </pre>
 *
 * <p>then the resulting {@code Descriptor} will contain the following
 * fields:</p>
 *
 * <table border="2">
 * <tr><th>Name</th><th>Value</th></tr>
 * <tr><td>units</td><td>"bytes"</td></tr>
 * <tr><td>descriptionResourceKey</td><td>"bytes.key"</td></tr>
 * <tr><td>descriptionResourceBundleBaseName</td>
 *     <td>"com.example.foo.MBeanResources"</td></tr>
 * </table>
 *
 * <p>An annotation such as {@code @Units} can be applied to:</p>
 *
 * <ul>
 * <li>a Standard MBean or MXBean interface;
 * <li>a method in such an interface;
 * <li>a parameter of a method in a Standard MBean or MXBean interface
 * when that method is an operation (not a getter or setter for an attribute);
 * <li>a public constructor in the class that implements a Standard MBean
 * or MXBean;
 * <li>a parameter in such a constructor.
 * </ul>
 *
 * <p>Other uses of the annotation are ignored.</p>
 *
 * <p>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 @DescriptorKey} annotations in
 * the method in the child interface are considered.
 *
 * <p>The Descriptor fields contributed in this way by different
 * annotations on the same program element must be consistent with
 * each other and with any fields contributed by a 
 * DescriptorFields annotation.  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.</p>
 *
 * <p>The Descriptor resulting from these annotations will be merged
 * with any Descriptor fields provided by the implementation, such as
 * the <a href="Descriptor.html#immutableInfo">{@code
 * immutableInfo}</a> field for an MBean.  The fields from the annotations
 * must be consistent with these fields provided by the implementation.</p>
 *
 * <p>An annotation element to be converted into a descriptor field
 * can be of any type allowed by the Java language, except an annotation
 * or an array of annotations.  The value of the field is derived from
 * the value of the annotation element as follows:</p>
 *
 * <table border="2">
 * <tr><th>Annotation element</th><th>Descriptor field</th></tr>
 * <tr><td>Primitive value ({@code 5}, {@code false}, etc)</td>
 *     <td>Wrapped value ({@code Integer.valueOf(5)},
 *         {@code Boolean.FALSE}, etc)</td></tr>
 * <tr><td>Class constant (e.g. {@code Thread.class})</td>
 *     <td>Class name from Class.getName()
 *         (e.g. {@code "java.lang.Thread"})</td></tr>
 * <tr><td>Enum constant (e.g. ElementType.FIELD)</td>
 *     <td>Constant name from Enum.name()
 *         (e.g. {@code "FIELD"})</td></tr>
 * <tr><td>Array of class constants or enum constants</td>
 *     <td>String array derived by applying these rules to each
 *         element</td></tr>
 * <tr><td>Value of any other type<br>
 *         ({@code String}, {@code String[]}, {@code int[]}, etc)</td>
 *     <td>The same value</td></tr>
 * </table>
 *
 * @since 1.6
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD, ElementType.FIELD })
public @interface DescriptorKey {
    String value();

    
Do not include this field in the Descriptor if the annotation element has its default value. For example, suppose @Units is defined like this:


@Documented
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Units {
    @DescriptorKey("units")
    String value();
    @DescriptorKey(value = "descriptionResourceKey",
                   omitIfDefault = true)
    String resourceKey() default "";
    @DescriptorKey(value = "descriptionResourceBundleBaseName",
                   omitIfDefault = true)
    String resourceBundleBaseName() default "";
}



Then consider a usage such as @Units("bytes") or @Units(value = "bytes", resourceKey = ""), where the resourceKey and resourceBundleBaseNames elements have their default values. In this case the Descriptor resulting from these annotations will not include a descriptionResourceKey or descriptionResourceBundleBaseName field.


/**
     * <p>Do not include this field in the Descriptor if the annotation
     * element has its default value.  For example, suppose {@code @Units} is
     * defined like this:</p>
     *
     * <pre>
     * &#64;Documented
     * &#64;Target(ElementType.METHOD)
     * &#64;Retention(RetentionPolicy.RUNTIME)
     * public &#64;interface Units {
     *     &#64;DescriptorKey("units")
     *     String value();
     *
     *     <b>&#64;DescriptorKey(value = "descriptionResourceKey",
     *                    omitIfDefault = true)</b>
     *     String resourceKey() default "";
     *
     *     <b>&#64;DescriptorKey(value = "descriptionResourceBundleBaseName",
     *                    omitIfDefault = true)</b>
     *     String resourceBundleBaseName() default "";
     * }
     * </pre>
     *
     * <p>Then consider a usage such as {@code @Units("bytes")} or
     * {@code @Units(value = "bytes", resourceKey = "")}, where the
     * {@code resourceKey} and {@code resourceBundleBaseNames} elements
     * have their default values.  In this case the Descriptor resulting
     * from these annotations will not include a {@code descriptionResourceKey}
     * or {@code descriptionResourceBundleBaseName} field.</p>
     */
    boolean omitIfDefault() default false;
}