Page edited by Claus Ibsen

Recipient List

The Recipient List from the EIP patterns allows you to route messages to a number of dynamically specified recipients.

The recipients will receive a copy of the same Exchange and Camel will execute them sequentially.

Static Recipient List

The following example shows how to route a request from an input queue:a endpoint to a static list of destinations

Using Annotations
You can use the RecipientList Annotation on a POJO to create a Dynamic Recipient List. For more details see the Bean Integration.

Using the Fluent Builders

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        errorHandler(deadLetterChannel("mock:error"));


        from("seda:a").multicast().to("seda:b", "seda:c", "seda:d");
    }
};

Using the Spring XML Extensions

<camelContext errorHandlerRef="errorHandler" streamCache="false" id="camel" xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="seda:a"/>
        <multicast>
            <to uri="seda:b"/>
            <to uri="seda:c"/>
            <to uri="seda:d"/>
        </multicast>
    </route>
</camelContext>

Dynamic Recipient List

Usually one of the main reasons for using the Recipient List 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 _expression_ (which in this case it extracts a named header value dynamically) to calculate the list of endpoints which are either of type Endpoint or are converted to a String and then resolved using the endpoint URIs.

Using the Fluent Builders

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        errorHandler(deadLetterChannel("mock:error"));

        from("seda:a").recipientList(header("foo"));
    }
};

The above assumes that the header contains a list of endpoint URIs. The following takes a single string header and tokenizes it

from("direct:a").recipientList(
        header("recipientListHeader").tokenize(","));

Iteratable value

The dynamic list of recipients that are defined in the header must be iteratable such as:

java.util.Collection
java.util.Iterator
arrays
org.w3c.dom.NodeList
Camel 1.5.1: a single String with values separated with comma
any other type will be regarded as a single value

Using the Spring XML Extensions

<camelContext errorHandlerRef="errorHandler" streamCache="false" id="camel" xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="seda:a"/>
        <recipientList>
            <xpath>$foo</xpath>
        </recipientList>
    </route>
</camelContext>

For further examples of this pattern in use you could look at one of the junit test case

Using delimiter in Spring XML

Available as of Camel 1.5.1
In Spring DSL you can set the delimiter 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.

<route>
  <from uri="direct:a" />
  <!-- use comma as a delimiter for String based values -->
  <recipientList delimiter=",">
    <header>myHeader</header>
  </recipientList>
</route>

So if myHeader contains a String with the value "activemq:queue:foo, activemq:topic:hello , log:bar" 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.

Note: In Java DSL you use the tokenizer to archive the same. The route above in Java DSL:

    from("direct:a").recipientList(header("myHeader").tokenize(","));

In Camel 2.1 its a bit easier as you can pass in the delimiter as 2nd parameter:

    from("direct:a").recipientList(header("myHeader"), "#");

Sending to multiple recipients in parallel

Available as of Camel 2.2

The Recipient List now supports parallelProcessing that for example Splitter also supports. You can use it to use a thread pool to have concurrent tasks sending the Exchange to multiple recipients concurrently.

    from("direct:a").recipientList(header("myHeader")).parallelProcessing();

And in Spring XML its an attribute on the recipient list tag.

   <route>
       <from uri="direct:a"/>
       <recipientList parallelProcessing="true">
           <header>myHeader</header>
       </recipientList>
   </route>

Stop continuing in case one recipient failed

Available as of Camel 2.2

The Recipient List now supports stopOnException that for example Splitter also supports. You can use it to stop sending to any further recipients in case any recipient failed.

    from("direct:a").recipientList(header("myHeader")).stopOnException();

And in Spring XML its an attribute on the recipient list tag.

   <route>
       <from uri="direct:a"/>
       <recipientList stopOnException="true">
           <header>myHeader</header>
       </recipientList>
   </route>

Note: You can combine parallelProcessing and stopOnException and have them both true.

Using custom `AggregationStrategy`

Available as of Camel 2.2

You can now use you own AggregationStrategy with the Recipient List. However its not that often you need that. What its good for is that in case you are using Request Reply messaging then the replies from the recipient can be aggregated. By default Camel uses UseLatestAggregationStrategy 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 Aggregator EIP so check it out for details.

    from("direct:a").recipientList(header("myHeader")).aggregationStrategy(new MyOwnAggregationStrategy());

And in Spring XML its an attribute on the recipient list tag.

   <route>
       <from uri="direct:a"/>
       <recipientList strategyRef="myStrategy">
           <header>myHeader</header>
       </recipientList>
   </route>

   <bean id="myStrategy" class="com.mycompany.MyOwnAggregationStrategy"/>

Using custom thread pool

Available as of Camel 2.2

This is only needed when you use parallelProcessing. By default Camel uses a thread pool with 10 threads. Notice this is subject to change when we overhaul thread pool management and configuration later (hopefully in Camel 2.2).

You configure this just as you would with the custom aggregation strategy.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started, you may also find the Architecture useful particularly the description of Endpoint and URIs. Then you could try out some of the Examples first before trying this pattern out.

Change Notification Preferences

View Online | View Change | Add Comment

[CONF] Apache Camel > Recipient List

Recipient List

Page edited by Claus Ibsen

Recipient List

Static Recipient List

Dynamic Recipient List

Iteratable value

Using delimiter in Spring XML

Sending to multiple recipients in parallel

Stop continuing in case one recipient failed

Using custom `AggregationStrategy`

Using custom thread pool

Using This Pattern

Reply via email to

[CONF] Apache Camel > Recipient List

Recipient List

Page edited by Claus Ibsen

Recipient List

Static Recipient List

Dynamic Recipient List

Iteratable value

Using delimiter in Spring XML

Sending to multiple recipients in parallel

Stop continuing in case one recipient failed

Using custom AggregationStrategy

Using custom thread pool

Using This Pattern

Reply via email to

Using custom `AggregationStrategy`