This tutorial aims to guide the reader through the stages of creating a project which uses Camel to facilitate the routing of messages from a JMS queue to a Spring service. The route works in a synchronous fashion returning a response to the client.

The method can be invoked in a number of ways as described in the Bean Integration such as

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.

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 AggregationStrategy that will assemble th e 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.
`strategyMethodName`		Camel 2.12: This option can be used to explicit declare the method name to use, when using POJOs 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` values 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's 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. 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 implementa tion, 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 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 a bit of care. 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 uni t 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 all together.

Static Recipient List

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

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 AggregationStrategy that will assemble th e 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 explicit declare the method name to use, when using POJOs as the `AggregationStrategy< /code>. 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` values 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's 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. Though in some use-cases this ca n 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 failu res. 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 rep lies 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 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 a bit of care. 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 all together.

Static Recip ient 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

The splitter can use any Expression language so you could use any of the Languages Supported such as XPath, XQuery, SQL or one of the Scripting Languages to perform the split. e.g.

Using the Spring XML Extensions

@@ -12933,7 +12933,7 @@ RouteBuilder builder = new RouteBuilder(
     </route>
 </camelContext>
 ]]>
-

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

Splitting a Collection, Iterator or Array

A common use case is to split a Collection, Iterator or Array from the message. In the sample below we simply use an Expression to identify the value to split.

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

Splitting a Collection, Iterator or Array

A common use case is to split a Collection, Iterator or Array from the message. In the sample below we simply use an Expression to identify the value to split.

 
@@ -13083,7 +13083,7 @@ from("direct:message")
         .split().method("mySplitterBean", "splitMessage")
         .to("mock:result");
 ]]>
-

And the logic for our Bean is as simple as. Notice we use Camel Bean Binding to pass in the message body as a String object.

And the OrderService bean is as follows:

And our custom aggregationStrategy that is responsible for holding the in progress aggregated message that after the splitter is ended will be sent to the buildCombinedResponse method for final processing before the combined response can be returned to the waiting caller.

So lets run the sample and see how it works.
We send an Exchange to the direct:start endpoint containing a IN body with the String value: A@B@C. The flow is:

Now in this example what would happen is that in case there is a problem processing each sub message, the error handler will kick in (yes error handling still applies for the sub messages). But what doesn't happen is that if a sub message fails all redelivery attempts (its exhausted), then its not moved into that dead letter queue. The reason is that we have shared the unit of work, so the sub message will report the error on the shared unit of work. When the Splitter is done, it checks the state of the shared unit of work and checks if any errors occurred. And if an error occurred it will set the exception on the Exchange and mark it for rollback. The error handler will yet again kick in, as the Exchange has been marked as rollback and it had an exception as well. No redelivery attempts is performed (as it was ma rked for rollback) and the Exchange will be moved into the dead letter queue.

Using this from XML DSL is just as easy as you just have to set the shareUnitOfWork attribute to true:

Now in this example what would happen is that in case there is a problem processing each sub message, the error handler will kick in (yes error handling still applies for the sub messages). But what doesn't happen is that if a sub message fails all redelivery attempts (its exhausted), then its not moved into that dead letter queue. The reason is that we have shared the unit of work, so the sub message will report the error on the shared unit of work. When the Splitter is done, it checks the state of the shared unit of work and checks if any errors occurred. And if an error occurred it will set the exception on the Exchange and mark it for rollback. The error handler will yet again kick in, as the Exchange has been marked as rollback and it had an exception as well. No redelivery attempts is performed (as it was marke d for rollback) and the Exchange will be moved into the dead letter queue.

Using this from XML DSL is just as easy as you just have to set the shareUnitOfWork attribute to true:

By default Multicast invokes each endpoint sequentially. If parallel processing is desired, simply use

In case of using InOut MEP, an AggregationStrategy is used for aggregating all reply messages. The default is to only use the latest reply message and discard any earlier replies. The aggregation strategy is configurable:

@@ -14878,7 +14876,7 @@ public class Animal implements Serializa
     }
 }
 ]]>
-

Then we can create a deep clone processor which clones the message body:

AnimalDeepClonePrepare

Then we can create a deep clone processor which clones the message body:

AnimalDeepClonePrepare

Then we can use the AnimalDeepClonePrepare class in the Multicast route using the onPrepare option as shown:

Multicast using onPrepare

Then we can use the AnimalDeepClonePrepare class in the Multicast route using the onPrepare option as shown:

Multicast using onPrepare

And the same example in XML DSL

Multicast using onPrepare

And the same example in XML DSL

Multicast using onPrepare

Notice the onPrepare option is also available on other EIPs such as Splitter, Recipient List, and Wire Tap.

Using This Pattern

Loop

Tutorial on Spring Remoting with JMS

Preface

Using This Pattern

Recipient List

Options

Static Recipient List

Recipient List

Options

Static Recip ient List

Splitting a Collection, Iterator or Array

Splitting a Collection, Iterator or Array

Using This Pattern

Using This Pattern

Loop

See Also

CXF Component