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

Extending reference manual

Browse Source
This commit is contained in:
Mark Fisher
2008-01-22 00:43:11 +00:00
parent 89e990f661
commit c9c9a0875c
3 changed files with 163 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
spring-integration-reference/reference/images/logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.4 KiB

119
spring-integration-reference/reference/src/configuration.xml
View File

@@ -65,22 +65,133 @@
<title>Configuring Message Channels</title>
<para>
To create a Message Channel instance, use the 'channel' element:
<programlisting>&lt;channel/&gt;</programlisting>
<programlisting>&lt;channel id="exampleChannel"/&gt;</programlisting>
</para>
<para>
You can also specify the channel's capacity: <programlisting>&lt;channel capacity="100"/&gt;</programlisting>
You can also specify the channel's capacity: <programlisting>&lt;channel id="exampleChannel" capacity="100"/&gt;</programlisting>
</para>
<para>
The default channel type is <emphasis>Point to Point</emphasis>. To create a
<emphasis>Publish Subscribe</emphasis> channel, provide a value of <emphasis>true</emphasis> for the
'publish-subscribe' attribute of the channel element:
<programlisting>&lt;channel publish-subscribe="true"/&gt;</programlisting>
<programlisting>&lt;channel id="exampleChannel" publish-subscribe="true"/&gt;</programlisting>
</para>
<para>
When the <classname>MessageBus</classname> detects and registers channels, it will establish a dispatcher for
each channel. The default dispatcher settings were previously displayed in
<xref linkend="api-messagebus-dispatcherpolicy"/>. To customize these settings for a particular channel, add
the 'dispatcher-policy' sub-element and provide one or more of the attributes shown below:
<programlisting><![CDATA[<channel id="exampleChannel" publish-subscribe="true">
<dispatcher-policy max-messages-per-task="25"
receive-timeout="10"
rejection-limit="3"
retry-interval="500"
should-fail-on-rejection-limit="false"/>
</channel>]]></programlisting>
</para>
</section>
<section id="endpoint">
<section id="namespace-endpoint">
<title>Configuring Message Endpoints</title>
<para>
To create a Message Endpoint instance, use the 'endpoint' element with the 'input-channel' and 'handler-ref'
attributes:
<programlisting>&lt;endpoint input-channel="exampleChannel" handler-ref="exampleHandler"/&gt;</programlisting>
</para>
<para>
The configuration above assumes that "exampleHandler" is an actual implementation of the
<interfacename>MessageHandler</interfacename> interface as described in <xref linkend="api-messagehandler"/>.
To delegate to an arbitrary method of any object, simply add the "handler-method" attribute.
<programlisting>&lt;endpoint input-channel="exampleChannel" handler-ref="somePojo" handler-method="someMethod"/&gt;</programlisting>
</para>
<para>
In either case (<interfacename>MessageHandler</interfacename> or arbitrary object/method), when the handling
method returns a non-null value, the endpoint will attempt to send the reply message to an appropriate reply
channel. To determine the reply channel, it will first check for a value in the message header's
'replyChannelName' property. If that value is available, it will attempt to resolve the channel by performing a
lookup in the <interfacename>ChannelRegistry</interfacename>. If the message header does not contain a
'replyChannelName' property, then it will fallback to its own 'defaultOutputChannel' property. If neither is
available, then a <classname>MessageHandlingException</classname> will be thrown. To configure the default
output channel when using the XML namespace, provide the 'default-output-channel' attribute:
<programlisting>&lt;endpoint input-channel="exampleChannel"
handler-ref="somePojo"
handler-method="someMethod"
default-output-channel="replyChannel"/&gt;</programlisting>
</para>
<para>
When the <interfacename>MessageBus</interfacename> registers the endpoint, it will activate the subscription
by assigning the endpoint to the input channel's dispatcher. The dispatcher is capable of handling multiple
endpoint subscriptions for its channel and delegates to a scheduler for managing the tasks that pull messages
from the channel and push them to the endpoints. To configure the polling period for an individual endpoint's
schedule, provide a 'schedule' sub-element with the 'period' in milliseconds:
<programlisting><![CDATA[<endpoint input-channel="exampleChannel" handler-ref="exampleHandler"/>
]]><emphasis><![CDATA[<schedule period="3000"/>]]></emphasis><![CDATA[
</endpoint>]]></programlisting>
</para>
<note>
Individual endpoint schedules only apply for "Point-to-Point" channels, since in that case only a single
subscriber needs to receive the message. On the other hand, when a Spring Integration channel is configured as
a "Publish-Subscribe" channel, then the dispatcher will drive all endpoint notifications according to its own
default schedule, and any 'schedule' element configured for those endpoints will be ignored.
</note>
<para>
One of the most important configuration options for endpoints is the concurrency policy. Each endpoint is
capable of managing a thread pool for its handler, and the values you provide for that pool's core and max
size can make a substantial difference in how the handler performs under load. These settings are available
per-endpoint since the performance characteristics of an endpoint's handler is one of the major factors to
consider (the other major factor being the expected volume on the channel to which the endpoint subscribes).
To enable concurrency for an endpoint that is configured with the XML namespace support, provide the
'concurrency' sub-element and one or more of the properties shown below:
<programlisting><![CDATA[<endpoint input-channel="exampleChannel" handler-ref="exampleHandler"/>
]]><emphasis><![CDATA[<concurrency core="5" max="25" queue-capacity="20" keep-alive="120"/>]]></emphasis><![CDATA[
</endpoint>]]></programlisting>
Recall the default concurrency policy values as listed in <xref linkend="api-messagebus-concurrencypolicy"/>.
</para>
<tip>
The default queue capacity of 0 triggers the creation of a <classname>SynchronousQueue</classname>. In many
cases, this is preferable since the direct handoff eliminates the chance of a message handling task being
"stuck" in the queue (thread pool executors will favor adding to the queue rather than increasing the pool
size). Specifically, whenever a dispatcher for a Point-to-Point channel has more than one subscribed endpoint,
a task that is rejected due to an exhausted thread pool can be handled immediately by another endpoint whose
pool has one or more threads available. On the other hand, when a particular channel/endpoint may be expecting
bursts of activity, setting a queue capacity value might be the best way to accommodate the volume.
</tip>
</section>
<section id="namespace-messagebus">
<title>Configuring the Message Bus</title>
<para>
As described in <xref linkend="api-messagebus"/>, the <classname>MessageBus</classname> plays a central role.
Nevertheless, its configuration is quite simple since it is primarily concerned with managing internal details
based on the configuration of channels and endpoints. The bus is aware of its host application context, and
therefore is also capable of auto-detecting the channels and endpoints. Typically, the
<classname>MessageBus</classname> can be configured with a single empty element:
<programlisting>&lt;message-bus/&gt;</programlisting>
</para>
<para>
The Message Bus provides default error handling for its components in the form of a configurable error channel,
and the 'message-bus' element accepts a reference with its 'error-channel' attribute:
<programlisting><![CDATA[<message-bus error-channel="errorChannel"/>
<channel id="errorChannel" publish-subscribe="true" capacity="500"/>]]></programlisting>
</para>
<para>
The 'message-bus' element accepts two more optional attributes. First is the size of the dispatcher thread
pool. The dispatcher threads are responsible for polling channels and then passing the messages to handlers.
When the endpoints are concurrency-enabled as described in the previous section, the invocation of the handling
methods will happen within the handler thread pool and not the dispatcher pool. Finally, the Message Bus is
capable of automatically creating channel instances (with default settings) if an endpoint registers a
subscription by providing the name of a channel that the bus does not recognize.
<programlisting><![CDATA[<message-bus dispatcher-pool-size="25" auto-create-channels="true"/>]]></programlisting>
</para>
</section>
<section id="namespace-annotationdriven">
<title>Enabling Annotation-Driven Configuration</title>
<para>
The next section will describe Spring Integration's support for annotation-driven configuration. To enable
those features, add this single element to the XML-based configuration:
<programlisting>&lt;annotation-driven/&gt;</programlisting>
</para>
</section>
</section>

