camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Camel > Recipient List
Date Mon, 19 Mar 2012 22:05:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=CAMEL&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CAMEL/Recipient+List">Recipient
List</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~rubytuesdaydono">Reuben
Garrett</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        minor editorial changes<br />
    </div>
        <br/>
                         <h4>Changes (4)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >!http://www.enterpriseintegrationpatterns.com/img/RecipientList.gif!
<br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The recipients will receive a
copy of the *same* <span class="diff-changed-words">[Exchange]<span class="diff-added-chars"style="background-color:
#dfd;">,</span></span> and Camel will execute them sequentially. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h3. Options <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >|| Name || Default Value || Description
|| <br>| {{delimiter}} | {{,}} | Delimiter used if the [Expression] returned multiple
endpoints. | <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">|
{{strategyRef}} | | Refers to an [AggregationStrategy|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html]
to be used to assemble the replies from the recipients, into a single outgoing message from
the [Recipient List]. By default Camel will use the last reply as the outgoing message. |
<br>| {{parallelProcessing}} | {{false}} | *Camel 2.2:* If enables then sending messages
to the recipients occurs concurrently. Note the caller thread will still wait until all messages
has been fully processed, before it continues. Its only the sending and processing the replies
from the recipients which happens concurrently. |  <br>| {{executorServiceRef}} | |
*Camel 2.2:* Refers to a custom [Thread Pool|Threading Model] to be used for parallel processing.
Notice if you set this option, then parallel processing is automatic implied, and you do not
have to enable that option as well. | <br>| {{stopOnException}} | {{false}} | *Camel
2.2:* Whether or not to stop continue processing immediately when an exception occurred. If
disable, then Camel will send the message to all recipients regardless if one of them failed.
You can deal with exceptions in the [AggregationStrategy|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html]
class where you have full control how to handle that. | <br>| {{ignoreInvalidEndpoints}}
| {{false}} | *Camel 2.3:* If an endpoint uri could not be resolved, should it be ignored.
Otherwise Camel will thrown an exception stating the endpoint uri is not valid. | <br>|
{{streaming}} | {{false}} | *Camel 2.5:* If enabled then Camel will process replies out-of-order,
eg in the order they come back. If disabled, Camel will process replies in the same order
as the [Expression] specified. | <br>| {{timeout}} | | *Camel 2.5:* Sets a total timeout
specified in millis. If the [Recipient List] hasn&#39;t been able to send and process
all replies within the given timeframe, then the timeout triggers and the [Recipient List]
breaks out and continues. Notice if you provide a [TimeoutAwareAggregationStrategy|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/TimeoutAwareAggregationStrategy.html]
then the {{timeout}} method is invoked before breaking out. | <br>| {{onPrepareRef}}
| | *Camel 2.8:* Refers to a custom [Processor] to prepare the copy of the [Exchange] each
recipient will receive. This allows you to do any custom logic, such as deep-cloning the message
payload if that&#39;s needed etc. | <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">|
{{strategyRef}} | | An [AggregationStrategy|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html]
that will assemble the replies from recipients into a single outgoing message from the [Recipient
List]. By default Camel will use the last reply as the outgoing message. | <br>| {{parallelProcessing}}
| {{false}} | *Camel 2.2:* 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&#39;s the sending and processing of replies from recipients which happens
in parallel. |  <br>| {{executorServiceRef}} | | *Camel 2.2:* A custom [Thread Pool|Threading
Model] to use for parallel processing. Note that enabling this option implies parallel processing,
so you need not enable that option as well. | <br>| {{stopOnException}} | {{false}}
| *Camel 2.2:* 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 [AggregationStrategy|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html]
implementation, which supports full control of error handling. | <br>| {{ignoreInvalidEndpoints}}
| {{false}} | *Camel 2.3:* Whether to ignore an endpoint URI that could not be resolved. If
disabled, Camel will throw an exception identifying the invalid endpoint URI. | <br>|
{{streaming}} | {{false}} | *Camel 2.5:* 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 [Expression]. | <br>| {{timeout}} | |
*Camel 2.5:* Specifies a processing timeout milliseconds. If the [Recipient List] hasn&#39;t
been able to send and process all replies within this timeframe, then the timeout triggers
and the [Recipient List] breaks out, with message flow continuing to the next element. Note
that if you provide a [TimeoutAwareAggregationStrategy|http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/TimeoutAwareAggregationStrategy.html],
its {{timeout}} method is invoked before breaking out. | <br>| {{onPrepareRef}} | |
*Camel 2.8:* A custom [Processor] to prepare the copy of the [Exchange] each recipient will
receive. This allows you to perform arbitrary transformations, such as deep-cloning the message
payload (or any other custom logic). | <br></td></tr>
            <tr><td class="diff-changed-lines" >| {{shareUnitOfWork}} | {{false}}
