The textual description of an MBean or part of an MBean. This * description is intended to be displayed to users to help them * understand what the MBean does. Ultimately it will be the value of * the {@code getDescription()} method of an {@link MBeanInfo}, {@link * MBeanAttributeInfo}, or similar.
* *This annotation applies to Standard MBean interfaces and to * MXBean interfaces, as well as to MBean classes defined using the * {@link MBean @MBean} or {@link MXBean @MXBean} annotations. For * example, a Standard MBean might be defined like this:
* *
* {@code @Description}("Application configuration")
* public interface ConfigurationMBean {
* {@code @Description}("Cache size in bytes")
* public int getCacheSize();
* public void setCacheSize(int size);
*
* {@code @Description}("Last time the configuration was changed, " +
* "in milliseconds since 1 Jan 1970")
* public long getLastChangedTime();
*
* {@code @Description}("Save the configuration to a file")
* public void save(
* {@code @Description}("Optional name of the file, or null for the default name")
* String fileName);
* }
*
*
* The {@code MBeanInfo} for this MBean will have a {@link * MBeanInfo#getDescription() getDescription()} that is {@code * "Application configuration"}. It will contain an {@code * MBeanAttributeInfo} for the {@code CacheSize} attribute that is * defined by the methods {@code getCacheSize} and {@code * setCacheSize}, and another {@code MBeanAttributeInfo} for {@code * LastChangedTime}. The {@link MBeanAttributeInfo#getDescription() * getDescription()} for {@code CacheSize} will be {@code "Cache size * in bytes"}. Notice that there is no need to add a * {@code @Description} to both {@code getCacheSize} and {@code * setCacheSize} - either alone will do. But if you do add a * {@code @Description} to both, it must be the same.
* *The {@code MBeanInfo} will also contain an {@link * MBeanOperationInfo} where {@link * MBeanOperationInfo#getDescription() getDescription()} is {@code * "Save the configuration to a file"}. This {@code * MBeanOperationInfo} will contain an {@link MBeanParameterInfo} * where {@link MBeanParameterInfo#getDescription() getDescription()} * is {@code "Optional name of the file, or null for the default * name"}.
* *The {@code @Description} annotation can also be applied to the * public constructors of the implementation class. Continuing the * above example, the {@code Configuration} class implementing {@code * ConfigurationMBean} might look like this:
* *
* public class Configuration implements ConfigurationMBean {
* {@code @Description}("A Configuration MBean with the default file name")
* public Configuration() {
* this(DEFAULT_FILE_NAME);
* }
*
* {@code @Description}("A Configuration MBean with a specified file name")
* public Configuration(
* {@code @Description}("Name of the file the configuration is stored in")
* String fileName) {...}
* ...
* }
*
*
* The {@code @Description} annotation also works in MBeans that * are defined using the {@code @MBean} or {@code @MXBean} annotation * on classes. Here is an alternative implementation of {@code * Configuration} that does not use an {@code ConfigurationMBean} * interface.
* *
* {@code @MBean}
* {@code @Description}("Application configuration")
* public class Configuration {
* {@code @Description}("A Configuration MBean with the default file name")
* public Configuration() {
* this(DEFAULT_FILE_NAME);
* }
*
* {@code @Description}("A Configuration MBean with a specified file name")
* public Configuration(
* {@code @Description}("Name of the file the configuration is stored in")
* String fileName) {...}
*
* {@code @ManagedAttribute}
* {@code @Description}("Cache size in bytes")
* public int getCacheSize() {...}
* {@code @ManagedAttribute}
* public void setCacheSize(int size) {...}
*
* {@code @ManagedOperation}
* {@code @Description}("Last time the configuration was changed, " +
* "in milliseconds since 1 Jan 1970")
* public long getLastChangedTime() {...}
*
* {@code @ManagedOperation}
* {@code @Description}("Save the configuration to a file")
* public void save(
* {@code @Description}("Optional name of the file, or null for the default name")
* String fileName) {...}
* ...
* }
*
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.PARAMETER,
ElementType.TYPE})
public @interface Description {
/**
* The description.
*/ String value(); /** *The base name for the {@link ResourceBundle} in which the key given in * the {@code descriptionResourceKey} field can be found, for example * {@code "com.example.myapp.MBeanResources"}. If a non-default value * is supplied for this element, it will appear in the * {@code Descriptor} for the annotated item.
*/ @DescriptorKey( value = "descriptionResourceBundleBaseName", omitIfDefault = true) String bundleBaseName() default ""; /** *A resource key for the description of this element. In * conjunction with the {@link #bundleBaseName bundleBaseName}, * this can be used to find a localized version of the description. * If a non-default value * is supplied for this element, it will appear in the * {@code Descriptor} for the annotated item.
*/ @DescriptorKey(value = "descriptionResourceKey", omitIfDefault = true) String key() default ""; }