Spring/spring-integration
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

added JMX chapter

Browse Source
This commit is contained in:
Mark Fisher
2010-03-12 21:30:58 +00:00
parent f27891530b
commit 50cb0f45a0
2 changed files with 176 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
spring-integration-reference/src/jmx.xml Normal file
View File

@@ -0,0 +1,175 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="jmx">
<title>JMX Support</title>
<para>
Spring Integration provides Channel Adapters for receiving and publishing JMX Notifications.
There is also an inbound Channel Adapter for polling JMX MBean attribute values, and an
outbound Channel Adapter for invoking JMX MBean operations.
</para>
<section id="jmx-notification-listening-channel-adapter">
<title>Notification Listening Channel Adapter</title>
<para>
The Notification-listening Channel Adapter requires a JMX ObjectName for the MBean that publishes
Notifications to which this listener should be registered. A very simple configuration might look like this:
<programlisting language="xml"><![CDATA[ <jmx:notification-listening-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"/>
]]></programlisting>
<tip>
The notification-listening-channel-adapter registers with an MBeanServer at startup, and
the default bean name is "mbeanServer" which happens to be the same bean name generated
when using Spring's &lt;context:mbean-server/&gt; element. If you need to use a different
name be sure to include the "mbean-server" attribute.
</tip>
The adapter can also accept a reference to a NotificationFilter and a "handback" Object
to provide some context that is passed back with each Notification. Both of those attributes
are optional. Extending the above example to include those attributes as well as an explicit
MBeanServer bean name would produce the following:
<programlisting language="xml"><![CDATA[ <jmx:notification-listening-channel-adapter id="adapter"
channel="channel"
mbean-server="someServer"
object-name="example.domain:name=somePublisher"
notification-fliter="notificationFilter"
handback="myHandback"/>
]]></programlisting>
Since the notification-listening adapter is registered with the MBeanServer directly, it is
event-driven and does not require any poller configuration.
</para>
</section>
<section id="jmx-notification-publishing-channel-adapter">
<title>Notification Publishing Channel Adapter</title>
<para>
The Notification-publishing Channel Adapter is relatively simple. It only requires a
JMX ObjectName in its configuration as shown below.
<programlisting language="xml"><![CDATA[ <context:mbean:export/>
<jmx:notification-publishing-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"/>
]]></programlisting>
It does also require that an MBeanExporter be present in the context. That is why the
&lt;context:mbean-export/&gt; element is shown above as well.
</para>
<para>
When Messages are sent to the channel for this adapter, the Notification
is created from the Message content. If the payload is a String it will be
passed as the "message" text for the Notification. Any other payload type
will be passed as the "userData" of the Notification.
</para>
<para>
JMX Notifications also have a "type", and it should be a dot-delimited String.
There are two ways to provide the type. Precedence will always be given to a
Message header value associated with the JmxHeaders.NOTIFICATION_TYPE key.
On the other hand, you can rely on a fallback "default-notification-type"
attribute provided in the configuration.
<programlisting language="xml"><![CDATA[ <context:mbean:export/>
<jmx:notification-publishing-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"
default-notification-type="some.default.type"/>
]]></programlisting>
</para>
</section>
<section id="jmx-attribute-polling-channel-adapter">
<title>Attribute Polling Channel Adapter</title>
<para>
The attribute polling adapter is useful when you have a requirement to periodically
check on some value that is available through an MBean as a managed attribute. The
poller can be configured in the same way as any other polling adapter in Spring
Integration (or it's possible to rely on the default poller). The "object-name"
and "attribute-name" are required. An MBeanServer reference is also required, but
it will automatically check for a bean named "mbeanServer" by default just like
the notification-listening-channel-adapter described above.
<programlisting language="xml"><![CDATA[ <jmx:attribute-polling-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=someService"
attribute-name="InvocationCount">
<si:poller max-messages-per-poll="1">
<si:interval-trigger interval="5000"/>
</si:poller>
</jmx:attribute-polling-channel-adapter>
]]></programlisting>
</para>
</section>
<section id="jmx-operation-invoking-channel-adapter">
<title>Operation Invoking Channel Adapter</title>
<para>
The operation-invoking-channel-adapter enables Message-driven invocation of
any managed operation exposed by an MBean. Each invocation requires the
operation name to be invoked and the ObjectName of the target MBean. In each
case, the adapter will first check for header values on the Message itself.
The keys for these headers are defined as JmxHeaders.OPERATION_NAME and
JmxHeaders.OBJECT_NAME, respectively. If relying on those Message headers,
the configuration is trivial.
<programlisting language="xml"><![CDATA[ <jmx:operation-invoking-channel-adapter id="adapter"/>
]]></programlisting>
That adapter only needs to be able to discover the "mbeanServer" bean. If
a different bean name is required, then provide the "mbean-server" attribute
with a reference.
</para>
<para>
The payload of the Message will be mapped to the parameters of the operation, if any.
A Map-typed payload with String keys is treated as name/value pairs whereas a List or
array would be passed as a simple argument list (with no explicit parameter names).
If the operation requires a single parameter value, then the payload can represent
that single value, and if the operation requires no parameters, then the payload
would be ignored.
</para>
<para>
Similar to the behavior described above for the Notification type resoltion,
the operation-invoking-channel-adapter will also fallback to default values if
provided:
<programlisting language="xml"><![CDATA[ <jmx:operation-invoking-channel-adapter id="adapter"
default-object-name="example.domain:name=TestBean"
default-operation-name="ping"/>
]]></programlisting>
If you want to expose a channel for a single common operation to be invoked
by Messages that need not contain headers, then that option works well.
</para>
</section>
<section id="jmx-control-bus">
<title>Control Bus</title>
<para>
Spring Integration components themselves may be exposed as MBeans when the Control Bus
is configured. As described in (<ulink url="http://www.eaipatterns.com/ControlBus.html">EIP</ulink>),
the idea behind the Control Bus is that the same messaging system can be used for monitoring
and managing the components within the framework as is used for "application-level" messaging.
In Spring Integration we build upon the adapters described above so that it's possible to
send Messages as a means of invoking exposed operations. Internally, the Control Bus uses
a Spring MBeanExporter instance to expose the various endpoints and channels. To create
an instance of the Control Bus, define a bean and provide a reference to an MBeanServer
and a domain name (we will be providing namespace support). The domain can be left out
in which case the default domain is "org.springframework.integration".
<programlisting language="xml"><![CDATA[ <bean id="controlBus" class="org.springframework.integration.control.ControlBus">
<constructor-arg ref="mbeanServer"/>
<constructor-arg value="example.domain"/>
</bean>
<bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean">
<property name="locateExistingServerIfPossible" value="true"/>
</bean>
]]></programlisting>
</para>
<para>
The Control Bus has an "operationChannel" that can be accessed for invoking operations
on the MBeans that it has exported. This will also be covered by namespace support soon
to make it easier to configure references to that channel for other producers. We will
likely add some other channels for notifications and attribute polling as well.
</para>
<para>
The Control Bus functionality is a work in progress. At this time, one can perform some
basic monitoring of Message Channels and/or invoke Lifecycle operations (start/stop) on
Message Endpoints. Now that the foundation is available, however, we will be able to extend
the attributes and operations that are being exposed.
</para>
</section>
</chapter>

1
spring-integration-reference/src/spring-integration-reference.xml
View File

@@ -75,6 +75,7 @@
<xi:include href="./http.xml"/>
<xi:include href="./ip.xml"/>
<xi:include href="./mail.xml"/>
<xi:include href="./jmx.xml"/>
<xi:include href="./stream.xml"/>
<xi:include href="./event.xml"/>
<xi:include href="./xml.xml"/>