1 /*

     2  * Copyright 2007-2008 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package javax.management;

    27 

    28 import java.lang.annotation.Documented;

    29 import java.lang.annotation.ElementType;

    30 import java.lang.annotation.Inherited;

    31 import java.lang.annotation.Retention;

    32 import java.lang.annotation.RetentionPolicy;

    33 import java.lang.annotation.Target;

    34 

    35 /**

    36  * <p>Annotation that adds fields to a {@link Descriptor}.  This can be the

    37  * Descriptor for an MBean, or for an attribute, operation, or constructor

    38  * in an MBean, or for a parameter of an operation or constructor.</p>

    39  *

    40  * <p>Consider this Standard MBean interface, for example:</p>

    41  *

    42  * <pre>

    43  * public interface CacheControlMBean {

    44  *     <b>&#64;DescriptorFields("units=bytes")</b>

    45  *     public long getCacheSize();

    46  * }

    47  * </pre>

    48  *

    49  * <p>When a Standard MBean is made using this interface, the usual rules

    50  * mean that it will have an attribute called {@code CacheSize} of type

    51  * {@code long}.  The {@code DescriptorFields} annotation will ensure

    52  * that the {@link MBeanAttributeInfo} for this attribute will have a

    53  * {@code Descriptor} that has a field called {@code units} with

    54  * corresponding value {@code bytes}.</p>

    55  *

    56  * <p>Similarly, if the interface looks like this:</p>

    57  *

    58  * <pre>

    59  * public interface CacheControlMBean {

    60  *     <b>&#64;DescriptorFields({"units=bytes", "since=1.5"})</b>

    61  *     public long getCacheSize();

    62  * }

    63  * </pre>

    64  *

    65  * <p>then the resulting {@code Descriptor} will contain the following

    66  * fields:</p>

    67  *

    68  * <table border="2">

    69  * <tr><th>Name</th><th>Value</th></tr>

    70  * <tr><td>units</td><td>"bytes"</td></tr>

    71  * <tr><td>since</td><td>"1.5"</td></tr>

    72  * </table>

    73  *

    74  * <p>The {@code @DescriptorFields} annotation can be applied to:</p>

    75  *

    76  * <ul>

    77  * <li>a Standard MBean or MXBean interface;

    78  * <li>a method in such an interface;

    79  * <li>a parameter of a method in a Standard MBean or MXBean interface

    80  * when that method is an operation (not a getter or setter for an attribute);

    81  * <li>a public constructor in the class that implements a Standard MBean

    82  * or MXBean;

    83  * <li>a parameter in such a constructor.

    84  * </ul>

    85  *

    86  * <p>Other uses of the annotation will either fail to compile or be

    87  * ignored.</p>

    88  *

    89  * <p>Interface annotations are checked only on the exact interface

    90  * that defines the management interface of a Standard MBean or an

    91  * MXBean, not on its parent interfaces.  Method annotations are

    92  * checked only in the most specific interface in which the method

    93  * appears; in other words, if a child interface overrides a method

    94  * from a parent interface, only {@code @DescriptorFields} annotations in

    95  * the method in the child interface are considered.

    96  *

    97  * <p>The Descriptor fields contributed in this way must be consistent

    98  * with each other and with any fields contributed by {@link

    99  * DescriptorKey @DescriptorKey} annotations.  That is, two

   100  * different annotations, or two members of the same annotation, must

   101  * not define a different value for the same Descriptor field.  Fields

   102  * from annotations on a getter method must also be consistent with

   103  * fields from annotations on the corresponding setter method.</p>

   104  *

   105  * <p>The Descriptor resulting from these annotations will be merged

   106  * with any Descriptor fields provided by the implementation, such as

   107  * the <a href="Descriptor.html#immutableInfo">{@code

   108  * immutableInfo}</a> field for an MBean.  The fields from the annotations

   109  * must be consistent with these fields provided by the implementation.</p>

   110  *

   111  * <h4>{@literal @DescriptorFields and @DescriptorKey}</h4>

   112  *

   113  * <p>The {@link DescriptorKey @DescriptorKey} annotation provides

   114  * another way to use annotations to define Descriptor fields.

   115  * <code>&#64;DescriptorKey</code> requires more work but is also more

   116  * robust, because there is less risk of mistakes such as misspelling

   117  * the name of the field or giving an invalid value.

   118  * <code>&#64;DescriptorFields</code> is more convenient but includes

   119  * those risks.  <code>&#64;DescriptorFields</code> is more

   120  * appropriate for occasional use, but for a Descriptor field that you

   121  * add in many places, you should consider a purpose-built annotation

   122  * using <code>&#64;DescriptorKey</code>.

   123  *

   124  * @since 1.7

   125  */

   126 @Documented

   127 @Inherited  // for @MBean and @MXBean classes

   128 @Target({ElementType.CONSTRUCTOR, ElementType.METHOD,

   129          ElementType.PARAMETER, ElementType.TYPE})

   130 @Retention(RetentionPolicy.RUNTIME)

   131 public @interface DescriptorFields {

   132     /**

   133      * <p>The descriptor fields.  Each element of the string looks like

   134      * {@code "name=value"}.</p>

   135      */

   136     public String[] value();

   137 }