RFE 6204469 proposes adding Descriptor support to all types of MBean.  This allows the MBeanInfo and associated classes to include arbitrary extra information beyond the fixed fields that are currently defined.  Since that means that Descriptors are available for Standard MBeans, and since the MBeanInfo for a Standard MBean is derived from a Java interface, it would make sense if we could add annotations to the Java interface to define the Descriptor contents.

The intent here is not to define specific annotations that map to specific Descriptor fields, but to define a generic way in which users can define such annotations.

As a simple example, suppose you want to be able to write a Standard MBean with an interface like this:

public interface CacheMBean {
    @Units("bytes")
    int getSize();
}

and you want it to produce a Descriptor with a field "units" whose value is "bytes", then you would define the @Units annotation like this:

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

The @DescriptorKey annotation is what allows the JMX implementation to deduce the Descriptor field from the contents of the Java interface.

Similarly, if you wanted the annotation to define the fields "units", "descriptionResourceKey", and "descriptionResourceBundleBaseName", then it might look like this:

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

and be defined 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 "";
}
###@###.### 2005-1-25 17:44:25 GMT

In the example above, all of the members of the @Units annotation are Strings.  The proposal is that they can be any of the standard types supported by annotations, such as int, int[], or enumerations, and the value of the Descriptor field will be the same object (not a String mapping of that object).  At least initially, it is not proposed to support annotation members whose type is itself an annotation, so for example this would not be allowed:
public @interface Resource {
    String resourceKey() default "";
    String resourceBundleBaseName() default "";
}
public @interface Units {
    @DescriptorKey("units")
    String units();
    @DescriptorKey("resource")
    Resource resource() default @Resource();
}
###@###.### 2005-1-26 10:21:23 GMT

Examples where this is useful:

(a) When Standard MBeans are generated by mapping from an existing data model, for example CIM.  If unadorned Standard MBean interfaces are generated, there will typically be a loss of information.  For example all of the CIM qualifiers will be lost.  By defining appropriate annotations, the information can be preserved.

(b) Much interesting information can be added about attributes.  If an attribute is a metric, is it a counter or a gauge?  What are its units?  Its minimum and maximum possible values?  Its sampling frequency?  Is it a constant attribute?  How long can its value reasonably be cached?

(c) Information can also be added about operations.  Is the operation idempotent?  Is it currently enabled?  Parameters and return values can have information similar to that listed for attributes.

(d) Information can be added about the interface itself.  What notifications can it send?  Does the list change over the lifetime of the MBean?

(e) Information can be added about how to map the types referenced in attributes and operations, for example to XML.
###@###.### 2005-03-23 09:47:11 GMT