56
spring-integration-reference/reference/src/core-api.xml
View File

@@ -90,7 +90,7 @@ new GenericMessage&lt;T&gt;(T payload);</programlisting>
Spring Integration's <interfacename>MessageChannel</interfacename> interface is defined as follows.
<programlisting>public interface MessageChannel {
String getName();
boolean isPublishSubscribe();
DispatcherPolicy getDispatcherPolicy();
boolean send(Message message);
boolean send(Message message, long timeout);
Message receive();
@@ -138,7 +138,6 @@ new GenericMessage&lt;T&gt;(T payload);</programlisting>
<interfacename>MessageChannels</interfacename> and <interfacename>MessageHandlers</interfacename>. It provides
the following methods:
<programlisting>public void registerChannel(String name, MessageChannel channel)
public void registerChannel(String name, MessageChannel channel, DispatcherPolicy dispatcherPolicy)
public void registerHandler(String name, MessageHandler handler, Subscription subscription)
public void registerHandler(String name, MessageHandler handler, Subscription subscription, ConcurrencyPolicy concurrencyPolicy)</programlisting>
As those method signatures reveal, the message bus is handling several of the concerns here so that the channel
@@ -149,8 +148,8 @@ public void registerHandler(String name, MessageHandler handler, Subscription su
</para>
<para>
The bus creates and manages dispatchers that pull messages from a channel in order to push those messages to
handlers subscribed to that channel. The <classname>DispatcherPolicy</classname> contains metadata for
configuring those dispatchers:
handlers subscribed to that channel. Each channel has a <classname>DispatcherPolicy</classname> that contains
metadata for configuring those dispatchers:
<table id="api-messagebus-dispatcherpolicy">
<title>Properties of the DispatcherPolicy</title>
<tgroup cols="3">
@@ -183,6 +182,12 @@ public void registerHandler(String name, MessageHandler handler, Subscription su
<entry>1000 (milliseconds)</entry>
<entry>amount of time to wait between successive attempts to invoke handlers</entry>
</row>
<row>
<entry>shouldFailOnRejectionLimit</entry>
<entry>true</entry>
<entry>whether to throw a <classname>MessageDeliveryException</classname> if the 'rejectionLimit' is
reached - if this is set to 'false', then such undeliverable messages would be dropped silently</entry>
</row>
</tbody>
</tgroup>
</table>
@@ -258,10 +263,45 @@ public void registerHandler(String name, MessageHandler handler, Subscription su
</para>
<para>
The <classname>ConcurrencyPolicy</classname> is an optional parameter to provide when registering a handler.
It encapsulates two properties: 'coreSize' and 'maxSize'. When the <interfacename>MessageBus</interfacename>
registers a handler, it will use these properties to configure that handler's thread pool. These pool size
parameters are configurable on a per-handler basis since handlers may have differences in performance and
may have different expectations with regard to the volume of throughput.
When the <interfacename>MessageBus</interfacename> registers a handler, it will use these properties to configure
that handler's thread pool. These parameters are configurable on a per-handler basis since handlers may have
different performance characteristics and may have different expectations with regard to the volume of
throughput. The following table lists the available properties and their default values:
<table id="api-messagebus-concurrencypolicy">
<title>Properties of the ConcurrencyPolicy</title>
<tgroup cols="3">
<colspec align="left"/>
<thead>
<row>
<entry align="center">Property Name</entry>
<entry align="center">Default Value</entry>
<entry align="center">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>coreSize</entry>
<entry>1</entry>
<entry>the core size of the thread pool</entry>
</row>
<row>
<entry>maxSize</entry>
<entry>10</entry>
<entry>the maximum size the thread pool can reach when under demand</entry>
</row>
<row>
<entry>queueCapacity</entry>
<entry>0</entry>
<entry>capacity of the queue which defers an increase of the pool size</entry>
</row>
<row>
<entry>keepAliveSeconds</entry>
<entry>60</entry>
<entry>how long added threads (beyond core size) should remain idle before being removed from the pool</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>