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

INT-1420: re-org of existing docs

Browse Source
This commit is contained in:
David Syer
2010-09-03 15:36:20 +00:00
parent 13b46448bf
commit f2ed075db7
2 changed files with 151 additions and 343 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
src/docbkx/jdbc.xml~
View File

@@ -1,203 +0,0 @@
<?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="jdbc">
<title>JDBC Support</title>
<para>Spring Integration provides Channel Adapters for receiving and sending
messages via database queries.</para>
<section id="jdbc-inbound-channel-adapter">
<title>Inbound Channel Adapter</title>
<para>The main function of an inbound Channel Adapter is to execute a SQL
<code>SELECT</code> query and turn the result set into a message. The
message payload is the whole result set, expressed as a
<classname>List</classname>, and the types of the items in the list
depends on the row-mapping strategy that is used. The default strategy is
a generic mapper that just returns a <classname>Map</classname> for each
row i nthe query. Optionally this can be changed by adding a reference to
requires a reference to a <classname>RowMapper</classname> instance (see
the <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/jdbc.html">Spring
JDBC</ulink> documentation for more detailed information about row
mapping).<note>
<para>If you want to convert rows in the SELECT query result to
individual messages you can use a downstream splitter.</para>
</note></para>
<para>The inbound adapter also requires a reference to either
<classname>JdbcTemplate</classname> instance or
<interfacename>DataSource</interfacename>.</para>
<para>As well as the <code>SELECT</code> statement to generate the
messages, the adapter above also has an <code>UPDATE</code> statement that
is being used to mark the records as processed, so they don't show up in
the next poll. The update can be parameterised by the list of ids from the
original select. This is done through a naming convention by default (a
column in the input result set called "id" is translated into a list in
the parameter map for the update called "id"). The following example defines
an inbound Channel Adapter with an update query and a <classname>DataSource</classname>
reference. <programlisting language="xml"><![CDATA[<jdbc:inbound-channel-adapter query="select * from item where status=2"
channel="target" data-source="dataSource"
update="update item set status=10 where id in (:id)" />]]></programlisting>
<note>
The parameters in the update query are specified with a colon (:) prefix to the name of a parameter (which in this case is an expression to be applied to each of the rows in the polled result set). This is a standard feature of the named parameter JDBC support in Spring JDBC combined with a convention (projection onto the polled result list) adopted in Spring Integration. The underlying Spring JDBC features limit the available expressions (e.g. most special characters other than period are disallowed), but since the target is usually a list of or an individual object addressable by simple bean paths this isn't unduly restrictive.
</note>
To change the parameter
generation strategy you can inject a
<classname>SqlParameterSourceFactory</classname> into the adapter to
override the default behaviour (the adapter has a
<code>sql-parameter-source-factory</code> attribute).</para>
<section>
<title>Polling and Transactions</title>
<para>The inbound adapter accepts a regular Spring Integration poller as
a sub element, so for instance the frequency of the polling can be
controlled. A very important feature of the poller for JDBC usage is the
option to wrap the poll operation in a transaction, for example:</para>
<programlisting><![CDATA[<jdbc:inbound-channel-adapter query="..."
channel="target" data-source="dataSource"
update="...">
<poller>
<interval-trigger interval="1000"/>
<transactional/>
</poller>
</jdbc:inbound-channel-adapter>]]></programlisting>
<para><note>
If a poller is not explicitly specified a default value will be used (and as per normal with Spring Integration can be defined as a top level bean)
</note> In this example the database is polled every 1000
milliseconds, and the update and select queries are both executed in the
same transaction. The transaction manager configuration is not shown,
but as long as it is aware of the data source then the poll is
transactional. A common use case is for the downstream channels to be
direct channels (the default), so that the endpoints are invoked in the
same thread, and hence the same transaction. then if any of them fails,
the transaction rolls back and the input data are reverted to their
original state.</para>
</section>
</section>
<section id="jdbc-outbound-channel-adapter">
<title>Outbound Channel Adapter</title>
<para>The outbound Channel Adapter is the inverse of the inbound: its role
is to handle a message and use it to execute a SQL query. The message
payload and headers are available by default as input parameters to the
query, for instance: <programlisting language="xml"><![CDATA[<jdbc:outbound-channel-adapter
query="insert into foos (id, status, name) values (:headers[$id], 0, :payload[foo])"
channel="input" data-source="dataSource"/>]]></programlisting> In the
example above, messages arriving on the channel "input" have a payload of
a map with key "foo", so the <code>[]</code> operator dereferences that
value from the map. The headers are also accessed as a map. <note>
The parameters in the query above are bean property expressions on the incoming message (not Spring EL expressions). This behaviour is part of the
<classname>SqlParameterSource</classname> which is the default
source created by the outbound adapter. Other behaviour is possible
in the adapter, and requires the user to inject a different
<classname>SqlParameterSourceFactory</classname>.
</note></para>
<para>The outbound adapter requires a reference to either a DataSource or
a JdbcTemplate. It can also have a
<classname>SqlParameterSourceFactory</classname> injected to control the
binding of incoming message to the query.</para>
<para>If the input channel is a direct channel then the outbound adapter
runs its query in the same thread, and therefor ethe same transaction (if
there is one) as the sender of the message.</para>
</section>
<section id="jdbc-outbound-gateway">
<title>Outbound Gateway</title>
<para>The outbound Gateway is like a combination of the inbound and outbound adapters: its role
is to handle a message and use it to execute a SQL query. The message
payload and headers are available by default as input parameters to the
query, for instance: <programlisting language="xml"><![CDATA[<jdbc:outbound-channel-adapter
query="insert into foos (id, status, name) values (:headers[$id], 0, :payload[foo])"
channel="input" data-source="dataSource"/>]]></programlisting> In the
example above, messages arriving on the channel "input" have a payload of
a map with key "foo", so the <code>[]</code> operator dereferences that
value from the map. The headers are also accessed as a map. <note>
The parameters in the query above are bean property expressions on the incoming message (not Spring EL expressions). This behaviour is part of the
<classname>SqlParameterSource</classname> which is the default
source created by the outbound adapter. Other behaviour is possible
in the adapter, and requires the user to inject a different
<classname>SqlParameterSourceFactory</classname>.
</note></para>
<para>The outbound adapter requires a reference to either a DataSource or
a JdbcTemplate. It can also have a
<classname>SqlParameterSourceFactory</classname> injected to control the
binding of incoming message to the query.</para>
<para>If the input channel is a direct channel then the outbound adapter
runs its query in the same thread, and therefor ethe same transaction (if
there is one) as the sender of the message.</para>
</section>
<section>
<title>Message Store</title>
<para>The JDBC module provides an implementation of the Spring Integration
<classname>MessageStore</classname> (important in the Claim Check pattern)
and <classname>MessageGroupStore</classname> (important in stateful
patterns like Aggregator) backed by a database. Both interfaces are
implemented by the JdbcMessageStore and there is also support for
configuring store instances in XML. For example:</para>
<programlisting><![CDATA[<jdbc:message-store id="messageStore" data-source="dataSource"/>]]></programlisting>
<para>A <classname>JdbcTemplate</classname> can be specified instead of a
<classname>DataSource</classname>.</para>
<para>Other optional attributes are show in the next example:</para>
<para><programlisting><![CDATA[<jdbc:message-store id="messageStore" data-source="dataSource"
lob-handler="lobHandler" table-prefix="MY_INT_"/>]]></programlisting>Here we
have specified a <classname>LobHandler</classname> for dealing with
messages as large objects (e.g. often necessary if using Oracle) and a
prefix for the table names in the queries generated by the store. The
table name prefix defaults to "INT_".</para>
<section>
<title>Initializing the Database</title>
<para>Spring Integration ships with some sample scripts that can be used
to initialize a database. In the spring-integration-jdbc JAR file you
will find scripts in the
<classname>org.springframework.integration.jdbc</classname> package:
there is a create and a drop script example for a range of common
database platforms. A common way to use these scripts is to reference
them in a <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/jdbc.html#d0e24182">Spring
JDBC data source initializer</ulink>. Note that the scripts are provided
as samples or specifications of the the required table and column names.
You may find that you need to enhance them for production use (e.g. with
index declarations).</para>
</section>
<section>
<title>Partitioning a Message Store</title>
<para>It is common to use a <classname>JdbcMessageStore</classname> as a
global store for a group of applications, or nodes in the same
application. To provide some portection against name clashes, and to
give control over the database meta-data configuration, the message
store allows the tables to be partitioned in two ways. One is to use
separate table names, by changing the prefix as described above, and the
other is to specify a "region" name for partitioning data within a
single table. An important use case for this is using the store to
manage persistent queues backing a Spring Integration channel. The
message data for a persistent channel is keyed in the store on the
channel name, so if the channel names are not globally unique then there
is the danger of channels picking up data that was not intended for
them. To avoid this the message store region can be used to keep data
separate for different physical channels that happen to have the same
logical name.</para>
</section>
</section>
</chapter>

