The <int-file:outbound-channel-adapter> and <int-file:outbound-gateway> now support an append-new-line attribute. If set to true, a new line is appended to the file after a message is written. The default attribute value is false.

The ignore-hidden attribute has been introduced for the <int-file:inbound-channel-adapter> to pick up or not the hidden files from the source directory. It is true by default.

The FileWritingMessageHandler now also accepts InputStream as a valid message payload type.

The HeadDirectoryScanner can now be used with other FileListFilter s.

The LastModifiedFileListFilter has been added.

The WatchServiceDirectoryScanner is now available.

The AbstractPersistentFileListFilter has a new property flushOnUpdate which, when set to true, will flush() the metadata store if it implements Flushable (e.g. the PropertiesPersistingMetadataStore).

The TCP Serializers no longer flush() the OutputStream; this is now done by the TcpNxxConnection classes. If you are using the serializers directly within user code, you may have to flush() the OutputStream.

TcpConnectionServerExceptionEvent s are now published whenever an unexpected exception occurs on a TCP server socket (also added to 4.1.3, 4.0.7). See Section 31.5, “TCP Connection Events” for more information.

If a TCP server socket factory is configured to listen on a random port, the actual port chosen by the OS can now be obtained using getPort(). getServerSocketAddress() is also available.

See Section 31.3, “TCP Connection Factories” for more information.

The TcpOutboundGateway now supports remote-timeout-expression as an alternative to the existing remote-timeout attribute. This allows setting the timeout based on each message.

Also, the remote-timeout no longer defaults to the same value as reply-timeout which has a completely different meaning.

See Table 31.7, “TCP Outbound Gateway Attributes” for more information.

TcpConnection s now support getSslSession() to enable users to extract information from the session to add to message headers.

See Section 31.12, “IP Message Headers” for more information.

New events are now published whenever a correlation exception occurs - for example sending a message to a non-existent socket.

The TcpConnectionEventListeningMessageProducer is deprecated; use the generic event adapter instead.

See Section 31.5, “TCP Connection Events” for more information.

It is now possible to configure the reply listener in JMS outbound gateways to be initialized on-demand and stopped after an idle period, instead of being controlled by the gateway’s lifecycle.

See Section 20.5, “Outbound Gateway” for more information.

The error-channel now is used for the conversion errors, which have caused a transaction rollback and message redelivery previously.

See Section 20.2, “Message-Driven Channel Adapter” and Section 20.4, “Inbound Gateway” for more information.

When using an implicitly defined DefaultMessageListenerContainer, the default acknowledge is now transacted. transacted is recommended when using this container, to avoid message loss. This default now applies to the message-driven inbound adapter and the inbound gateway, it was already the default for jms-backed channels.

See Section 20.2, “Message-Driven Channel Adapter” and Section 20.4, “Inbound Gateway” for more information.

Namespace support for shared subscriptions (JMS 2.0) has been added to message-driven endpoints and the <int-jms:publish-subscribe-channel>. Previously, you had to wire up listener containers as <bean/> s to use shared connections.

See Chapter 20, JMS Support for more information.

The <int-amqp:outbound-gateway> now supports confirm-correlation-expression and confirm-(n)ack-channel attributes with similar purpose as for <int-amqp:outbound-channel-adapter>.

For both the outbound channel adapter and gateway, if the correlation data is a Message<?>, it will be the basis of the message on the ack/nack channel, with the additional header(s) added. Previously, any correlation data (including Message<?>) was returned as the payload of the ack/nack message.

The <int-amqp:inbound-gateway> now exposes the amqp-template attribute to allow more control over an external bean for the reply RabbitTemplate or even provide your own AmqpTemplate implementation. In addition the default-reply-to is exposed to be used if request message doesn’t have replyTo property.

See Chapter 11, AMQP Support for more information.

The HTTP Inbound Endpoints (<int-http:inbound-channel-adapter> and <int-http:inbound-gateway>) now allow the configuration of Cross-Origin Resource Sharing (CORS).

See Section 17.4.4, “Cross-Origin Resource Sharing (CORS) Support” for more information.

The HTTP inbound gateway can be configured as to what status code to return when a request times out. The default is now 500 Internal Server Error instead of 200 OK.

See Section 17.4.5, “Response StatusCode” for more information.

Documentation is provided for when proxying multipart/form-data requests. See Chapter 17, HTTP Support for more information.

When using Java 8, gateway methods can now return CompletableFuture<?>. See the section called “CompletableFuture” for more information.

The request and reply timeout properties are now String instead of Long to allow configuration with property placeholders or SpEL. See Section 8.3.6, “@MessagingGateway Annotation”.

This release includes some performance improvements for aggregating components (aggregator, resequencer, etc), by more efficiently removing messages from groups when they are released. New methods (removeMessagesFromGroup) have been added to the message store. Set the removeBatchSize property (default 100) to adjust the number of messages deleted in each operation. Currently, JDBC, Redis and MongoDB message stores support this property.

When using a ref or inner bean for the aggregator, it is now possible to bind a MessageGroupProcessor directly. In addition, a SimpleMessageGroupProcessor is provided that simply returns the collection of messages in the group. When an output processor produces a collection of Message<?>, the aggregator releases those messages individually. Configuring the SimpleMessageGroupProcessor makes the aggregator a message barrier, were messages are held up until they all arrive, and are then released individually. See Section 6.4, “Aggregator” for more information.

You can now specify a remote-directory-expression on the inbound channel adapters, to determine the directory at runtime. See Chapter 15, FTP/FTPS Adapters and Chapter 27, SFTP Adapters for more information.

When use FTP/SFTP outbound gateways to operate on multiple files (mget, mput), it is possible for an exception to occur after part of the request is completed. If such a condition occurs, a PartialSuccessException is thrown containing the partial results. See Section 15.6, “FTP Outbound Gateway” and Section 27.8, “SFTP Outbound Gateway” for more information.

A delegating session factory is now available, enabling the selection of a particular session factory based on some thread context value.

See Section 15.3, “Delegating Session Factory” and Section 27.3, “Delegating Session Factory” for more information.

Previously, the DefaultSftpSessionFactory unconditionally allowed connections to unknown hosts. This is now configurable (default false).

The factory now requires a configured knownHosts file unless the allowUnknownKeys property is true (default false).

See Section 27.2.1, “Configuration Properties” for more information.

The MessageSessionCallback<F, T> has been introduced to perform any custom Session operation(s) with the requestMessage context in the <int-(s)ftp:outbound-gateway/>.

See Section 15.9, “MessageSessionCallback” and Section 27.10, “MessageSessionCallback” for more information.

Since Message Channels may or may not buffer Messages (as discussed in the overview), there are two sub-interfaces defining the buffering (pollable) and non-buffering (subscribable) channel behavior. Here is the definition of PollableChannel.

