Split

A common use case is to split a list/set/collection/map, array, or something that is iterable from the message body.

The Split EIP will by default split the message body based on the value type:

For any other type the message body is not split, and instead used as-is, meaning that the Split EIP will be split into a single message (the same).

To use this with the splitter you should just use body as the expression:

You can enable parallel processing with Split EIP so each split message is processed by its own thread in parallel.

The example below enabled parallel mode:

You may want to continue routing the exchange after the Split EIP. In Java DSL you need to use end() to mark where split ends, and where other EIPs can be added to continue the route.

In the example above then sending to mock:result happens after the Spllit EIP has finished. In other words the message should finish splitting the entire message before the message continues.

The Splitter will by default return the original input message.

You can control this by using a custom AggregationStrategy.

The AggregationStrategy is used for aggregating all the split exchanges together as a single response exchange, that becomes the outgoing exchange after the Split EIP block.

The example now aggregates with the MyAggregationStrategy class:

The Split EIP operates in two modes when splitting:

You can split in streaming mode as shown:

You can also supply a custom Bean to perform the splitting in streaming mode like this:

Then the custom bean could for example be implemented as follows:

The bean should just return something that the splitter can work with when splitting, such as a List or Iterator etc.

There are two tokenizers that can be used to tokenize an XML payload:

The first tokenizer uses the same principle as in the text tokenizer to scan the XML payload and extract a sequence of tokens. If you have a big XML payload, from a file source, and want to split it in streaming mode, then you can use the Tokenize language with start/end tokens to do this with low memory footprint.

For example, you may have an XML payload structured as follows:

Now to split this big file using XPath would cause the entire content to be loaded into memory. So instead we can use the Tokenize language to do this as follows:

This will split the file using the tag name of the child nodes (more precisely speaking, the local name of the element without its namespace prefix if any), which mean it will grab the content between the <order> and </order> tags (incl. the tags).

So for example a split message would be structured as follows:

If you want to inherit namespaces from a root/parent tag, then you can do this as well by providing the name of the root/parent tag:

You can set inheritNamsepaceTagName property to * to include the preceding context in each token (i.e., generating each token enclosed in its ancestor elements). It is noted that each token must share the same ancestor elements in this case. The above tokenizer works well on simple structures but has some inherent limitations in handling more complex XML structures.

The second tokenizer (XML Tokenize) uses a StAX parser to overcome these limitations. This tokenizer recognizes XML namespaces and also handles simple and complex XML structures more naturally and efficiently.

To split with XML namespaces on a tag with a local namespace such as {urn:shop}order, we can write:

Two arguments control the behavior of the tokenizer:

The available extraction modes are:

Having an input XML:

Each mode will result in the following tokens,

In XML, the equivalent route would be written as follows:

or setting the extraction mode explicitly as

Note that this StAX based tokenizer uses StAX Location API and requires a StAX Reader implementation (such as Woodstox) that correctly returns the offset position pointing to the beginning of each event triggering segment (the offset position of < at each start and end element event). If you use a StAX Reader which does not implement that API correctly it results in invalid XML snippets after the split.

For example the snippet could be wrong terminated:

The Tokenize language can be used for grouping N parts together, for example to split big files into chunks of 1000 lines.

Doing this is easy as the following example shows:

The group value must be a positive number dictating how many elements to combine together in a group. Each part will be combined using the token.

In the example above the message being sent to the activemq order queue, will contain 1000 lines, and each line separated by the token (which is a new line token).

The output when using the group option is always a java.lang.String type.

This sample shows how you can split an Exchange, process each split message, aggregate and return a combined response to the original caller.

The route below illustrates this and how the split supports a custom AggregationStrategy to build up the combined response message.

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 message body with the String value: A@B@C. The flow is:

The Splitter will by default continue to process the entire Exchange even in case of one of the split message will throw an exception during routing.

For example if you have an Exchange with 1000 rows that you split. During processing of these split messages an exception is thrown at the 17th. What Camel does by default is to process the remainder 983 messages. You have the chance to deal with the exception when aggregating using an AggregationStrategy.

But sometimes you just want Camel to stop and let the exception be propagated back, and let the Camel Error Handler handle it. You can do this by specifying that it should stop in case of an exception occurred. This is done by the stopOnException option as shown below:

In the example above, then MyProcessor is causing a failure and throws an exception. This means the Split EIP will stop after this, and not split anymore.

The Splitter will by default not share unit of work between the parent exchange and each split exchange. This means each sub exchange has its own individual unit of work.

For example, you need to split a big message, and regard that process as an atomic isolated operation that either is a success or failure. In case of a failure you want that big message to be moved into a dead letter queue.

To support this use case, you would have to share the unit of work on the Splitter.

Here is an example in Java DSL:

What would happen is that in case there is an exception thrown during splitting then the error handler will kick in (yes error handling still applies for the sub messages).

The error handler in this example is configured to retry up till 3 times. And when a split message fails all redelivery attempts (its exhausted), then this message is not moved into that dead letter queue.

The reason is that we have shared the unit of work, so the split 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. 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. No redelivery attempts are performed (as it was marked for rollback) and the Exchange will be moved into the dead letter queue.

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