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.Retention;

    31 import java.lang.annotation.RetentionPolicy;

    32 import java.lang.annotation.Target;

    33 import java.util.ResourceBundle;

    34 

    35 /**

    36  * <p>The textual description of an MBean or part of an MBean.  This

    37  * description is intended to be displayed to users to help them

    38  * understand what the MBean does.  Ultimately it will be the value of

    39  * the {@code getDescription()} method of an {@link MBeanInfo}, {@link

    40  * MBeanAttributeInfo}, or similar.</p>

    41  *

    42  * <p>This annotation applies to Standard MBean interfaces and to

    43  * MXBean interfaces, as well as to MBean classes defined using the

    44  * {@link MBean @MBean} or {@link MXBean @MXBean} annotations.  For

    45  * example, a Standard MBean might be defined like this:</p>

    46  *

    47  * <pre>

    48  * <b>{@code @Description}</b>("Application configuration")

    49  * public interface ConfigurationMBean {

    50  *     <b>{@code @Description}</b>("Cache size in bytes")

    51  *     public int getCacheSize();

    52  *     public void setCacheSize(int size);

    53  *

    54  *     <b>{@code @Description}</b>("Last time the configuration was changed, " +

    55  *                  "in milliseconds since 1 Jan 1970")

    56  *     public long getLastChangedTime();

    57  *

    58  *     <b>{@code @Description}</b>("Save the configuration to a file")

    59  *     public void save(

    60  *         <b>{@code @Description}</b>("Optional name of the file, or null for the default name")

    61  *         String fileName);

    62  * }

    63  * </pre>

    64  *

    65  * <p>The {@code MBeanInfo} for this MBean will have a {@link

    66  * MBeanInfo#getDescription() getDescription()} that is {@code

    67  * "Application configuration"}.  It will contain an {@code

    68  * MBeanAttributeInfo} for the {@code CacheSize} attribute that is

    69  * defined by the methods {@code getCacheSize} and {@code

    70  * setCacheSize}, and another {@code MBeanAttributeInfo} for {@code

    71  * LastChangedTime}.  The {@link MBeanAttributeInfo#getDescription()

    72  * getDescription()} for {@code CacheSize} will be {@code "Cache size

    73  * in bytes"}.  Notice that there is no need to add a

    74  * {@code @Description} to both {@code getCacheSize} and {@code

    75  * setCacheSize} - either alone will do.  But if you do add a

    76  * {@code @Description} to both, it must be the same.</p>

    77  *

    78  * <p>The {@code MBeanInfo} will also contain an {@link

    79  * MBeanOperationInfo} where {@link

    80  * MBeanOperationInfo#getDescription() getDescription()} is {@code

    81  * "Save the configuration to a file"}.  This {@code

    82  * MBeanOperationInfo} will contain an {@link MBeanParameterInfo}

    83  * where {@link MBeanParameterInfo#getDescription() getDescription()}

    84  * is {@code "Optional name of the file, or null for the default

    85  * name"}.</p>

    86  *

    87  * <p>The {@code @Description} annotation can also be applied to the

    88  * public constructors of the implementation class.  Continuing the

    89  * above example, the {@code Configuration} class implementing {@code

    90  * ConfigurationMBean} might look like this:</p>

    91  *

    92  * <pre>

    93  * public class Configuration implements ConfigurationMBean {

    94  *     <b>{@code @Description}</b>("A Configuration MBean with the default file name")

    95  *     public Configuration() {

    96  *         this(DEFAULT_FILE_NAME);

    97  *     }

    98  *

    99  *     <b>{@code @Description}</b>("A Configuration MBean with a specified file name")

   100  *     public Configuration(

   101  *         <b>{@code @Description}</b>("Name of the file the configuration is stored in")

   102  *         String fileName) {...}

   103  *     ...

   104  * }

   105  * </pre>

   106  *

   107  * <p>The {@code @Description} annotation also works in MBeans that

   108  * are defined using the {@code @MBean} or {@code @MXBean} annotation

   109  * on classes.  Here is an alternative implementation of {@code

   110  * Configuration} that does not use an {@code ConfigurationMBean}

   111  * interface.</p>

   112  *

   113  * <pre>

   114  * <b>{@code @MBean}</b>

   115  * <b>{@code @Description}</b>("Application configuration")

   116  * public class Configuration {

   117  *     <b>{@code @Description}</b>("A Configuration MBean with the default file name")

   118  *     public Configuration() {

   119  *         this(DEFAULT_FILE_NAME);

   120  *     }

   121  *

   122  *     <b>{@code @Description}</b>("A Configuration MBean with a specified file name")

   123  *     public Configuration(

   124  *         <b>{@code @Description}</b>("Name of the file the configuration is stored in")

   125  *         String fileName) {...}

   126  *

   127  *     <b>{@code @ManagedAttribute}</b>

   128  *     <b>{@code @Description}</b>("Cache size in bytes")

   129  *     public int getCacheSize() {...}

   130  *     <b>{@code @ManagedAttribute}</b>

   131  *     public void setCacheSize(int size) {...}

   132  *

   133  *     <b>{@code @ManagedOperation}</b>

   134  *     <b>{@code @Description}</b>("Last time the configuration was changed, " +

   135  *                  "in milliseconds since 1 Jan 1970")

   136  *     public long getLastChangedTime() {...}

   137  *

   138  *     <b>{@code @ManagedOperation}</b>

   139  *     <b>{@code @Description}</b>("Save the configuration to a file")

   140  *     public void save(

   141  *         <b>{@code @Description}</b>("Optional name of the file, or null for the default name")

   142  *         String fileName) {...}

   143  *     ...

   144  * }

   145  * </pre>

   146  */

   147 @Documented

   148 @Retention(RetentionPolicy.RUNTIME)

   149 @Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.PARAMETER,

   150          ElementType.TYPE})

   151 public @interface Description {

   152     /**

   153      * <p>The description.</p>

   154      */

   155     String value();

   156 

   157     /**

   158      * <p>The base name for the {@link ResourceBundle} in which the key given in

   159      * the {@code descriptionResourceKey} field can be found, for example

   160      * {@code "com.example.myapp.MBeanResources"}.  If a non-default value

   161      * is supplied for this element, it will appear in the

   162      * <a href="Descriptor.html#descriptionResourceBundleBaseName"><!--

   163      * -->{@code Descriptor}</a> for the annotated item.</p>

   164      */

   165     @DescriptorKey(

   166         value = "descriptionResourceBundleBaseName", omitIfDefault = true)

   167     String bundleBaseName() default "";

   168 

   169     /**

   170      * <p>A resource key for the description of this element.  In

   171      * conjunction with the {@link #bundleBaseName bundleBaseName},

   172      * this can be used to find a localized version of the description.

   173      * If a non-default value

   174      * is supplied for this element, it will appear in the

   175      * <a href="Descriptor.html#descriptionResourceKey"><!--

   176      * -->{@code Descriptor}</a> for the annotated item.</p>

   177      */

   178     @DescriptorKey(value = "descriptionResourceKey", omitIfDefault = true)

   179     String key() default "";

   180 }