195 lines
10 KiB
XML
195 lines
10 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<section version="5.0" xml:id="jmx" xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:ns5="http://www.w3.org/1999/xhtml"
|
|
xmlns:ns4="http://www.w3.org/1998/Math/MathML"
|
|
xmlns:ns3="http://www.w3.org/2000/svg"
|
|
xmlns:ns="http://docbook.org/ns/docbook">
|
|
<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"> <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"> <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"> <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"> <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"> <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" fixed-rate="5000"/>
|
|
</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"> <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"> <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-mbean-exporter">
|
|
<title>MBean Exporter</title>
|
|
|
|
<para>Spring Integration components themselves may be exposed as MBeans
|
|
when the <classname>IntegrationMBeanExporter</classname> is configured. To
|
|
create an instance of the <classname>IntegrationMBeanExporter</classname>,
|
|
define a bean and provide a reference to an MBeanServer and a domain name
|
|
(if desired). The domain can be left out in which case the default domain
|
|
is "org.springframework.integration". <programlisting language="xml"> <jmx:mbean-exporter domain="my.company.domain" mbean-server="mbeanServer"/>
|
|
|
|
<bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean">
|
|
<property name="locateExistingServerIfPossible" value="true"/>
|
|
</bean></programlisting></para>
|
|
|
|
<para>The MBean exporter is orthogonal to the one provided in Spring core
|
|
- it registers message channels and message handlers, but not itself. You
|
|
can expose the exporter itself, and certain other components in Spring
|
|
Integration, using the standard
|
|
<literal><context:mbean-export/></literal> tag. </para>
|
|
</section>
|
|
|
|
<section id="jmx-control-bus">
|
|
<title>Control Bus</title>
|
|
|
|
<para>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. <programlisting
|
|
language="xml"> <jmx:control-bus mbean-exporter="mbeanExporter" operation-channel="operationChannel"/>
|
|
|
|
<jmx:mbean-exporter id="mbeanExporter" mbean-server="mbeanServer"/>
|
|
</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>
|
|
</section>
|