From 362926daf07583b809e59790f9243ebf7afa5189 Mon Sep 17 00:00:00 2001
From: Luke Taylor <ltaylor@vmware.com>
Date: Fri, 13 Nov 2009 17:18:13 +0000
Subject: [PATCH] SPR-6338: Rewrite of source-level JMX metadata to remove
 references to commons attributes

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@2431 50f2f4bb-b051-0410-bef5-90022cba6387
---
 spring-framework-reference/src/jmx.xml | 234 +++++--------------------
 1 file changed, 48 insertions(+), 186 deletions(-)

diff --git a/spring-framework-reference/src/jmx.xml b/spring-framework-reference/src/jmx.xml
index 1620fa16171..d5d2a5e6370 100644
--- a/spring-framework-reference/src/jmx.xml
+++ b/spring-framework-reference/src/jmx.xml
@@ -421,60 +421,46 @@ public class JmxTestBean implements IJmxTestBean {
     </section>
 
     <section id="jmx-interface-metadata">
-      <title>Using source-Level metadata</title>
+      <title>Using source-Level metadata (JDK 5.0 annotations)</title>
 
       <para>Using the <classname>MetadataMBeanInfoAssembler</classname> you
       can define the management interfaces for your beans using source level
       metadata. The reading of metadata is encapsulated by the
       <classname>org.springframework.jmx.export.metadata.JmxAttributeSource</classname>
-      interface. Out of the box, Spring JMX provides support for two
-      implementations of this interface:
-      <classname>org.springframework.jmx.export.metadata.AttributesJmxAttributeSource</classname>
-      for Commons Attributes and
-      <classname>org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource</classname>
-      for JDK 5.0 annotations. The
+      interface. Spring JMX provides a default implementation which uses JDK 5.0 annotations, namely
+      <classname>org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource</classname>. The
       <classname>MetadataMBeanInfoAssembler</classname>
       <emphasis>must</emphasis> be configured with an implementation instance
       of the <classname>JmxAttributeSource</classname> interface for it to
-      function correctly (there is <emphasis>no</emphasis> default). For the
-      following example, we will use the Commons Attributes metadata
-      approach.</para>
+      function correctly (there is <emphasis>no</emphasis> default).</para>
 
       <para>To mark a bean for export to JMX, you should annotate the bean
-      class with the <classname>ManagedResource</classname> attribute. In the
-      case of the Commons Attributes metadata approach this class can be found
-      in the <literal>org.springframework.jmx.metadata</literal> package. Each
+      class with the <classname>ManagedResource</classname> annotation. Each
       method you wish to expose as an operation must be marked with the
-      <classname>ManagedOperation</classname> attribute and each property you
+      <classname>ManagedOperation</classname> annotation and each property you
       wish to expose must be marked with the
-      <classname>ManagedAttribute</classname> attribute. When marking
+      <classname>ManagedAttribute</classname> annotation. When marking
       properties you can omit either the annotation of the getter or the
       setter to create a write-only or read-only attribute
       respectively.</para>
 
-      <para>The example below shows the <classname>JmxTestBean</classname>
-      class that you saw earlier marked with Commons Attributes
-      metadata:</para>
-
+      <para>The example below shows the annotated version of the 
+        <classname>JmxTestBean</classname> class that you saw earlier:</para>
       <programlisting language="java"><![CDATA[package org.springframework.jmx;
 
-/**
- * @@org.springframework.jmx.export.metadata.ManagedResource
- *  (description="My Managed Bean", objectName="spring:bean=test",
- *  log=true, logFile="jmx.log", currencyTimeLimit=15, persistPolicy="OnUpdate",
- *  persistPeriod=200, persistLocation="foo", persistName="bar")
- */
-public class JmxTestBean implements IJmxTestBean {
+import org.springframework.jmx.export.annotation.ManagedResource;
+import org.springframework.jmx.export.annotation.ManagedOperation;
+import org.springframework.jmx.export.annotation.ManagedAttribute;
 
-  private String name;
+@ManagedResource(objectName="bean:name=testBean4", description="My Managed Bean", log=true,
+    logFile="jmx.log", currencyTimeLimit=15, persistPolicy="OnUpdate", persistPeriod=200,
+    persistLocation="foo", persistName="bar")
+public class AnnotationTestBean implements IJmxTestBean {
 
+  private String name;
   private int age;
 
-
-  /**
-   * @@org.springframework.jmx.export.metadata.ManagedAttribute
-   *   (description="The Age Attribute", currencyTimeLimit=15)
-   */
+  @ManagedAttribute(description="The Age Attribute", currencyTimeLimit=15)
   public int getAge() {
     return age;
   }
@@ -483,27 +469,23 @@ public class JmxTestBean implements IJmxTestBean {
     this.age = age;
   }
 
-  /**
-   * @@org.springframework.jmx.export.metadata.ManagedAttribute
-   *  (description="The Name Attribute",  currencyTimeLimit=20,
-   *   defaultValue="bar", persistPolicy="OnUpdate")
-   */
+  @ManagedAttribute(description="The Name Attribute",
+      currencyTimeLimit=20,
+      defaultValue="bar",
+      persistPolicy="OnUpdate")
   public void setName(String name) {
     this.name = name;
   }
 
-  /**
-   * @@org.springframework.jmx.export.metadata.ManagedAttribute
-   *   (defaultValue="foo", persistPeriod=300)
-   */
+  @ManagedAttribute(defaultValue="foo", persistPeriod=300)
   public String getName() {
     return name;
   }
 
-  /**
-   * @@org.springframework.jmx.export.metadata.ManagedOperation
-   *  (description="Add Two Numbers Together")
-   */
+  @ManagedOperation(description="Add two numbers")
+  @ManagedOperationParameters({
+    @ManagedOperationParameter(name = "x", description = "The first number"),
+    @ManagedOperationParameter(name = "y", description = "The second number")})
   public int add(int x, int y) {
     return x + y;
   }
@@ -514,8 +496,8 @@ public class JmxTestBean implements IJmxTestBean {
 }]]></programlisting>
 
       <para>Here you can see that the <classname>JmxTestBean</classname> class
-      is marked with the <classname>ManagedResource</classname> attribute and
-      that this <classname>ManagedResource</classname> attribute is configured
+      is marked with the <classname>ManagedResource</classname> annotation and
+        that this <classname>ManagedResource</classname> annotation is configured
       with a set of properties. These properties can be used to configure
       various aspects of the MBean that is generated by the
       <classname>MBeanExporter</classname>, and are explained in greater
@@ -524,7 +506,7 @@ public class JmxTestBean implements IJmxTestBean {
 
       <para>You will also notice that both the <literal>age</literal> and
       <literal>name</literal> properties are annotated with the
-      <classname>ManagedAttribute</classname> attribute, but in the case of
+      <classname>ManagedAttribute</classname> annotation, but in the case of
       the <literal>age</literal> property, only the getter is marked. This
       will cause both of these properties to be included in the management
       interface as attributes, but the <literal>age</literal> attribute will
@@ -537,114 +519,9 @@ public class JmxTestBean implements IJmxTestBean {
       <literal>add(int, int)</literal>, when using the
       <classname>MetadataMBeanInfoAssembler</classname>.</para>
 
-      <para>The code below shows how you configure the
+      <para>The configuration below shouws how you configure the
       <classname>MBeanExporter</classname> to use the
       <classname>MetadataMBeanInfoAssembler</classname>:</para>
-
-      <programlisting language="xml"><![CDATA[<beans>
-
-  <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter">
-    <property name="beans">
-      <map>
-        <entry key="bean:name=testBean1" value-ref="testBean"/>
-      </map>
-    </property>
-    <property name="assembler" ref="assembler"/>
-  </bean>
-
-  <bean id="testBean" class="org.springframework.jmx.JmxTestBean">
-    <property name="name" value="TEST"/>
-    <property name="age" value="100"/>
-  </bean>
-
-  <bean id="attributeSource"
-        class="org.springframework.jmx.export.metadata.AttributesJmxAttributeSource">
-    <property name="attributes">
-      <bean class="org.springframework.metadata.commons.CommonsAttributes"/>
-    </property>
-  </bean>
-
-  <bean id="assembler" class="org.springframework.jmx.export.assembler.MetadataMBeanInfoAssembler">
-    <property name="attributeSource" ref="attributeSource"/>
-  </bean>
-
-</beans>]]></programlisting>
-
-      <para>Here you can see that an
-      <classname>MetadataMBeanInfoAssembler</classname> bean has been
-      configured with an instance of the
-      <classname>AttributesJmxAttributeSource</classname> class and passed to
-      the <classname>MBeanExporter</classname> through the assembler property.
-      This is all that is required to take advantage of metadata-driven
-      management interfaces for your Spring-exposed MBeans.</para>
-    </section>
-
-    <section id="jmx-interface-annotations">
-      <title>Using JDK 5.0 Annotations</title>
-
-      <para>To enable the use of JDK 5.0 annotations for management interface
-      definition, Spring provides a set of annotations that mirror the Commons
-      Attribute attribute classes and an implementation of the
-      <interfacename>JmxAttributeSource</interfacename> strategy interface,
-      the <classname>AnnotationsJmxAttributeSource</classname> class, that
-      allows the <interfacename>MBeanInfoAssembler</interfacename> to read
-      them.</para>
-
-      <para>The example below shows a bean where the management interface is defined
-      by the presence of JDK 5.0 annotation types:</para>
-
-      <programlisting language="java"><![CDATA[package org.springframework.jmx;
-
-import org.springframework.jmx.export.annotation.ManagedResource;
-import org.springframework.jmx.export.annotation.ManagedOperation;
-import org.springframework.jmx.export.annotation.ManagedAttribute;
-
-@ManagedResource(objectName="bean:name=testBean4", description="My Managed Bean", log=true,
-    logFile="jmx.log", currencyTimeLimit=15, persistPolicy="OnUpdate", persistPeriod=200,
-    persistLocation="foo", persistName="bar")
-public class AnnotationTestBean implements IJmxTestBean {
-
-  private String name;
-  private int age;
-
-  @ManagedAttribute(description="The Age Attribute", currencyTimeLimit=15)
-  public int getAge() {
-    return age;
-  }
-
-  public void setAge(int age) {
-    this.age = age;
-  }
-
-  @ManagedAttribute(description="The Name Attribute",
-      currencyTimeLimit=20,
-      defaultValue="bar",
-      persistPolicy="OnUpdate")
-  public void setName(String name) {
-    this.name = name;
-  }
-
-  @ManagedAttribute(defaultValue="foo", persistPeriod=300)
-  public String getName() {
-    return name;
-  }
-
-  @ManagedOperation(description="Add two numbers")
-  @ManagedOperationParameters({
-    @ManagedOperationParameter(name = "x", description = "The first number"),
-    @ManagedOperationParameter(name = "y", description = "The second number")})
-  public int add(int x, int y) {
-    return x + y;
-  }
-
-  public void dontExposeMe() {
-    throw new RuntimeException();
-  }
-}]]></programlisting>
-
-      <para>As you can see little has changed, other than the basic syntax of
-      the metadata definitions.</para>
-
       <programlisting language="xml"><![CDATA[<beans>
     <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter">
         <property name="assembler" ref="assembler"/>
@@ -672,6 +549,15 @@ public class AnnotationTestBean implements IJmxTestBean {
         <property name="age" value="100"/>
     </bean>
 </beans>]]></programlisting>
+      
+
+      <para>Here you can see that an
+      <classname>MetadataMBeanInfoAssembler</classname> bean has been
+      configured with an instance of the
+        <classname>AnnotationJmxAttributeSource</classname> class and passed to
+      the <classname>MBeanExporter</classname> through the assembler property.
+      This is all that is required to take advantage of metadata-driven
+      management interfaces for your Spring-exposed MBeans.</para>
     </section>
 
     <section id="jmx-interface-metadata-types">
@@ -690,17 +576,13 @@ public class AnnotationTestBean implements IJmxTestBean {
 
             <colspec colname="spycolgen2" colnum="2" colwidth="*" />
 
-            <colspec colname="spycolgen3" colnum="3" colwidth="*" />
-
             <thead>
               <row>
                 <entry align="center">Purpose</entry>
 
-                <entry align="center">Commons Attributes Attribute</entry>
-
-                <entry align="center">JDK 5.0 Annotation</entry>
+                <entry align="center">Annotation</entry>
 
-                <entry align="center">Attribute / Annotation Type</entry>
+                <entry align="center">Annotation Type</entry>
               </row>
             </thead>
 
@@ -709,8 +591,6 @@ public class AnnotationTestBean implements IJmxTestBean {
                 <entry>Mark all instances of a <classname>Class</classname> as
                 JMX managed resources</entry>
 
-                <entry><classname>ManagedResource</classname></entry>
-
                 <entry><literal>@ManagedResource</literal></entry>
 
                 <entry>Class</entry>
@@ -719,8 +599,6 @@ public class AnnotationTestBean implements IJmxTestBean {
               <row>
                 <entry>Mark a method as a JMX operation</entry>
 
-                <entry><classname>ManagedOperation</classname></entry>
-
                 <entry><literal>@ManagedOperation</literal></entry>
 
                 <entry>Method</entry>
@@ -730,8 +608,6 @@ public class AnnotationTestBean implements IJmxTestBean {
                 <entry>Mark a getter or setter as one half of a JMX
                 attribute</entry>
 
-                <entry><classname>ManagedAttribute</classname></entry>
-
                 <entry><classname>@ManagedAttribute</classname></entry>
 
                 <entry>Method (only getters and setters)</entry>
@@ -740,8 +616,6 @@ public class AnnotationTestBean implements IJmxTestBean {
               <row>
                 <entry>Define descriptions for operation parameters</entry>
 
-                <entry><classname>ManagedOperationParameter</classname></entry>
-
                 <entry><classname>@ManagedOperationParameter</classname> and
                 <classname>@ManagedOperationParameters</classname></entry>
 
@@ -924,22 +798,10 @@ public class AnnotationTestBean implements IJmxTestBean {
     <property name="age" value="100"/>
   </bean>
 
-  ]]><lineannotation>&lt;!-- (for Commons Attributes-based metadata) --&gt;</lineannotation><![CDATA[
-  <bean id="attributeSource"
-        class="org.springframework.jmx.export.metadata.AttributesJmxAttributeSource">
-    <property name="attributes">
-      <bean class="org.springframework.metadata.commons.CommonsAttributes"/>
-    </property>
-  </bean>
-  
-  ]]><lineannotation>&lt;!-- (for Java 5+ annotations-based metadata) --&gt;</lineannotation><emphasis><![CDATA[
-  <!--
-  <bean id="attributeSource"
-        class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource"/>
-  -->]]></emphasis><![CDATA[
-
   <bean id="assembler" class="org.springframework.jmx.export.assembler.MetadataMBeanInfoAssembler">
-    <property name="attributeSource" ref="attributeSource"/>
+    <property name="attributeSource">
+        <bean class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource"/>
+    </property>
   </bean>
 
 </beans>]]></programlisting>
@@ -1222,9 +1084,9 @@ public class AnnotationTestBean implements IJmxTestBean {
       <literal>assembler</literal>, and <literal>attributeSource</literal>
       configuration is no longer needed, since it will always use standard Java
       annotation-based metadata (autodetection is always enabled as well). In fact,
-      an even simpler syntax is supported with the inclusion of Spring's
-      '<literal>context</literal>' namespace in Spring 2.5. Rather than defining an
-      <classname>MBeanExporter</classname> bean, provide this single element:</para>
+      an even simpler syntax is supported by Spring's
+      '<literal>context</literal>' namespace.. Rather than defining an
+      <classname>MBeanExporter</classname> bean, just provide this single element:</para>
 
       <programlisting language="xml"><![CDATA[<context:mbean-export/>]]></programlisting>