public interface PollableChannel extends MessageChannel {

    Message<?> receive();

    Message<?> receive(long timeout);

}

Similar to the send methods, when receiving a message, the return value will be null in the case of a timeout or interrupt.

The SubscribableChannel base interface is implemented by channels that send Messages directly to their subscribed MessageHandler s. Therefore, they do not provide receive methods for polling, but instead define methods for managing those subscribers:

public interface SubscribableChannel extends MessageChannel {

    boolean subscribe(MessageHandler handler);

    boolean unsubscribe(MessageHandler handler);

}

The PublishSubscribeChannel implementation broadcasts any Message sent to it to all of its subscribed handlers. This is most often used for sending_Event Messages_ whose primary role is notification as opposed to Document Messages which are generally intended to be processed by a single handler. Note that the PublishSubscribeChannel is intended for sending only. Since it broadcasts to its subscribers directly when its` send(Message)` method is invoked, consumers cannot poll for Messages (it does not implement PollableChannel and therefore has no receive() method). Instead, any subscriber must be a MessageHandler itself, and the subscriber’s handleMessage(Message) method will be invoked in turn.

Prior to version 3.0, invoking the send method on a PublishSubscribeChannel that had no subscribers returned false. When used in conjunction with a MessagingTemplate, a MessageDeliveryException was thrown. Starting with version 3.0, the behavior has changed such that a send is always considered successful if at least the minimum subscribers are present (and successfully handle the message). This behavior can be modified by setting the minSubscribers property, which defaults to 0.

	Note
	If a TaskExecutor is used, only the presence of the correct number of subscribers is used for this determination, because the actual handling of the message is performed asynchronously.

The QueueChannel implementation wraps a queue. Unlike the PublishSubscribeChannel, the QueueChannel has point-to-point semantics. In other words, even if the channel has multiple consumers, only one of them should receive any Message sent to that channel. It provides a default no-argument constructor (providing an essentially unbounded capacity of Integer.MAX_VALUE) as well as a constructor that accepts the queue capacity:

public QueueChannel(int capacity)

A channel that has not reached its capacity limit will store messages in its internal queue, and the send() method will return immediately even if no receiver is ready to handle the message. If the queue has reached capacity, then the sender will block until room is available. Or, if using the send call that accepts a timeout, it will block until either room is available or the timeout period elapses, whichever occurs first. Likewise, a receive call will return immediately if a message is available on the queue, but if the queue is empty, then a receive call may block until either a message is available or the timeout elapses. In either case, it is possible to force an immediate return regardless of the queue’s state by passing a timeout value of 0. Note however, that calls to the no-arg versions of send() and receive() will block indefinitely.

Whereas the QueueChannel enforces first-in/first-out (FIFO) ordering, the PriorityChannel is an alternative implementation that allows for messages to be ordered within the channel based upon a priority. By default the priority is determined by the priority header within each message. However, for custom priority determination logic, a comparator of type Comparator<Message<?>> can be provided to the PriorityChannel's constructor.

The RendezvousChannel enables a "direct-handoff" scenario where a sender will block until another party invokes the channel’s receive() method or vice-versa. Internally, this implementation is quite similar to the QueueChannel except that it uses a SynchronousQueue (a zero-capacity implementation of BlockingQueue). This works well in situations where the sender and receiver are operating in different threads but simply dropping the message in a queue asynchronously is not appropriate. In other words, with a RendezvousChannel at least the sender knows that some receiver has accepted the message, whereas with a QueueChannel, the message would have been stored to the internal queue and potentially never received.

Tip

Keep in mind that all of these queue-based channels are storing messages in-memory only by default. When persistence is required, you can either provide a message-store attribute within the queue element to reference a persistent MessageStore implementation, or you can replace the local channel with one that is backed by a persistent broker, such as a JMS-backed channel or Channel Adapter. The latter option allows you to take advantage of any JMS provider’s implementation for message persistence, and it will be discussed in Chapter 20, JMS Support. However, when buffering in a queue is not necessary, the simplest approach is to rely upon the DirectChannel discussed next.

The RendezvousChannel is also useful for implementing request-reply operations. The sender can create a temporary, anonymous instance of RendezvousChannel which it then sets as the replyChannel header when building a Message. After sending that Message, the sender can immediately call receive (optionally providing a timeout value) in order to block while waiting for a reply Message. This is very similar to the implementation used internally by many of Spring Integration’s request-reply components.

The DirectChannel has point-to-point semantics but otherwise is more similar to the PublishSubscribeChannel than any of the queue-based channel implementations described above. It implements the SubscribableChannel interface instead of the PollableChannel interface, so it dispatches Messages directly to a subscriber. As a point-to-point channel, however, it differs from the PublishSubscribeChannel in that it will only send each Message to a single subscribed MessageHandler.

In addition to being the simplest point-to-point channel option, one of its most important features is that it enables a single thread to perform the operations on "both sides" of the channel. For example, if a handler is subscribed to a DirectChannel, then sending a Message to that channel will trigger invocation of that handler’s handleMessage(Message) method directly in the sender’s thread, before the send() method invocation can return.

The key motivation for providing a channel implementation with this behavior is to support transactions that must span across the channel while still benefiting from the abstraction and loose coupling that the channel provides. If the send call is invoked within the scope of a transaction, then the outcome of the handler’s invocation (e.g. updating a database record) will play a role in determining the ultimate result of that transaction (commit or rollback).

Note

Since the DirectChannel is the simplest option and does not add any additional overhead that would be required for scheduling and managing the threads of a poller, it is the default channel type within Spring Integration. The general idea is to define the channels for an application and then to consider which of those need to provide buffering or to throttle input, and then modify those to be queue-based PollableChannels. Likewise, if a channel needs to broadcast messages, it should not be a DirectChannel but rather a PublishSubscribeChannel. Below you will see how each of these can be configured.

The DirectChannel internally delegates to a Message Dispatcher to invoke its subscribed Message Handlers, and that dispatcher can have a load-balancing strategy exposed via_load-balancer_ or load-balancer-ref attributes (mutually exclusive). The load balancing strategy is used by the Message Dispatcher to help determine how Messages are distributed amongst Message Handlers in the case that there are multiple Message Handlers subscribed to the same channel. As a convinience the load-balancer attribute exposes enumeration of values pointing to pre-existing implementations of LoadBalancingStrategy. The "round-robin" (load-balances across the handlers in rotation) and "none" (for the cases where one wants to explicitely disable load balancing) are the only available values. Other strategy implementations may be added in future versions. However, since version 3.0 you can provide your own implementation of the LoadBalancingStrategy and inject it using load-balancer-ref attribute which should point to a bean that implements LoadBalancingStrategy.

<int:channel id="lbRefChannel">
  <int:dispatcher load-balancer-ref="lb"/>
</int:channel>