| *Camel 2.8:* Whether the unit of work should be shared. See <span class="diff-changed-words"><span
class="diff-added-chars"style="background-color: #dfd;">[</span>the</span>
same option on <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[Splitter]</span>
<span class="diff-added-words"style="background-color: #dfd;">Splitter|Splitter#Sharingunitofwork]</span>
for more details. | <br></td></tr>
            <tr><td class="diff-unchanged" >{div} <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h3><a name="RecipientList-RecipientList"></a>Recipient List</h3>

<p>The <a href="http://www.enterpriseintegrationpatterns.com/RecipientList.html"
class="external-link" rel="nofollow">Recipient List</a> from the <a href="/confluence/display/CAMEL/Enterprise+Integration+Patterns"
title="Enterprise Integration Patterns">EIP patterns</a> allows you to route messages
to a number of dynamically specified recipients.</p>

<p><span class="image-wrap" style=""><img src="http://www.enterpriseintegrationpatterns.com/img/RecipientList.gif"
style="border: 0px solid black" /></span></p>

<p>The recipients will receive a copy of the <b>same</b> <a href="/confluence/display/CAMEL/Exchange"
title="Exchange">Exchange</a>, and Camel will execute them sequentially.</p>

<h3><a name="RecipientList-Options"></a>Options</h3>

<div class="confluenceTableSmall"><div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Name </th>
<th class='confluenceTh'> Default Value </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>delimiter</tt> </td>
<td class='confluenceTd'> <tt>,</tt> </td>
<td class='confluenceTd'> Delimiter used if the <a href="/confluence/display/CAMEL/Expression"
title="Expression">Expression</a> returned multiple endpoints. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>strategyRef</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> An <a href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html"
class="external-link" rel="nofollow">AggregationStrategy</a> that will assemble the
replies from recipients into a single outgoing message from the <a href="/confluence/display/CAMEL/Recipient+List"
title="Recipient List">Recipient List</a>. By default Camel will use the last reply
as the outgoing message. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>parallelProcessing</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> <b>Camel 2.2:</b> 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's the sending and processing of replies
from recipients which happens in parallel. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>executorServiceRef</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> <b>Camel 2.2:</b> A custom <a href="/confluence/display/CAMEL/Threading+Model"
title="Threading Model">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.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>stopOnException</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> <b>Camel 2.2:</b> 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 href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/AggregationStrategy.html"
class="external-link" rel="nofollow">AggregationStrategy</a> implementation, which
supports full control of error handling. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>ignoreInvalidEndpoints</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> <b>Camel 2.3:</b> Whether to ignore an endpoint
URI that could not be resolved. If disabled, Camel will throw an exception identifying the
invalid endpoint URI. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>streaming</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> <b>Camel 2.5:</b> 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 href="/confluence/display/CAMEL/Expression"
title="Expression">Expression</a>. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>timeout</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> <b>Camel 2.5:</b> Specifies a processing timeout
milliseconds. If the <a href="/confluence/display/CAMEL/Recipient+List" title="Recipient
List">Recipient List</a> hasn't been able to send and process all replies within
this timeframe, then the timeout triggers and the <a href="/confluence/display/CAMEL/Recipient+List"
title="Recipient List">Recipient List</a> breaks out, with message flow continuing
to the next element. Note that if you provide a <a href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/processor/aggregate/TimeoutAwareAggregationStrategy.html"
class="external-link" rel="nofollow">TimeoutAwareAggregationStrategy</a>, its <tt>timeout</tt>
method is invoked before breaking out. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>onPrepareRef</tt> </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> <b>Camel 2.8:</b> A custom <a href="/confluence/display/CAMEL/Processor"
title="Processor">Processor</a> to prepare the copy of the <a href="/confluence/display/CAMEL/Exchange"
title="Exchange">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).
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>shareUnitOfWork</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> <b>Camel 2.8:</b> Whether the unit of work should
be shared. See <a href="/confluence/display/CAMEL/Splitter#Splitter-Sharingunitofwork">the
same option on Splitter</a> for more details. </td>
</tr>
</tbody></table>
</div>
</div>

