diff --git a/spring-integration-reference/src/configuration.xml b/spring-integration-reference/src/configuration.xml
index c12aface1a..2d255d16e8 100644
--- a/spring-integration-reference/src/configuration.xml
+++ b/spring-integration-reference/src/configuration.xml
@@ -100,26 +100,61 @@
defined on the MessageBus (see below).
- To specificially create a QueueChannel, use the "queue-channel" element.
- By using this element, you can also specify the channel's capacity:
- <queue-channel id="exampleChannel" capacity="100"/>
-
-
- To create a PriorityChannel, use the "priority-channel" element:
- ]]>
- By default, the channel will consult the MessagePriority value in the
- message's header. However, a custom Comparator reference may be
- provided instead. Also, the PriorityChannel does support the "datatype"
- attribute. The following example demonstrates both:
-
+ It is also possible to use more specific elements for the various channel types (as described in
+ ). Depending on the channel, these may provide additional configuration
+ options. Examples of each are shown below.
+
+
+ The <queue-channel/> element
+
+ To create a QueueChannel, use the "queue-channel" element.
+ By using this element, you can also specify the channel's capacity:
+ <queue-channel id="exampleChannel" capacity="25"/>
+
+
+
+ The <priority-channel/> element
+
+ To create a PriorityChannel, use the "priority-channel" element:
+ ]]>
+ By default, the channel will consult the MessagePriority value in the
+ message's header. However, a custom Comparator reference may be
+ provided instead. Also, note that the PriorityChannel (like the other types)
+ does support the "datatype" attribute. As with the "queue-channel", it also supports a "capacity" attribute.
+ The following example demonstrates all of these:
+
]]>
-
+
+
+
+ The <rendezvous-channel/> element
+
+ The RendezvousChannel does not provide any additional configuration options.
+ ]]>
+
+
+
+ The <direct-channel/> element
+
+ The DirectChannel does not provide any additional configuration options.
+ ]]>
+
+
+
+ The <thread-local-channel/> element
+
+ The ThreadLocalChannel does not provide any additional configuration options.
+ ]]>
+
+
Message channels may also have interceptors as described in . One or
- more <interceptor> elements can be added as sub-elements of <channel>. Provide the "ref" attribute
- to reference any Spring-managed object that implements the ChannelInterceptor
- interface:
+ more <interceptor> elements can be added as sub-elements of <channel> (or the more specific element
+ types). Provide the "ref" attribute to reference any Spring-managed object that implements the
+ ChannelInterceptor interface:
]]>]]>]]>
@@ -131,83 +166,116 @@
Configuring Message Endpoints
- To create a Message Endpoint instance, use the 'handler-endpoint' element with the 'input-channel' and 'handler'
- attributes:
- <handler-endpoint input-channel="exampleChannel" handler="exampleHandler"/>
+ Each of the three endpoint types (source, target, and handler) has its own element in the namespace.
-
- The configuration above assumes that "exampleHandler" is an actual implementation of the
- MessageHandler interface as described in .
- To delegate to an arbitrary method of any object, simply add the "method" attribute.
- <handler-endpoint input-channel="exampleChannel" handler="somePojo" method="someMethod"/>
-
-
- In either case (MessageHandler 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
- 'returnAddress' property. If that value is available, it will then check its type. If it is
- a MessageChannel, the reply message will be sent to that channel. If it is a
- String, then the endpoint will attempt to resolve the channel by performing a
- lookup in the ChannelRegistry. If the message header does not contain a
- 'returnAddress' property at all, then it will fallback to its own 'outputChannelName' property. If
- neither is available, then a MessageHandlingException will be thrown. To configure the
- output channel when using the XML namespace, provide the 'output-channel' attribute:
- <handler-endpoint input-channel="exampleChannel"
- handler="somePojo"
- method="someMethod"
- output-channel="replyChannel"/>
-
-
- Endpoints also support MessageSelectors as described in
- . To configure selectors with namespace support, simply add one or more
- <selector> sub-elements to the endpoint definition:
-
- ]]>]]>]]>
-
-
- When the MessageBus 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:
-
+
+ The <source-endpoint/> element
+
+ A SourceEndpoint connects an implementation of the Source
+ interface to a MessageChannel. The <source-endpoint/> therefore requires
+ these two references as well as the scheduling information so that the MessageBus can
+ manage the message-receiving tasks.
+
+
+]]>
+
+
+
+ The <target-endpoint/> element
+
+ A TargetEndpoint connects a MessageChannel to an implementation
+ of the Target interface. The <target-endpoint/> requires these two references.
+ ]]>
+ When the MessageBus 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:
+
]]>]]>]]>
-
-
-
- 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.
-
+
+
+ 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.
+
+
+
+ The <target-endpoint/> accepts additional attributes and child elements, but since these configuration
+ options are also available for the <handler-endpoint/> element, they will be discussed below.
+
+
+
+ The <handler-endpoint/> element
+
+ To create a Handler Endpoint instance, use the 'handler-endpoint' element with the 'input-channel' and
+ 'handler' attributes:
+ <handler-endpoint input-channel="exampleChannel" handler="exampleHandler"/>
+
+
+ The configuration above assumes that "exampleHandler" is an actual implementation of the
+ MessageHandler interface as described in .
+ To delegate to an arbitrary method of any object, simply add the "method" attribute.
+ <handler-endpoint input-channel="exampleChannel" handler="somePojo" method="someMethod"/>
+
+
+ In either case (MessageHandler 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 if an "output-channel" was provided in the
+ endpoint configuration:
+ <handler-endpoint input-channel="exampleChannel" output-channel="replyChannel"
+ handler="somePojo" method="someMethod"/>
+ If no "output-channel" is available, it will next check the message header's 'returnAddress'
+ property. If that value is available, it will then check its type. If it is a MessageChannel,
+ the reply message will be sent to that channel. If it is a String, then the endpoint will
+ attempt to resolve the channel by performing a lookup in the ChannelRegistry.
+
+
+ To reverse the order so that the 'returnAddress' is given priority over the endpoint's "output-channel", then
+ provide the "return-address-overrides" attribute with a value of 'true':
+ <handler-endpoint input-channel="exampleChannel" output-channel="replyChannel"
+ handler="somePojo" method="someMethod" return-address-overrides="true"/>
+ If neither is available, then a MessageHandlingException will be thrown.
+
+
- 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:
+ Handler and Target Endpoints also support MessageSelectors as described in
+ . To configure a selector with namespace support, simply add the
+ "selector" attribute to the endpoint definition and reference an implementation of the
+ MessageSelector interface.
+ ]]>
+
+
+ Another important configuration option for handler and target endpoints is the concurrency policy. Each
+ endpoint is capable of managing a thread pool for its handler or target, and the values you provide for that
+ pool's core and max size can make a substantial difference in how the handler or target performs under load.
+ These settings are available per-endpoint since the performance characteristics of an endpoint's handler or
+ target 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:
]]>]]>]]>
Recall the default concurrency policy values as listed in .
If no concurrency settings are provided (i.e. a null
- ConcurrencyPolicy), the endpoint's handler will be invoked in the caller's thread.
+ ConcurrencyPolicy), the endpoint's handler or target will be invoked in the caller's thread.
+ Note that the "caller" is usually the dispatcher except in the case of a DirectChannel
+ (see for more detail).
- The default queue capacity of 0 triggers the creation of a SynchronousQueue. 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.
+ For the concurrency settings, the default queue capacity of 0 triggers the creation of a
+ SynchronousQueue. 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.
@@ -228,28 +296,40 @@
]]>
- When exceptions occur in an endpoint's execution of its MessageHandler callback,
- those exceptions will be wrapped in ErrorMessages and sent to the Message Bus'
+ When exceptions occur in a concurrent endpoint's execution of its MessageHandler
+ callback, those exceptions will be wrapped in ErrorMessages and sent to the Message Bus'
'errorChannel' by default. To enable global error handling, simply register a handler on that channel. For
example, you can configure Spring Integration's PayloadTypeRouter as the handler of
an endpoint that is subscribed to the 'errorChannel'. That router can then spread the error messages across
- multiple channels based on Exception type.
+ multiple channels based on Exception type. However, since most of the errors will already
+ have been wrapped in MessageDeliveryException or MessageHandlingException,
+ the RootCauseErrorMessageRouter is typically a better option.
- 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.
+ The 'message-bus' element accepts several more optional attributes. First, you can control whether the
+ MessageBus will be started automatically (the default) or will require explicit startup
+ by invoking its start() method (MessageBus implements
+ Spring's Lifecycle interface):
+ ]]>
+
+
+ Another configurable property 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 if an endpoint registers a subscription by providing the
- name of a channel that the bus does not recognize.
- ]]>
+ methods will happen within the handler thread pool and not the dispatcher pool. However, when no concurrency
+ policy is provided to an endpoint, then it will be invoked in the dispatcher's thread (with the exception of
+ DirectChannels).
+
+
+ Also, the Message Bus is capable of automatically creating channel instances if an endpoint registers a
+ subscription by providing the name of a channel that the bus does not recognize.
+ ]]>
- The type of channel that gets created automatically by the bus can be customized by using the "channel-factory"
- element on the "message-bus" definition as in the following example:
-
-
-
+ Finally, the type of channel that gets created automatically by the bus can be customized by using the
+ "channel-factory" attribute on the "message-bus" definition as in the following example:
+
]]>
diff --git a/spring-integration-reference/src/core-api.xml b/spring-integration-reference/src/core-api.xml
index 379c879c69..5b31bf9423 100644
--- a/spring-integration-reference/src/core-api.xml
+++ b/spring-integration-reference/src/core-api.xml
@@ -169,7 +169,7 @@ target.send(new StringMessage("test"));
Spring Integration provides several different implementations of the
MessageChannel interface. Each is briefly described in the sections below.
-
+
QueueChannel
The QueueChannel implementation wraps a queue. It provides a no-argument constructor
@@ -185,7 +185,7 @@ target.send(new StringMessage("test"));
receive() will block indefinitely.
-
+
PriorityChannel
Whereas the QueueChannel enforces first-in/first-out (FIFO) ordering, the
@@ -196,7 +196,7 @@ target.send(new StringMessage("test"));
PriorityChannel's constructor.
-
+
RendezvousChannel
The RendezvousChannel enables a "direct-handoff" scenario where a sender will block
@@ -216,7 +216,7 @@ target.send(new StringMessage("test"));
call receive (optionally providing a timeout value) in order to block while waiting for a reply Message.
-
+
DirectChannel
The DirectChannel is significantly different than the channel implementations described
@@ -229,7 +229,7 @@ target.send(new StringMessage("test"));
that transaction (commit or rollback).
-
+
ThreadLocalChannel
The final channel implementation type is ThreadLocalChannel. This channel also delegates