<bean id="lb" class="foo.bar.SampleLoadBalancingStrategy"/>

Note that load-balancer or load-balancer-ref attributes are mutually exclusive.

The load-balancing 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.

	Note
	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.

The ExecutorChannel is a point-to-point channel that supports 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.

Tip

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. Since that situation would only occur in a non-predictable way, that obviously cannot be relied upon for transactions.

Spring Integration 1.0 provided a ThreadLocalChannel implementation, but that has been removed as of 2.0. Now, there is a more general way for handling the same requirement by simply adding a "scope" attribute to a channel. The value of the attribute can be any name of a Scope that is available within the context. For example, in a web environment, certain Scopes are available, and any custom Scope implementations can be registered with the context. Here’s an example of a ThreadLocal-based scope being applied to a channel, including the registration of the Scope itself.

<int:channel id="threadScopedChannel" scope="thread">
     <int:queue />
</int:channel>

<bean class="org.springframework.beans.factory.config.CustomScopeConfigurer">
    <property name="scopes">
        <map>
            <entry key="thread" value="org.springframework.context.support.SimpleThreadScope" />
        </map>
    </property>
</bean>

The channel above also delegates to a queue internally, but the channel is bound to the current thread, so the contents of the queue are as well. That way the thread that sends to the channel will later be able to receive those same Messages, but no other thread would be able to access them. While thread-scoped channels are rarely needed, they can be useful in situations where DirectChannels are being used to enforce a single thread of operation but any reply Messages should be sent to a "terminal" channel. If that terminal channel is thread-scoped, the original sending thread can collect its replies from it.

Now, since any channel can be scoped, you can define your own scopes in addition to Thread Local.

As mentioned above, DirectChannel is the default type.

<int:channel id="directChannel"/>

A default channel will have a round-robin load-balancer and will also have failover enabled (See the discussion in the section called “DirectChannel” for more detail). To disable one or both of these, add a <dispatcher/> sub-element and configure the attributes:

<int:channel id="failFastChannel">
    <int:dispatcher failover="false"/>
</channel>

<int:channel id="channelWithFixedOrderSequenceFailover">
    <int:dispatcher load-balancer="none"/>
</int:channel>

There are times when a consumer can only process a particular type of payload and you need to therefore ensure the payload type of input Messages. Of course the first thing that comes to mind is Message Filter. However all that Message Filter will do is filter out Messages that are not compliant with the requirements of the consumer. Another way would be to use a Content Based Router and route Messages with non-compliant data-types to specific Transformers to enforce transformation/conversion to the required data-type. This of course would work, but a simpler way of accomplishing the same thing is to apply the Datatype Channel pattern. You can use separate Datatype Channels for each specific payload data-type.

To create a Datatype Channel that only accepts messages containing a certain payload type, provide the fully-qualified class name in the channel element’s datatype attribute:

<int:channel id="numberChannel" datatype="java.lang.Number"/>

Note that the type check passes for any type that is assignable to the channel’s datatype. In other words, the "numberChannel" above would accept messages whose payload is java.lang.Integer or java.lang.Double. Multiple types can be provided as a comma-delimited list:

<int:channel id="stringOrNumberChannel" datatype="java.lang.String,java.lang.Number"/>

So the numberChannel above will only accept Messages with a data-type of java.lang.Number. But what happens if the payload of the Message is not of the required type? It depends on whether you have defined a bean named "integrationConversionService" that is an instance of Spring’s Conversion Service. If not, then an Exception would be thrown immediately, but if you do have an "integrationConversionService" bean defined, it will be used in an attempt to convert the Message’s payload to the acceptable type.

You can even register custom converters. For example, let’s say you are sending a Message with a String payload to the numberChannel we configured above.

MessageChannel inChannel = context.getBean("numberChannel", MessageChannel.class);
inChannel.send(new GenericMessage<String>("5"));

Typically this would be a perfectly legal operation, however since we are using Datatype Channel the result of such operation would generate an exception:

Exception in thread "main" org.springframework.integration.MessageDeliveryException:
Channel 'numberChannel'
expected one of the following datataypes [class java.lang.Number],
but received [class java.lang.String]
…

And rightfully so since we are requiring the payload type to be a Number while sending a String. So we need something to convert String to a Number. All we need to do is implement a Converter.

public static class StringToIntegerConverter implements Converter<String, Integer> {
	public Integer convert(String source) {
		return Integer.parseInt(source);
	}
}

Then, register it as a Converter with the Integration Conversion Service:

<int:converter ref="strToInt"/>

<bean id="strToInt" class="org.springframework.integration.util.Demo.StringToIntegerConverter"/>

When the converter element is parsed, it will create the "integrationConversionService" bean on-demand if one is not already defined. With that Converter in place, the send operation would now be successful since the Datatype Channel will use that Converter to convert the String payload to an Integer.

	Note
	For more information regarding Payload Type Conversion, please read Section 8.1.6, “Payload Type Conversion”.

Beginning with version 4.0, the integrationConversionService is invoked by the DefaultDatatypeChannelMessageConverter, which looks up the conversion service in the application context. To use a different conversion technique, you can specify the message-converter attribute on the channel. This must be a reference to a MessageConverter implementation. Only the fromMessage method is used, which provides the converter with access to the message headers (for example if the conversion might need information from the headers, such as content-type). The method can return just the converted payload, or a full Message object. If the latter, the converter must be careful to copy all the headers from the inbound message.

Alternatively, declare a <bean/> of type MessageConverter with an id "datatypeChannelMessageConverter" and that converter will be used by all channels with a datatype.

To create a QueueChannel, use the <queue/> sub-element. You may specify the channel’s capacity:

<int:channel id="queueChannel">
    <queue capacity="25"/>
</int:channel>

	Note
	If you do not provide a value for the capacity attribute on this <queue/> sub-element, the resulting queue will be unbounded. To avoid issues such as OutOfMemoryErrors, it is highly recommended to set an explicit value for a bounded queue.

Persistent QueueChannel Configuration

Since a QueueChannel provides the capability to buffer Messages, but does so in-memory only by default, it also introduces a possibility that Messages could be lost in the event of a system failure. To mitigate this risk, a QueueChannel may be backed by a persistent implementation of the MessageGroupStore strategy interface. For more details on MessageGroupStore and MessageStore see Section 9.4, “Message Store”.

When a QueueChannel receives a Message, it will add it to the Message Store, and when a Message is polled from a QueueChannel, it is removed from the Message Store.

By default, a QueueChannel stores its Messages in an in-memory Queue and can therefore lead to the lost message scenario mentioned above. However Spring Integration provides persistent stores, such as the JdbcMessageStore.

You can configure a Message Store for any QueueChannel by adding the message-store attribute as shown in the next example.

<int:channel id="dbBackedChannel">
    <int:queue message-store="channelStore"/>
