Skip to content

Iterate Mediator

The Iterate Mediator implements the Splitter enterprise integration pattern and splits the message into several different messages derived from the parent message.

Info

The Iterate mediator is similar to the Clone mediator. The difference between the two mediators is, that the Iterate mediator splits a message into different parts, whereas the Clone mediator makes multiple identical copies of the message.

Info

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

  • Use the ForEach mediator only for message transformations. If you need to make back-end calls from each iteration, use the iterate mediator.
  • The ForEach mediator supports modifying the original payload. You can use the Iterate mediator for situations where you send the split messages to a target and collect them by an Aggreagte mediator in a different flow.
  • You need to always accompany an Iterate mediator with an Aggregate mediator. ForEach mediator loops over the sub-messages and merges them back to the same parent element of the message.
  • In Iterate mediator, you need to send the split messages to an endpoint to continue the message flow. However, ForEach mediator does not allow using Call, Send and Callout mediators in the sequence.
  • The ForEach mediator does not split the message flow, unlike the Iterate mediator. It guarantees execution in the same thread until all iterations are complete.

Syntax

<iterate [sequential=(true|false)] [continueParent=(true|false)] [preservePayload=(true|false)] [(attachPath="expression")? expression="expression"]>
   <target [to="uri"] [soapAction="qname"] [sequence="sequenceKey"] [endpoint="endpointKey"]>
     <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 out 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 mediation flow continues on the mediators defined after the iterate mediator. Possible values are as follows.

  • True: If this is selected, the mediation flow continues at the point where the iteration started, once all iterations are finished.
  • False: If this is selected, the mediation flow will not return to the parent sequence after the iterations are complete.
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. The split elements are attached to the specified attach path.
  • False: If this is selected, the original message payload will not be used as a template. After the iteration, the payload is replaced by the split elements. This is the default value.
Iterate Expression

The expression is used to split the message. This expression selects the set of sub messages from the request payload that are applied to the mediation defined within the iterate target. Each iteration of the iterate mediator will be executed on each sub message. 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.

In the Expression Editor you can click + Add Namespace to add namespaces.
Attach Path

When preserve payload is true, to form new messages, you can specify an expression to identify the parent element to which the split elements are attached.

In the Expression Editor you can click + Add Namespace to add namespaces.

Target configuration

Each Iterate mediator has its own target by default. It appears in the mediation tree 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.

  • 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.
  • Key: If this is selected, you can refer to a predefined sequence.
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.
  • Key: If this is selected, you can refer to a predefined endpoint.

Examples

In these examples, the Iterate mediator splits the messages into parts and processes them asynchronously. Also see the Splitting Messages and Aggregating Responses documentation.

    <iterate expression="//m0:getQuote/m0:request" preservePayload="true"
             attachPath="//m0:getQuote"
             xmlns:m0="http://services.samples">
        <target>
            <sequence>
                <call>
                    <endpoint>
                        <address
                            uri="http://localhost:9000/services/SimpleStockQuoteService"/>
                    </endpoint>
                </call>
            </sequence>
        </target>
    </iterate>

    <iterate id="jsonIterator" preservePayload="true" 
             attachPath="json-eval($.placeHolder)" 
             expression="json-eval($.students.studentlist)">
       <target>
          <sequence>
             <call>
                 <endpoint>
                       <http method="POST" uri-template="http://localhost:8280/iteratesample/echojson"/>
                 </endpoint>
             </call>
          </sequence>
       </target>
    </iterate>