<h4><a name="RecipientList-StaticRecipientList"></a>Static Recipient List</h4>

<p>The following example shows how to route a request from an input <b>queue:a</b>
endpoint to a static list of destinations</p>

<p><b>Using Annotations</b><br/>
You can use the <a href="/confluence/display/CAMEL/RecipientList+Annotation" title="RecipientList
Annotation">RecipientList Annotation</a> on a POJO to create a Dynamic Recipient
List. For more details see the <a href="/confluence/display/CAMEL/Bean+Integration" title="Bean
Integration">Bean Integration</a>.</p>

<p><b>Using the <a href="/confluence/display/CAMEL/Fluent+Builders" title="Fluent
Builders">Fluent Builders</a></b></p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">RouteBuilder builder = <span class="code-keyword">new</span>
RouteBuilder() {
    <span class="code-keyword">public</span> void configure() {
        errorHandler(deadLetterChannel(<span class="code-quote">"mock:error"</span>));

        from(<span class="code-quote">"seda:a"</span>)
            .multicast().to(<span class="code-quote">"seda:b"</span>, <span
class="code-quote">"seda:c"</span>, <span class="code-quote">"seda:d"</span>);
    }
};
</pre>
</div></div>

<p><b>Using the <a href="/confluence/display/CAMEL/Spring+XML+Extensions" title="Spring
XML Extensions">Spring XML Extensions</a></b></p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;camelContext errorHandlerRef=<span
class="code-quote">"errorHandler"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>
    <span class="code-tag">&lt;route&gt;</span>
        <span class="code-tag">&lt;from uri=<span class="code-quote">"seda:a"</span>/&gt;</span>
        <span class="code-tag">&lt;multicast&gt;</span>
            <span class="code-tag">&lt;to uri=<span class="code-quote">"seda:b"</span>/&gt;</span>
            <span class="code-tag">&lt;to uri=<span class="code-quote">"seda:c"</span>/&gt;</span>
            <span class="code-tag">&lt;to uri=<span class="code-quote">"seda:d"</span>/&gt;</span>
        <span class="code-tag">&lt;/multicast&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>
<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<h4><a name="RecipientList-DynamicRecipientList"></a>Dynamic Recipient List</h4>

<p>Usually one of the main reasons for using the <a href="http://www.enterpriseintegrationpatterns.com/RecipientList.html"
class="external-link" 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 href="/confluence/display/CAMEL/Expression"
title="Expression">Expression</a> (which in this case it extracts a named header
value dynamically) to calculate the list of endpoints which are either of type <a href="http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/Endpoint.html"
class="external-link" rel="nofollow">Endpoint</a> or are converted to a String and
then resolved using the endpoint <a href="/confluence/display/CAMEL/URIs" title="URIs">URIs</a>.</p>

<p><b>Using the <a href="/confluence/display/CAMEL/Fluent+Builders" title="Fluent
Builders">Fluent Builders</a></b></p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">RouteBuilder builder = <span class="code-keyword">new</span>
RouteBuilder() {
    <span class="code-keyword">public</span> void configure() {
        errorHandler(deadLetterChannel(<span class="code-quote">"mock:error"</span>));

        from(<span class="code-quote">"seda:a"</span>)
            .recipientList(header(<span class="code-quote">"foo"</span>));
    }
};
</pre>
</div></div>

