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.

Options

< tr>

Name	Default Value	Description
`delimiter`	`,`	Delimiter used if the Expression returned multiple endpoints. Camel 2.13 can be disabled using "false"
`strategyRef`		An Aggregatio nStrategy 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. From Camel 2.12 onwards you can also use a POJO as the `AggregationStrategy`, see the Aggregate 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.
`strategyMethodName`		Camel 2.12: This option can be used to explicitly declare the method name to use, when using PO JOs as the `AggregationStrategy`. See the Aggregate page for more details.
`strategyMethodAllowNull`	`false`	Camel 2.12: If this option is `false` then the aggregate method is not used if there was no data to enrich. If this option is `true` then `null` is used as the `oldExchange` (when no data to enrich), when using POJOs as the `AggregationStrategy`. See the Aggregate page for more details.
`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 is the sending and processing of replies from recipients which happens in parallel.
`parallelAggregate`	`false`	Camel 2.14: If enabled then the `aggregate` method on `AggregationStrategy` can be called concurrently. Notice that this would require the implementation of `AggregationStrategy` to be implemented as thread-safe. By default this is `false` meaning that Camel synchronizes the call to the `aggregate` method. T hough in some use-cases this can be used to archive higher performance when the `AggregationStrategy` is implemented as thread-safe.
`executorServiceRef`		Camel 2.2: A custom Thread Pool to use for parallel processing. Note that enabling this option implies parallel processing, so you need not enable that option as well.
`stopOnException`	`false`	Camel 2.2: Whether to immediately stop processing when an exception occurs. If disabled, Camel will send the message to all recipients reg ardless of any individual failures. You can process exceptions in an AggregationStrategy implementation, which supports full control of error handling.
`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.
`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.
`timeout`		Camel 2.5: Specifies a processing timeout in milliseconds. If the Recipient List hasn'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, its `timeout` method is invoked before breaking out. Beware: 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.
`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).
`shareUnitOfWork`	`false`	Camel 2.8: Whether the unit of work should be shared. See the same option on Splitter for more details.
`cacheSize`	`1000`	Camel 2.13.1/2.12.4: Allows to configure the cache size for the `ProducerCache` 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.

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

+

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.

Options

Name	Default Value	Description
`delimiter`	`,`	Delimiter used if the Expression returned multiple endpoints. Camel 2.13 can be disabled using "false"
`strategyRef`		An Aggregatio nStrategy 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. From Camel 2.12 onwards you can also use a POJO as the `AggregationStrategy`, see the Aggregator 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.
`strategyMethodName`		Camel 2.12: This option can be used to explicitly declare the method name to use, when using P OJOs as the `AggregationStrategy`. See the Aggregator page for more details.
`strategyMethodAllowNull`	`false`	Camel 2.12: If this option is `false` then the aggregate method is not used if there was no data to enrich. If this option is `true` then `null` is used as the `oldExchange` (when no data to enrich), when using POJOs as the `AggregationStrategy`. See the Aggregator page for more details.
`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 is the sending and processing of replies from recipients which happens in parallel.
`parallelAggregate`	`false`	Camel 2.14: If enabled then the `aggregate` method on `AggregationStrategy` can be called concurrently. Notice that this would require the implementation of `AggregationStrategy` to be implemented as thread-safe. By default this is `false` meaning that Camel synchronizes the call to the `aggre gate` method. Though in some use-cases this can be used to archive higher performance when the `AggregationStrategy` is implemented as thread-safe.
`executorServiceRef`		Camel 2.2: A custom Thread Pool to use for parallel processing. Note that enabling this option implies parallel processing, so you need not enable that option as well.
`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 implementation, which supports full control of error handling.
`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.
`streaming`	`false`	Ca mel 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.
`timeout`		Camel 2.5: Specifies a processing timeout in milliseconds. If the Recipient List hasn'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, its `timeout` method is invoked before breaking out. Beware: 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.
`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 l ogic).
`shareUnitOfWork`	`false`	Camel 2.8: Whether the unit of work should be shared. See the same option on Splitter for more details.
`cacheSize`	`1000`	Camel 2.13.1/2.12.4: Allows to configure the cache size for the `ProducerCache` 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.

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

-

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

Using delimiter in Spring XML

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 custom delimiter to use instead.

+

For further examples of this pattern in action you could take a look at one of the junit test cases.

Using delimiter in Spring XML

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 custom delimiter to use instead.

-

Then let us say the myHeader contains the following two endpoints direct:foo,xxx:bar. 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.

Using custom `AggregationStrategy`

Available as of Camel 2.2

You can now use your own AggregationStrategy with the Recipient List. However this is rarely needed. What it is good for is that in case you are using Request Reply messaging then the replies from the recipients can be aggregated. By default Camel uses UseLatestAggregationStrategy which just keeps that last received reply. If you must remember all the bodies that all the recipients send back, then you can use your own custom aggregator that keeps those. It is the same principle as with the Aggregator EIP so check it out for details.

+

Then let us say the myHeader contains the following two endpoints direct:foo,xxx:bar. 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.

Using custom `AggregationStrategy`

Available as of Camel 2.2

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

-

Well you should only do like that above (using @RecipientList) if you route just route to a Bean which you then want to act as a recipient list.
So the original route can be changed to:

+

You should only use the snippet above (using @RecipientList) if you just route to a Bean which you then want to act as a recipient list.
So the original route can be changed to:

Which then would invoke the routeTo method and detect that it is annotated with @RecipientList and then act accordingly as if it was a recipient list EIP.

Using timeout

Available as of Camel 2.5

If you use parallelProcessing then you can configure a total timeout 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.

Tasks may keep running

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.

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 "BC".

Recipient List

Options

Static Recipient List

Recipient List

Options

Static Recipient List

Using delimiter in Spring XML

Using delimiter in Spring XML

Using custom AggregationStrategy

Using custom AggregationStrategy

Using timeout

Using custom `AggregationStrategy`

Using custom `AggregationStrategy`