291
src/docbkx/jmx.xml
View File

@@ -3,180 +3,191 @@
"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>
<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"
<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"/>
]]></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"><![CDATA[ <jmx:notification-listening-channel-adapter id="adapter"
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"/>
]]></programlisting>
Since the notification-listening adapter is registered with the MBeanServer directly, it is
event-driven and does not require any poller configuration.
</para>
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"><![CDATA[ <context:mbean:export/>
<jmx:notification-publishing-channel-adapter id="adapter"
<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"/>
]]></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/>
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>
<jmx:notification-publishing-channel-adapter id="adapter"
<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"/>
]]></programlisting>
</para>
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"><![CDATA[ <jmx:attribute-polling-channel-adapter id="adapter"
<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">
<si:poller max-messages-per-poll="1">
<si:interval-trigger interval="5000"/>
</si:poller>
</jmx:attribute-polling-channel-adapter>
]]></programlisting>
</para>
attribute-name="InvocationCount"&gt;
&lt;si:poller max-messages-per-poll="1"&gt;
&lt;si:interval-trigger interval="5000"/&gt;
&lt;/si:poller&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"><![CDATA[ <jmx:operation-invoking-channel-adapter id="adapter"
<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"/>
]]></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>
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"><![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>
<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-control-bus">
<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>
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>
<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>
</chapter>