root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

SPR-6338: Rewrite of source-level JMX metadata to remove references to commons attributes

This commit is contained in:
Luke Taylor 2009-11-13 17:18:13 +00:00
parent a0b71d867f
commit ef02feed55
1 changed files with 52 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

242
spring-framework-reference/src/jmx.xml
View File

@ -421,178 +421,31 @@ public class JmxTestBean implements IJmxTestBean {
</section> </section>
<section id="jmx-interface-metadata"> <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 <para>Using the <classname>MetadataMBeanInfoAssembler</classname> you
can define the management interfaces for your beans using source level can define the management interfaces for your beans using source level
metadata. The reading of metadata is encapsulated by the metadata. The reading of metadata is encapsulated by the
<classname>org.springframework.jmx.export.metadata.JmxAttributeSource</classname> <classname>org.springframework.jmx.export.metadata.JmxAttributeSource</classname>
interface. Out of the box, Spring JMX provides support for two interface. Spring JMX provides a default implementation which uses JDK 5.0 annotations, namely
implementations of this interface: <classname>org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource</classname>. The
<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
<classname>MetadataMBeanInfoAssembler</classname> <classname>MetadataMBeanInfoAssembler</classname>
<emphasis>must</emphasis> be configured with an implementation instance <emphasis>must</emphasis> be configured with an implementation instance
of the <classname>JmxAttributeSource</classname> interface for it to of the <classname>JmxAttributeSource</classname> interface for it to
function correctly (there is <emphasis>no</emphasis> default). For the function correctly (there is <emphasis>no</emphasis> default).</para>
following example, we will use the Commons Attributes metadata
approach.</para>
<para>To mark a bean for export to JMX, you should annotate the bean <para>To mark a bean for export to JMX, you should annotate the bean
class with the <classname>ManagedResource</classname> attribute. In the class with the <classname>ManagedResource</classname> annotation. Each
case of the Commons Attributes metadata approach this class can be found
in the <literal>org.springframework.jmx.metadata</literal> package. Each
method you wish to expose as an operation must be marked with the 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 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 properties you can omit either the annotation of the getter or the
setter to create a write-only or read-only attribute setter to create a write-only or read-only attribute
respectively.</para> respectively.</para>
<para>The example below shows the <classname>JmxTestBean</classname> <para>The example below shows the annotated version of the
class that you saw earlier marked with Commons Attributes <classname>JmxTestBean</classname> class that you saw earlier:</para>
metadata:</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 {
private String name;
private int age;
/**
* @@org.springframework.jmx.export.metadata.ManagedAttribute
* (description="The Age Attribute", currencyTimeLimit=15)
*/
public int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
}
/**
* @@org.springframework.jmx.export.metadata.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)
*/
public String getName() {
return name;
}
/**
* @@org.springframework.jmx.export.metadata.ManagedOperation
* (description="Add Two Numbers Together")
*/
public int add(int x, int y) {
return x + y;
}
public void dontExposeMe() {
throw new RuntimeException();
}
}]]></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
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
detail later in section entitled <xref
linkend="jmx-interface-metadata-types" />.</para>
<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
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
be read-only.</para>
<para>Finally, you will notice that the <literal>add(int, int)</literal>
method is marked with the <classname>ManagedOperation</classname>
attribute whereas the <literal>dontExposeMe()</literal> method is not.
This will cause the management interface to contain only one operation,
<literal>add(int, int)</literal>, when using the
<classname>MetadataMBeanInfoAssembler</classname>.</para>
<para>The code below shows 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; <programlisting language="java"><![CDATA[package org.springframework.jmx;
import org.springframework.jmx.export.annotation.ManagedResource; import org.springframework.jmx.export.annotation.ManagedResource;
@ -642,9 +495,33 @@ public class AnnotationTestBean implements IJmxTestBean {
} }
}]]></programlisting> }]]></programlisting>
<para>As you can see little has changed, other than the basic syntax of <para>Here you can see that the <classname>JmxTestBean</classname> class
the metadata definitions.</para> 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
detail later in section entitled <xref
linkend="jmx-interface-metadata-types" />.</para>
<para>You will also notice that both the <literal>age</literal> and
<literal>name</literal> properties are annotated with the
<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
be read-only.</para>
<para>Finally, you will notice that the <literal>add(int, int)</literal>
method is marked with the <classname>ManagedOperation</classname>
attribute whereas the <literal>dontExposeMe()</literal> method is not.
This will cause the management interface to contain only one operation,
<literal>add(int, int)</literal>, when using the
<classname>MetadataMBeanInfoAssembler</classname>.</para>
<para>The configuration below shouws how you configure the
<classname>MBeanExporter</classname> to use the
<classname>MetadataMBeanInfoAssembler</classname>:</para>
<programlisting language="xml"><![CDATA[<beans> <programlisting language="xml"><![CDATA[<beans>
<bean id="exporter" class="org.springframework.jmx.export.MBeanExporter"> <bean id="exporter" class="org.springframework.jmx.export.MBeanExporter">
<property name="assembler" ref="assembler"/> <property name="assembler" ref="assembler"/>
@ -672,6 +549,15 @@ public class AnnotationTestBean implements IJmxTestBean {
<property name="age" value="100"/> <property name="age" value="100"/>
</bean> </bean>
</beans>]]></programlisting> </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>
<section id="jmx-interface-metadata-types"> <section id="jmx-interface-metadata-types">
@ -690,17 +576,13 @@ public class AnnotationTestBean implements IJmxTestBean {
<colspec colname="spycolgen2" colnum="2" colwidth="*" /> <colspec colname="spycolgen2" colnum="2" colwidth="*" />
<colspec colname="spycolgen3" colnum="3" colwidth="*" />
<thead> <thead>
<row> <row>
<entry align="center">Purpose</entry> <entry align="center">Purpose</entry>
<entry align="center">Commons Attributes Attribute</entry> <entry align="center">Annotation</entry>
<entry align="center">JDK 5.0 Annotation</entry> <entry align="center">Annotation Type</entry>
<entry align="center">Attribute / Annotation Type</entry>
</row> </row>
</thead> </thead>
@ -709,8 +591,6 @@ public class AnnotationTestBean implements IJmxTestBean {
<entry>Mark all instances of a <classname>Class</classname> as <entry>Mark all instances of a <classname>Class</classname> as
JMX managed resources</entry> JMX managed resources</entry>
<entry><classname>ManagedResource</classname></entry>
<entry><literal>@ManagedResource</literal></entry> <entry><literal>@ManagedResource</literal></entry>
<entry>Class</entry> <entry>Class</entry>
@ -719,8 +599,6 @@ public class AnnotationTestBean implements IJmxTestBean {
<row> <row>
<entry>Mark a method as a JMX operation</entry> <entry>Mark a method as a JMX operation</entry>
<entry><classname>ManagedOperation</classname></entry>
<entry><literal>@ManagedOperation</literal></entry> <entry><literal>@ManagedOperation</literal></entry>
<entry>Method</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 <entry>Mark a getter or setter as one half of a JMX
attribute</entry> attribute</entry>
<entry><classname>ManagedAttribute</classname></entry>
<entry><classname>@ManagedAttribute</classname></entry> <entry><classname>@ManagedAttribute</classname></entry>
<entry>Method (only getters and setters)</entry> <entry>Method (only getters and setters)</entry>
@ -740,8 +616,6 @@ public class AnnotationTestBean implements IJmxTestBean {
<row> <row>
<entry>Define descriptions for operation parameters</entry> <entry>Define descriptions for operation parameters</entry>
<entry><classname>ManagedOperationParameter</classname></entry>
<entry><classname>@ManagedOperationParameter</classname> and <entry><classname>@ManagedOperationParameter</classname> and
<classname>@ManagedOperationParameters</classname></entry> <classname>@ManagedOperationParameters</classname></entry>
@ -924,22 +798,10 @@ public class AnnotationTestBean implements IJmxTestBean {
<property name="age" value="100"/> <property name="age" value="100"/>
</bean> </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"> <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> </bean>
</beans>]]></programlisting> </beans>]]></programlisting>
@ -1222,9 +1084,9 @@ public class AnnotationTestBean implements IJmxTestBean {
<literal>assembler</literal>, and <literal>attributeSource</literal> <literal>assembler</literal>, and <literal>attributeSource</literal>
configuration is no longer needed, since it will always use standard Java configuration is no longer needed, since it will always use standard Java
annotation-based metadata (autodetection is always enabled as well). In fact, annotation-based metadata (autodetection is always enabled as well). In fact,
an even simpler syntax is supported with the inclusion of Spring's an even simpler syntax is supported by Spring's
'<literal>context</literal>' namespace in Spring 2.5. Rather than defining an '<literal>context</literal>' namespace.. Rather than defining an
<classname>MBeanExporter</classname> bean, provide this single element:</para> <classname>MBeanExporter</classname> bean, just provide this single element:</para>
<programlisting language="xml"><![CDATA[<context:mbean-export/>]]></programlisting> <programlisting language="xml"><![CDATA[<context:mbean-export/>]]></programlisting>