</int:channel>

<bean id="channelStore" class="o.s.i.jdbc.store.JdbcChannelMessageStore">
    <property name="dataSource" ref="dataSource"/>
    <property name="channelMessageStoreQueryProvider" ref="queryProvider"/>
</bean>

The Spring Integration JDBC module also provides schema DDL for a number of popular databases. These schemas are located in the org.springframework.integration.jdbc.store.channel package of that module (spring-integration-jdbc).

	Important
	One important feature is that with any transactional persistent store (e.g., JdbcChannelMessageStore), as long as the poller has a transaction configured, a Message removed from the store will only be permanently removed if the transaction completes successfully, otherwise the transaction will roll back and the Message will not be lost.

Many other implementations of the Message Store will be available as the growing number of Spring projects related to "NoSQL" data stores provide the underlying support. Of course, you can always provide your own implementation of the MessageGroupStore interface if you cannot find one that meets your particular needs.

Since version 4.0, it is recommended that QueueChannel s are configured to use a ChannelMessageStore if possible. These are generally optimized for this use, when compared with a general message store. If the ChannelMessageStore is a ChannelPriorityMessageStore the messages will be received in FIFO within priority order. The notion of priority is determined by the message store implementation. For example the Java Configuration for the Section 22.3.1, “MongoDB Channel Message Store”:

@Bean
public BasicMessageGroupStore mongoDbChannelMessageStore(MongoDbFactory mongoDbFactory) {
    MongoDbChannelMessageStore store = new MongoDbChannelMessageStore(mongoDbFactory);
    store.setPriorityEnabled(true);
    return store;
}

@Bean
public PollableChannel priorityQueue(BasicMessageGroupStore mongoDbChannelMessageStore) {
   return new QueueChannel(new MessageGroupQueue(mongoDbChannelMessageStore, "priorityQueue"));
}

	Note
	Pay attention to the MessageGroupQueue class. That is a BlockingQueue implementation to utilize the MessageGroupStore operations.

The same with Java DSL may look like:

@Bean
public IntegrationFlow priorityFlow(PriorityCapableChannelMessageStore mongoDbChannelMessageStore) {
    return IntegrationFlows.from((Channels c) ->
            c.priority("priorityChannel", mongoDbChannelMessageStore, "priorityGroup"))
            ....
            .get();
}

Another option to customize the QueueChannel environment is provided by the ref attribute of the <int:queue> sub-element. This attribute implies the reference to any java.util.Queue implementation. An implementation is provided by the Project Reactor and its reactor.queue.PersistentQueue implementation for the IndexedChronicle:

@Bean
public QueueChannel reactorQueue() {
    return new QueueChannel(new PersistentQueueSpec<Message<?>>()
                    .codec(new JavaSerializationCodec<Message<?>>())
                    .basePath(System.getProperty("java.io.tmpdir") + "/reactor-queue")
                    .get());
}

To create a PublishSubscribeChannel, use the <publish-subscribe-channel/> element. When using this element, you can also specify the task-executor used for publishing Messages (if none is specified it simply publishes in the sender’s thread):

<int:publish-subscribe-channel id="pubsubChannel" task-executor="someExecutor"/>

If you are providing a Resequencer or Aggregator downstream from a PublishSubscribeChannel, then you can set the apply-sequence property on the channel to true. That will indicate that the channel should set the sequence-size and sequence-number Message headers as well as the correlation id prior to passing the Messages along. For example, if there are 5 subscribers, the sequence-size would be set to 5, and the Messages would have sequence-number header values ranging from 1 to 5.

<int:publish-subscribe-channel id="pubsubChannel" apply-sequence="true"/>

	Note
	The apply-sequence value is false by default so that a Publish Subscribe Channel can send the exact same Message instances to multiple outbound channels. Since Spring Integration enforces immutability of the payload and header references, the channel creates new Message instances with the same payload reference but different header values when the flag is set to true.

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).

<int:channel id="executorChannel">
    <int:dispatcher task-executor="someExecutor"/>
</int:channel>

Note

The load-balancer and failover options are also both available on the <dispatcher/> sub-element as described above in the section called “DirectChannel Configuration”. 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. <int:channel id="executorChannelWithoutFailover"> <int:dispatcher task-executor="someExecutor" failover="false"/> </int:channel>

To create a PriorityChannel, use the <priority-queue/> sub-element:

<int:channel id="priorityChannel">
    <int:priority-queue capacity="20"/>
</int:channel>

By default, the channel will consult the priority header of the message. 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 QueueChannel, it also supports a capacity attribute. The following example demonstrates all of these:

<int:channel id="priorityChannel" datatype="example.Widget">
    <int:priority-queue comparator="widgetComparator"
                    capacity="10"/>
</int:channel>

Since version 4.0, the priority-channel child element supports the message-store option (comparator is not allowed in that case). The message store must be a PriorityCapableChannelMessageStore and, in this case, the namespace parser will declare a QueueChannel instead of a PriorityChannel. Implementations of the PriorityCapableChannelMessageStore are currently provided for Redis, JDBC and MongoDB. See the section called “QueueChannel Configuration”.

A RendezvousChannel is created when the queue sub-element is a <rendezvous-queue>. It does not provide any additional configuration options to those described above, and its queue does not accept any capacity value since it is a 0-capacity direct handoff queue.

<int:channel id="rendezvousChannel"/>
    <int:rendezvous-queue/>
</int:channel>

Any channel can be configured with a "scope" attribute.

<int:channel id="threadLocalChannel" scope="thread"/>

Message channels may also have interceptors as described in Section 4.1.3, “Channel Interceptors”. The <interceptors/> sub-element can be added within a <channel/> (or the more specific element types). Provide the ref attribute to reference any Spring-managed object that implements the ChannelInterceptor interface:

<int:channel id="exampleChannel">
    <int:interceptors>
        <ref bean="trafficMonitoringInterceptor"/>
    </int:interceptors>
</int:channel>

In general, it is a good idea to define the interceptor implementations in a separate location since they usually provide common behavior that can be reused across multiple channels.

Channel Interceptors provide a clean and concise way of applying cross-cutting behavior per individual channel. If the same behavior should be applied on multiple channels, configuring the same set of interceptors for each channel would not be the most efficient way. To avoid repeated configuration while also enabling interceptors to apply to multiple channels, Spring Integration provides Global Interceptors. Look at the example below:

<int:channel-interceptor pattern="input*, bar*, foo" order="3">
    <bean class="foo.barSampleInterceptor"/>
</int:channel-interceptor>

or

<int:channel-interceptor ref="myInterceptor" pattern="input*, bar*, foo" order="3"/>

<bean id="myInterceptor" class="foo.barSampleInterceptor"/>

