182 lines
9.9 KiB
XML
182 lines
9.9 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/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 <emphasis>notification-listening-channel-adapter</emphasis> 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 <context:mbean-server/> 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
|
|
<context:mbean-export/> 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 <emphasis>operation-invoking-channel-adapter</emphasis> 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. Both of these must be explicitly provided via adapter configuration:
|
|
<programlisting language="xml"><![CDATA[ <jmx:operation-invoking-channel-adapter id="adapter"
|
|
object-name="example.domain:name=TestBean"
|
|
operation-name="ping"/>
|
|
]]></programlisting>
|
|
Then the 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>
|
|
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-operation-invoking-outbound-gateway">
|
|
<title>Operation Invoking outbound Gateway</title>
|
|
<para>
|
|
Similar to <emphasis>operation-invoking-channel-adapter</emphasis> Spring Integration also provides <emphasis>operation-invoking-outbound-gateway</emphasis>
|
|
which could be used when dealing with non-void operations and return value is required.
|
|
Such return value will be sent as message payload to the 'reply-channel' specified by this Gateway.
|
|
<programlisting language="xml"><![CDATA[ <jmx:operation-invoking-outbound-gateway request-channel="requestChannel"
|
|
reply-channel="replyChannel"
|
|
object-name="org.springframework.integration.jmx.config:type=TestBean,name=testBeanGateway"
|
|
operation-name="testWithReturn"/>
|
|
]]></programlisting>
|
|
Another way of provideing the 'reply-channel' is by setting <interfacename>MessageHeaders.REPLY_CHANNEL</interfacename> Message Header
|
|
</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> |