<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
      "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
  <title>WSO2 ESB - Iterate Mediator </title>
  <link href="css/esb-docs.css" rel="stylesheet" />
  <link href="styles/dist-docs.css" rel="stylesheet" type="text/css"
  media="all" />
</head>

<body>
<h2>Iterate Mediator</h2>

<p>The iterate mediator implements another EIP and will split the message into
number of different messages derived from the parent message by finding
matching elements for the XPath expression specified. New messages will be
created for each and every matching element and processed in parallel (default behavior) using
either the specified sequence or endpoint. 
Created messages can also be set to process sequentially by setting the optional 'sequential' 
attribute to 'true'. Parent message can be continued or
dropped in the same way as in the clone mediator. The 'preservePayload'
attribute specifies if the original message should be used as a template when
creating the splitted messages, and defaults to 'false', in which case the
splitted messages would contain the split elements as the SOAP body. 
The optional 'id' attribute can be used to identify the iterator which created a particular 
splitted message when nested iterate mediators are used. This is particularly useful when 
aggregating responses of messages that are created using nested iterate mediators. 
</p>

<h3>Syntax</h3>
<pre xml:space="preserve"> &lt;iterate [id="id"] [continueParent=(true | false)] [preservePayload=(true | false)] [sequential=(true | false)] (attachPath="xpath")? expression="xpath"&gt;
   &lt;target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]&gt;
     &lt;sequence&gt;
       (mediator)+
     &lt;/sequence&gt;?
     &lt;endpoint&gt;
       endpoint
     &lt;/endpoint&gt;?
   &lt;/target&gt;+
 &lt;/iterate&gt;</pre>

<h3>UI Configuration</h3>

<p><img src="../iterate-mediator/docs/images/iterate_mediator_screenshot.png"
alt="" /> </p>

<p><strong>Figure1: Iterate Mediator</strong> </p>

<p>Iterate Mediator can be configured with the following options. </p>
<ul>
  <li>Iterate ID: (Optional) This can be used identify messages created by this iterate mediator, useful
    when nested iterate mediators are used.
  </li>
  <li>Sequential Mediation: (True/False), Specify whether splitted messages should be processed sequentially
    or in parallel. Default value is 'false' (parallel processing).
  </li>
  <li>Continue Parent: (True/False), Specify whether the original message
    should be continued or dropped, this is default to 'false'. </li>
  <li>Preserve Payload: (True/False), Specify whether the original message
    should be used as a template when creating the splitted messages or not,
    this is default to 'false'. </li>
  <li>Iterate Expression: Xpath expression that matches the elements which you
    want to split the message from. You can specify the namespaces that you
    used in the xpath expression by clicking the namespace link in the right
    hand side. </li>
  <li>Attach Path: (Optional), You can specify an xpath expression for elements
    that the splitted elements (as expressed in Iterate expression) are
    attached to, to form new messages </li>
</ul>

<p>For more information about target please refer Target.</p>

<h3>Example</h3>
<pre xml:space="preserve">
&lt;iterate expression="//m0:getQuote/m0:request" preservePayload="true"
         attachPath="//m0:getQuote"
         xmlns:m0="http://services.samples"&gt;
    &lt;target&gt;
        &lt;sequence&gt;
            &lt;send&gt;
                &lt;endpoint&gt;
                    &lt;address
                        uri="http://localhost:9000/services/SimpleStockQuoteService"/&gt;
                &lt;/endpoint&gt;
            &lt;/send&gt;
        &lt;/sequence&gt;
    &lt;/target&gt;
&lt;/iterate&gt;
</pre>

<p>In this scenario the Iterate mediator splits the messages in to parts and process them asynchronously.</p>


<p></p>
</body>
</html>