Each <channel-interceptor/> element allows you to define a global interceptor which will be applied on all channels that match any patterns defined via the pattern attribute. In the above case the global interceptor will be applied on the foo channel and all other channels that begin with bar or input. The order attribute allows you to manage where this interceptor will be injected if there are multiple interceptors on a given channel. For example, channel inputChannel could have individual interceptors configured locally (see below):

<int:channel id="inputChannel"> 
  <int:interceptors>
    <int:wire-tap channel="logger"/> 
  </int:interceptors>
</int:channel>

A reasonable question is how will a global interceptor be injected in relation to other interceptors configured locally or through other global interceptor definitions? The current implementation provides a very simple mechanism for defining the order of interceptor execution. A positive number in the order attribute will ensure interceptor injection after any existing interceptors and a negative number will ensure that the interceptor is injected before existing interceptors. This means that in the above example, the global interceptor will be injected AFTER (since its order is greater than 0) the wire-tap interceptor configured locally. If there were another global interceptor with a matching pattern, its order would be determined by comparing the values of the order attribute. To inject a global interceptor BEFORE the existing interceptors, use a negative value for the order attribute.

	Note
	Note that both the order and pattern attributes are optional. The default value for order will be 0 and for pattern, the default is * (to match all channels).

As mentioned above, Spring Integration provides a simple Wire Tap interceptor out of the box. You can configure a Wire Tap on any channel within an <interceptors/> element. This is especially useful for debugging, and can be used in conjunction with Spring Integration’s logging Channel Adapter as follows:

<int:channel id="in">
    <int:interceptors>
        <int:wire-tap channel="logger"/>
    </int:interceptors>
</int:channel>

<int:logging-channel-adapter id="logger" level="DEBUG"/>

Tip

The logging-channel-adapter also accepts an expression attribute so that you can evaluate a SpEL expression against payload and/or headers variables. Alternatively, to simply log the full Message toString() result, provide a value of "true" for the log-full-message attribute. That is false by default so that only the payload is logged. Setting that to true enables logging of all headers in addition to the payload. The expression option does provide the most flexibility, however (e.g. expression="payload.user.name").

A little more on Wire Tap

One of the common misconceptions about the wire tap and other similar components (Section B.1, “Message Publishing Configuration”) is that they are automatically asynchronous in nature. Wire-tap as a component is not invoked asynchronously be default. Instead, Spring Integration focuses on a single unified approach to configuring asynchronous behavior: the Message Channel. What makes certain parts of the message flow sync or async is the type of Message Channel that has been configured within that flow. That is one of the primary benefits of the Message Channel abstraction. From the inception of the framework, we have always emphasized the need and the value of the Message Channel as a first-class citizen of the framework. It is not just an internal, implicit realization of the EIP pattern, it is fully exposed as a configurable component to the end user. So, the Wire-tap component is ONLY responsible for performing the following 3 tasks:

It is essentially a variation of the Bridge, but it is encapsulated within a channel definition (and hence easier to enable and disable without disrupting a flow). Also, unlike the bridge, it basically forks another message flow. Is that flow synchronous or asynchronous? The answer simply depends on the type of Message Channel that channelB is. And, now you know that we have: Direct Channel, Pollable Channel, and Executor Channel as options. The last two do break the thread boundary making communication via such channels asynchronous simply because the dispatching of the message from that channel to its subscribed handlers happens on a different thread than the one used to send the message to that channel. That is what is going to make your wire-tap flow sync or async. It is consistent with other components within the framework (e.g., Message Publisher) and actually brings a level of consistency and simplicity by sparing you from worrying in advance (other than writing thread safe code) whether a particular piece of code should be implemented as sync or async. The actual wiring of two pieces of code (component A and component B) via Message Channel is what makes their collaboration sync or async. You may even want to change from sync to async in the future and Message Channel is what’s going to allow you to do it swiftly without ever touching the code.

One final point regarding the Wire Tap is that, despite the rationale provided above for not being async by default, one should keep in mind it is usually desirable to hand off the Message as soon as possible. Therefore, it would be quite common to use an asynchronous channel option as the wire-tap’s outbound channel. Nonetheless, another reason that we do not enforce asynchronous behavior by default is that you might not want to break a transactional boundary. Perhaps you are using the Wire Tap for auditing purposes, and you DO want the audit Messages to be sent within the original transaction. As an example, you might connect the wire-tap to a JMS outbound-channel-adapter. That way, you get the best of both worlds: 1) the sending of a JMS Message can occur within the transaction while 2) it is still a "fire-and-forget" action thereby preventing any noticeable delay in the main message flow.

Important

Starting with version 4.0, it is important to avoid circular references when an interceptor (such as WireTap) references a channel itself. You need to exclude such channels from those being intercepted by the current interceptor. This can be done with appropriate patterns or programmatically. If you have a custom ChannelInterceptor that references a channel, consider implementing VetoCapableInterceptor. That way, the framework will ask the interceptor if it’s OK to intercept each channel that is a candidate based on the pattern. You can also add runtime protection in the interceptor methods that ensures that the channel is not one that is referenced by the interceptor. The WireTap uses both of these techniques.

Wire taps can be made conditional, using the selector or selector-expression attributes. The selector references a MessageSelector bean, which can determine at runtime whether the message should go to the tap channel. Similarly, the` selector-expression` is a boolean SpEL expression that performs the same purpose - if the expression evaluates to true, the message will be sent to the tap channel.

It is possible to configure a global wire tap as a special case of the the section called “Global Channel Interceptor Configuration”. Simply configure a top level wire-tap element. Now, in addition to the normal wire-tap namespace support, the pattern and order attributes are supported and work in exactly the same way as with the channel-interceptor

<int:wire-tap pattern="input*, bar*, foo" order="3" channel="wiretapChannel"/>

	Tip
	A global wire tap provides a convenient way to configure a single channel wire tap externally without modifying the existing channel configuration. Simply set the pattern attribute to the target channel name. For example, This technique may be used to configure a test case to verify messages on a channel.

Advice objects, in an advice-chain on a poller, advise the whole polling task (message retrieval and processing). These "around advice" methods do not have access to any context for the poll, just the poll itself. This is fine for requirements such as making a task transactional, or skipping a poll due to some external condition as discussed above. What if we wish to take some action depending on the result of the receive part of the poll, or if we want to adjust the poller depending on conditions?

Version 4.2 introduced the AbstractMessageSourceAdvice. Any Advice objects in the advice-chain that subclass this class, are applied to just the receive operation. Such classes implement the following methods:

beforeReceive(MessageSource<?> source)

This method is called before the MessageSource.receive() method. It enables you to examine and or reconfigure the source at this time. Returning false cancels this poll (similar to the PollSkipAdvice mentioned above).

Message<?> afterReceive(Message<?> result, MessageSource<?> source)

This method is called after the receive() method; again, you can reconfigure the source, or take any action perhaps depending on the result (which can be null if there was no message created by the source). You can even return a different message!