<p>The above assumes that the header contains a list of endpoint URIs. The following
takes a single string header and tokenizes it</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">from(<span class="code-quote">"direct:a"</span>).recipientList(
        header(<span class="code-quote">"recipientListHeader"</span>).tokenize(<span
class="code-quote">","</span>));
</pre>
</div></div>

<h5><a name="RecipientList-Iteratablevalue"></a>Iteratable value</h5>
<p>The dynamic list of recipients that are defined in the header must be iteratable
such as:</p>
<ul class="alternate" type="square">
	<li><tt>java.util.Collection</tt></li>
	<li><tt>java.util.Iterator</tt></li>
	<li>arrays</li>
	<li><tt>org.w3c.dom.NodeList</tt></li>
	<li><b>Camel 1.6.0:</b> a single String with values separated with comma</li>
	<li>any other type will be regarded as a single value</li>
</ul>


<p><b>Using the <a href="/confluence/display/CAMEL/Spring+XML+Extensions" title="Spring
XML Extensions">Spring XML Extensions</a></b></p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;camelContext errorHandlerRef=<span
class="code-quote">"errorHandler"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>
    <span class="code-tag">&lt;route&gt;</span>
        <span class="code-tag">&lt;from uri=<span class="code-quote">"seda:a"</span>/&gt;</span>
        <span class="code-tag">&lt;recipientList&gt;</span>
            <span class="code-tag">&lt;xpath&gt;</span>$foo<span class="code-tag">&lt;/xpath&gt;</span>
        <span class="code-tag">&lt;/recipientList&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>
<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<p>For further examples of this pattern in use you could look at one of the <a href="http://svn.apache.org/viewvc/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/RecipientListTest.java?view=markup"
class="external-link" rel="nofollow">junit test case</a></p>

<h5><a name="RecipientList-UsingdelimiterinSpringXML"></a>Using delimiter
in Spring XML</h5>
<p><b>Available as of Camel 1.6.0</b><br/>
In Spring DSL you can set the <tt>delimiter</tt> 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 customer delimiter to use
instead.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;route&gt;</span>
  <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:a"</span>
/&gt;</span>
  <span class="code-tag"><span class="code-comment">&lt;!-- use comma as a
delimiter for String based values --&gt;</span></span>
  <span class="code-tag">&lt;recipientList delimiter=<span class="code-quote">","</span>&gt;</span>
    <span class="code-tag">&lt;header&gt;</span>myHeader<span class="code-tag">&lt;/header&gt;</span>
  <span class="code-tag">&lt;/recipientList&gt;</span>
<span class="code-tag">&lt;/route&gt;</span>
</pre>
</div></div>

<p>So if <b>myHeader</b> contains a String with the value <tt>"activemq:queue:foo,
activemq:topic:hello , log:bar"</tt> 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 <tt>tokenizer</tt> to archive the same.
The route above in Java DSL:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    from(<span class="code-quote">"direct:a"</span>).recipientList(header(<span
class="code-quote">"myHeader"</span>).tokenize(<span class="code-quote">","</span>));
</pre>
</div></div>

<p>In <b>Camel 2.1</b> its a bit easier as you can pass in the delimiter
as 2nd parameter:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    from(<span class="code-quote">"direct:a"</span>).recipientList(header(<span
class="code-quote">"myHeader"</span>), <span class="code-quote">"#"</span>);
</pre>
</div></div>

<h3><a name="RecipientList-Sendingtomultiplerecipientsinparallel"></a>Sending
to multiple recipients in parallel</h3>
<p><b>Available as of Camel 2.2</b></p>

<p>The <a href="/confluence/display/CAMEL/Recipient+List" title="Recipient List">Recipient
List</a> now supports <tt>parallelProcessing</tt> that for example <a
href="/confluence/display/CAMEL/Splitter" title="Splitter">Splitter</a> also supports.
You can use it to use a thread pool to have concurrent tasks sending the <a href="/confluence/display/CAMEL/Exchange"
title="Exchange">Exchange</a> to multiple recipients concurrently.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    from(<span class="code-quote">"direct:a"</span>).recipientList(header(<span
class="code-quote">"myHeader"</span>)).parallelProcessing();
</pre>
</div></div>

