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

Major progress on Gradle port

Browse Source 
Complete:
--------
- src/* documentation resources moved to 'docs' subproject

- docbook sources upgraded to Docbook 5

- formatted all docbook sources to strip tab characters and
  eliminate trailing whitespace

- all projects compile and test successfully

- all artifacts upload successfully to s3, static.sf.org, etc.

Remaining:
---------
- documentation L&F needs work. CSS, images, and highlighting aren't
  hooked up properly

- spring-integration-jdbc codegen bits in Maven POM need to be
  transcribed into gradle

- dependencies that were optional or provided scope in maven are
  currently 'compile' scope in Gradle.  Need to figure out support
  in Gradle to fix this.

- run through Eclipse classpath and project generation scenarios

- delete all Maven artifacts
This commit is contained in:
Chris Beams
2010-10-26 18:43:14 -04:00
parent d677da9c62
commit 677fca51a9
207 changed files with 10983 additions and 1459 deletions
Download Patch File Download Diff File Expand all files Collapse all files

190
docs/src/reference/docbook/jmx.xml Normal file
View File

@@ -0,0 +1,190 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="jmx"
xmlns:xlink="http://www.w3.org/1999/xlink">
<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"> &lt;jmx:notification-listening-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"/&gt;
</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 &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"> &lt;jmx:notification-listening-channel-adapter id="adapter"
channel="channel"
mbean-server="someServer"
object-name="example.domain:name=somePublisher"
notification-fliter="notificationFilter"
handback="myHandback"/&gt;
</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"> &lt;context:mbean:export/&gt;
&lt;jmx:notification-publishing-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"/&gt;
</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"> &lt;context:mbean:export/&gt;
&lt;jmx:notification-publishing-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"
default-notification-type="some.default.type"/&gt;
</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"> &lt;jmx:attribute-polling-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=someService"
attribute-name="InvocationCount"&gt;
&lt;si:poller max-messages-per-poll="1" fixed-rate="5000"/&gt;
&lt;/jmx:attribute-polling-channel-adapter&gt;
</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"> &lt;jmx:operation-invoking-channel-adapter id="adapter"
object-name="example.domain:name=TestBean"
operation-name="ping"/&gt;
</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"> &lt;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"/&gt;</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 "spring.application". <programlisting language="xml"> &lt;jmx:mbean-exporter domain="my.company.domain" mbean-server="mbeanServer"/&gt;
&lt;bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean"&gt;
&lt;property name="locateExistingServerIfPossible" value="true"/&gt;
&lt;/bean&gt;</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 using the standard
<literal>&lt;context:mbean-export/&gt;</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"> &lt;jmx:control-bus mbean-exporter="mbeanExporter" operation-channel="operationChannel"/&gt;
&lt;jmx:mbean-exporter id="mbeanExporter" mbean-server="mbeanServer"/&gt;
</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>