The ForEach mediator splits the message into a number of different messages derived from the parent message by finding matching elements for the XPath expression specified. Based on the matching elements, new messages are created for each iteration and processed sequentially. The processing is carried out based on a specified sequence. The behaviour of ForEach mediator is similar to a generic loop. The mediated messages will be merged back to the original message sequentially.
ForEach mediator requires an XPath expression and a sequence (inline or referred). The original message is split into sub-messages based on the XPath expression and is mediated as instructed by the given sequence. Also, ForEach mediator mediation happens in a single thread as a blocked execution. After mediation, the sub-messages are merged back to their original parent element in the original message
The ForEach mediator creates the following properties during mediation.
| Property | Description |
|---|---|
| FOREACH_ORIGINAL_MESSAGE | This contains the original envelope of the messages split by the ForEach mediator. |
| FOREACH_COUNTER | This contains the count of the messages processed. The message count increases during each iteration. |
Iterate mediator is quite similar to the ForEach mediator. You can use complex XPath expressions to conditionally select elements to iterate over in both mediators. Following are the main difference between ForEach and Iterate mediators:
- ForEach supports modifying the original payload. You can use Iterate for situations where you send the split messages to a target and collect them by an Aggregate in a different flow.
- ForEach is for modifying a split message. This eliminates the need for complex XSLT mediators.
- You need to always accompany an Iterate with an Aggregate mediator. ForEach loops over the sub-messages and merges them back to the same parent element of the message.
- Iterate allows sending a message to an endpoint, whereas ForEach will not. ForEach will not allow to use Call, Send or CallOut mediators in the sequence.
- ForEach does not split the message flow, unlike Iterate Mediator. It guarantees to execute in the same thread until all iterations are complete.
Syntax
<for-each expression="xpath" [sequence="sequence_ref"] [id="foreach_id"] >
<sequence>
(mediator)+
</sequence>?
</for-each>
UI Configuration
The parameters available to configure the ForEach mediator are as follows.
| Parameter Name | Description |
|---|---|
| ForEach ID | If a value is entered for this parameter, it will be used as the prefix for the FOREACH_ORIGINAL_MESSAGE and FOREACH_COUNTER properties created during mediation. This is an optional parameter. However, it is recommended to define a ForEach ID in nested ForEach scenarios to avoid the properties mentioned from being overwritten. |
| Expression | The XPath expression with which different messages are derived by splitting the parent message. This expression should have matching elements based on which the splitting is carried out. You can click NameSpaces to add namespaces when you are providing an expression. Then the Namespace Editor panel would appear where you can provide any number of namespace prefixes and URLs used in the XPath expression. |
| Sequence | The mediation sequence that should be applied to the message is derived from the parent message. ForEach mediator is used only for transformations, thereby, you should not include Call, Send and Callout mediators, which are used to invoke endpoints, in this sequence.
|
Note
You can configure the mediator using XML. Click switch to source view in the Mediator window.
Example
In this configuration, the //m0:getQuote/m0:request" XPath expression evaluates the split messages to be derived from the parent message. Then the split messages pass through a sequence which includes a Log mediator with the log level set to full.
<foreach id="foreach_1" expression="//m0:getQuote/m0:request" xmlns:m0="http://services.samples">
<sequence>
<log level="full">
</sequence>
</foreach>
Sample
See Sample 18: Transforming a Message Using ForEach Mediator.