spring-integration/src/reference/docbook/splitter.xml

<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="splitter"
    xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Splitter</title>

  <section id="splitter-annotation">
    <title>Introduction</title>

    <para>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.</para>
  </section>

  <section>
    <title>Programming model</title>

    <para>The API for performing splitting consists of one base class,
    <classname>AbstractMessageSplitter</classname>, which is a 
    <interfacename>MessageHandler</interfacename> 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 enables tracking
    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 
    <ulink url="http://www.eaipatterns.com/DistributionAggregate.html">
    Composed Message Processor</ulink> scenario.</para>

    <para>An excerpt from <classname>AbstractMessageSplitter</classname> can be seen below:</para>

    <programlisting lang="java">public abstract class AbstractMessageSplitter
                extends AbstractReplyProducingMessageConsumer {
  ...
  protected abstract Object splitMessage(Message&lt;?&gt; message);

}</programlisting>

    <para>To implement a specific Splitter in an application, 
    extend <classname>AbstractMessageSplitter</classname> and implement the <code>splitMessage</code> method,
    which contains logic for splitting the messages. The return
    value may be one of the following:</para>

    <itemizedlist>
      <listitem>
        <para>a <interfacename>Collection</interfacename> (or subclass thereof) or an array of 
        <interfacename>Message</interfacename> 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.</para>
      </listitem>

      <listitem>
        <para>a <interfacename>Collection</interfacename> (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.</para>
      </listitem>

      <listitem>
        <para>a <interfacename>Message</interfacename> or non-Message object
         (but not a Collection or an Array) - it works like the previous cases,
          except a single message will be sent out.</para>
      </listitem>
    </itemizedlist>

    <para>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 <interfacename>Message</interfacename> 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.</para>
  </section>


	<section id="splitter-config">
		<title>Configuring Splitter</title>
		 <section>
    <title>Configuring a Splitter using XML</title>

    <para>A splitter can be configured through XML as follows:<programlisting language="xml">&lt;int:channel id="inputChannel"/&gt;

&lt;int:splitter id="splitter" <co id="split1" />
  ref="splitterBean" <co id="split2" />
  method="split" <co id="split3" />
  input-channel="inputChannel" <co id="split4" />
  output-channel="outputChannel" <co id="split5" />/&gt;

&lt;int:channel id="outputChannel"/&gt;

&lt;beans:bean id="splitterBean" class="sample.PojoSplitter"/&gt;</programlisting><calloutlist>
        <callout arearefs="split1">
          <para>The id of the splitter is
          <emphasis>optional</emphasis>.</para>
        </callout>

        <callout arearefs="split2">
          <para>A reference to a bean defined in the application context. The
          bean must implement the splitting logic as described in the section
          above .<emphasis>Optional</emphasis>.
          If reference to a bean is not provided, then it is assumed that the <emphasis>payload</emphasis>
          of the Message that arrived on the <code>input-channel</code> is
          an implementation of <interfacename>java.util.Collection</interfacename> 
          and the default splitting logic will be applied to the Collection,
          incorporating each individual element into a Message and sending it to the <code>output-channel</code>.
          </para>
        </callout>

        <callout arearefs="split3">
          <para>The method (defined on the bean specified above) that
          implements the splitting logic.
          <emphasis>Optional</emphasis>.</para>
        </callout>

        <callout arearefs="split4">
          <para>The input channel of the splitter.
          <emphasis>Required</emphasis>.</para>
        </callout>

        <callout arearefs="split5">
          <para>The channel to which the splitter will send the results of
          splitting the incoming message. <emphasis>Optional (because incoming
          messages can specify a reply channel themselves)</emphasis>.</para>
        </callout>
      </calloutlist></para>
      <para>
        Using a <code>ref</code> attribute is generally recommended if the custom splitter implementation may be referenced in other
        <code>&lt;splitter&gt;</code> definitions. However if the custom splitter handler implementation should be scoped to a
        single definition of the <code>&lt;splitter&gt;</code>, configure an inner bean definition:
<programlisting language="xml"><![CDATA[<int:splitter id="testSplitter" input-channel="inChannel" method="split"
                output-channel="outChannel">
  <beans:bean class="org.foo.TestSplitter"/>
</int:spliter>]]></programlisting>
    </para>
    <note>
    <para>
       Using both a <code>ref</code> attribute and an inner handler definition in the same <code>&lt;int:splitter&gt;</code>
       configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
    </para>
    </note>
  </section>

  <section>
    <title>Configuring a Splitter with Annotations</title>

    <para>The <interfacename>@Splitter</interfacename> annotation is
    applicable to methods that expect either the
    <interfacename>Message</interfacename> type or the message payload type,
    and the return values of the method should be a <interfacename>Collection</interfacename> of any type. 
    If the returned values are not actual <interfacename>Message</interfacename>
    objects, then each item will be wrapped in a Message as its payload. Each
    message will be sent to the designated output channel for the endpoint
    on which the <interfacename>@Splitter</interfacename> is defined.
    <programlisting language="java">@Splitter
List&lt;LineItem&gt; extractItems(Order order) {
    return order.getItems()
}</programlisting></para>
  </section>
	</section>
</section>