This advice is a simple implementation of AbstractMessageSourceAdvice, when used in conjunction with a DynamicPeriodicTrigger, it adjuststhe polling frequency depending on whether or not the previous poll resulted in a message or not. The poller must also have a reference to the same DynamicPeriodicTrigger.

	Important: Async Handoff
	This advice modifies the trigger based on the receive() result. This will only work if the advice is called on the poller thread. It will not work if the poller has a task-executor. To use this advice where you wish to use async operations after the result of a poll, do the async handoff later, perhaps by using an ExecutorChannel.

Advice Chain Ordering

It is important to understand how the advice chain is processed during initialization. Advice objects that do not extend AbstractMessageSourceAdvice are applied to the whole poll process and are all invoked first, in order, before any AbstractMessageSourceAdvice; then AbstractMessageSourceAdvice objects are invoked in order around the MessageSource receive() method. If you have, say Advice objects a, b, c, d, where b and d are AbstractMessageSourceAdvice, they will be applied in the order a, c, b, d. Also, if a MessageSource is already a Proxy, the AbstractMessageSourceAdvice will be invoked after any existing Advice objects. If you wish to change the order, you should wire up the proxy yourself.

Starting with Spring Framework 4.0 and Spring Integration 4.0, the core Messaging abstraction has been moved to the spring-messaging module and the new MessageHeaderAccessor API has been introduced to provide additional abstraction over Messaging implementations. All (core) Spring Integration specific Message Headers constants are now declared in the IntegrationMessageHeaderAccessor class:

IntegrationMessageHeaderAccessor.
    CORRELATION_ID

java.lang.Object

IntegrationMessageHeaderAccessor.
    SEQUENCE_NUMBER

java.lang.Integer

IntegrationMessageHeaderAccessor.
    SEQUENCE_SIZE

java.lang.Integer

IntegrationMessageHeaderAccessor.
    EXPIRATION_DATE

java.lang.Long

IntegrationMessageHeaderAccessor.
    PRIORITY

java.lang.Integer

IntegrationMessageHeaderAccessor.
    DUPLICATE_MESSAGE

java.lang.Boolean

Convenient typed getters for some of these headers are provided on the IntegrationMessageHeaderAccessor class:

IntegrationMessageHeaderAccessor accessor = new IntegrationMessageHeaderAccessor(message);
int sequenceNumber = accessor.getSequenceNumber();
Object correlationId = accessor.getCorrelationId();
...

The following headers also appear in the IntegrationMessageHeaderAccessor but are generally not used by user code; their inclusion here is for completeness:

IntegrationMessageHeaderAccessor.
    SEQUENCE_DETAILS

java.util.List<
List<Object>>

IntegrationMessageHeaderAccessor.
    ROUTING_SLIP

java.util.Map<
List<Object>, Integer>

When a message transitions through an application, each time it is mutated (e.g. by a transformer) a new message id is assigned. The message id is a UUID. Beginning with Spring Integration 3.0, the default strategy used for id generation is more efficient than the previous java.util.UUID.randomUUID() implementation. It uses simple random numbers based on a secure random seed, instead of creating a secure random number each time.

A different UUID generation strategy can be selected by declaring a bean that implements org.springframework.util.IdGenerator in the application context.

Important

Only one UUID generation strategy can be used in a classloader. This means that if two or more application contexts are running in the same classloader, they will share the same strategy. If one of the contexts changes the strategy, it will be used by all contexts. If two or more contexts in the same classloader declare a bean of type org.springframework.util.IdGenerator, they must all be an instance of the same class, otherwise the context attempting to replace a custom strategy will fail to initialize. If the strategy is the same, but parameterized, the strategy in the first context to initialize will be used.

In addition to the default strategy, two additional IdGenerators are provided; org.springframework.util.JdkIdGenerator uses the previous UUID.randomUUID() mechanism; o.s.i.support.IdGenerators.SimpleIncrementingIdGenerator can be used in cases where a UUID is not really needed and a simple incrementing value is sufficient.

The following parameters are valid for all routers inside and outside of chains.

	Note
	A Message will only be sent to the default-output-channel if resolution-required is false and the channel is not resolved.

	Note
	A Message will only be sent to the default-output-channel, if specified, when resolution-required is false and the channel is not resolved.

The exact behavior of this attribute depends on the type of the Channel messages are sent to. For example, when using direct channels (single threaded), send-failures can be caused by exceptions thrown by components much further down-stream. However, when sending messages to a simple queue channel (asynchronous) the likelihood of an exception to be thrown is rather remote.

Note

While most routers will route to a single channel, they are allowed to return more than one channel name. The recipient-list-router, for instance, does exactly that. If you set this attribute to true on a router that only routes to a single channel, any caused exception is simply swallowed, which usually makes little sense to do. In that case it would be better to catch the exception in an error flow at the flow entry point. Therefore, setting the ignore-send-failures attribute to true usually makes more sense when the router implementation returns more than one channel name, because the other channel(s) following the one that fails would still receive the Message.

This attribute defaults to false.

The following parameters are valid only across all top-level routers that are ourside of chains.

A PayloadTypeRouter will send Messages to the channel as defined by payload-type mappings.

<bean id="payloadTypeRouter"
      class="org.springframework.integration.router.PayloadTypeRouter">
    <property name="channelMapping">
        <map>
            <entry key="java.lang.String" value-ref="stringChannel"/>
            <entry key="java.lang.Integer" value-ref="integerChannel"/>
        </map>
    </property>
</bean>

Configuration of the PayloadTypeRouter is also supported via the namespace provided by Spring Integration (see Section F.2, “Namespace Support”), which essentially simplifies configuration by combining the <router/> configuration and its corresponding implementation defined using a <bean/> element into a single and more concise configuration element. The example below demonstrates a PayloadTypeRouter configuration which is equivalent to the one above using the namespace support:

<int:payload-type-router input-channel="routingChannel">
    <int:mapping type="java.lang.String" channel="stringChannel" />
    <int:mapping type="java.lang.Integer" channel="integerChannel" />
</int:payload-type-router>

A HeaderValueRouter will send Messages to the channel based on the individual header value mappings. When a HeaderValueRouter is created it is initialized with the name of the header to be evaluated. The value of the header could be one of two things:

1. Arbitrary value

2. Channel name

If arbitrary then additional mappings for these header values to channel names is required, otherwise no additional configuration is needed.

Spring Integration provides a simple namespace-based XML configuration to configure a HeaderValueRouter. The example below demonstrates two types of namespace-based configuration for the HeaderValueRouter.

1. Configuration where mapping of header values to channels is required

<int:header-value-router input-channel="routingChannel" header-name="testHeader">
    <int:mapping value="someHeaderValue" channel="channelA" />
    <int:mapping value="someOtherHeaderValue" channel="channelB" />