<p>And in Spring XML its an attribute on the recipient list tag.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   &lt;route&gt;
       &lt;from uri=<span class="code-quote">"direct:a"</span>/&gt;
       &lt;recipientList parallelProcessing=<span class="code-quote">"<span class="code-keyword">true</span>"</span>&gt;
           &lt;header&gt;myHeader&lt;/header&gt;
       &lt;/recipientList&gt;
   &lt;/route&gt;
</pre>
</div></div>

<h3><a name="RecipientList-Stopcontinuingincaseonerecipientfailed"></a>Stop
continuing in case one recipient failed</h3>
<p><b>Available as of Camel 2.2</b></p>

<p>The <a href="/confluence/display/CAMEL/Recipient+List" title="Recipient List">Recipient
List</a> now supports <tt>stopOnException</tt> that for example <a href="/confluence/display/CAMEL/Splitter"
title="Splitter">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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    from(<span class="code-quote">"direct:a"</span>).recipientList(header(<span
class="code-quote">"myHeader"</span>)).stopOnException();
</pre>
</div></div>

<p>And in Spring XML its an attribute on the recipient list tag.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   &lt;route&gt;
       &lt;from uri=<span class="code-quote">"direct:a"</span>/&gt;
       &lt;recipientList stopOnException=<span class="code-quote">"<span class="code-keyword">true</span>"</span>&gt;
           &lt;header&gt;myHeader&lt;/header&gt;
       &lt;/recipientList&gt;
   &lt;/route&gt;
</pre>
</div></div>

<p><b>Note:</b> You can combine <tt>parallelProcessing</tt>
and <tt>stopOnException</tt> and have them both <tt>true</tt>.</p>

<h3><a name="RecipientList-Ignoreinvalidendpoints"></a>Ignore invalid endpoints</h3>
<p><b>Available as of Camel 2.3</b></p>

<p>The <a href="/confluence/display/CAMEL/Recipient+List" title="Recipient List">Recipient
List</a> now supports <tt>ignoreInvalidEndpoints</tt> which the <a href="/confluence/display/CAMEL/Routing+Slip"
title="Routing Slip">Routing Slip</a> also supports. You can use it to skip endpoints
which is invalid.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    from(<span class="code-quote">"direct:a"</span>).recipientList(header(<span
class="code-quote">"myHeader"</span>)).ignoreInvalidEndpoints();
</pre>
</div></div>

<p>And in Spring XML its an attribute on the recipient list tag.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   &lt;route&gt;
       &lt;from uri=<span class="code-quote">"direct:a"</span>/&gt;
       &lt;recipientList ignoreInvalidEndpoints=<span class="code-quote">"<span
class="code-keyword">true</span>"</span>&gt;
           &lt;header&gt;myHeader&lt;/header&gt;
       &lt;/recipientList&gt;
   &lt;/route&gt;
</pre>
</div></div>

<p>Then lets say the <tt>myHeader</tt> contains the following two endpoints
<tt>direct:foo,xxx:bar</tt>. The first endpoint is valid and works. However the
2nd is invalid and will just be ignored. Camel logs at INFO level about, so you can see why
the endpoint was invalid.</p>


<h3><a name="RecipientList-Usingcustom%7B%7BAggregationStrategy%7D%7D"></a>Using
custom <tt>AggregationStrategy</tt></h3>
<p><b>Available as of Camel 2.2</b></p>

<p>You can now use you own <tt>AggregationStrategy</tt> with the <a href="/confluence/display/CAMEL/Recipient+List"
title="Recipient List">Recipient List</a>. However its not that often you need that.
What its good for is that in case you are using <a href="/confluence/display/CAMEL/Request+Reply"
title="Request Reply">Request Reply</a> messaging then the replies from the recipient
can be aggregated. By default Camel uses <tt>UseLatestAggregationStrategy</tt>
which just keeps that last received reply. What if you must remember all the bodies that all
the recipients send back, then you can use your own custom aggregator that keeps those. Its
the same principle as with the <a href="/confluence/display/CAMEL/Aggregator" title="Aggregator">Aggregator</a>
EIP so check it out for details.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    from(<span class="code-quote">"direct:a"</span>)
        .recipientList(header(<span class="code-quote">"myHeader"</span>)).aggregationStrategy(<span
class="code-keyword">new</span> MyOwnAggregationStrategy())
        .to(<span class="code-quote">"direct:b"</span>);
