Iterate Mediator

The Iterate Mediator implements the Splitter enterprise integration pattern and splits the message into a number of different messages derived from the parent message. The Iterate mediator is similar to the Clone mediator. The difference between the two mediators is, the Iterate mediator splits a message into different parts, whereas the Clone mediator makes multiple identical copies of the message.

The Iterate mediator is a content aware mediator.

Iterate Mediator is quite similar to the ForEach mediator. You can use complex XPath expressions or JSON expressions to conditionally select elements to iterate over in both mediators. Following are the main difference between ForEach and Iterate mediators:

Use the ForEach mediator only for message transformations. If you need to make back-end calls from each iteration, then use the iterate mediator.
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
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.
In Iterate you need to send the split messages to an endpoint to continue the message flow. However, ForEach does not allow using Call, Send and 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.

When you use ForEach mediator, you can only loop through segments of the message and do changes to a particular segment. For example, you can change the payload using payload factory mediator. But you cannot send the split message out to a service. Once you exit from the for-each loop, it automatically aggregates the split segments. This replaces the for-each function of the complex XSLT mediators using a ForEach mediator and a Payload Factory mediator. However, to implement the split-aggregate pattern, you still need to use Iterate mediator.

Syntax

<iterate [sequential=(true | false)] [continueParent=(true | false)] [preservePayload=(true | false)] [(attachPath="XPath|json-eval(JSON Path)")? expression="XPath|json-eval(JSON Path)"]>
   <target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]>
     <sequence>
       (mediator)+
     </sequence>?
     <endpoint>
       endpoint
     </endpoint>?
   </target>+
</iterate>

Configuration

The parameters available to configure the Iterate mediator are as follows.

Parameter Name	Description
Iterate ID	The iterate ID can be used to identify messages created by the iterate mediator. This is particularly useful when aggregating responses of messages that are created using nested iterate mediators.
Sequential Mediation	This parameter is used to specify whether the split messages should be processed sequentially or not. The processing is carried based on the information relating to the sequence and endpoint specified in the target configuration. The possible values are as follows. True: If this is selected, the split messages will be processed sequentially. Note that selecting True might cause delays due to high resource consumption. False: If this is selected, the split messages will not be processed sequentially. This is the default value and it results in better performance. The responses will not necessarily be aggregated in the same order that the requests were sent, even if the `sequential Mediation` parameter is set to `true`.
Continue Parent	This parameter is used to specify whether the original message should be preserved or not. Possible values are as follows. True: If this is selected, the original message will be preserved. False: If this is selected, the original message will be discarded. This is the default value.
Preserve Payload	This parameter is used to specify whether the original message payload should be used as a template when creating split messages. Possible values are as follows. True: If this is selected, the original message payload will be used as a template. False: If this is selected, the original message payload will not be used as a template. This is the default value.
Iterate Expression	The XPath expression used to split the message.. This expression selects the set of XML elements from the request payload that are applied to the mediation defined within the iterate target. Each iteration of the iterate mediator will get one element from that set. New messages are created for each and every matching element and processed in parallel or in sequence based on the value specified for the Sequential Mediation parameter. You can click NameSpaces to add namespaces if 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.
Attach Path	To form new messages, you can specify an XPath expression or a JSONPath expression to identify the parent element to which the split elements are attached (as expressed in Iterate expression). You can click NameSpaces to add namespaces if 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.

Each Iterate mediator has its own target by default. It appears in the mediation tree as shown below once you configure the above parameters and save them.

The parameters available to configure the target configuration are as follows.

Parameter Name	Description
SOAP Action	The SOAP action of the message.
To Address	The target endpoint address.
Sequence	This parameter is used to specify whether split messages should be mediated via a sequence or not, and to specify the sequence if they are to be further mediated. Possible options are as follows. None: If this is selected, no further mediation will be performed for the split messages. Anonymous: If this is selected, you can define an anonymous sequence for the split messages by adding the required mediators as children to Target in the mediator tree. Pick From Registry: If this is selected, you can refer to a pre-defined sequence that is currently saved as a resource in the registry. Click either Configuration Registry or Governance Registry as relevant to select the required sequence from the resource tree.
Endpoint	The endpoint to which the split messages should be sent. Possible options are as follows. None: If this is selected, the split messages are not sent to an endpoint. Anonymous: If this is selected, you can define an anonymous endpoint within the iterate target configuration to which the split messages should be sent. Click the Add link which appears after selecting this option to add the anonymous endpoint. See Adding an Endpoint for further information. Pick from Registry: If this is selected, you can refer to a pre-defined endpoint that is currently saves as a resource in the registry. Click either Configuration Registry or Governance Registry as relevant to select the required endpoint from the resource tree.

Examples

In these examples, the Iterate mediator splits the messages into parts and processes them asynchronously. Also see Splitting Messages into Parts and Processing in Parallel (Iterate/Aggregate).

Sample

See /wiki/spaces/EI6xx/pages/49611285 for another example.