</int:header-value-router>

During the resolution process this router may encounter channel resolution failures, causing an exception. If you want to suppress such exceptions and send unresolved messages to the default output channel (identified with the default-output-channel attribute) set resolution-required to false.

Normally, messages for which the header value is not explicitly mapped to a channel will be sent to the default-output-channel. However, in cases where the header value is mapped to a channel name but the channel cannot be resolved, setting the resolution-required attribute to false will result in routing such messages to the default-output-channel.

	Important
	With Spring Integration 2.1 the attribute was changed from ignore-channel-name-resolution-failures to resolution-required. Attribute resolution-required will default to true.

2. Configuration where mapping of header values to channel names is not required since header values themselves represent channel names

<int:header-value-router input-channel="routingChannel" header-name="testHeader"/>

Note

Since Spring Integration 2.1 the behavior of resolving channels is more explicit. For example, if you ommit the default-output-channel attribute and the Router was unable to resolve at least one valid channel, and any channel name resolution failures were ignored by setting resolution-required to false, then a MessageDeliveryException is thrown. Basically, by default the Router must be able to route messages successfully to at least one channel. If you really want to drop messages, you must also have default-output-channel set to nullChannel.

A RecipientListRouter will send each received Message to a statically defined list of Message Channels:

<bean id="recipientListRouter"
      class="org.springframework.integration.router.RecipientListRouter">
    <property name="channels">
        <list>
            <ref bean="channel1"/>
            <ref bean="channel2"/>
            <ref bean="channel3"/>
        </list>
    </property>
</bean>

Spring Integration also provides namespace support for the RecipientListRouter configuration (see Section F.2, “Namespace Support”) as the example below demonstrates.

<int:recipient-list-router id="customRouter" input-channel="routingChannel"
        timeout="1234"
        ignore-send-failures="true"
        apply-sequence="true">
  <int:recipient channel="channel1"/>
  <int:recipient channel="channel2"/>
</int:recipient-list-router>

	Note
	The apply-sequence flag here has the same effect as it does for a publish-subscribe-channel, and like a publish-subscribe-channel, it is disabled by default on the recipient-list-router. Refer tothe section called “PublishSubscribeChannel Configuration” for more information.

Another convenient option when configuring a RecipientListRouter is to use Spring Expression Language (SpEL) support as selectors for individual recipient channels. This is similar to using a Filter at the beginning of chain to act as a "Selective Consumer". However, in this case, it’s all combined rather concisely into the router’s configuration.

<int:recipient-list-router id="customRouter" input-channel="routingChannel">
    <int:recipient channel="channel1" selector-expression="payload.equals('foo')"/>
    <int:recipient channel="channel2" selector-expression="headers.containsKey('bar')"/>
</int:recipient-list-router>

In the above configuration a SpEL expression identified by the selector-expression attribute will be evaluated to determine if this recipient should be included in the recipient list for a given input Message. The evaluation result of the expression must be a boolean. If this attribute is not defined, the channel will always be among the list of recipients.

Starting with version 4.1, the RecipientListRouter provides several operation to manipulate with recipients dynamically at runtime. These management operations are presented by RecipientListRouterManagement @ManagedResource. They are available using Section 9.6, “Control Bus” as well as via JMX:

<control-bus input-channel="controlBus"/>

<recipient-list-router id="simpleRouter" input-channel="routingChannelA">
   <recipient channel="channel1"/>
</recipient-list-router>

<channel id="channel2"/>

          messagingTemplate.convertAndSend(controlBus,
          "@'simpleRouter.handler'.addRecipient('channel2')");

From the application start up the simpleRouter will have only one channel1 recipient. But after the addRecipient command above the new channel2 recipient will be added. It is a "registering an interest in something that is part of the Message" use case, when we may be interested in messages from the router at some time period, so we are subscribing to the the recipient-list-router and in some point decide to unsubscribe our interest.

Having the runtime management operation for the <recipient-list-router>, it can be configured without any <recipient> from the start. In this case the behaviour of RecipientListRouter is the same, when there is no one matching recipient for the message: if defaultOutputChannel is configured, the message will be sent there, otherwise the MessageDeliveryException is thrown.

The XPath Router is part of the XML Module. As such, please read chapter Section 35.6, “Routing XML Messages Using XPath”

Spring Integration also provides a special type-based router called ErrorMessageExceptionTypeRouter for routing Error Messages (Messages whose payload is a Throwable instance). ErrorMessageExceptionTypeRouter is very similar to the PayloadTypeRouter. In fact they are almost identical. The only difference is that while PayloadTypeRouter navigates the instance hierarchy of a payload instance (e.g., payload.getClass().getSuperclass()) to find the most specific type/channel mappings, the ErrorMessageExceptionTypeRouter navigates the hierarchy of exception causes (e.g., payload.getCause()) to find the most specific Throwable type/channel mappings.

Below is a sample configuration for ErrorMessageExceptionTypeRouter.

<int:exception-type-router input-channel="inputChannel"
                           default-output-channel="defaultChannel">
    <int:mapping exception-type="java.lang.IllegalArgumentException"
                 channel="illegalChannel"/>
    <int:mapping exception-type="java.lang.NullPointerException"
                 channel="npeChannel"/>
</int:exception-type-router>

<int:channel id="illegalChannel" />
<int:channel id="npeChannel" />

The "router" element provides a simple way to connect a router to an input channel and also accepts the optional default-output-channel attribute. The ref attribute references the bean name of a custom Router implementation (extending AbstractMessageRouter):

<int:router ref="payloadTypeRouter" input-channel="input1"
            default-output-channel="defaultOutput1"/>

<int:router ref="recipientListRouter" input-channel="input2"
            default-output-channel="defaultOutput2"/>

<int:router ref="customRouter" input-channel="input3"
            default-output-channel="defaultOutput3"/>

<beans:bean id="customRouterBean" class="org.foo.MyCustomRouter"/>

Alternatively, ref may point to a simple POJO that contains the @Router annotation (see below), or the ref may be combined with an explicit method name. Specifying a method applies the same behavior described in the @Router annotation section below.

<int:router input-channel="input" ref="somePojo" method="someMethod"/>

Using a ref attribute is generally recommended if the custom router implementation is referenced in other <router> definitions. However if the custom router implementation should be scoped to a single definition of the <router>, you may provide an inner bean definition:

<int:router method="someMethod" input-channel="input3"
            default-output-channel="defaultOutput3">
    <beans:bean class="org.foo.MyCustomRouter"/>
</int:router>

	Note
	Using both the ref attribute and an inner handler definition in the same <router> configuration is not allowed, as it creates an ambiguous condition, and an Exception will be thrown.

Routers and the Spring Expression Language (SpEL)

