10. Splitter

10.1 Introduction

The Splitter is a component whose role is to partition a message in several parts, and send the resulting messages to be processed independently. Very often, they are upstream producers in a pipeline that includes an Aggregator.

10.2 Programming model

The API for performing splitting consists from one base class, AbstractMessageSplitter, which is a MessageHandler implementation, encapsulating features which are common to splitters, such as filling in the appropriate message headers CORRELATION_ID, SEQUENCE_SIZE, and SEQUENCE_NUMBER on the messages that are produced. This allows to track down the messages and the results of their processing (in a typical scenario, these headers would be copied over to the messages that are produced by the various transforming endpoints), and use them, for example, in a Composed Message Processor scenario.

An excerpt from AbstractMessageSplitter can be seen below:

public abstract class AbstractMessageSplitter
                extends AbstractReplyProducingMessageConsumer {
  protected abstract Object splitMessage(Message<?> message);


For implementing a specific Splitter in an application, a developer can extend AbstractMessageSplitter and implement the splitMessage method, thus defining the actual logic for splitting the messages. The return value can be one of the following:

  • a Collection (or subclass thereof) or an array of Message objects - in this case the messages will be sent as such (after the CORRELATION_ID, SEQUENCE_SIZE and SEQUENCE_NUMBER are populated). Using this approach gives more control to the developer, for example for populating custom message headers as part of the splitting process.

  • a Collection (or subclass thereof) or an array of non-Message objects - works like the prior case, except that each collection element will be used as a Message payload. Using this approach allows developers to focus on the domain objects without having to consider the Messaging system and produces code that is easier to test.

  • a Message or non-Message object (but not a Collection or an Array) - it works like the previous cases, except that there is a single message to be sent out.

In Spring Integration, any POJO can implement the splitting algorithm, provided that it defines a method that accepts a single argument and has a return value. In this case, the return value of the method will be interpreted as described above. The input argument might either be a Message or a simple POJO. In the latter case, the splitter will receive the payload of the incoming message. Since this decouples the code from the Spring Integration API and will typically be easier to test, it is the recommended approach.

10.3 Configuring a Splitter using XML

A splitter can be configured through XML as follows:

<channel id="inputChannel"/>

<splitter id="splitter" 1
  ref="splitterBean" 2
  method="split" 3
  input-channel="inputChannel" 4
  output-channel="outputChannel" 5/>

<channel id="outputChannel"/>

<beans:bean id="splitterBean" class="sample.PojoSplitter"/>


The id of the splitter is optional.


A reference to a bean defined in the application context. The bean must implement the splitting logic as described in the section above. Optional. If reference to a bean is not provided, then it is assumed that the payload of the Message that arrived on the input-channel is an implementation of java.util.Collection and the default splitting logic will be applied on such Collection, incorporating each individual element into a Message and depositing it on the output-channel.


The method (defined on the bean specified above) that implements the splitting logic. Optional.


The input channel of the splitter. Required.


The channel where the splitter will send the results of splitting the incoming message. Optional (because incoming messages can specify a reply channel themselves).

Using a "ref" attribute is generally recommended if the custom splitter handler implementation can be reused in other <splitter> definitions. However if the custom splitter handler implementation should be scoped to a single definition of the <splitter>, you can configure an inner bean definition:

<splitter id="testSplitter" input-channel="inChannel" method="split"
  <beans:bean class="org.foo.TestSplitter"/>


Using both a "ref" attribute and an inner handler definition in the same <splitter> configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.

10.4 Configuring a Splitter with Annotations

The @Splitter annotation is applicable to methods that expect either the Message type or the message payload type, and the return values of the method should be a collection of any type. If the returned values are not actual Message objects, then each of them will be sent as the payload of a message. Those messages will be sent to the output channel as designated for the endpoint on which the @Splitter is defined.

List<LineItem> extractItems(Order order) {
    return order.getItems()