Writing Iterators

Iterators are services (agents) that loop. Each iteration results in an XDDocument that is emitted to the next node in a process flow, with the exception of the final loop step, which passes control to the end of data node. An example of an iterator might be one that sends the incoming document into the loop a specified number of times (a count iterator). Other iterators split incoming payloads on line breaks or by using XPATH into the XML payload.

An iterator must declare itself to the Process Flow Interpreter, which is accomplished by including the isIterator() method in the service code (as shown in the sample iterator syntax at the end of this topic).

An iterator takes action depending on the edge on which it receives control. The following image shows a sample iterator in a process flow, which is used for demonstration purposes.

The iterator accepts documents on one of the following edges:

The iterator can test the incoming edge by using the following call:

public String getEdgeName()

This returns the name of the edge on which the agent received control. If the edge name is not $jump, then it is the initial entry to the iterator and the first output document must be created. If the edge name is $jump, then this is a subsequent entry and a subsequent document is to be created. In either case, the result should be returned in the output document as it would be for any normal agent.

The iterator should return a success result or a failure edge name depending upon the result of the iteration. Ideally, on original (non-$jump edge) it should attempt to determine whether the iteration can be completed, so as to avoid returning failures while it is looping. On the last entry, if there are no further data to be emitted, the iterator then returns a status or other document as configured, and returns the $eos edge. This causes the Process Flow Interpreter to pass control to the node following the origin of the $jump edges. In the example shown, this is the node named End of Data Handler.

When the process flow ends, it is returned to the system. At this time, the following method is called:

public void reset()

Your iterator should ensure that all resources used in the iteration are reset. For example, if your iterator is using a database, it releases the resources in this call if they have not been released earlier. Be aware that an error in the loop, such as the Service node in this example, may prevent your iterator from reaching the final $jump to return $eos.

Be aware that no XML tree or resource should be referenced by the iterator and the output document. Your iterator may need to copy information to prevent crossed-references. For example, an XML tree is changed in the loop but the original iterator retains a reference to it.

The following syntax is an example of a simple count iterator:

private int counter=0;  // we keep counter here
private XDDocument originalDoc;
  public String execute(XDDocument docIn, XDDocument docOut) 
        throws  XDException
    {
        String edgeName = getEdgeName();
        if (!edgeName.equals("$jump")) // if not on "loop" edge, this is
start of iteration
        {
            docIn.moveTo(originalDoc);   // save for iterations
            counter = 0;
        }
        if (counter > countWanted)  // have we reached the count of
iterations? If so, return a status document
        {
             XDNode statusNode=new XDNode("status");
             statusNode.setAttribute("count",""+counter);
             docOut.setRoot(statusNode);
             originalDoc=null;   // help the GC
             counter=0;
             return "$eos";   // tell engine that end of set has been reached
        }
        else  
        {
            counter++;
            originalDoc.copyTo(docOut);   // iterating document
            return "success";
        }
    }
Public boolean isIterator()
{
      return true;
}

Assume that the limit has been set into the countWanted field. This will loop and return a copy for the number of times that are required. Note that copies are returned, not simply references to the original. A more realistic iterator might process the incoming document on the entry for iteration, perhaps simply reloading the payload (the XML or other content), which allows other changes to the document to be made in the iteration loop. In addition, this example returns a trivial status document to the $eos point.


iWay Software