</pre>
</div></div>


<p>And in Spring XML its an attribute on the recipient list tag.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   &lt;route&gt;
       &lt;from uri=<span class="code-quote">"direct:a"</span>/&gt;
       &lt;recipientList strategyRef=<span class="code-quote">"myStrategy"</span>&gt;
           &lt;header&gt;myHeader&lt;/header&gt;
       &lt;/recipientList&gt;
       &lt;to uri=<span class="code-quote">"direct:b"</span>/&gt;
   &lt;/route&gt;

   &lt;bean id=<span class="code-quote">"myStrategy"</span> class=<span
class="code-quote">"com.mycompany.MyOwnAggregationStrategy"</span>/&gt;
</pre>
</div></div>

<h3><a name="RecipientList-Usingcustomthreadpool"></a>Using custom thread
pool</h3>
<p><b>Available as of Camel 2.2</b></p>

<p>A thread pool is only used for <tt>parallelProcessing</tt>. You supply
your own custom thread pool via the <tt>ExecutorServiceStrategy</tt> (see Camel's
<a href="/confluence/display/CAMEL/Threading+Model" title="Threading Model">Threading
Model</a>), the same way you would do it for the <tt>aggregationStrategy</tt>.
By default Camel uses a thread pool with 10 threads (subject to change in a future version).</p>

<h3><a name="RecipientList-Usingmethodcallasrecipientlist"></a>Using method
call as recipient list</h3>
<p>You can use a <a href="/confluence/display/CAMEL/Bean" title="Bean">Bean</a>
to provide the recipients, for example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:queue:test"</span>).recipientList().method(MessageRouter.class,
<span class="code-quote">"routeTo"</span>);
</pre>
</div></div>

<p>And then <tt>MessageRouter</tt>:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class MessageRouter {

    <span class="code-keyword">public</span> <span class="code-object">String</span>
routeTo() {
        <span class="code-object">String</span> queueName = <span class="code-quote">"activemq:queue:test2"</span>;
        <span class="code-keyword">return</span> queueName;
    }
}
</pre>
</div></div>

<p>When you use a <a href="/confluence/display/CAMEL/Bean" title="Bean">Bean</a>
then do <b>not</b> also use the <tt>@RecipientList</tt> annotation
as this will in fact add yet another recipient list, so you end up having two. Do <b>not</b>
do like this.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class MessageRouter {

    @RecipientList
    <span class="code-keyword">public</span> <span class="code-object">String</span>
routeTo() {
        <span class="code-object">String</span> queueName = <span class="code-quote">"activemq:queue:test2"</span>;
        <span class="code-keyword">return</span> queueName;
    }
}
</pre>
</div></div>

<p>Well you should only do like that above (using <tt>@RecipientList</tt>)
if you route just route to a <a href="/confluence/display/CAMEL/Bean" title="Bean">Bean</a>
which you then want to act as a recipient list.<br/>
So the original route can be changed to:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:queue:test"</span>).bean(MessageRouter.class,
<span class="code-quote">"routeTo"</span>);
</pre>
</div></div>
<p>Which then would invoke the routeTo method and detect its annotated with <tt>@RecipientList</tt>
and then act accordingly as if it was a recipient list EIP.</p>


<h3><a name="RecipientList-Usingtimeout"></a>Using timeout</h3>
<p><b>Available as of Camel 2.5</b></p>

<p>If you use <tt>parallelProcessing</tt> then you can configure a total
<tt>timeout</tt> 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 is slow. For
example you can set a timeout value of 20 sec.</p>

