SPR-6338: Rewrite of source-level JMX metadata to remove references to commons attributes
This commit is contained in:
Luke Taylor
parent
a0b71d867f
commit
ef02feed55
|
|
@ -421,178 +421,31 @@ 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>
|
||||
|
||||
<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>
|
||||
|
||||
<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;
|
||||
|
||||
import org.springframework.jmx.export.annotation.ManagedResource;
|
||||
|
|
@ -642,9 +495,33 @@ public class AnnotationTestBean implements IJmxTestBean {
|
|||
}
|
||||
}]]></programlisting>
|
||||
|
||||
<para>As you can see little has changed, other than the basic syntax of
|
||||
the metadata definitions.</para>
|
||||
<para>Here you can see that the <classname>JmxTestBean</classname> class
|
||||
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>
|
||||
<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">Annotation</entry>
|
||||
|
||||
<entry align="center">JDK 5.0 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><!-- (for Commons Attributes-based metadata) --></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><!-- (for Java 5+ annotations-based metadata) --></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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue