Modified: websites/production/camel/content/splitter.html
==============================================================================
--- websites/production/camel/content/splitter.html (original)
+++ websites/production/camel/content/splitter.html Fri Aug 25 09:20:43 2017
@@ -36,17 +36,6 @@
<![endif]-->
- <link href='//camel.apache.org/styles/highlighter/styles/shCoreCamel.css'
rel='stylesheet' type='text/css' />
- <link href='//camel.apache.org/styles/highlighter/styles/shThemeCamel.css'
rel='stylesheet' type='text/css' />
- <script src='//camel.apache.org/styles/highlighter/scripts/shCore.js'
type='text/javascript'></script>
- <script src='//camel.apache.org/styles/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
- <script src='//camel.apache.org/styles/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
- <script src='//camel.apache.org/styles/highlighter/scripts/shBrushPlain.js'
type='text/javascript'></script>
-
- <script type="text/javascript">
- SyntaxHighlighter.defaults['toolbar'] = false;
- SyntaxHighlighter.all();
- </script>
<title>
Apache Camel: Splitter
@@ -86,81 +75,27 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><h3
id="Splitter-Splitter">Splitter</h3><p>The <a shape="rect"
class="external-link"
href="http://www.enterpriseintegrationpatterns.com/Sequencer.html";
rel="nofollow">Splitter</a> from the <a shape="rect"
href="enterprise-integration-patterns.html">EIP patterns</a> allows you split a
message into a number of pieces and process them individually</p><p><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://www.enterpriseintegrationpatterns.com/img/Sequencer.gif";
data-image-src="http://www.enterpriseintegrationpatterns.com/img/Sequencer.gif";></span></p><p>You
need to specify a Splitter as <code>split()</code>. In earlier versions of
Camel, you need to use <code>splitter()</code>.</p><h3
id="Splitter-Options">Options</h3><div class="confluenceTableSmall"><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Name</p>
</th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default
Value</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>strategyRef</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Refers to an <a shape="rect"
class="external-link"
href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html";>AggregationStrategy</a>
to be used to assemble the replies from the sub-messages, into a single
outgoing message from the <a shape="rect" href="splitter.html">Splitter</a>.
See the defaults described below in <em><a shape="rect"
href="#Splitter-WhattheSplitterreturns">What the Splitter returns</a></em>.
From <strong>Camel 2.12</strong> onwards you can also use a POJO as the
<code>AggregationStrategy</code>, see the <a shape="rect" href="aggregator2.htm
l">Aggregate</a> page for more details. If an exception is thrown from the
aggregate method in the AggregationStrategy, then by default, that
exception is not handled by the error handler. The error handler can be
enabled to react if enabling the shareUnitOfWork option.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>strategyMethodName</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.12:</strong> This option can be used to
explicit declare the method name to use, when using POJOs as the
<code>AggregationStrategy</code>. See the <a shape="rect"
href="aggregator2.html">Aggregate</a> page for more
details.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>strategyMethodAllowNull</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><strong>
Camel 2.12:</strong> If this option is <code>false</code> then the aggregate
method is not used for the very first splitted message. If this option is
<code>true</code> then <code>null</code> values is used as the
<code>oldExchange</code> (for the very first message splitted), when using
POJOs as the <code>AggregationStrategy</code>. See the <a shape="rect"
href="aggregator2.html">Aggregate</a> page for more
details.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>parallelProcessing</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>If enabled then processing the sub-messages
occurs concurrently. Note the caller thread will still wait until all
sub-messages has been fully processed, before it continues.</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> </p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>parallelAggregate</c
ode></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.14:</strong> If enabled then the
<code>aggregate</code> method on <code>AggregationStrategy</code> can be called
concurrently. Notice that this would require the implementation of
<code>AggregationStrategy</code> to be implemented as thread-safe. By default
this is <code>false</code> meaning that Camel synchronizes the call to the
<code>aggregate</code> method. Though in some use-cases this can be used to
achieve higher performance when the <code>AggregationStrategy</code> is
implemented as thread-safe.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>executorServiceRef</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Refers to a custom <a shape="rect"
href="threading-model.html">Thread Pool</a> to be used for parall
el processing. Notice if you set this option, then parallel processing is
automatically implied, and you do not have to enable that option as
well.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>stopOnException</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.2:</strong> Whether or not
to stop continue processing immediately when an exception occurred. If disable,
then Camel continue splitting and process the sub-messages regardless if one of
them failed. You can deal with exceptions in the <a shape="rect"
class="external-link"
href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html";>AggregationStrategy</a>
class where you have full control how to handle that.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>streaming</code></p></td><td colspan="1" ro
wspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>If enabled then Camel will split in a
streaming fashion, which means it will split the input message in chunks. This
reduces the memory overhead. For example if you split big messages its
recommended to enable streaming. If streaming is enabled then the sub-message
replies will be aggregated out-of-order, eg in the order they come back. If
disabled, Camel will process sub-message replies in the same order as they
where splitted.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>timeout</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.5:</strong> Sets a total timeout
specified in millis. If the <a shape="rect"
href="recipient-list.html">Recipient List</a> hasn't been able to split and
process all replies within the given timeframe, then the timeout
triggers and the <a shape="rect" href="splitter.html">Splitter</a> breaks out
and continues. Notice if you provide a <a shape="rect" class="external-link"
href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/TimeoutAwareAggregationStrategy.html";>TimeoutAwareAggregationStrategy</a>
then the <code>timeout</code> method is invoked before breaking out. If the
timeout is reached with running tasks still remaining, certain tasks for which
it is difficult for Camel to shut down in a graceful manner may continue to
run. So use this option with a bit of care. We may be able to improve this
functionality in future Camel releases.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>onPrepareRef</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.8:</strong> Refers to a
custom <a shape="rect" href="processor.html">Processor</a> t
o prepare the sub-message of the <a shape="rect"
href="exchange.html">Exchange</a>, before its processed. This allows you to do
any custom logic, such as deep-cloning the message payload if that's needed
etc.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>shareUnitOfWork</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.8:</strong> Whether the
unit of work should be shared. See further below for more
details.</p></td></tr></tbody></table></div></div>
+<div class="wiki-content maincontent"><h3
id="Splitter-Splitter">Splitter</h3><p>The <a shape="rect"
class="external-link"
href="http://www.enterpriseintegrationpatterns.com/Sequencer.html";
rel="nofollow">Splitter</a> from the <a shape="rect"
href="enterprise-integration-patterns.html">EIP patterns</a> allows you split a
message into a number of pieces and process them individually</p><p><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://www.enterpriseintegrationpatterns.com/img/Sequencer.gif";
data-image-src="http://www.enterpriseintegrationpatterns.com/img/Sequencer.gif";></span></p><p>You
need to specify a Splitter as <code>split()</code>. In earlier versions of
Camel, you need to use <code>splitter()</code>.</p><h3
id="Splitter-Options">Options</h3><parameter
ac:name="class">confluenceTableSmall</parameter><rich-text-body><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" row
span="1" class="confluenceTh"><p>Name</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Default Value</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>strategyRef</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Refers to an <a shape="rect"
class="external-link"
href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html";>AggregationStrategy</a>
to be used to assemble the replies from the sub-messages, into a single
outgoing message from the <a shape="rect" href="splitter.html">Splitter</a>.
See the defaults described below in <em><a shape="rect"
href="#Splitter-WhattheSplitterreturns">What the Splitter returns</a></em>.
From <strong>Camel 2.12</strong> onwards you can also use a POJO as the
<code>AggregationStrategy</code>, see
the <a shape="rect" href="aggregator2.html">Aggregate</a> page for more
details. If an exception is thrown from the aggregate method in the
AggregationStrategy, then by default, that exception is not handled by the
error handler. The error handler can be enabled to react if enabling the
shareUnitOfWork option.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>strategyMethodName</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.12:</strong> This option can be used to
explicit declare the method name to use, when using POJOs as the
<code>AggregationStrategy</code>. See the <a shape="rect"
href="aggregator2.html">Aggregate</a> page for more
details.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>strategyMethodAllowNull</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td
colspan="1" row
span="1" class="confluenceTd"><p><strong>Camel 2.12:</strong> If this option
is <code>false</code> then the aggregate method is not used for the very first
splitted message. If this option is <code>true</code> then <code>null</code>
values is used as the <code>oldExchange</code> (for the very first message
splitted), when using POJOs as the <code>AggregationStrategy</code>. See the <a
shape="rect" href="aggregator2.html">Aggregate</a> page for more
details.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>parallelProcessing</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>If enabled then processing the sub-messages
occurs concurrently. Note the caller thread will still wait until all
sub-messages has been fully processed, before it continues.</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> </p></td></tr><tr><td
colspan="1" rowspan="1" class="co
nfluenceTd"><p><code>parallelAggregate</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.14:</strong> If enabled
then the <code>aggregate</code> method on <code>AggregationStrategy</code> can
be called concurrently. Notice that this would require the implementation of
<code>AggregationStrategy</code> to be implemented as thread-safe. By default
this is <code>false</code> meaning that Camel synchronizes the call to the
<code>aggregate</code> method. Though in some use-cases this can be used to
achieve higher performance when the <code>AggregationStrategy</code> is
implemented as thread-safe.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>executorServiceRef</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Refers to a custom <a shape="rect"
href="threading-model.ht
ml">Thread Pool</a> to be used for parallel processing. Notice if you set this
option, then parallel processing is automatically implied, and you do not have
to enable that option as well.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>stopOnException</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.2:</strong> Whether or not
to stop continue processing immediately when an exception occurred. If disable,
then Camel continue splitting and process the sub-messages regardless if one of
them failed. You can deal with exceptions in the <a shape="rect"
class="external-link"
href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html";>AggregationStrategy</a>
class where you have full control how to handle that.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>st
reaming</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>If enabled then Camel will split in a streaming
fashion, which means it will split the input message in chunks. This reduces
the memory overhead. For example if you split big messages its recommended to
enable streaming. If streaming is enabled then the sub-message replies will be
aggregated out-of-order, eg in the order they come back. If disabled, Camel
will process sub-message replies in the same order as they where
splitted.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>timeout</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.5:</strong> Sets a total timeout
specified in millis. If the <a shape="rect"
href="recipient-list.html">Recipient List</a> hasn't been able to split and
process all replies with
in the given timeframe, then the timeout triggers and the <a shape="rect"
href="splitter.html">Splitter</a> breaks out and continues. Notice if you
provide a <a shape="rect" class="external-link"
href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/TimeoutAwareAggregationStrategy.html";>TimeoutAwareAggregationStrategy</a>
then the <code>timeout</code> method is invoked before breaking out. If the
timeout is reached with running tasks still remaining, certain tasks for which
it is difficult for Camel to shut down in a graceful manner may continue to
run. So use this option with a bit of care. We may be able to improve this
functionality in future Camel releases.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>onPrepareRef</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.8:</strong> Refers to a
custom <a shape="re
ct" href="processor.html">Processor</a> to prepare the sub-message of the <a
shape="rect" href="exchange.html">Exchange</a>, before its processed. This
allows you to do any custom logic, such as deep-cloning the message payload if
that's needed etc.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>shareUnitOfWork</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.8:</strong> Whether the
unit of work should be shared. See further below for more
details.</p></td></tr></tbody></table></div></rich-text-body><h3
id="Splitter-Exchangeproperties">Exchange properties</h3><p>The following
properties are set on each Exchange that are split:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>property</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>type</p></th><th colspan="1" ro
wspan="1" class="confluenceTh"><p>description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>CamelSplitIndex</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A split counter that increases for each
Exchange being split. The counter starts from 0.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>CamelSplitSize</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The total number of Exchanges that was splitted. This
header is not applied for stream based splitting. From <strong>Camel
2.9</strong> onwards this header is also set in stream based splitting, but
only on the completed Exchange.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>CamelSplitComplete</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>boolean</p></td><td colspan
="1" rowspan="1" class="confluenceTd"><p><strong>Camel 2.4:</strong> Whether
or not this Exchange is the last.</p></td></tr></tbody></table></div><h3
id="Splitter-Examples">Examples</h3><p>The following example shows how to take
a request from the <strong>direct:a</strong> endpoint the split it into pieces
using an <a shape="rect" href="expression.html">Expression</a>, then forward
each piece to <strong>direct:b</strong></p><p><strong>Using the <a shape="rect"
href="fluent-builders.html">Fluent
Builders</a></strong><plain-text-body>{snippet:id=splitter|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/builder/RouteBuilderTest.java}</plain-text-body>The
splitter can use any <a shape="rect" href="expression.html">Expression</a>
language so you could use any of the <a shape="rect"
href="languages-supported.html">Languages Supported</a> such as <a shape="rect"
href="xpath.html">XPath</a>, <a shape="rect" href="xquery.html">XQuery</a>, <a
shape="rect" href="sql.html">SQ
L</a> or one of the <a shape="rect" href="scripting-languages.html">Scripting
Languages</a> to perform the split.
e.g.</p><plain-text-body>from("activemq:my.queue").split(xpath("//foo/bar")).convertBodyTo(String.class).to("file://some/directory")
+</plain-text-body><p><strong>Using the <a shape="rect"
href="spring-xml-extensions.html">Spring XML
Extensions</a></strong><plain-text-body>{snippet:id=example|lang=xml|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/xml/buildSplitter.xml}</plain-text-body>For
further examples of this pattern in use you could look at one of the <a
shape="rect" class="external-link"
href="http://svn.apache.org/viewvc/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/SplitterTest.java?view=markup";>junit
test case</a></p><h3
id="Splitter-SplittingaCollection,IteratororArray">Splitting a Collection,
Iterator or Array</h3><p>A common use case is to split a Collection, Iterator
or Array from the <span class="confluence-link">message</span>. In the sample
below we simply use an <a shape="rect"
href="expression.html">Expression</a> to identify the value to
split.</p><parameter
ac:name="language">java</parameter><plain-text-body>from("direct:splitUsingBod
y").split(body()).to("mock:result");
-
-<h3 id="Splitter-Exchangeproperties">Exchange properties</h3><p>The following
properties are set on each Exchange that are split:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>property</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>type</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>CamelSplitIndex</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A split counter that increases for each
Exchange being split. The counter starts from 0.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>CamelSplitSize</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>int</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The total number of Exchanges that was splitted. This
header is not
applied for stream based splitting. From <strong>Camel 2.9</strong> onwards
this header is also set in stream based splitting, but only on the completed
Exchange.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>CamelSplitComplete</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>boolean</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.4:</strong> Whether or not this
Exchange is the last.</p></td></tr></tbody></table></div><h3
id="Splitter-Examples">Examples</h3><p>The following example shows how to take
a request from the <strong>direct:a</strong> endpoint the split it into pieces
using an <a shape="rect" href="expression.html">Expression</a>, then forward
each piece to <strong>direct:b</strong></p><p><strong>Using the <a shape="rect"
href="fluent-builders.html">Fluent Builders</a></strong></p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[
-RouteBuilder builder = new RouteBuilder() {
- public void configure() {
- errorHandler(deadLetterChannel("mock:error"));
-
- from("direct:a")
- .split(body(String.class).tokenize("\n"))
- .to("direct:b");
- }
-};
-]]></script>
-</div></div>The splitter can use any <a shape="rect"
href="expression.html">Expression</a> language so you could use any of the <a
shape="rect" href="languages-supported.html">Languages Supported</a> such as <a
shape="rect" href="xpath.html">XPath</a>, <a shape="rect"
href="xquery.html">XQuery</a>, <a shape="rect" href="sql.html">SQL</a> or one
of the <a shape="rect" href="scripting-languages.html">Scripting Languages</a>
to perform the split. e.g.<div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[from("activemq:my.queue").split(xpath("//foo/bar")).convertBodyTo(String.class).to("file://some/directory")
-]]></script>
-</div></div><p><strong>Using the <a shape="rect"
href="spring-xml-extensions.html">Spring XML Extensions</a></strong></p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[
-<camelContext errorHandlerRef="errorHandler"
xmlns="http://camel.apache.org/schema/spring">
- <route>
- <from uri="direct:a"/>
- <split>
- <xpath>/invoice/lineItems</xpath>
- <to uri="direct:b"/>
- </split>
- </route>
-</camelContext>
-]]></script>
-</div></div>For further examples of this pattern in use you could look at one
of the <a shape="rect" class="external-link"
href="http://svn.apache.org/viewvc/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/SplitterTest.java?view=markup";>junit
test case</a><h3 id="Splitter-SplittingaCollection,IteratororArray">Splitting
a Collection, Iterator or Array</h3><p>A common use case is to split a
Collection, Iterator or Array from the <span
class="confluence-link">message</span>. In the sample below we simply use
an <a shape="rect" href="expression.html">Expression</a> to identify the
value to split.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[from("direct:splitUsingBody").split(body()).to("mock:result");
-
-from("direct:splitUsingHeader").split(header("foo")).to("mock:result");Â
]]></script>
-</div></div><p>In Spring XML you can use the <a shape="rect"
href="simple.html">Simple</a> language to identify the value to split.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[<split>
+from("direct:splitUsingHeader").split(header("foo")).to("mock:result"); </plain-text-body><p>In
Spring XML you can use the <a shape="rect" href="simple.html">Simple</a>
language to identify the value to split.</p><parameter
ac:name="">xml</parameter><plain-text-body><split>
<simple>${body}</simple>
- <to uri="mock:result"/>
+ <to uri="mock:result"/>
</split>
<split>
<simple>${header.foo}</simple>
- <to uri="mock:result"/>
-</split> Â ]]></script>
-</div></div><h3 id="Splitter-UsingTokenizerfrom*">Using Tokenizer from <a
shape="rect" href="spring-xml-extensions.html">Spring XML
Extensions</a>*</h3><p>You can use the tokenizer expression in the Spring DSL
to split bodies or headers using a token. This is a common use-case, so we
provided a special <strong>tokenizer</strong> tag for this.<br clear="none"> In
the sample below we split the body using a @ as separator. You can of course
use comma or space or even a regex pattern, also set regex=true.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[
-<camelContext xmlns="http://camel.apache.org/schema/spring">
- <route>
- <from uri="direct:start"/>
- <split>
- <tokenize token="@"/>
- <to uri="mock:result"/>
- </split>
- </route>
-</camelContext>
-]]></script>
-</div></div><h3 id="Splitter-WhattheSplitterreturns">What the Splitter
returns</h3><p><strong>Camel 2.2 or older:</strong><br clear="none"> The <a
shape="rect" href="splitter.html">Splitter</a> will by default return the
<strong>last</strong> splitted message.</p><p><strong>Camel 2.3 and
newer</strong><br clear="none"> The <a shape="rect"
href="splitter.html">Splitter</a> will by default return the original input
message.</p><p><strong>For all versions</strong><br clear="none"> You can
override this by suppling your own strategy as an
<code>AggregationStrategy</code>. There is a sample on this page (Split
aggregate request/reply sample). Notice its the same strategy as the <a
shape="rect" href="aggregator.html">Aggregator</a> supports. This <a
shape="rect" href="splitter.html">Splitter</a> can be viewed as having a build
in light weight <a shape="rect" href="aggregator.html">Aggregator</a>.</p><h3
id="Splitter-Parallelexecutionofdistinct'parts'">Parallel execution of distinct
'parts
'</h3><p>If you want to execute all parts in parallel you can use special
notation of <code>split()</code> with two arguments, where the second one is a
<strong>boolean</strong> flag if processing should be parallel. e.g.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[XPathBuilder xPathBuilder = new
XPathBuilder("//foo/bar");
-from("activemq:my.queue").split(xPathBuilder,
true).to("activemq:my.parts");
-]]></script>
-</div></div><p>The boolean option has been refactored into a builder method
<code>parallelProcessing</code> so its easier to understand what the route does
when we use a method instead of true|false.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[XPathBuilder xPathBuilder = new
XPathBuilder("//foo/bar");
-from("activemq:my.queue").split(xPathBuilder).parallelProcessing().to("activemq:my.parts");
-]]></script>
-</div></div><h3 id="Splitter-Streambased">Stream based</h3><div
class="confluence-information-macro
confluence-information-macro-information"><p class="title">Splitting big XML
payloads</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>The XPath engine in Java and <a
shape="rect" href="xquery.html">saxon</a> will load the entire XML content into
memory. And thus they are not well suited for very big XML payloads.<br
clear="none"> Instead you can use a custom <a shape="rect"
href="expression.html">Expression</a> which will iterate the XML payload in a
streamed fashion. From Camel 2.9 onwards you can use the Tokenizer language<br
clear="none"> which supports this when you supply the start and end tokens.
From Camel 2.14, you can use the XMLTokenizer language which is
<span>specifically </span>provided for tokenizing XML
documents.</p></div></div><p>You can split streams by enabling the
streaming mode using the <code>streaming</code> builder method.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[
from("direct:streaming").split(body().tokenize(",")).streaming().to("activemq:my.parts");
-]]></script>
-</div></div><p>You can also supply your custom splitter to use with streaming
like this:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[import static
org.apache.camel.builder.ExpressionBuilder.beanExpression;
-from("direct:streaming")
- .split(beanExpression(new MyCustomIteratorFactory(),
"iterator"))
- .streaming().to("activemq:my.parts")
-]]></script>
-</div></div><h4
id="Splitter-StreamingbigXMLpayloadsusingTokenizerlanguage">Streaming big XML
payloads using Tokenizer language</h4><p>There are two tokenizers that can be
used to tokenize an XML payload. The first tokenizer uses the same principle as
in the text tokenizer to scan the XML payload and extract a sequence of
tokens.</p><p><strong>Available as of Camel 2.9</strong><br clear="none"> If
you have a big XML payload, from a file source, and want to split it in
streaming mode, then you can use the Tokenizer language with start/end tokens
to do this with low memory footprint.</p><div
class="confluence-information-macro confluence-information-macro-tip"><p
class="title">StAX component</p><span class="aui-icon aui-icon-small
aui-iconfont-approve confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>The Camel <a shape="rect"
href="stax.html">StAX</a> component can also be used to split big XML files in
a streaming mode. See more details at <a
shape="rect" href="stax.html">StAX</a>.</p></div></div><p>For example you may
have a XML payload structured as follows</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[<orders>
+ <to uri="mock:result"/>
+</split>  </plain-text-body><h3
id="Splitter-UsingTokenizerfrom*">Using Tokenizer from <a shape="rect"
href="spring-xml-extensions.html">Spring XML Extensions</a>*</h3><p>You can use
the tokenizer expression in the Spring DSL to split bodies or headers using a
token. This is a common use-case, so we provided a special
<strong>tokenizer</strong> tag for this.<br clear="none"> In the sample below
we split the body using a @ as separator. You can of course use comma or space
or even a regex pattern, also set
regex=true.<plain-text-body>{snippet:id=e1|lang=xml|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/processor/splitterTokenizerTest.xml}</plain-text-body></p><h3
id="Splitter-WhattheSplitterreturns">What the Splitter
returns</h3><p><strong>Camel 2.2 or older:</strong><br clear="none"> The <a
shape="rect" href="splitter.html">Splitter</a> will by default return the
<strong>last</strong> splitted message.</p><p><strong>Camel 2.3 and newer
</strong><br clear="none"> The <a shape="rect"
href="splitter.html">Splitter</a> will by default return the original input
message.</p><p><strong>For all versions</strong><br clear="none"> You can
override this by suppling your own strategy as an
<code>AggregationStrategy</code>. There is a sample on this page (Split
aggregate request/reply sample). Notice its the same strategy as the <a
shape="rect" href="aggregator.html">Aggregator</a> supports. This <a
shape="rect" href="splitter.html">Splitter</a> can be viewed as having a build
in light weight <a shape="rect" href="aggregator.html">Aggregator</a>.</p><h3
id="Splitter-Parallelexecutionofdistinct'parts'">Parallel execution of distinct
'parts'</h3><p>If you want to execute all parts in parallel you can use special
notation of <code>split()</code> with two arguments, where the second one is a
<strong>boolean</strong> flag if processing should be parallel.
e.g.</p><plain-text-body>XPathBuilder xPathBuilder = new XPathBuilder("//foo/
bar");
+from("activemq:my.queue").split(xPathBuilder, true).to("activemq:my.parts");
+</plain-text-body><p>The boolean option has been refactored into a builder
method <code>parallelProcessing</code> so its easier to understand what the
route does when we use a method instead of
true|false.</p><plain-text-body>XPathBuilder xPathBuilder = new
XPathBuilder("//foo/bar");
+from("activemq:my.queue").split(xPathBuilder).parallelProcessing().to("activemq:my.parts");
+</plain-text-body><h3 id="Splitter-Streambased">Stream based</h3><parameter
ac:name="title">Splitting big XML payloads</parameter><rich-text-body><p>The
XPath engine in Java and <a shape="rect" href="xquery.html">saxon</a> will load
the entire XML content into memory. And thus they are not well suited for very
big XML payloads.<br clear="none"> Instead you can use a custom <a shape="rect"
href="expression.html">Expression</a> which will iterate the XML payload in a
streamed fashion. From Camel 2.9 onwards you can use the Tokenizer language<br
clear="none"> which supports this when you supply the start and end tokens.
From Camel 2.14, you can use the XMLTokenizer language which is
<span>specifically </span>provided for tokenizing XML
documents.</p></rich-text-body><p>You can split streams by enabling the
streaming mode using the <code>streaming</code> builder
method.</p><plain-text-body>
from("direct:streaming").split(body().tokenize(",")).streaming().to("activemq:my.parts");
+</plain-text-body><p>You can also supply your custom splitter to use with
streaming like this:</p><plain-text-body>import static
org.apache.camel.builder.ExpressionBuilder.beanExpression;
+from("direct:streaming")
+ .split(beanExpression(new MyCustomIteratorFactory(), "iterator"))
+ .streaming().to("activemq:my.parts")
+</plain-text-body><h4
id="Splitter-StreamingbigXMLpayloadsusingTokenizerlanguage">Streaming big XML
payloads using Tokenizer language</h4><p>There are two tokenizers that can be
used to tokenize an XML payload. The first tokenizer uses the same principle as
in the text tokenizer to scan the XML payload and extract a sequence of
tokens.</p><p><strong>Available as of Camel 2.9</strong><br clear="none"> If
you have a big XML payload, from a file source, and want to split it in
streaming mode, then you can use the Tokenizer language with start/end tokens
to do this with low memory footprint.</p><parameter ac:name="title">StAX
component</parameter><rich-text-body><p>The Camel <a shape="rect"
href="stax.html">StAX</a> component can also be used to split big XML files in
a streaming mode. See more details at <a shape="rect"
href="stax.html">StAX</a>.</p></rich-text-body><p>For example you may have a
XML payload structured as follows</p><parameter
ac:name="">xml</parameter><plain-text-body>
<orders>
<order>
<!-- order stuff here -->
</order>
@@ -172,230 +107,64 @@ from("direct:streaming")
<!-- order stuff here -->
</order>
</orders>
-]]></script>
-</div></div><p>Now to split this big file using <a shape="rect"
href="xpath.html">XPath</a> would cause the entire content to be loaded into
memory. So instead we can use the Tokenizer language to do this as
follows:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[ from("file:inbox")
- .split().tokenizeXML("order").streaming()
- .to("activemq:queue:order");
-]]></script>
-</div></div><p>In XML DSL the route would be as follows:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[<route>
- <from uri="file:inbox"/>
- <split streaming="true">
- <tokenize token="order" xml="true"/>
- <to uri="activemq:queue:order"/>
+</plain-text-body><p>Now to split this big file using <a shape="rect"
href="xpath.html">XPath</a> would cause the entire content to be loaded into
memory. So instead we can use the Tokenizer language to do this as
follows:</p><plain-text-body> from("file:inbox")
+ .split().tokenizeXML("order").streaming()
+ .to("activemq:queue:order");
+</plain-text-body><p>In XML DSL the route would be as follows:</p><parameter
ac:name="">xml</parameter><plain-text-body><route>
+ <from uri="file:inbox"/>
+ <split streaming="true">
+ <tokenize token="order" xml="true"/>
+ <to uri="activemq:queue:order"/>
</split>
</route>
-]]></script>
-</div></div><p>Notice the <code>tokenizeXML</code> method which will split the
file using the tag name of the child node (more precisely speaking, the local
name of the element without its namespace prefix if any), which mean it will
grab the content between the <code><order></code> and
<code></order></code> tags (incl. the tokens). So for example a splitted
message would be as follows:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[ <order>
+</plain-text-body><p>Notice the <code>tokenizeXML</code> method which will
split the file using the tag name of the child node (more precisely speaking,
the local name of the element without its namespace prefix if any), which mean
it will grab the content between the <code><order></code> and
<code></order></code> tags (incl. the tokens). So for example a splitted
message would be as follows:</p><parameter
ac:name="">xml</parameter><plain-text-body> <order>
<!-- order stuff here -->
</order>
-]]></script>
-</div></div><p>If you want to inherit namespaces from a root/parent tag, then
you can do this as well by providing the name of the root/parent tag:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[<route>
- <from uri="file:inbox"/>
- <split streaming="true">
- <tokenize token="order"
inheritNamespaceTagName="orders" xml="true"/>
- <to uri="activemq:queue:order"/>
+</plain-text-body><p>If you want to inherit namespaces from a root/parent tag,
then you can do this as well by providing the name of the root/parent
tag:</p><parameter ac:name="">xml</parameter><plain-text-body><route>
+ <from uri="file:inbox"/>
+ <split streaming="true">
+ <tokenize token="order" inheritNamespaceTagName="orders" xml="true"/>
+ <to uri="activemq:queue:order"/>
</split>
</route>
-]]></script>
-</div></div><p>And in Java DSL its as follows:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[ from("file:inbox")
- .split().tokenizeXML("order", "orders").streaming()
- .to("activemq:queue:order");
-]]></script>
-</div></div><p><span style="line-height: 1.4285715;">Available as of Camel
2.13.1, you can set the above inheritNamsepaceTagName property to "*"
to include the preceding context in each token (i.e., generating each
token enclosed in its ancestor elements). It is noted that each token must
share the same ancestor elements in this case.</span></p><p><span
style="line-height: 1.4285715;">The above tokenizer works well on simple
structures but has some inherent limitations in handling more complex XML
structures.</span></p><p><strong>Available as of Camel 2.14</strong></p><p>The
second tokenizer uses a StAX parser to overcome these limitations. This
tokenizer recognizes XML namespaces and also handles simple and complex XML
structures more naturally and efficiently. </p><p>To split using this
tokenizer at {<a shape="rect" rel="nofollow">urn:shop}order</a>, we can
write</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[ Namespaces ns = new
Namespaces("ns1", "urn:shop");
+</plain-text-body><p>And in Java DSL its as follows:</p><plain-text-body>
from("file:inbox")
+ .split().tokenizeXML("order", "orders").streaming()
+ .to("activemq:queue:order");
+</plain-text-body><p><span style="line-height: 1.4285715;">Available as of
Camel 2.13.1, you can set the above inheritNamsepaceTagName property to "*"
to include the preceding context in each token (i.e., generating each
token enclosed in its ancestor elements). It is noted that each token must
share the same ancestor elements in this case.</span></p><p><span
style="line-height: 1.4285715;">The above tokenizer works well on simple
structures but has some inherent limitations in handling more complex XML
structures.</span></p><p><strong>Available as of Camel 2.14</strong></p><p>The
second tokenizer uses a StAX parser to overcome these limitations. This
tokenizer recognizes XML namespaces and also handles simple and complex XML
structures more naturally and efficiently. </p><p>To split using this
tokenizer at {<a shape="rect" rel="nofollow">urn:shop}order</a>, we can
write</p><plain-text-body> Namespaces ns = new Namespaces("ns1", "urn:shop");
...
- from("file:inbox")
- .split().xtokenize("//ns1:order", 'i', ns).streaming()
- .to("activemq:queue:order)]]></script>
-</div></div><p><span style="line-height: 1.4285715;">Two arguments control the
behavior of the tokenizer. The first argument specifies the element using a
path notation. This path notation uses a subset of xpath with wildcard support.
The second argument represents the extraction mode. The available extraction
modes are:</span></p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh">mode</th><th colspan="1" rowspan="1"
class="confluenceTh">description</th></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">i</td><td colspan="1" rowspan="1"
class="confluenceTd">injecting the contextual namespace bindings into the
extracted token (default)</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">w</td><td colspan="1" rowspan="1"
class="confluenceTd">wrapping the extracted token in its ancestor
context</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">u</td><td
colspan="1" rowspan="1" class="confluence
Td">unwrapping the extracted token to its child content</td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">t</td><td colspan="1" rowspan="1"
class="confluenceTd">extracting the text content of the specified
element</td></tr></tbody></table></div><p><span style="line-height:
1.4285715;"> </span><span style="line-height: 1.4285715;">Having an input
XML</span></p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[<m:orders xmlns:m="urn:shop"
xmlns:cat="urn:shop:catalog">
+ from("file:inbox")
+ .split().xtokenize("//ns1:order", 'i', ns).streaming()
+ .to("activemq:queue:order)</plain-text-body><p><span style="line-height:
1.4285715;">Two arguments control the behavior of the tokenizer. The first
argument specifies the element using a path notation. This path notation uses a
subset of xpath with wildcard support. The second argument represents the
extraction mode. The available extraction modes are:</span></p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh">mode</th><th colspan="1" rowspan="1"
class="confluenceTh">description</th></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">i</td><td colspan="1" rowspan="1"
class="confluenceTd">injecting the contextual namespace bindings into the
extracted token (default)</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">w</td><td colspan="1" rowspan="1"
class="confluenceTd">wrapping the extracted token in its ancestor
context</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">u</td><td
col
span="1" rowspan="1" class="confluenceTd">unwrapping the extracted token to
its child content</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">t</td><td colspan="1" rowspan="1"
class="confluenceTd">extracting the text content of the specified
element</td></tr></tbody></table></div><p><span style="line-height:
1.4285715;"> </span><span style="line-height: 1.4285715;">Having an input
XML</span></p><parameter
ac:name="">xml</parameter><plain-text-body><m:orders xmlns:m="urn:shop"
xmlns:cat="urn:shop:catalog">
<m:order><id>123</id><date>2014-02-25</date>...</m:order>
-...]]></script>
-</div></div><p><span style="line-height: 1.4285715;">Each mode will result in
the following tokens, </span></p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd">i</td><td colspan="1" rowspan="1"
class="confluenceTd"><pre><m:order xmlns:m="urn:shop"
xmlns:cat="urn:shop:catalog"><id>123</id><date>2014-02-25</date>...</m:order></pre></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">w</td><td colspan="1" rowspan="1"
class="confluenceTd"><pre><m:orders xmlns:m="urn:shop"
xmlns:cat="urn:shop:catalog">
-
<m:order><id>123</id><date>2014-02-25</date>...</m:order></m:orders></pre></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">u</td><td colspan="1" rowspan="1"
class="confluenceTd"><pre><id>123</id><date>2014-02-25</date>...</pre></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">t</td><td colspan="1" rowspan="1"
class="confluenceTd"><pre>1232014-02-25...</pre></td></tr></tbody></table></div><p><span
style="line-height: 1.4285715;"> </span><span style="line-height:
1.4285715;">In XML DSL, the equivalent route would be written as
follows:</span></p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[<camelContext
xmlns:ns1="urn:shop">
+...</plain-text-body><p><span style="line-height: 1.4285715;">Each mode will
result in the following tokens, </span></p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd">i</td><td colspan="1" rowspan="1"
class="confluenceTd"><pre><m:order xmlns:m="urn:shop"
xmlns:cat="urn:shop:catalog"><id>123</id><date>2014-02-25</date>...</m:order></pre></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">w</td><td colspan="1" rowspan="1"
class="confluenceTd"><pre><m:orders xmlns:m="urn:shop"
xmlns:cat="urn:shop:catalog">
+
<m:order><id>123</id><date>2014-02-25</date>...</m:order></m:orders></pre></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">u</td><td colspan="1" rowspan="1"
class="confluenceTd"><pre><id>123</id><date>2014-02-25</date>...</pre></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">t</td><td colspan="1" rowspan="1"
class="confluenceTd"><pre>1232014-02-25...</pre></td></tr></tbody></table></div><p><span
style="line-height: 1.4285715;"> </span><span style="line-height:
1.4285715;">In XML DSL, the equivalent route would be written as
follows:</span></p><parameter
ac:name="">xml</parameter><plain-text-body><camelContext
xmlns:ns1="urn:shop">
<route>
- <from uri="file:inbox"/>
- <split streaming="true">
+ <from uri="file:inbox"/>
+ <split streaming="true">
<xtokenize>//ns1:order</xtokenize>
- <to uri="activemq:queue:order"/>
+ <to uri="activemq:queue:order"/>
</split>
</route>
-</camelContext>]]></script>
-</div></div><p><span style="line-height: 1.4285715;"> </span><span
style="line-height: 1.4285715;">or setting the extraction mode explicitly
as</span></p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[ ...
- <xtokenize mode="i">//ns1:order</xtokenize>
- ...]]></script>
-</div></div><p>Note that this StAX based tokenizer's uses StAX Location API
and requires a StAX Reader implementation (e.g., woodstox) that correctly
returns the offset position pointing to the beginning of each event triggering
segment (e.g., the offset position of '<' at each start and end element
event). If you use a StAX Reader which does not implement that API correctly it
results in invalid xml snippets after the split. For example the snippet could
be wrong terminated:</p><pre><Start>...<</Start> ....
<Start>...</</Start></pre><h4
id="Splitter-SplittingfilesbygroupingNlinestogether">Splitting files by
grouping N lines together</h4><p><strong>Available as of Camel
2.10</strong></p><p>The <a shape="rect" href="tokenizer.html">Tokenizer</a>
language has a new option <code>group</code> that allows you to group N parts
together, for example to split big files into chunks of 1000 lines.</p><div
class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[ from("file:inbox")
- .split().tokenize("\n", 1000).streaming()
- .to("activemq:queue:order");
-]]></script>
-</div></div><p>And in XML DSL</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[<route>
- <from uri="file:inbox"/>
- <split streaming="true">
- <tokenize token="\n" group="1000"/>
- <to uri="activemq:queue:order"/>
+</camelContext></plain-text-body><p><span style="line-height:
1.4285715;"> </span><span style="line-height: 1.4285715;">or setting the
extraction mode explicitly as</span></p><parameter
ac:name="">xml</parameter><plain-text-body> ...
+ <xtokenize mode="i">//ns1:order</xtokenize>
+ ...</plain-text-body><p>Note that this StAX based tokenizer's uses StAX
Location API and requires a StAX Reader implementation (e.g., woodstox) that
correctly returns the offset position pointing to the beginning of each event
triggering segment (e.g., the offset position of '<' at each start and end
element event). If you use a StAX Reader which does not implement that API
correctly it results in invalid xml snippets after the split. For example the
snippet could be wrong terminated:</p><pre><Start>...<</Start>
.... <Start>...</</Start></pre><h4
id="Splitter-SplittingfilesbygroupingNlinestogether">Splitting files by
grouping N lines together</h4><p><strong>Available as of Camel
2.10</strong></p><p>The <a shape="rect" href="tokenizer.html">Tokenizer</a>
language has a new option <code>group</code> that allows you to group N parts
together, for example to split big files into chunks of 1000
lines.</p><plain-text-body> from("file:inbox")
+ .split().tokenize("\n", 1000).streaming()
+ .to("activemq:queue:order");
+</plain-text-body><p>And in XML DSL</p><parameter
ac:name="">xml</parameter><plain-text-body><route>
+ <from uri="file:inbox"/>
+ <split streaming="true">
+ <tokenize token="\n" group="1000"/>
+ <to uri="activemq:queue:order"/>
</split>
</route>
-]]></script>
-</div></div><p>The <code>group</code> option is a number that must be a
positive number that dictates how many groups to combine together. Each part
will be combined using the token.<br clear="none"> So in the example above the
message being sent to the activemq order queue, will contain 1000 lines, and
each line separated by the token (which is a new line token).<br clear="none">
The output when using the <code>group</code> option is always a
<code>java.lang.String</code> type.</p><h4
id="Splitter-Specifyingacustomaggregationstrategy">Specifying a custom
aggregation strategy</h4><p>This is specified similar to the <a shape="rect"
href="aggregator.html">Aggregator</a>.</p><h4
id="Splitter-SpecifyingacustomThreadPoolExecutor">Specifying a custom
ThreadPoolExecutor</h4><p>You can customize the underlying ThreadPoolExecutor
used in the parallel splitter. In the Java DSL try something like this:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelConte
nt pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[XPathBuilder xPathBuilder = new
XPathBuilder("//foo/bar");
+</plain-text-body><p>The <code>group</code> option is a number that must be a
positive number that dictates how many groups to combine together. Each part
will be combined using the token.<br clear="none"> So in the example above the
message being sent to the activemq order queue, will contain 1000 lines, and
each line separated by the token (which is a new line token).<br clear="none">
The output when using the <code>group</code> option is always a
<code>java.lang.String</code> type.</p><h4
id="Splitter-Specifyingacustomaggregationstrategy">Specifying a custom
aggregation strategy</h4><p>This is specified similar to the <a shape="rect"
href="aggregator.html">Aggregator</a>.</p><h4
id="Splitter-SpecifyingacustomThreadPoolExecutor">Specifying a custom
ThreadPoolExecutor</h4><p>You can customize the underlying ThreadPoolExecutor
used in the parallel splitter. In the Java DSL try something like
this:</p><parameter
ac:name="language">Java</parameter><plain-text-body>XPathBuilder xPathBu
ilder = new XPathBuilder("//foo/bar");
ExecutorService pool = ...
-from("activemq:my.queue")
+from("activemq:my.queue")
.split(xPathBuilder).executorService(pool)
- .to("activemq:my.parts");
-]]></script>
-</div></div><h4 id="Splitter-UsingaPojotodothesplitting">Using a Pojo to do
the splitting</h4><p>As the <a shape="rect" href="splitter.html">Splitter</a>
can use any <a shape="rect" href="expression.html">Expression</a> to do the
actual splitting we leverage this fact and use a <strong>method</strong>
expression to invoke a <a shape="rect" href="bean.html">Bean</a> to get the
splitted parts.<br clear="none"> The <a shape="rect" href="bean.html">Bean</a>
should return a value that is iterable such as: <code>java.util.Collection,
java.util.Iterator</code> or an array. <br clear="none"> So the returned value,
will then be used by Camel at runtime, to split the message.</p><div
class="confluence-information-macro confluence-information-macro-tip"><p
class="title">Streaming mode and using pojo</p><span class="aui-icon
aui-icon-small aui-iconfont-approve
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>When you have enabled the
streaming mode, th
en you should return a <code>Iterator</code> to ensure streamish fashion. For
example if the message is a big file, then by using an iterator, that returns a
piece of the file in chunks, in the <code>next</code> method of the
<code>Iterator</code> ensures low memory footprint. This avoids the need for
reading the entire content into memory. For an example see the source code for
the <a shape="rect" class="external-link"
href="https://svn.apache.org/repos/asf/camel/trunk/camel-core/src/main/java/org/apache/camel/support/TokenPairExpressionIterator.java";>TokenizePair</a>
implementation.</p></div></div><p>In the route we define the <a shape="rect"
href="expression.html">Expression</a> as a method call to invoke our <a
shape="rect" href="bean.html">Bean</a> that we have registered with the id
mySplitterBean in the <a shape="rect"
href="registry.html">Registry</a>.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[
-from("direct:body")
- // here we use a POJO bean mySplitterBean to do the split of the
payload
- .split().method("mySplitterBean", "splitBody")
- .to("mock:result");
-from("direct:message")
- // here we use a POJO bean mySplitterBean to do the split of the
message
- // with a certain header value
- .split().method("mySplitterBean", "splitMessage")
- .to("mock:result");
-]]></script>
-</div></div>And the logic for our <a shape="rect" href="bean.html">Bean</a> is
as simple as. Notice we use Camel <a shape="rect" href="bean-binding.html">Bean
Binding</a> to pass in the message body as a String object.<div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[
-public class MySplitterBean {
-
- /**
- * The split body method returns something that is iteratable such as a
java.util.List.
- *
- * @param body the payload of the incoming message
- * @return a list containing each part splitted
- */
- public List<String> splitBody(String body) {
- // since this is based on an unit test you can of cause
- // use different logic for splitting as Camel have out
- // of the box support for splitting a String based on comma
- // but this is for show and tell, since this is java code
- // you have the full power how you like to split your messages
- List<String> answer = new ArrayList<String>();
- String[] parts = body.split(",");
- for (String part : parts) {
- answer.add(part);
- }
- return answer;
- }
-
- /**
- * The split message method returns something that is iteratable such as a
java.util.List.
- *
- * @param header the header of the incoming message with the name user
- * @param body the payload of the incoming message
- * @return a list containing each part splitted
- */
- public List<Message> splitMessage(@Header(value = "user")
String header, @Body String body, CamelContext camelContext) {
- // we can leverage the Parameter Binding Annotations
- // http://camel.apache.org/parameter-binding-annotations.html
- // to access the message header and body at same time,
- // then create the message that we want, splitter will
- // take care rest of them.
- // *NOTE* this feature requires Camel version >= 1.6.1
- List<Message> answer = new ArrayList<Message>();
- String[] parts = header.split(",");
- for (String part : parts) {
- DefaultMessage message = new DefaultMessage(camelContext);
- message.setHeader("user", part);
- message.setBody(body);
- answer.add(message);
- }
- return answer;
- }
-}
-]]></script>
-</div></div><h4 id="Splitter-Splitaggregaterequest/replysample">Split
aggregate request/reply sample</h4><p>This sample shows how you can split an <a
shape="rect" href="exchange.html">Exchange</a>, process each splitted message,
aggregate and return a combined response to the original caller using
request/reply.</p><p>The route below illustrates this and how the split
supports a <strong>aggregationStrategy</strong> to hold the in progress
processed messages:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[
-// this routes starts from the direct:start endpoint
-// the body is then splitted based on @ separator
-// the splitter in Camel supports InOut as well and for that we need
-// to be able to aggregate what response we need to send back, so we provide
our
-// own strategy with the class MyOrderStrategy.
-from("direct:start")
- .split(body().tokenize("@"), new MyOrderStrategy())
- // each splitted message is then send to this bean where we can
process it
- .to("bean:MyOrderService?method=handleOrder")
- // this is important to end the splitter route as we do not want to do
more routing
- // on each splitted message
- .end()
- // after we have splitted and handled each message we want to send a
single combined
- // response back to the original caller, so we let this bean build it for
us
- // this bean will receive the result of the aggregate strategy:
MyOrderStrategy
- .to("bean:MyOrderService?method=buildCombinedResponse")
-]]></script>
-</div></div>And the OrderService bean is as follows:<div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[
-public static class MyOrderService {
-
- private static int counter;
-
- /**
- * We just handle the order by returning a id line for the order
- */
- public String handleOrder(String line) {
- LOG.debug("HandleOrder: " + line);
- return "(id=" + ++counter + ",item=" + line +
")";
- }
-
- /**
- * We use the same bean for building the combined response to send
- * back to the original caller
- */
- public String buildCombinedResponse(String line) {
- LOG.debug("BuildCombinedResponse: " + line);
- return "Response[" + line + "]";
- }
-}
-]]></script>
-</div></div>And our custom <strong>aggregationStrategy</strong> that is
responsible for holding the in progress aggregated message that after the
splitter is ended will be sent to the <strong>buildCombinedResponse</strong>
method for final processing before the combined response can be returned to the
waiting caller.<div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[
-/**
- * This is our own order aggregation strategy where we can control
- * how each splitted message should be combined. As we do not want to
- * loos any message we copy from the new to the old to preserve the
- * order lines as long we process them
- */
-public static class MyOrderStrategy implements AggregationStrategy {
-
- public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {
- // put order together in old exchange by adding the order from new
exchange
-
- if (oldExchange == null) {
- // the first time we aggregate we only have the new exchange,
- // so we just return it
- return newExchange;
- }
-
- String orders = oldExchange.getIn().getBody(String.class);
- String newLine = newExchange.getIn().getBody(String.class);
-
- LOG.debug("Aggregate old orders: " + orders);
- LOG.debug("Aggregate new order: " + newLine);
-
- // put orders together separating by semi colon
- orders = orders + ";" + newLine;
- // put combined order back on old to preserve it
- oldExchange.getIn().setBody(orders);
-
- // return old as this is the one that has all the orders gathered
until now
- return oldExchange;
- }
-}
-]]></script>
-</div></div>So lets run the sample and see how it works.<br clear="none"> We
send an <a shape="rect" href="exchange.html">Exchange</a> to the
<strong>direct:start</strong> endpoint containing a IN body with the String
value: <code>A@B@C</code>. The flow is:<div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[HandleOrder: A
+ .to("activemq:my.parts");
+</plain-text-body><h4 id="Splitter-UsingaPojotodothesplitting">Using a Pojo to
do the splitting</h4><p>As the <a shape="rect"
href="splitter.html">Splitter</a> can use any <a shape="rect"
href="expression.html">Expression</a> to do the actual splitting we leverage
this fact and use a <strong>method</strong> expression to invoke a <a
shape="rect" href="bean.html">Bean</a> to get the splitted parts.<br
clear="none"> The <a shape="rect" href="bean.html">Bean</a> should return a
value that is iterable such as: <code>java.util.Collection,
java.util.Iterator</code> or an array. <br clear="none"> So the returned value,
will then be used by Camel at runtime, to split the message.</p><parameter
ac:name="title">Streaming mode and using
pojo</parameter><rich-text-body><p>When you have enabled the streaming mode,
then you should return a <code>Iterator</code> to ensure streamish fashion. For
example if the message is a big file, then by using an iterator, that returns a
piece of the file in chu
nks, in the <code>next</code> method of the <code>Iterator</code> ensures low
memory footprint. This avoids the need for reading the entire content into
memory. For an example see the source code for the <a shape="rect"
class="external-link"
href="https://svn.apache.org/repos/asf/camel/trunk/camel-core/src/main/java/org/apache/camel/support/TokenPairExpressionIterator.java";>TokenizePair</a>
implementation.</p></rich-text-body><p>In the route we define the <a
shape="rect" href="expression.html">Expression</a> as a method call to invoke
our <a shape="rect" href="bean.html">Bean</a> that we have registered with the
id mySplitterBean in the <a shape="rect"
href="registry.html">Registry</a>.<plain-text-body>{snippet:id=e1|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/SplitterPojoTest.java}</plain-text-body>And
the logic for our <a shape="rect" href="bean.html">Bean</a> is as simple as.
Notice we use Camel <a shape="rect" href="bean-binding.html">Bean Bindi
ng</a> to pass in the message body as a String
object.<plain-text-body>{snippet:id=e2|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/SplitterPojoTest.java}</plain-text-body></p><h4
id="Splitter-Splitaggregaterequest/replysample">Split aggregate request/reply
sample</h4><p>This sample shows how you can split an <a shape="rect"
href="exchange.html">Exchange</a>, process each splitted message, aggregate and
return a combined response to the original caller using
request/reply.</p><p>The route below illustrates this and how the split
supports a <strong>aggregationStrategy</strong> to hold the in progress
processed
messages:<plain-text-body>{snippet:id=e1|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/SplitAggregateInOutTest.java}</plain-text-body>And
the OrderService bean is as
follows:<plain-text-body>{snippet:id=e2|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/SplitAggregateInOutTest.java}</p
lain-text-body>And our custom <strong>aggregationStrategy</strong> that is
responsible for holding the in progress aggregated message that after the
splitter is ended will be sent to the <strong>buildCombinedResponse</strong>
method for final processing before the combined response can be returned to the
waiting
caller.<plain-text-body>{snippet:id=e3|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/SplitAggregateInOutTest.java}</plain-text-body>So
lets run the sample and see how it works.<br clear="none"> We send an <a
shape="rect" href="exchange.html">Exchange</a> to the
<strong>direct:start</strong> endpoint containing a IN body with the String
value: <code>A@B@C</code>. The flow is:</p><plain-text-body>HandleOrder: A
HandleOrder: B
Aggregate old orders: (id=1,item=A)
Aggregate new order: (id=2,item=B)
@@ -404,80 +173,19 @@ Aggregate old orders: (id=1,item=A);(id=
Aggregate new order: (id=3,item=C)
BuildCombinedResponse: (id=1,item=A);(id=2,item=B);(id=3,item=C)
Response to caller: Response[(id=1,item=A);(id=2,item=B);(id=3,item=C)]
-]]></script>
-</div></div><h3 id="Splitter-Stopprocessingincaseofexception">Stop processing
in case of exception</h3><p><strong>Available as of Camel
2.1</strong></p><p>The <a shape="rect" href="splitter.html">Splitter</a> will
by default continue to process the entire <a shape="rect"
href="exchange.html">Exchange</a> even in case of one of the splitted message
will thrown an exception during routing.<br clear="none"> For example if you
have an <a shape="rect" href="exchange.html">Exchange</a> with 1000 rows that
you split and route each sub message. During processing of these sub messages
an exception is thrown at the 17th. What Camel does by default is to process
the remainder 983 messages. You have the chance to remedy or handle this in the
<code>AggregationStrategy</code>.</p><p>But sometimes you just want Camel to
stop and let the exception be propagated back, and let the Camel error handler
handle it. You can do this in Camel 2.1 by specifying that it should stop in
case of an exception occ
urred. This is done by the <code>stopOnException</code> option as shown
below:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[ from("direct:start")
- .split(body().tokenize(",")).stopOnException()
+</plain-text-body><h3 id="Splitter-Stopprocessingincaseofexception">Stop
processing in case of exception</h3><p><strong>Available as of Camel
2.1</strong></p><p>The <a shape="rect" href="splitter.html">Splitter</a> will
by default continue to process the entire <a shape="rect"
href="exchange.html">Exchange</a> even in case of one of the splitted message
will thrown an exception during routing.<br clear="none"> For example if you
have an <a shape="rect" href="exchange.html">Exchange</a> with 1000 rows that
you split and route each sub message. During processing of these sub messages
an exception is thrown at the 17th. What Camel does by default is to process
the remainder 983 messages. You have the chance to remedy or handle this in the
<code>AggregationStrategy</code>.</p><p>But sometimes you just want Camel to
stop and let the exception be propagated back, and let the Camel error handler
handle it. You can do this in Camel 2.1 by specifying that it should stop in
case of an excepti
on occurred. This is done by the <code>stopOnException</code> option as shown
below:</p><plain-text-body> from("direct:start")
+ .split(body().tokenize(",")).stopOnException()
.process(new MyProcessor())
- .to("mock:split");
-]]></script>
-</div></div><p>And using XML DSL you specify it as follows:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[ <route>
- <from uri="direct:start"/>
- <split stopOnException="true">
- <tokenize token=","/>
- <process ref="myProcessor"/>
- <to uri="mock:split"/>
+ .to("mock:split");
+</plain-text-body><p>And using XML DSL you specify it as
follows:</p><parameter ac:name="">xml</parameter><plain-text-body>
<route>
+ <from uri="direct:start"/>
+ <split stopOnException="true">
+ <tokenize token=","/>
+ <process ref="myProcessor"/>
+ <to uri="mock:split"/>
</split>
</route>
-]]></script>
-</div></div><h3
id="Splitter-UsingonPreparetoexecutecustomlogicwhenpreparingmessages">Using
onPrepare to execute custom logic when preparing
messages</h3><p><strong>Available as of Camel 2.8</strong></p><p>See details at
<a shape="rect" href="multicast.html">Multicast</a></p><h3
id="Splitter-Sharingunitofwork">Sharing unit of work</h3><p><strong>Available
as of Camel 2.8</strong></p><p>The <a shape="rect"
href="splitter.html">Splitter</a> will by default not share unit of work
between the parent exchange and each splitted exchange. This means each sub
exchange has its own individual unit of work.</p><p>For example you may have an
use case, where you want to split a big message. And you want to regard that
process as an atomic isolated operation that either is a success or failure. In
case of a failure you want that big message to be moved into a <a shape="rect"
href="dead-letter-channel.html">dead letter queue</a>. To support this use
case, you would have to share the unit of work o
n the <a shape="rect" href="splitter.html">Splitter</a>.</p><p>Here is an
example in Java DSL</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[
-errorHandler(deadLetterChannel("mock:dead").useOriginalMessage()
- .maximumRedeliveries(3).redeliveryDelay(0));
-
-from("direct:start")
- .to("mock:a")
- // share unit of work in the splitter, which tells Camel to propagate
failures from
- // processing the splitted messages back to the result of the splitter,
which allows
- // it to act as a combined unit of work
- .split(body().tokenize(",")).shareUnitOfWork()
- .to("mock:b")
- .to("direct:line")
- .end()
- .to("mock:result");
-
-from("direct:line")
- .to("log:line")
- .process(new MyProcessor())
- .to("mock:line");
-]]></script>
-</div></div>Now in this example what would happen is that in case there is a
problem processing each sub message, the error handler will kick in (yes error
handling still applies for the sub messages). <strong>But</strong> what doesn't
happen is that if a sub message fails all redelivery attempts (its exhausted),
then its <strong>not</strong> moved into that dead letter queue. The reason is
that we have shared the unit of work, so the sub message will report the error
on the shared unit of work. When the <a shape="rect"
href="splitter.html">Splitter</a> is done, it checks the state of the shared
unit of work and checks if any errors occurred. And if an error occurred it
will set the exception on the <a shape="rect" href="exchange.html">Exchange</a>
and mark it for rollback. The error handler will yet again kick in, as the <a
shape="rect" href="exchange.html">Exchange</a> has been marked as rollback and
it had an exception as well. No redelivery attempts is performed (as it was
marke
d for rollback) and the <a shape="rect" href="exchange.html">Exchange</a> will
be moved into the <a shape="rect" href="dead-letter-channel.html">dead letter
queue</a>.<p>Using this from XML DSL is just as easy as you just have to set
the shareUnitOfWork attribute to true:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: xml; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[
-<camelContext errorHandlerRef="dlc"
xmlns="http://camel.apache.org/schema/spring">
-
- <!-- define error handler as DLC, with use original message enabled -->
- <errorHandler id="dlc" type="DeadLetterChannel"
deadLetterUri="mock:dead" useOriginalMessage="true">
- <redeliveryPolicy maximumRedeliveries="3"
redeliveryDelay="0"/>
- </errorHandler>
-
- <route>
- <from uri="direct:start"/>
- <to uri="mock:a"/>
- <!-- share unit of work in the splitter, which tells Camel to propagate
failures from
- processing the splitted messages back to the result of the splitter,
which allows
- it to act as a combined unit of work -->
- <split shareUnitOfWork="true">
- <tokenize token=","/>
- <to uri="mock:b"/>
- <to uri="direct:line"/>
- </split>
- <to uri="mock:result"/>
- </route>
-
- <!-- route for processing each splitted line -->
- <route>
- <from uri="direct:line"/>
- <to uri="log:line"/>
- <process ref="myProcessor"/>
- <to uri="mock:line"/>
- </route>
-
-</camelContext>
-]]></script>
-</div></div><div class="confluence-information-macro
confluence-information-macro-information"><p class="title">Implementation of
shared unit of work</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>So in reality the unit of work is
not shared as a single object instance. Instead <code>SubUnitOfWork</code> is
attached to their parent, and issues callback to the parent about their status
(commit or rollback). This may be refactored in Camel 3.0 where larger API
changes can be done.</p></div></div><p></p><h4
id="Splitter-UsingThisPattern">Using This Pattern</h4>
-
-<p>If you would like to use this EIP Pattern then please read the <a
shape="rect" href="getting-started.html">Getting Started</a>, you may also find
the <a shape="rect" href="architecture.html">Architecture</a> useful
particularly the description of <a shape="rect"
href="endpoint.html">Endpoint</a> and <a shape="rect"
href="uris.html">URIs</a>. Then you could try out some of the <a shape="rect"
href="examples.html">Examples</a> first before trying this pattern
out.</p></div>
+</plain-text-body><h3
id="Splitter-UsingonPreparetoexecutecustomlogicwhenpreparingmessages">Using
onPrepare to execute custom logic when preparing
messages</h3><p><strong>Available as of Camel 2.8</strong></p><p>See details at
<a shape="rect" href="multicast.html">Multicast</a></p><h3
id="Splitter-Sharingunitofwork">Sharing unit of work</h3><p><strong>Available
as of Camel 2.8</strong></p><p>The <a shape="rect"
href="splitter.html">Splitter</a> will by default not share unit of work
between the parent exchange and each splitted exchange. This means each sub
exchange has its own individual unit of work.</p><p>For example you may have an
use case, where you want to split a big message. And you want to regard that
process as an atomic isolated operation that either is a success or failure. In
case of a failure you want that big message to be moved into a <a shape="rect"
href="dead-letter-channel.html">dead letter queue</a>. To support this use
case, you would have to share the unit of
work on the <a shape="rect" href="splitter.html">Splitter</a>.</p><p>Here is
an example in Java
DSL<plain-text-body>{snippet:id=e1|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/SplitSubUnitOfWorkTest.java}</plain-text-body>Now
in this example what would happen is that in case there is a problem
processing each sub message, the error handler will kick in (yes error handling
still applies for the sub messages). <strong>But</strong> what doesn't happen
is that if a sub message fails all redelivery attempts (its exhausted), then
its <strong>not</strong> moved into that dead letter queue. The reason is that
we have shared the unit of work, so the sub message will report the error on
the shared unit of work. When the <a shape="rect"
href="splitter.html">Splitter</a> is done, it checks the state of the shared
unit of work and checks if any errors occurred. And if an error occurred it
will set the exception on the <a shape="rect" href="exchange.html">Exchange
</a> and mark it for rollback. The error handler will yet again kick in, as
the <a shape="rect" href="exchange.html">Exchange</a> has been marked as
rollback and it had an exception as well. No redelivery attempts is performed
(as it was marked for rollback) and the <a shape="rect"
href="exchange.html">Exchange</a> will be moved into the <a shape="rect"
href="dead-letter-channel.html">dead letter queue</a>.</p><p>Using this from
XML DSL is just as easy as you just have to set the shareUnitOfWork attribute
to
true:<plain-text-body>{snippet:id=e1|lang=xml|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/processor/SpringSplitSubUnitOfWorkTest.xml}</plain-text-body></p><parameter
ac:name="title">Implementation of shared unit of
work</parameter><rich-text-body><p>So in reality the unit of work is not shared
as a single object instance. Instead <code>SubUnitOfWork</code> is attached to
their parent, and issues callback to the parent about their status (co
mmit or rollback). This may be refactored in Camel 3.0 where larger API
changes can be done.</p></rich-text-body><p><parameter ac:name=""><a
shape="rect" href="using-this-pattern.html">Using This
Pattern</a></parameter></p></div>
</td>
<td valign="top">
<div class="navigation">
![http://www.enterpriseintegrationpatterns.com/img/Sequencer.gif"](http://www.enterpriseintegrationpatterns.com/img/Sequencer.gif"){kind=link}
