Please note that this documentation is not final and is subject to change.

javax.management
Annotation Type Description

@Documented
@Retention(value=RUNTIME)
@Target(value={CONSTRUCTOR,METHOD,PARAMETER,TYPE})
public @interface Description

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 getDescription() method of an MBeanInfo, MBeanAttributeInfo, or similar.

This annotation applies to Standard MBean interfaces and to MXBean interfaces, as well as to MBean classes defined using the @MBean or @MXBean annotations. For example, a Standard MBean might be defined like this:

 @Description("Application configuration")
 public interface ConfigurationMBean {
     @Description("Cache size in bytes")
     public int getCacheSize();
     public void setCacheSize(int size);

     @Description("Last time the configuration was changed, " +
                  "in milliseconds since 1 Jan 1970")
     public long getLastChangedTime();

     @Description("Save the configuration to a file")
     public void save(
         @Description("Optional name of the file, or null for the default name")
         String fileName);
 }
 

The MBeanInfo for this MBean will have a getDescription() that is "Application configuration". It will contain an MBeanAttributeInfo for the CacheSize attribute that is defined by the methods getCacheSize and setCacheSize, and another MBeanAttributeInfo for LastChangedTime. The getDescription() for CacheSize will be "Cache size in bytes". Notice that there is no need to add a @Description to both getCacheSize and setCacheSize - either alone will do. But if you do add a @Description to both, it must be the same.

The MBeanInfo will also contain an MBeanOperationInfo where getDescription() is "Save the configuration to a file". This MBeanOperationInfo will contain an MBeanParameterInfo where getDescription() is "Optional name of the file, or null for the default name".

The @Description annotation can also be applied to the public constructors of the implementation class. Continuing the above example, the Configuration class implementing ConfigurationMBean might look like this:

 public class Configuration implements ConfigurationMBean {
     @Description("A Configuration MBean with the default file name")
     public Configuration() {
         this(DEFAULT_FILE_NAME);
     }

     @Description("A Configuration MBean with a specified file name")
     public Configuration(
         @Description("Name of the file the configuration is stored in")
         String fileName) {...}
     ...
 }
 

The @Description annotation also works in MBeans that are defined using the @MBean or @MXBean annotation on classes. Here is an alternative implementation of Configuration that does not use an ConfigurationMBean interface.

 @MBean
 @Description("Application configuration")
 public class Configuration {
     @Description("A Configuration MBean with the default file name")
     public Configuration() {
         this(DEFAULT_FILE_NAME);
     }

     @Description("A Configuration MBean with a specified file name")
     public Configuration(
         @Description("Name of the file the configuration is stored in")
         String fileName) {...}

     @ManagedAttribute
     @Description("Cache size in bytes")
     public int getCacheSize() {...}
     @ManagedAttribute
     public void setCacheSize(int size) {...}

     @ManagedOperation
     @Description("Last time the configuration was changed, " +
                  "in milliseconds since 1 Jan 1970")
     public long getLastChangedTime() {...}

     @ManagedOperation
     @Description("Save the configuration to a file")
     public void save(
         @Description("Optional name of the file, or null for the default name")
         String fileName) {...}
     ...
 }
 

Required Element Summary

Modifier and Type	Required Element and Description
String	value The description.

Optional Element Summary

Modifier and Type	Optional Element and Description
String	bundleBaseName The base name for the ResourceBundle in which the key given in the descriptionResourceKey field can be found, for example "com.example.myapp.MBeanResources".
String	key A resource key for the description of this element.

Element Detail

value

public abstract String value

The description.

bundleBaseName

@DescriptorKey(value="descriptionResourceBundleBaseName",
               omitIfDefault=true)
public abstract String bundleBaseName

The base name for the ResourceBundle in which the key given in the descriptionResourceKey field can be found, for example "com.example.myapp.MBeanResources". If a non-default value is supplied for this element, it will appear in the Descriptor for the annotated item.

Default:

""

key

@DescriptorKey(value="descriptionResourceKey",
               omitIfDefault=true)
public abstract String key

A resource key for the description of this element. In conjunction with the 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 Descriptor for the annotated item.

Default:

""