United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-6221321 Add annotations to specify MBean descriptor contents
JDK-6221321 : Add annotations to specify MBean descriptor contents

Details
Type:
Enhancement
Submit Date:
2005-01-25
Status:
Resolved
Updated Date:
2010-07-29
Project Name:
JDK
Resolved Date:
2005-08-20
Component:
core-svc
OS:
generic
Sub-Component:
javax.management
CPU:
generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
6
Fixed Versions:

Related Reports
Relates:
Relates:

Sub Tasks

Description
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

                                    

Comments
SUGGESTED FIX

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

with corresponding changes to the logic for building MBeanInfo in Standard MBeans.
###@###.### 2005-1-25 17:44:25 GMT
                                     
2005-01-25
EVALUATION

Fix is quite straightforward.  In addition to the other reasons for making it, it is worth noting that the addition of MXBeans makes it now fairly hard to achieve a similar effect by subclassing StandardMBean and overriding getMBeanInfo or cacheMBeanInfo.  The reason is that you need to map back from an MBeanAttributeInfo or MBeanOperationInfo to the method in the MXBean interface that generated it.  With Standard MBeans this is not hard, but with MXBeans you have to reverse the type mapping so you can give the right parameters to Class.getMethod.  With the change here, you no longer need to do this.  Other uses of annotations, for example to fill in MBeanAttributeInfo.getDescription() or MBeanOperationInfo.getImpact(), can be achieved by transferring the @Description or @Impact annotation into the Descriptor via this feature, then from there into the description or impact property.
                                     
2005-07-28



Hardware and Software, Engineered to Work Together