From 4abb0fdc26361f774030b6f30809d32351d7ae8f Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Sun, 12 Jul 2009 14:18:58 +0000 Subject: [PATCH] INT-720 Updated documentation for new 'dispatcher' sub-element on channels --- spring-integration-reference/src/channel.xml | 92 +++++++++++++++----- 1 file changed, 72 insertions(+), 20 deletions(-) diff --git a/spring-integration-reference/src/channel.xml b/spring-integration-reference/src/channel.xml index 7de93029b7..cfa177cdba 100644 --- a/spring-integration-reference/src/channel.xml +++ b/spring-integration-reference/src/channel.xml @@ -183,29 +183,56 @@ - The DirectChannel can have one of two dispatcher strategies. These determine how - invocations will be ordered in the case that there are multiple handlers subscribed to the same channel. - The default strategy is "round-robin" and essentially load-balances across the handlers in rotation. The - other strategy is "failover" and it will always try to invoke the first handler, falling back to any - subsequent handlers as necessary. The order is determined by an optional order value defined on the - handlers themselves or, if no such value exists, the order in which the handlers are subscribed. + The DirectChannel internally delegates to a Message Dispatcher to invoke its + subscribed Message Handlers, and that dispatcher can have a load-balancing strategy. The load-balancer + determines how invocations will be ordered in the case that there are multiple handlers subscribed to the + same channel. When using the namespace support described below, the default strategy is + "round-robin" which essentially load-balances across the handlers in rotation. + + The "round-robin" strategy is currently the only implementation available out-of-the-box in Spring + Integration. Other strategy implementations may be added in future versions. + + + The load-balancer also works in combination with a boolean failover property. + If the "failover" value is true (the default), then the dispatcher will fall back to any subsequent + handlers as necessary when preceding handlers throw Exceptions. The order is determined by an optional + order value defined on the handlers themselves or, if no such value exists, the order in which the + handlers are subscribed. + + + If a certain situation requires that the dispatcher always try to invoke the first handler, then + fallback in the same fixed order sequence every time an error occurs, no load-balancing strategy should + be provided. In other words, the dispatcher still supports the failover boolean property even when no + load-balancing is enabled. Without load-balancing, however, the invocation of handlers will always begin + with the first according to their order. For example, this approach works well when there is a clear + definition of primary, secondary, tertiary, and so on. When using the namespace support, the "order" + attribute on any endpoint will determine that order. + + + Keep in mind that load-balancing and failover only apply when a channel has more than one + subscribed Message Handler. When using the namespace support, this means that more than one + endpoint shares the same channel reference in the "input-channel" attribute. +
ExecutorChannel The ExecutorChannel is a point-to-point channel that supports - the same dispatcher strategies as DirectChannel. The key difference is that - it delegates to an instance of TaskExecutor to perform the dispatch. - This means that the send method typically will not block, but it also means that the handler - invocation may not occur in the sender's thread. It therefore does not support - transactions spanning the sender and receiving handler. + the same dispatcher configuration as DirectChannel (load-balancing strategy + and the failover boolean property). The key difference between these two dispatching channel types + is that the ExecutorChannel delegates to an instance of + TaskExecutor to perform the dispatch. This means that the send method + typically will not block, but it also means that the handler invocation may not occur in the sender's + thread. It therefore does not support transactions spanning the sender and receiving + handler. Note that there are occasions where the sender may block. For example, when using a TaskExecutor with a rejection-policy that throttles back on the client (such as the ThreadPoolExecutor.CallerRunsPolicy), the sender's thread will execute the method directly anytime the thread pool is at its maximum capacity and the - executor's work queue is full. + executor's work queue is full. Since that situation would only occur in a non-predictable + way, that obviously cannot be relied upon for transactions.
@@ -364,6 +391,20 @@ public Message receive(final PollableChannel channel) { ... }]]>DirectChannel is the default type. ]]> + + A default channel will have a round-robin load-balancer and will also have + failover enabled (See the discussion in + for more detail). To disable one or both of these, add a <dispatcher/> sub-element and + configure the attributes: + + + + + + + +]]> +
QueueChannel Configuration @@ -406,15 +447,26 @@ public Message receive(final PollableChannel channel) { ... }]]> ExecutorChannel - To create an ExecutorChannel, add the 'task-executor' attribute. Its value - can reference any TaskExecutor within the context. For example, - this enables configuration of a thread-pool for dispatching messages to subscribed handlers. - As mentioned above, this does break the "single-threaded" execution context between sender - and receiver so that any active transaction context will not be shared by the invocation - of the handler (i.e. the handler may throw an Exception, but the send invocation has already - returned successfully). - <channel id="executorChannel" task-executor="someExecutor"/> + To create an ExecutorChannel, add the <dispatcher> sub-element along + with a 'task-executor' attribute. Its value can reference any TaskExecutor + within the context. For example, this enables configuration of a thread-pool for dispatching messages + to subscribed handlers. As mentioned above, this does break the "single-threaded" execution context + between sender and receiver so that any active transaction context will not be shared by the invocation + of the handler (i.e. the handler may throw an Exception, but the send invocation has already returned + successfully). + + +]]> + + The "load-balancer" and "failover" options are also both available on the dispatcher sub-element + as described above in . The same defaults + apply as well. So, the channel will have a round-robin load-balancing strategy with failover + enabled unless explicit configuration is provided for one or both of those attributes. + + +]]> +
PriorityChannel Configuration