Modified: websites/production/camel/content/recipient-list.html
==============================================================================
--- websites/production/camel/content/recipient-list.html (original)
+++ websites/production/camel/content/recipient-list.html Fri Aug 25 08:22:01
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: Recipient List
@@ -86,184 +75,64 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><h3
id="RecipientList-RecipientList">Recipient List</h3><p>The <a shape="rect"
class="external-link"
href="http://www.enterpriseintegrationpatterns.com/RecipientList.html";
rel="nofollow">Recipient List</a> from the <a shape="rect"
href="enterprise-integration-patterns.html">EIP patterns</a> allows you to
route messages to a number of dynamically specified recipients.</p><p><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://www.enterpriseintegrationpatterns.com/img/RecipientList.gif";
data-image-src="http://www.enterpriseintegrationpatterns.com/img/RecipientList.gif";></span></p><p>The
recipients will receive a copy of the <strong>same</strong> <a shape="rect"
href="exchange.html">Exchange</a>, and Camel will execute them
sequentially.</p><h3 id="RecipientList-Options">Options</h3><div
class="confluenceTableSmall"><div class="table-wrap"><table
class="confluenceTable"><tbod
y><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>delimiter</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>,</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Delimiter used if the <a
shape="rect" href="expression.html">Expression</a> returned multiple endpoints
(like "<span style="color: rgb(0,0,0);">direct:foo,direct:bar"</span>). From
<strong>Camel 2.13</strong> onwards this can be disabled by setting delimiter
to "false".</p></td></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>An <a shape="rect" class="external-link"
href="http://camel.apache.or
g/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html">AggregationStrategy</a>
that will assemble the replies from recipients into a single outgoing message
from the <a shape="rect" href="recipient-list.html">Recipient List</a>. By
default Camel will use the last reply as the outgoing message. 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">Aggregator</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><st
rong>Camel 2.12:</strong> This option can be used to explicitly declare the
method name to use, when using POJOs as the <code>AggregationStrategy</code>.
See the <a shape="rect"
href="aggregator2.html">Aggregator</a><span> </span>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 if
there was no data to enrich. If this option is <code>true</code> then
<code>null</code> is used as the <code>oldExchange</code> (when no data to
enrich), when using POJOs as the <code>AggregationStrategy</code>. See the <a
shape="rect" href="aggregator2.html">Aggregator</a> page for more
details.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>parallelProces
sing</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> If enabled, messages are
sent to the recipients concurrently. Note that the calling thread will still
wait until all messages have been fully processed before it continues; it is
the sending and processing of replies from recipients which happens in
parallel.</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> </p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><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 th
read-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 archive 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><strong>Camel 2.2:</strong> A custom <a shape="rect"
href="threading-model.html">Thread Pool</a> to use for parallel processing.
Note that enabling this option implies parallel processing, so you need not
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 to immediately stop processing when an exception occurs. If
> disabled, Camel will send the message to all recipients regardless of any
> individual failures. You can process exceptions in 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>
> implementation, which supports full control of error
> handling.</p></td></tr><tr><td colspan="1" rowspan="1"
> class="confluenceTd"><p><code>ignoreInvalidEndpoints</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.3:</strong> Whether to
> ignore an endpoint URI that could not be resolved. If disabled, Camel will
> throw an exception identifying the invalid endpoint
> URI.</p></td></tr><tr><td colspan="1" rowspan="1"
> class="confluenceTd"><p><code>streaming</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.5:</strong> If enabled, Camel will
process replies out-of-order - that is, in the order received in reply from
each recipient. If disabled, Camel will process replies in the same order as
specified by the <a shape="rect" href="expression.html">Expression</a>. <span
style="color: rgb(0,0,0);">So this specifies whether the response messages are
aggregated as they come in, or</span><span> i</span><span style="color:
rgb(0,0,0);">n the exact order as the recipient list was evaluated. </span>Only
relevant if you enable parallelProcessing.</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> Specifies a
processing timeout in milliseconds. If the <a shape="rect"
href="recipient-list.html">
Recipient List</a> hasn't been able to send and process all replies within
this timeframe, then the timeout triggers and the <a shape="rect"
href="recipient-list.html">Recipient List</a> breaks out, with message flow
continuing to the next element. Note that 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>,
its <code>timeout</code> method is invoked before breaking out.
<strong>Beware:</strong> 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 caution. 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="confluen
ceTd"><p> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.8:</strong> A custom <a shape="rect"
href="processor.html">Processor</a> to prepare the copy of the <a shape="rect"
href="exchange.html">Exchange</a> each recipient will receive. This allows you
to perform arbitrary transformations, such as deep-cloning the message payload
(or any other custom logic).</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 <a shape="rect"
href="splitter.html#Splitter-Sharingunitofwork">the same option on Splitter</a>
for more details.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>cacheSize</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>1000</code></p></t
d><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel
2.13.1/2.12.4:</strong> Allows to configure the cache size for the
<code>ProducerCache</code> which caches producers for reuse in the recipient
list. Will by default use the default cache size which is 1000. Setting the
value to -1 allows to turn off the cache
completely.</p></td></tr></tbody></table></div></div>
-
-
-<h4 id="RecipientList-StaticRecipientList">Static Recipient List</h4><p>The
following example shows how to route a request from an input
<strong>queue:a</strong> endpoint to a static list of
destinations</p><p><strong>Using Annotations</strong><br clear="none"> You can
use the <a shape="rect" href="recipientlist-annotation.html">RecipientList
Annotation</a> on a POJO to create a Dynamic Recipient List. For more details
see the <a shape="rect" href="bean-integration.html">Bean
Integration</a>.</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")
- .multicast().to("direct:b", "direct:c",
"direct:d");
- }
-};
-]]></script>
-</div></div><strong>Using the <a shape="rect"
href="spring-xml-extensions.html">Spring XML Extensions</a></strong><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"/>
- <multicast>
- <to uri="direct:b"/>
- <to uri="direct:c"/>
- <to uri="direct:d"/>
- </multicast>
- </route>
-</camelContext>
-]]></script>
-</div></div><h4 id="RecipientList-DynamicRecipientList">Dynamic Recipient
List</h4><p>Usually one of the main reasons for using the <a shape="rect"
class="external-link"
href="http://www.enterpriseintegrationpatterns.com/RecipientList.html";
rel="nofollow">Recipient List</a> pattern is that the list of recipients is
dynamic and calculated at runtime. The following example demonstrates how to
create a dynamic recipient list using an <a shape="rect"
href="expression.html">Expression</a> (which in this case extracts a named
header value dynamically) to calculate the list of endpoints which are either
of type <a shape="rect" class="external-link"
href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/Endpoint.html";>Endpoint</a>
or are converted to a String and then resolved using the endpoint <a
shape="rect" href="uris.html">URIs</a>.</p><p><strong>Using the <a shape="rect"
href="fluent-builders.html">Fluent Builders</a></strong></p><div class="code
panel pdl" st
yle="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")
- .recipientList(header("foo"));
- }
-};
-]]></script>
-</div></div>The above assumes that the header contains a list of endpoint
URIs. The following takes a single string header and tokenizes it<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:a").recipientList(
- header("recipientListHeader").tokenize(","));
-]]></script>
-</div></div><h5 id="RecipientList-Iteratablevalue">Iteratable value</h5><p>The
dynamic list of recipients that are defined in the header must be iterable such
as:</p><ul
class="alternate"><li><code>java.util.Collection</code></li><li><code>java.util.Iterator</code></li><li>arrays</li><li><code>org.w3c.dom.NodeList</code></li><li>a
single String with values separated by comma</li><li>any other type will be
regarded as a single value</li></ul><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"/>
- <recipientList>
- <xpath>$foo</xpath>
- </recipientList>
- </route>
-</camelContext>
-]]></script>
-</div></div>For further examples of this pattern in action you could take a
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/RecipientListTest.java?view=markup";>junit
test cases</a>.<h5 id="RecipientList-UsingdelimiterinSpringXML">Using
delimiter in Spring XML</h5><p>In Spring DSL you can set the
<code>delimiter</code> attribute for setting a delimiter to be used if the
header value is a single String with multiple separated endpoints. By default
Camel uses comma as delimiter, but this option lets you specify a custom
delimiter to use instead.</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:a" />
- <!-- use comma as a delimiter for String based values -->
- <recipientList delimiter=",">
- <header>myHeader</header>
- </recipientList>
-</route>
-]]></script>
-</div></div>So if <strong>myHeader</strong> contains a String with the value
<code>"activemq:queue:foo, activemq:topic:hello , log:bar"</code> then Camel
will split the String using the delimiter given in the XML that was comma,
resulting into 3 endpoints to send to. You can use spaces between the endpoints
as Camel will trim the value when it lookup the endpoint to send to.<p>Note: In
Java DSL you use the <code>tokenizer</code> to achieve the same. The route
above 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[
from("direct:a").recipientList(header("myHeader").tokenize(","));
-]]></script>
-</div></div><p>In <strong>Camel 2.1</strong> its a bit easier as you can pass
in the delimiter as 2nd parameter:</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:a").recipientList(header("myHeader"),
"#");
-]]></script>
-</div></div><h3
id="RecipientList-Sendingtomultiplerecipientsinparallel">Sending to multiple
recipients in parallel</h3><p><strong>Available as of Camel
2.2</strong></p><p>The <a shape="rect" href="recipient-list.html">Recipient
List</a> now supports <code>parallelProcessing</code> that for example <a
shape="rect" href="splitter.html">Splitter</a> also supports. You can use it to
use a thread pool to have concurrent tasks sending the <a shape="rect"
href="exchange.html">Exchange</a> to multiple recipients concurrently.</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:a").recipientList(header("myHeader")).parallelProcessing();
-]]></script>
-</div></div><p>And in Spring XML it is an attribute on the recipient list
tag.</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[ <route>
- <from uri="direct:a"/>
- <recipientList parallelProcessing="true">
+<div class="wiki-content maincontent"><h3
id="RecipientList-RecipientList">Recipient List</h3><p>The <a shape="rect"
class="external-link"
href="http://www.enterpriseintegrationpatterns.com/RecipientList.html";
rel="nofollow">Recipient List</a> from the <a shape="rect"
href="enterprise-integration-patterns.html">EIP patterns</a> allows you to
route messages to a number of dynamically specified recipients.</p><p><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://www.enterpriseintegrationpatterns.com/img/RecipientList.gif";
data-image-src="http://www.enterpriseintegrationpatterns.com/img/RecipientList.gif";></span></p><p>The
recipients will receive a copy of the <strong>same</strong> <a shape="rect"
href="exchange.html">Exchange</a>, and Camel will execute them
sequentially.</p><h3 id="RecipientList-Options">Options</h3><parameter
ac:name="class">confluenceTableSmall</parameter><rich-text-body><div
class="table-w
rap"><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>delimiter</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>,</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Delimiter used if the <a
shape="rect" href="expression.html">Expression</a> returned multiple endpoints
(like "<span style="color: rgb(0,0,0);">direct:foo,direct:bar"</span>). From
<strong>Camel 2.13</strong> onwards this can be disabled by setting delimiter
to "false".</p></td></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>An <a shape="rect" class="ex
ternal-link"
href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html";>AggregationStrategy</a>
that will assemble the replies from recipients into a single outgoing message
from the <a shape="rect" href="recipient-list.html">Recipient List</a>. By
default Camel will use the last reply as the outgoing message. 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">Aggregator</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 explicitly declare the method name to use, when using POJOs as
the <code>AggregationStrategy</code>. See the <a shape="rect"
href="aggregator2.html">Aggregator</a><span> </span>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 if
there was no data to enrich. If this option is <code>true</code> then
<code>null</code> is used as the <code>oldExchange</code> (when no data to
enrich), when using POJOs as the <code>AggregationStrategy</code>. See the <a
shape="rect" href="aggregator2.html">Aggregator</a> page for more
details.</p></td></tr><tr><td colspan="1" rowspan="1" cla
ss="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><strong>Camel 2.2:</strong> If enabled,
messages are sent to the recipients concurrently. Note that the calling thread
will still wait until all messages have been fully processed before it
continues; it is the sending and processing of replies from recipients which
happens in parallel.</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> </p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><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>Aggregati
onStrategy</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
archive 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><strong>Camel 2.2:</strong> A custom <a shape="rect"
href="threading-model.html">Thread Pool</a> to use for parallel processing.
Note that enabling this option implies parallel processing, so you need not
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="co
nfluenceTd"><p><strong>Camel 2.2:</strong> Whether to immediately stop
processing when an exception occurs. If disabled, Camel will send the message
to all recipients regardless of any individual failures. You can process
exceptions in 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>
implementation, which supports full control of error
handling.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>ignoreInvalidEndpoints</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.3:</strong>
Whether to ignore an endpoint URI that could not be resolved. If disabled,
Camel will throw an exception identifying the invalid endpoint
URI.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>streaming</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.5:</strong> If enabled, Camel will
process replies out-of-order - that is, in the order received in reply from
each recipient. If disabled, Camel will process replies in the same order as
specified by the <a shape="rect" href="expression.html">Expression</a>. <span
style="color: rgb(0,0,0);">So this specifies whether the response messages are
aggregated as they come in, or</span><span> i</span><span style="color:
rgb(0,0,0);">n the exact order as the recipient list was evaluated. </span>Only
relevant if you enable parallelProcessing.</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> Specifies a
processing timeout in milliseconds. If the <a
shape="rect" href="recipient-list.html">Recipient List</a> hasn't been able
to send and process all replies within this timeframe, then the timeout
triggers and the <a shape="rect" href="recipient-list.html">Recipient List</a>
breaks out, with message flow continuing to the next element. Note that 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>,
its <code>timeout</code> method is invoked before breaking out.
<strong>Beware:</strong> 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 caution. 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><t
d colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel 2.8:</strong> A
custom <a shape="rect" href="processor.html">Processor</a> to prepare the copy
of the <a shape="rect" href="exchange.html">Exchange</a> each recipient will
receive. This allows you to perform arbitrary transformations, such as
deep-cloning the message payload (or any other custom
logic).</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 <a shape="rect"
href="splitter.html#Splitter-Sharingunitofwork">the same option on Splitter</a>
for more details.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>cacheSize</code></p></td><td colspan="1"
rowspan="1" class="
confluenceTd"><p><code>1000</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.13.1/2.12.4:</strong> Allows to
configure the cache size for the <code>ProducerCache</code> which caches
producers for reuse in the recipient list. Will by default use the default
cache size which is 1000. Setting the value to -1 allows to turn off the cache
completely.</p></td></tr></tbody></table></div></rich-text-body><h4
id="RecipientList-StaticRecipientList">Static Recipient List</h4><p>The
following example shows how to route a request from an input
<strong>queue:a</strong> endpoint to a static list of
destinations</p><p><strong>Using Annotations</strong><br clear="none"> You can
use the <a shape="rect" href="recipientlist-annotation.html">RecipientList
Annotation</a> on a POJO to create a Dynamic Recipient List. For more details
see the <a shape="rect" href="bean-integration.html">Bean
Integration</a>.</p><p><strong>Using the <a shape="rect"
href="fluent-builders.htm
l">Fluent
Builders</a></strong><plain-text-body>{snippet:id=multicast|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/builder/RouteBuilderTest.java}</plain-text-body><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/buildStaticRecipientList.xml}</plain-text-body></p><h4
id="RecipientList-DynamicRecipientList">Dynamic Recipient List</h4><p>Usually
one of the main reasons for using the <a shape="rect" class="external-link"
href="http://www.enterpriseintegrationpatterns.com/RecipientList.html";
rel="nofollow">Recipient List</a> pattern is that the list of recipients is
dynamic and calculated at runtime. The following example demonstrates how to
create a dynamic recipient list using an <a shape="rect"
href="expression.html">Expression</a> (which in this case extracts a named
header valu
e dynamically) to calculate the list of endpoints which are either of type <a
shape="rect" class="external-link"
href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/Endpoint.html";>Endpoint</a>
or are converted to a String and then resolved using the endpoint <a
shape="rect" href="uris.html">URIs</a>.</p><p><strong>Using the <a shape="rect"
href="fluent-builders.html">Fluent
Builders</a></strong><plain-text-body>{snippet:id=e9|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/builder/RouteBuilderTest.java}</plain-text-body>The
above assumes that the header contains a list of endpoint URIs. The following
takes a single string header and tokenizes
it<plain-text-body>{snippet:id=example|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/RecipientListTest.java}</plain-text-body></p><h5
id="RecipientList-Iteratablevalue">Iteratable value</h5><p>The dynamic list of
recipients that are defined in the header must be ite
rable such as:</p><ul
class="alternate"><li><code>java.util.Collection</code></li><li><code>java.util.Iterator</code></li><li>arrays</li><li><code>org.w3c.dom.NodeList</code></li><li>a
single String with values separated by comma</li><li>any other type will be
regarded as a single value</li></ul><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/buildDynamicRecipientList.xml}</plain-text-body>For
further examples of this pattern in action you could take a 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/RecipientListTest.java?view=markup";>junit
test cases</a>.</p><h5 id="RecipientList-UsingdelimiterinSpringXML">Using
delimiter in Spring XML</h5><p>In Spring DSL you can set the <code>delimiter</
code> attribute for setting a delimiter to be used if the header value is a
single String with multiple separated endpoints. By default Camel uses comma as
delimiter, but this option lets you specify a custom delimiter to use
instead.<plain-text-body>{snippet:id=e1|lang=xml|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/processor/recipientListWithStringDelimitedHeader.xml}</plain-text-body>So
if <strong>myHeader</strong> contains a String with the value
<code>"activemq:queue:foo, activemq:topic:hello , log:bar"</code> then Camel
will split the String using the delimiter given in the XML that was comma,
resulting into 3 endpoints to send to. You can use spaces between the endpoints
as Camel will trim the value when it lookup the endpoint to send
to.</p><p>Note: In Java DSL you use the <code>tokenizer</code> to achieve the
same. The route above in Java DSL:</p><plain-text-body>
from("direct:a").recipientList(header("myHeader").tokenize(","));
+</plain-text-body><p>In <strong>Camel 2.1</strong> its a bit easier as you can
pass in the delimiter as 2nd parameter:</p><plain-text-body>
from("direct:a").recipientList(header("myHeader"), "#");
+</plain-text-body><h3
id="RecipientList-Sendingtomultiplerecipientsinparallel">Sending to multiple
recipients in parallel</h3><p><strong>Available as of Camel
2.2</strong></p><p>The <a shape="rect" href="recipient-list.html">Recipient
List</a> now supports <code>parallelProcessing</code> that for example <a
shape="rect" href="splitter.html">Splitter</a> also supports. You can use it to
use a thread pool to have concurrent tasks sending the <a shape="rect"
href="exchange.html">Exchange</a> to multiple recipients
concurrently.</p><plain-text-body>
from("direct:a").recipientList(header("myHeader")).parallelProcessing();
+</plain-text-body><p>And in Spring XML it is an attribute on the recipient
list tag.</p><plain-text-body> <route>
+ <from uri="direct:a"/>
+ <recipientList parallelProcessing="true">
<header>myHeader</header>
</recipientList>
</route>
-]]></script>
-</div></div><h3 id="RecipientList-Stopcontinuingincaseonerecipientfailed">Stop
continuing in case one recipient failed</h3><p><strong>Available as of Camel
2.2</strong></p><p>The <a shape="rect" href="recipient-list.html">Recipient
List</a> now supports <code>stopOnException</code> that for example <a
shape="rect" href="splitter.html">Splitter</a> also supports. You can use it to
stop sending to any further recipients in case any recipient failed.</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:a").recipientList(header("myHeader")).stopOnException();
-]]></script>
-</div></div><p>And in Spring XML its an attribute on the recipient list
tag.</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[ <route>
- <from uri="direct:a"/>
- <recipientList stopOnException="true">
+</plain-text-body><h3
id="RecipientList-Stopcontinuingincaseonerecipientfailed">Stop continuing in
case one recipient failed</h3><p><strong>Available as of Camel
2.2</strong></p><p>The <a shape="rect" href="recipient-list.html">Recipient
List</a> now supports <code>stopOnException</code> that for example <a
shape="rect" href="splitter.html">Splitter</a> also supports. You can use it to
stop sending to any further recipients in case any recipient
failed.</p><plain-text-body>
from("direct:a").recipientList(header("myHeader")).stopOnException();
+</plain-text-body><p>And in Spring XML its an attribute on the recipient list
tag.</p><plain-text-body> <route>
+ <from uri="direct:a"/>
+ <recipientList stopOnException="true">
<header>myHeader</header>
</recipientList>
</route>
-]]></script>
-</div></div><p><strong>Note:</strong> You can combine
<code>parallelProcessing</code> and <code>stopOnException</code> and have them
both <code>true</code>.</p><h3 id="RecipientList-Ignoreinvalidendpoints">Ignore
invalid endpoints</h3><p><strong>Available as of Camel 2.3</strong></p><p>The
<a shape="rect" href="recipient-list.html">Recipient List</a> now supports
<code>ignoreInvalidEndpoints</code> (like the <a shape="rect"
href="routing-slip.html">Routing Slip</a>). You can use it to skip endpoints
which are invalid.</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:a").recipientList(header("myHeader")).ignoreInvalidEndpoints();
-]]></script>
-</div></div><p>And in Spring XML it is an attribute on the recipient list
tag.</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[ <route>
- <from uri="direct:a"/>
- <recipientList ignoreInvalidEndpoints="true">
+</plain-text-body><p><strong>Note:</strong> You can combine
<code>parallelProcessing</code> and <code>stopOnException</code> and have them
both <code>true</code>.</p><h3 id="RecipientList-Ignoreinvalidendpoints">Ignore
invalid endpoints</h3><p><strong>Available as of Camel 2.3</strong></p><p>The
<a shape="rect" href="recipient-list.html">Recipient List</a> now supports
<code>ignoreInvalidEndpoints</code> (like the <a shape="rect"
href="routing-slip.html">Routing Slip</a>). You can use it to skip endpoints
which are invalid.</p><plain-text-body>
from("direct:a").recipientList(header("myHeader")).ignoreInvalidEndpoints();
+</plain-text-body><p>And in Spring XML it is an attribute on the recipient
list tag.</p><plain-text-body> <route>
+ <from uri="direct:a"/>
+ <recipientList ignoreInvalidEndpoints="true">
<header>myHeader</header>
</recipientList>
</route>
-]]></script>
-</div></div><p>Then let us say the <code>myHeader</code> contains the
following two endpoints <code>direct:foo,xxx:bar</code>. The first endpoint is
valid and works. However the second one is invalid and will just be ignored.
Camel logs at INFO level about it, so you can see why the endpoint was
invalid.</p><h3 id="RecipientList-UsingcustomAggregationStrategy">Using custom
<code>AggregationStrategy</code></h3><p><strong>Available as of Camel
2.2</strong></p><p>You can now use your own <code>AggregationStrategy</code>
with the <a shape="rect" href="recipient-list.html">Recipient List</a>. However
this is rarely needed. What it is good for is that in case you are using <a
shape="rect" href="request-reply.html">Request Reply</a> messaging then the
replies from the recipients can be aggregated. By default Camel uses
<code>UseLatestAggregationStrategy</code> which just keeps that last received
reply. If you must remember all the bodies that all the recipients sent back,
then you can use
your own custom aggregator that keeps those. It is the same principle as with
the <a shape="rect" href="aggregator.html">Aggregator</a> EIP so check it out
for details.</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:a")
- .recipientList(header("myHeader")).aggregationStrategy(new
MyOwnAggregationStrategy())
- .to("direct:b");
-]]></script>
-</div></div><p>And in Spring XML it is again an attribute on the recipient
list tag.</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[ <route>
- <from uri="direct:a"/>
- <recipientList strategyRef="myStrategy">
+</plain-text-body><p>Then let us say the <code>myHeader</code> contains the
following two endpoints <code>direct:foo,xxx:bar</code>. The first endpoint is
valid and works. However the second one is invalid and will just be ignored.
Camel logs at INFO level about it, so you can see why the endpoint was
invalid.</p><h3 id="RecipientList-UsingcustomAggregationStrategy">Using custom
<code>AggregationStrategy</code></h3><p><strong>Available as of Camel
2.2</strong></p><p>You can now use your own <code>AggregationStrategy</code>
with the <a shape="rect" href="recipient-list.html">Recipient List</a>. However
this is rarely needed. What it is good for is that in case you are using <a
shape="rect" href="request-reply.html">Request Reply</a> messaging then the
replies from the recipients can be aggregated. By default Camel uses
<code>UseLatestAggregationStrategy</code> which just keeps that last received
reply. If you must remember all the bodies that all the recipients sent back,
then you ca
n use your own custom aggregator that keeps those. It is the same principle as
with the <a shape="rect" href="aggregator.html">Aggregator</a> EIP so check it
out for details.</p><plain-text-body> from("direct:a")
+ .recipientList(header("myHeader")).aggregationStrategy(new
MyOwnAggregationStrategy())
+ .to("direct:b");
+</plain-text-body><p>And in Spring XML it is again an attribute on the
recipient list tag.</p><plain-text-body> <route>
+ <from uri="direct:a"/>
+ <recipientList strategyRef="myStrategy">
<header>myHeader</header>
</recipientList>
- <to uri="direct:b"/>
+ <to uri="direct:b"/>
</route>
- <bean id="myStrategy"
class="com.mycompany.MyOwnAggregationStrategy"/>
-]]></script>
-</div></div><h4
id="RecipientList-KnowingwhichendpointwhenusingcustomAggregationStrategy">Knowing
which endpoint when using custom
<code>AggregationStrategy</code></h4><p><strong>Available as of Camel
2.12</strong></p><p>When using a custom <code>AggregationStrategy</code> then
the <code>aggregate</code> method is always invoked in sequential order (also
if parallel processing is enabled) of the endpoints the <a shape="rect"
href="recipient-list.html">Recipient List</a> is using. However from Camel 2.12
onwards this is easier to know as the <code>newExchange</code> <a shape="rect"
href="exchange.html">Exchange</a> now has a property stored (key is
<code>Exchange.RECIPIENT_LIST_ENDPOINT</code> with the uri of the <a
shape="rect" href="endpoint.html">Endpoint</a>. So you know which endpoint you
are aggregating from. The code block shows how to access this property in your
<a shape="rect" href="aggregator2.html">Aggregator</a>. </p><div
class="code panel pdl" style="border-wi
dth: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[ @Override
+ <bean id="myStrategy" class="com.mycompany.MyOwnAggregationStrategy"/>
+</plain-text-body><h4
id="RecipientList-KnowingwhichendpointwhenusingcustomAggregationStrategy">Knowing
which endpoint when using custom
<code>AggregationStrategy</code></h4><p><strong>Available as of Camel
2.12</strong></p><p>When using a custom <code>AggregationStrategy</code> then
the <code>aggregate</code> method is always invoked in sequential order (also
if parallel processing is enabled) of the endpoints the <a shape="rect"
href="recipient-list.html">Recipient List</a> is using. However from Camel 2.12
onwards this is easier to know as the <code>newExchange</code> <a shape="rect"
href="exchange.html">Exchange</a> now has a property stored (key is
<code>Exchange.RECIPIENT_LIST_ENDPOINT</code> with the uri of the <a
shape="rect" href="endpoint.html">Endpoint</a>. So you know which endpoint you
are aggregating from. The code block shows how to access this property in your
<a shape="rect"
href="aggregator2.html">Aggregator</a>. </p><plain-text-body> @Override
public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {
String uri = newExchange.getProperty(Exchange.RECIPIENT_LIST_ENDPOINT,
String.class);
...
}
-]]></script>
-</div></div><h3 id="RecipientList-Usingcustomthreadpool">Using custom thread
pool</h3><p><strong>Available as of Camel 2.2</strong></p><p>A thread pool is
only used for <code>parallelProcessing</code>. You supply your own custom
thread pool via the <code>ExecutorServiceStrategy</code> (see Camel's <a
shape="rect" href="threading-model.html">Threading Model</a>), the same way you
would do it for the <code>aggregationStrategy</code>. By default Camel uses a
thread pool with 10 threads (subject to change in future versions).</p><h3
id="RecipientList-Usingmethodcallasrecipientlist">Using method call as
recipient list</h3><p>You can use a <a shape="rect" href="bean.html">Bean</a>
to provide the recipients, for example:</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("activemq:queue:test").recipientList().method(MessageRouter.class,
"routeTo");
-]]></script>
-</div></div><p>And then <code>MessageRouter</code>:</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[public class MessageRouter {
+</plain-text-body><h3 id="RecipientList-Usingcustomthreadpool">Using custom
thread pool</h3><p><strong>Available as of Camel 2.2</strong></p><p>A thread
pool is only used for <code>parallelProcessing</code>. You supply your own
custom thread pool via the <code>ExecutorServiceStrategy</code> (see Camel's <a
shape="rect" href="threading-model.html">Threading Model</a>), the same way you
would do it for the <code>aggregationStrategy</code>. By default Camel uses a
thread pool with 10 threads (subject to change in future versions).</p><h3
id="RecipientList-Usingmethodcallasrecipientlist">Using method call as
recipient list</h3><p>You can use a <a shape="rect" href="bean.html">Bean</a>
to provide the recipients, for
example:</p><plain-text-body>from("activemq:queue:test").recipientList().method(MessageRouter.class,
"routeTo");
+</plain-text-body><p>And then
<code>MessageRouter</code>:</p><plain-text-body>public class MessageRouter {
public String routeTo() {
- String queueName = "activemq:queue:test2";
+ String queueName = "activemq:queue:test2";
return queueName;
}
}
-]]></script>
-</div></div><p>When you use a <a shape="rect" href="bean.html">Bean</a> then
do <strong>not</strong> use the <code>@RecipientList</code> annotation as
this will in fact add yet another recipient list, so you end up having two. Do
<strong>not</strong> do the following.</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[public class MessageRouter {
+</plain-text-body><p>When you use a <a shape="rect" href="bean.html">Bean</a>
then do <strong>not</strong> use the <code>@RecipientList</code>
annotation as this will in fact add yet another recipient list, so you end up
having two. Do <strong>not</strong> do the
following.</p><plain-text-body>public class MessageRouter {
@RecipientList
public String routeTo() {
- String queueName = "activemq:queue:test2";
+ String queueName = "activemq:queue:test2";
return queueName;
}
}
-]]></script>
-</div></div><p>You should only use the snippet above (using
<code>@RecipientList</code>) if you just route to a <a shape="rect"
href="bean.html">Bean</a> which you then want to act as a recipient list.<br
clear="none"> So the original route can be changed to:</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("activemq:queue:test").bean(MessageRouter.class,
"routeTo");
-]]></script>
-</div></div><p>Which then would invoke the routeTo method and detect that it
is annotated with <code>@RecipientList</code> and then act accordingly as if it
was a recipient list EIP.</p><h3 id="RecipientList-Usingtimeout">Using
timeout</h3><p><strong>Available as of Camel 2.5</strong></p><p>If you use
<code>parallelProcessing</code> then you can configure a total
<code>timeout</code> value in millis. Camel will then process the messages in
parallel until the timeout is hit. This allows you to continue processing if
one message consumer is slow. For example you can set a timeout value of 20
sec.</p><div class="confluence-information-macro
confluence-information-macro-warning"><p class="title">Tasks may keep
running</p><span class="aui-icon aui-icon-small aui-iconfont-error
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>If the timeout is reached with
running tasks still remaining, certain tasks for which it is difficult for
Camel to shut do
wn 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></div></div><p>For example in the unit test below you can see that
we multicast the message to 3 destinations. We have a timeout of 2 seconds,
which means only the last two messages can be completed within the timeframe.
This means we will only aggregate the last two which yields a result
aggregation which outputs <code>"BC"</code>.</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")
- .multicast(new AggregationStrategy() {
- public Exchange aggregate(Exchange oldExchange, Exchange
newExchange) {
- if (oldExchange == null) {
- return newExchange;
- }
-
- String body = oldExchange.getIn().getBody(String.class);
- oldExchange.getIn().setBody(body +
newExchange.getIn().getBody(String.class));
- return oldExchange;
- }
- })
- .parallelProcessing().timeout(250).to("direct:a",
"direct:b", "direct:c")
- // use end to indicate end of multicast route
- .end()
- .to("mock:result");
-
-from("direct:a").delay(1000).to("mock:A").setBody(constant("A"));
-
-from("direct:b").to("mock:B").setBody(constant("B"));
-
-from("direct:c").to("mock:C").setBody(constant("C"));
-]]></script>
-</div></div><div class="confluence-information-macro
confluence-information-macro-tip"><p class="title">Timeout in other
EIPs</p><span class="aui-icon aui-icon-small aui-iconfont-approve
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>This <code>timeout</code> feature
is also supported by <a shape="rect" href="splitter.html">Splitter</a> and both
<code>multicast</code> and <code>recipientList</code>.</p></div></div><p>By
default if a timeout occurs the <code>AggregationStrategy</code> is not
invoked. However you can implement a special version</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width:
1px;"><b>TimeoutAwareAggregationStrategy</b></div><div class="codeContent
panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default"
type="syntaxhighlighter"><![CDATA[public interface
TimeoutAwareAggregationStrategy extends AggregationStrategy {
+</plain-text-body><p>You should only use the snippet above (using
<code>@RecipientList</code>) if you just route to a <a shape="rect"
href="bean.html">Bean</a> which you then want to act as a recipient list.<br
clear="none"> So the original route can be changed
to:</p><plain-text-body>from("activemq:queue:test").bean(MessageRouter.class,
"routeTo");
+</plain-text-body><p>Which then would invoke the routeTo method and detect
that it is annotated with <code>@RecipientList</code> and then act accordingly
as if it was a recipient list EIP.</p><h3 id="RecipientList-Usingtimeout">Using
timeout</h3><p><strong>Available as of Camel 2.5</strong></p><p>If you use
<code>parallelProcessing</code> then you can configure a total
<code>timeout</code> value in millis. Camel will then process the messages in
parallel until the timeout is hit. This allows you to continue processing if
one message consumer is slow. For example you can set a timeout value of 20
sec.</p><parameter ac:name="title">Tasks may keep
running</parameter><rich-text-body><p>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></rich-text-body><p>For ex
ample in the unit test below you can see that we multicast the message to 3
destinations. We have a timeout of 2 seconds, which means only the last two
messages can be completed within the timeframe. This means we will only
aggregate the last two which yields a result aggregation which outputs
<code>"BC"</code>.<plain-text-body>{snippet:id=e1|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/processor/MulticastParallelTimeoutTest.java}</plain-text-body></p><parameter
ac:name="title">Timeout in other EIPs</parameter><rich-text-body><p>This
<code>timeout</code> feature is also supported by <a shape="rect"
href="splitter.html">Splitter</a> and both <code>multicast</code> and
<code>recipientList</code>.</p></rich-text-body><p>By default if a timeout
occurs the <code>AggregationStrategy</code> is not invoked. However you can
implement a special version</p><parameter
ac:name="language">java</parameter><parameter
ac:name="java:title">TimeoutAwareAggregationStrategy</param
eter><parameter
ac:name="title">TimeoutAwareAggregationStrategy</parameter><plain-text-body>public
interface TimeoutAwareAggregationStrategy extends AggregationStrategy {
/**
* A timeout occurred
@@ -274,15 +143,10 @@ from("direct:c").to("mock
* @param timeout the timeout value in millis
*/
void timeout(Exchange oldExchange, int index, int total, long timeout);
-]]></script>
-</div></div><p>This allows you to deal with the timeout in the
<code>AggregationStrategy</code> if you really need to.</p><div
class="confluence-information-macro
confluence-information-macro-information"><p class="title">Timeout is
total</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>The timeout is total, which means
that after X time, Camel will aggregate the messages which have completed
within the timeframe. The remainders will be cancelled. Camel will also only
invoke the <code>timeout</code> method in the
<code>TimeoutAwareAggregationStrategy</code> once, for the first index which
caused the timeout.</p></div></div><h3
id="RecipientList-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="RecipientList-UsingExchangePatterninrecipients">Using
ExchangePattern in recipients</h3><p><strong>Available as of Camel
2.15</strong></p><p>The recipient list will by default use the current <a
shape="rect" href="exchange-pattern.html">Exchange Pattern</a>. Though one can
imagine use-cases where one wants to send a message to a recipient using a
different exchange pattern. For example you may have a route that initiates as
an InOnly route, but want to use InOut exchange pattern with a recipient list.
To do this in earlier Camel releases, you would need to change
the exchange pattern before the recipient list, or use onPrepare option to
alter the pattern. From Camel 2.15 onwards, you can configure the exchange
pattern directly in the recipient endpoints.</p><p>For example in the route
below we pick up new files (which will be started as InOnly) and then route to
a recipient list. As we want to use InOut with the ActiveMQ (JMS) endpoint we
can now specify this u
sing the exchangePattern=InOut option. Then the response from the JMS
request/reply will then be continued routed, and thus the response is what will
be stored in as a file in the outbox directory.</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")
+</plain-text-body><p>This allows you to deal with the timeout in the
<code>AggregationStrategy</code> if you really need to.</p><parameter
ac:name="title">Timeout is total</parameter><rich-text-body><p>The timeout is
total, which means that after X time, Camel will aggregate the messages which
have completed within the timeframe. The remainders will be cancelled. Camel
will also only invoke the <code>timeout</code> method in the
<code>TimeoutAwareAggregationStrategy</code> once, for the first index which
caused the timeout.</p></rich-text-body><h3
id="RecipientList-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="RecipientList-UsingExchangePatterninrecipients">Using ExchangePattern in
recipients</h3><p><strong>Available as of Camel 2.15</strong></p><p>The
recipient list will by de
fault use the current <a shape="rect"
href="exchange-pattern.html">Exchange Pattern</a>. Though one can imagine
use-cases where one wants to send a message to a recipient using a different
exchange pattern. For example you may have a route that initiates as an InOnly
route, but want to use InOut exchange pattern with a recipient list. To do this
in earlier Camel releases, you would need to change the exchange pattern
before the recipient list, or use onPrepare option to alter the pattern. From
Camel 2.15 onwards, you can configure the exchange pattern directly in the
recipient endpoints.</p><p>For example in the route below we pick up new files
(which will be started as InOnly) and then route to a recipient list. As we
want to use InOut with the ActiveMQ (JMS) endpoint we can now specify this
using the exchangePattern=InOut option. Then the response from the JMS
request/reply will then be continued routed, and thus the response is what will
be stored in as a file in the ou
tbox directory.</p><plain-text-body>from("file:inbox")
// the exchange pattern is InOnly initially when using a file route
-
.recipientList().constant("activemq:queue:inbox?exchangePattern=InOut")
- .to("file:outbox");]]></script>
-</div></div><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>The recipient list will not alter
the original exchange pattern. So in the example above the exchange pattern
will still be InOnly when the message is routed to the file:outbox
endpoint.</p><p>If you want to alter the exchange pattern permanently then use
the .setExchangePattern option. See more details at <a shape="rect"
href="request-reply.html">Request Reply</a> and <a shape="rect"
href="event-message.html">Event
Message</a>.</p></div></div><p> </p><p> </p><p></p><h4
id="RecipientList-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>
+ .recipientList().constant("activemq:queue:inbox?exchangePattern=InOut")
+ .to("file:outbox");</plain-text-body><rich-text-body><p>The recipient list
will not alter the original exchange pattern. So in the example above the
exchange pattern will still be InOnly when the message is routed to the
file:outbox endpoint.</p><p>If you want to alter the exchange pattern
permanently then use the .setExchangePattern option. See more details at <a
shape="rect" href="request-reply.html">Request Reply</a> and <a shape="rect"
href="event-message.html">Event
Message</a>.</p></rich-text-body><p> </p><p> </p><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">
Modified: websites/production/camel/content/redeliverypolicy.html
==============================================================================
--- websites/production/camel/content/redeliverypolicy.html (original)
+++ websites/production/camel/content/redeliverypolicy.html Fri Aug 25 08:22:01
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: RedeliveryPolicy
@@ -96,110 +85,34 @@
<p>For example you can define a default error handler to redelivery at most 3
times</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[
+<parameter ac:name="">java</parameter><plain-text-body>
errorHandler(defaultErrorHandler().maximumRedeliveries(3));
-]]></script>
-</div></div>
+</plain-text-body>
<p>And in XML</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[
-<errorHandler id="defaultEH">
- <redeliveryPolicy maximumRedeliveries="3"/>
+<parameter ac:name="">xml</parameter><plain-text-body>
+<errorHandler id="defaultEH">
+ <redeliveryPolicy maximumRedeliveries="3"/>
</errorHandler>
-]]></script>
-</div></div>
+</plain-text-body>
<p>See more details at <a shape="rect" href="error-handler.html">Error
Handler</a>.</p>
-<div class="confluence-information-macro
confluence-information-macro-tip"><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="error-handler.html">Error Handler</a> is
covered in great details in the <a shape="rect" href="books.html">Camel in
Action book</a> where the entire chapter 5 has been devoted.</p></div></div>
+<parameter ac:name="">Extensive coverage</parameter><rich-text-body>
+<p>The Camel <a shape="rect" href="error-handler.html">Error Handler</a> is
covered in great details in the <a shape="rect" href="books.html">Camel in
Action book</a> where the entire chapter 5 has been
devoted.</p></rich-text-body>
<h3 id="RedeliveryPolicy-UsingRedeliveryPolicyProfiles">Using
RedeliveryPolicyProfiles</h3>
<p><strong>Available as of Camel 2.7</strong></p>
<p>In the XML snippet below we have defined a
<code><redeliveryPolicyProfile></code> which we can refer to from the
<code><errorHandler></code>.</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">
-
- <!-- define the default error handler, and refer to a redelivery policy
to use -->
- <errorHandler id="eh"
redeliveryPolicyRef="myPolicy"/>
-
- <!-- and the redelivery policy is a profile where we can configure it
-->
- <redeliveryPolicyProfile id="myPolicy"
maximumRedeliveries="3" redeliveryDelay="25"
retryAttemptedLogLevel="WARN"/>
-
- <route errorHandlerRef="eh">
- <from uri="direct:start"/>
- <throwException ref="damn"/>
- </route>
-
-</camelContext>
-]]></script>
-</div></div>
+<plain-text-body>{snippet:id=e1|lang=xml|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/processor/SpringErrorHandlerRedeliveryPolicyProfileTest.xml}</plain-text-body>
<p>Camel's <a shape="rect" href="properties.html">Properties</a> placeholder
is also supported which the following XML example shows:</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">
- <!-- use Camel property placeholders -->
- <propertyPlaceholder id="properties"
location="org/apache/camel/component/properties/cheese.properties"/>
-
- <!-- setup endpoint -->
- <endpoint id="dead" uri="mock:dead"/>
-
- <!-- setup a common redelivery policy, using property placeholders
-->
- <redeliveryPolicyProfile id="myRedelivery"
redeliveryDelay="{{delay}}"
maximumRedeliveries="{{max}}"/>
-
- <route>
- <from uri="direct:start"/>
- <onException redeliveryPolicyRef="myRedelivery">
- <!-- refer to common redelivery policy -->
- <exception>java.lang.Exception</exception>
- <!-- but we can override the profile and log retry attempts at
WARN level -->
- <redeliveryPolicy logRetryAttempted="true"
retryAttemptedLogLevel="WARN"/>
- <to ref="dead"/>
- </onException>
- <throwException ref="damn"/>
- </route>
-
-</camelContext>
-]]></script>
-</div></div>
+<plain-text-body>{snippet:id=e1|lang=xml|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/component/properties/SpringPropertiesComponentOnExceptionRefTest.xml}</plain-text-body>
<p>And you can also use Spring Frameworks property placeholders as shown
below:</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[
-
-<!-- use Spring property placeholder -->
-<context:property-placeholder
location="org/apache/camel/component/properties/cheese.properties"/>
-
-<camelContext xmlns="http://camel.apache.org/schema/spring">
-
- <!-- setup endpoint -->
- <endpoint id="dead" uri="mock:dead"/>
-
- <!-- setup a common redelivery policy, using Spring property
placeholders -->
- <redeliveryPolicyProfile id="myRedelivery"
redeliveryDelay="${delay}" maximumRedeliveries="${max}"/>
-
- <route>
- <from uri="direct:start"/>
- <onException redeliveryPolicyRef="myRedelivery">
- <!-- refer to common redelivery policy -->
- <exception>java.lang.Exception</exception>
- <!-- but we can override the profile and log retry attempts at
WARN level -->
- <redeliveryPolicy logRetryAttempted="true"
retryAttemptedLogLevel="WARN"/>
- <to ref="dead"/>
- </onException>
- <throwException ref="damn"/>
- </route>
-
-</camelContext>
-]]></script>
-</div></div>
+<plain-text-body>{snippet:id=e1|lang=xml|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/component/properties/SpringPropertyPlaceholderOnExceptionRefTest.xml}</plain-text-body>
<h3 id="RedeliveryPolicy-SeeAlso">See Also</h3>
Modified: websites/production/camel/content/route-throttling-example.html
==============================================================================
--- websites/production/camel/content/route-throttling-example.html (original)
+++ websites/production/camel/content/route-throttling-example.html Fri Aug 25
08:22:01 2017
@@ -150,7 +150,7 @@
For example you can change the option <code>maxInflightExchanges</code> while
its running to find a more suitable value.</p>
<p>The screenshot below illustrates it from a JConsole.<br clear="none">
-<span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image"
src="route-throttling-example.data/throttling%20services.png"
data-image-src="/confluence/download/attachments/5604305/throttling%20services.png?version=1&modificationDate=1257166177000&api=v2"
data-unresolved-comment-count="0" data-linked-resource-id="5865480"
data-linked-resource-version="1" data-linked-resource-type="attachment"
data-linked-resource-default-alias="throttling services.png"
data-base-url="https://cwiki.apache.org/confluence";
data-linked-resource-content-type="image/png"
data-linked-resource-container-id="5604305"
data-linked-resource-container-version="21"></span></p>
+<span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image"
src="route-throttling-example.data/throttling%20services.png"
data-image-src="/confluence/download/attachments/5604305/throttling%20services.png?version=1&modificationDate=1257166177000&api=v2"
data-unresolved-comment-count="0" data-linked-resource-id="5865480"
data-linked-resource-version="1" data-linked-resource-type="attachment"
data-linked-resource-default-alias="throttling services.png"
data-base-url="https://cwiki.apache.org/confluence";
data-linked-resource-content-type="image/png"
data-linked-resource-container-id="5604305"
data-linked-resource-container-version="22"></span></p>
<p>See more at <a shape="rect" href="camel-jmx.html">using JMX with
Camel</a>.</p>
![http://www.enterpriseintegrationpatterns.com/img/RecipientList.gif"](http://www.enterpriseintegrationpatterns.com/img/RecipientList.gif"){kind=link}