Sometimes the routing logic may be simple and writing a separate class for it and configuring it as a bean may seem like overkill. As of Spring Integration 2.0 we offer an alternative where you can now use SpEL to implement simple computations that previously required a custom POJO router.

	Note
	For more information about the Spring Expression Language, please refer to the respective chapter in the Spring Framework Reference Documentation at:

null

Generally a SpEL expression is evaluated and the result is mapped to a channel:

<int:router input-channel="inChannel" expression="payload.paymentType">
    <int:mapping value="CASH" channel="cashPaymentChannel"/>
    <int:mapping value="CREDIT" channel="authorizePaymentChannel"/>
    <int:mapping value="DEBIT" channel="authorizePaymentChannel"/>
</int:router>

To simplify things even more, the SpEL expression may evaluate to a channel name:

<int:router input-channel="inChannel" expression="payload + 'Channel'"/>

In the above configuration the result channel will be computed by the SpEL expression which simply concatenates the value of the payload with the literal String Channel.

Another value of SpEL for configuring routers is that an expression can actually return a Collection, effectively making every <router> a Recipient List Router. Whenever the expression returns multiple channel values the Message will be forwarded to each channel.

<int:router input-channel="inChannel" expression="headers.channels"/>

In the above configuration, if the Message includes a header with the name channels the value of which is a List of channel names then the Message will be sent to each channel in the list. You may also find Collection Projection and Collection Selection expressions useful to select multiple channels. For further information, please see:

When using @Router to annotate a method, the method may return either a MessageChannel or String type. In the latter case, the endpoint will resolve the channel name as it does for the default output channel. Additionally, the method may return either a single value or a collection. If a collection is returned, the reply message will be sent to multiple channels. To summarize, the following method signatures are all valid.

@Router
public MessageChannel route(Message message) {...}

@Router
public List<MessageChannel> route(Message message) {...}

@Router
public String route(Foo payload) {...}

@Router
public List<String> route(Foo payload) {...}

In addition to payload-based routing, a Message may be routed based on metadata available within the message header as either a property or attribute. In this case, a method annotated with @Router may include a parameter annotated with @Header which is mapped to a header value as illustrated below and documented in Section F.6, “Annotation Support”.

@Router
public List<String> route(@Header("orderStatus") OrderStatus status)

	Note
	For routing of XML-based Messages, including XPath support, see Chapter 35, XML Support - Dealing with XML Payloads.

One way to manage the router mappings is through the Control Bus pattern which exposes a Control Channel where you can send control messages to manage and monitor Spring Integration components, including routers.

	Note
	For more information about the Control Bus, please see chapter Section 9.6, “Control Bus”.

Typically you would send a control message asking to invoke a particular operation on a particular managed component (e.g. router). Two managed operations (methods) that are specific to changing the router resolution process are:

Note that these methods can be used for simple changes (updating a single route or adding/removing a route). However, if you want to remove one route and add another, the updates are not atomic. This means the routing table may be in an indeterminate state between the updates. Starting with version 4.0, you can now use the control bus to update the entire routing table atomically.

"@'router.handler'.replaceChannelMappings('foo=qux \n baz=bar')"

You can also expose a router instance with Spring’s JMX support, and then use your favorite JMX client (e.g., JConsole) to manage those operations (methods) for changing the router’s configuration.

	Note
	For more information about Spring Integration’s JMX support, please see chapter Section 9.2, “JMX Support”.

Starting with version 4.1, Spring Integration provides an implementation of the Routing Slip Enterprise Integration Pattern. It is implemented as a routingSlip message header which is used to determine the next channel in AbstractMessageProducingHandler s, when an outputChannel isn’t specified for the endpoint. This pattern is useful in complex, dynamic, cases when it can become difficult to configure multiple routers to determine message flow. When a message arrives at an endpoint that has no output-channel, the routingSlip is consulted to determine the next channel to which the message will be sent. When the routing slip is exhausted, normal replyChannel processing resumes.

Configuration for the Routing Slip is presented as a HeaderEnricher option - a semicolon-separated Routing Slip path entries:

<util:properties id="properties">
		<beans:prop key="myRoutePath1">channel1</beans:prop>
		<beans:prop key="myRoutePath2">request.headers[myRoutingSlipChannel]</beans:prop>
	</util:properties>

	<context:property-placeholder properties-ref="properties"/>

	<header-enricher input-channel="input" output-channel="process">
		<routing-slip
				value="${myRoutePath1}; @routingSlipRoutingPojo.get(request, reply);
							routingSlipRoutingStrategy; ${myRoutePath2}; finishChannel"/>
	</header-enricher>

In this sample we have:

Routing Slip path entries can contain MessageChannel bean names, RoutingSlipRouteStrategy bean names and also Spring expressions (SpEL). The RoutingSlipHeaderValueMessageProcessor checks each Routing Slip path entry against the BeanFactory on the first processMessage invocation. It converts entries, which aren’t bean names in the application context, to ExpressionEvaluatingRoutingSlipRouteStrategy instances. RoutingSlipRouteStrategy entries are invoked multiple times, until they return null, or an empty String.

Since the Routing Slip is involved in the getOutputChannel process we have a request-reply context. The RoutingSlipRouteStrategy has been introduced to determine the next outputChannel using the requestMessage, as well as the reply object. An implementation of this strategy should be registered as a bean in the application context and its bean name is used in the Routing Slip path. The ExpressionEvaluatingRoutingSlipRouteStrategy implementation is provided. It accepts a SpEL expression, and an internal ExpressionEvaluatingRoutingSlipRouteStrategy.RequestAndReply object is used as the root object of the evaluation context. This is to avoid the overhead of EvaluationContext creation for each ExpressionEvaluatingRoutingSlipRouteStrategy.getNextPath() invocation. It is a simple Java Bean with two properties - Message<?> request and Object reply. With this expression implementation, we can specify Routing Slip path entries using SpEL (@routingSlipRoutingPojo.get(request, reply), request.headers[myRoutingSlipChannel]) avoiding a bean definition for the RoutingSlipRouteStrategy.

Important

If a Routing Slip is involved in a distributed environment - cross-JVM application, request-reply through a Message Broker (e.g. Chapter 11, AMQP Support, Chapter 20, JMS Support), or persistence MessageStore (Section 9.4, “Message Store”) is used in the integration flow, etc., - it is recommended to not use inline expressions for the Routing Slip path. The framework (RoutingSlipHeaderValueMessageProcessor) converts them to ExpressionEvaluatingRoutingSlipRouteStrategy objects and they are used in the routingSlip message header. Since this class isn’t Serializable (and it can’t be, because it depends on the BeanFactory) the entire Message becomes non-serializable and in any distributed operation we end up with NotSerializableException. To overcome this limitation, register an ExpressionEvaluatingRoutingSlipRouteStrategy bean with the desired SpEL and use its bean name in the Routing Slip path configuration.