<p>For example in the unit test below you can see 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 <tt>"BC"</tt>.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">from(<span class="code-quote">"direct:start"</span>)
    .multicast(<span class="code-keyword">new</span> AggregationStrategy() {
            <span class="code-keyword">public</span> Exchange aggregate(Exchange
oldExchange, Exchange newExchange) {
                <span class="code-keyword">if</span> (oldExchange == <span
class="code-keyword">null</span>) {
                    <span class="code-keyword">return</span> newExchange;
                }

                <span class="code-object">String</span> body = oldExchange.getIn().getBody(<span
class="code-object">String</span>.class);
                oldExchange.getIn().setBody(body + newExchange.getIn().getBody(<span class="code-object">String</span>.class));
                <span class="code-keyword">return</span> oldExchange;
            }
        })
        .parallelProcessing().timeout(250).to(<span class="code-quote">"direct:a"</span>,
<span class="code-quote">"direct:b"</span>, <span class="code-quote">"direct:c"</span>)
    <span class="code-comment">// use end to indicate end of multicast route
</span>    .end()
    .to(<span class="code-quote">"mock:result"</span>);

from(<span class="code-quote">"direct:a"</span>).delay(1000).to(<span class="code-quote">"mock:A"</span>).setBody(constant(<span
class="code-quote">"A"</span>));

from(<span class="code-quote">"direct:b"</span>).to(<span class="code-quote">"mock:B"</span>).setBody(constant(<span
class="code-quote">"B"</span>));

from(<span class="code-quote">"direct:c"</span>).to(<span class="code-quote">"mock:C"</span>).setBody(constant(<span
class="code-quote">"C"</span>));
</pre>
</div></div>

<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td><b>Timeout in other EIPs</b><br
/>This <tt>timeout</tt> feature is also supported by <a href="/confluence/display/CAMEL/Splitter"
title="Splitter">Splitter</a> and both <tt>multicast</tt> and <tt>recipientList</tt>.</td></tr></table></div>

<p>By default if a timeout occurs the <tt>AggregationStrategy</tt> is not
invoked. However you can implement a specialized version</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> <span class="code-keyword">interface</span>
TimeoutAwareAggregationStrategy <span class="code-keyword">extends</span> AggregationStrategy
{

    /**
     * A timeout occurred
     *
     * @param oldExchange  the oldest exchange (is &lt;tt&gt;<span class="code-keyword">null</span>&lt;/tt&gt;
on first aggregation as we only have the <span class="code-keyword">new</span>
exchange)
     * @param index        the index
     * @param total        the total
     * @param timeout      the timeout value in millis
     */
    void timeout(Exchange oldExchange, <span class="code-object">int</span> index,
<span class="code-object">int</span> total, <span class="code-object">long</span>
timeout);
</pre>
</div></div>

<p>This allows you to deal with the timeout in the <tt>AggregationStrategy</tt>
if you really need to. </p>

<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Timeout is
total</b><br />The timeout is total, which means that after X time, Camel will
aggregate the messages which has completed within the timeframe. The remainders will be cancelled.
Camel will also only invoke the <tt>timeout</tt> method in the <tt>TimeoutAwareAggregationStrategy</tt>
once, for the first index which caused the timeout.</td></tr></table></div>


<h3><a name="RecipientList-UsingonPreparetoexecutecustomlogicwhenpreparingmessages"></a>Using
onPrepare to execute custom logic when preparing messages</h3>
<p><b>Available as of Camel 2.8</b></p>

<p>See details at <a href="/confluence/display/CAMEL/Multicast" title="Multicast">Multicast</a></p>


<h4><a name="RecipientList-UsingThisPattern"></a>Using This Pattern</h4>

<p>If you would like to use this EIP Pattern then please read the <a href="/confluence/display/CAMEL/Getting+Started"
title="Getting Started">Getting Started</a>, you may also find the <a href="/confluence/display/CAMEL/Architecture"
title="Architecture">Architecture</a> useful particularly the description of <a
href="/confluence/display/CAMEL/Endpoint" title="Endpoint">Endpoint</a> and <a
href="/confluence/display/CAMEL/URIs" title="URIs">URIs</a>. Then you could try out
some of the <a href="/confluence/display/CAMEL/Examples" title="Examples">Examples</a>
first before trying this pattern out.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/Recipient+List">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=49325&revisedVersion=39&originalVersion=38">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/Recipient+List?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message