Iterators

An iterator is a specialized form of subdiagram that implements loops or iterations. Use an iterator to perform an operation:

An iterator can also be used as a loop. Any values required for initializing, testing, and incrementing the loop must be supplied in the Iterator Properties dialog box.

An iterator diagram can call subdiagrams or other iterators. A hierarchy of iterators is necessary to process hierarchical business objects or hierarchical business object arrays.

When execution of the parent diagram reaches the Iterator symbol, control passes to the iterator activity diagram. The collaboration repeats execution of the iterator diagram for each attribute in the business object or each business object in the business object array. You have access to the item currently in the iterator through the iterator variable specified in the Iterator Properties dialog.

After the iterator has finished executing, control passes back to the parent diagram.

Creating an iterator

To add an iterator to the activity diagram:

  1. In the Symbols toolbar, click the Iterator button.
  2. Click in the workspace to place the Iterator symbol.

    A unique identifier appears for the iterator in the scenario tree, hierarchically arranged under the parent diagram. The scenario tree displays the name in the following format:

    (UID)
     

    If you provide a label for the iterator, the scenario tree displays the name in the following format:

    label (UID)
     

    The UID is a unique identifier that is also the name of the iterator object in the scenario tree. As with UIDs for other symbols, you can choose whether or not to display the UID for the iterator. To turn on or off display of the UID, use the context menu on the scenarios node in the template tree.

Creating iterator variables

An iterator working on attributes of a business object or an array of business objects needs to have a variable to hold the item being processed in each iteration. This iterator variable is actually a scenario variable that is created and initialized in the Scenario Definitions dialog box. Create iterator variables before defining the properties of an iterator.

If the iterator is working on the attributes of a business object, you can use an Object to hold the current attribute. For example, you might have the following declaration:

Object iterAttr = null;
 

If the iterator is working on business objects in an array, you can use a variable of type BusObj to hold the current business object. For example:

BusObj iterBusObj = new BusObj("LineItem");
 

If the iterator is being used as a loop, you do not need to create an iterator variable. The system creates one automatically during processing. The loop index variable can then be retrieved with the getCurrentLoopIndex() API.

Defining an iterator

After the iterator appears in the activity diagram, you can define its properties in the

Iterator Properties dialog box (see Figure 40).

Figure 40. Iterator Properties dialog box


Open the Iterator Properties dialog box by right-clicking the iterator and selecting Properties from its context menu. You can define the iterator's label and provide a description; both of these properties are optional. However, you must define certain other properties depending on the type of iterator you want to use. The following sections describe the requirements for defining each type of iterator.

Using an iterator on attributes of a business object

If you want to iterate attributes of a business object, do the following:

  1. Use the Iterator Variable field to specify the variable that is going to hold the item being processed during an iteration. The drop-down list in this field contains all template and scenario variables. You can select the variable from the list, or type the variable name directly in the field.
  2. Click the Iterate attributes in a business object radio button.
  3. Use the Iterate through this business object field to specify the business object whose attributes you want to iterate through. Either type the name directly in the field or use the drop-down list to select the business object.
  4. Click Apply.

After you have defined an iterator's properties, you must edit its activity diagram to define what the iterator does for each attribute it processes. Open an iterator's activity diagram by double-clicking the iterator name in the template tree view of Process Designer Express.

Using an iterator on business objects in an array

If you want to iterate business objects in an array, do the following:

  1. Use the Iterator Variable field to specify the variable that is going to hold the item being processed during an iteration. The drop-down list in this field contains all template and scenario variables. You can select the variable from the list, or type the variable name directly in the field.
  2. Click the Iterate business objects in an array radio button.
  3. Use the Iterate through this array field to specify the array you want to iterate through. Either type the name directly in the field or use the drop-down list to select the array.

    Use the following syntax if you type the value directly in the field:

    BusinessObjectVariable.AttributeName
     

    where BusinessObjectVariable is the name of the parent business object and AttributeName is the name of the attribute that represents the array of child business objects.

    For example, to iterate through business objects in an array represented by the Items attributes in a business object contained in the variable order, type order.Items in the Iterate through this array field.

  4. Click Apply.

After you have defined an iterator's properties, you must edit its activity diagram to define what the iterator does for each business object it processes. Open an iterator's activity diagram by double-clicking the iterator name in the template tree view of Process Designer Express.

Using an iterator as a loop

To define a loop, do the following:

  1. Click the Loop radio button.
  2. Use the Start Value field to specify the initial value of the counter variable. You can use the drop-down list to select a variable that holds the value, or you can type the value directly in the field.
  3. In the Condition field, specify the condition that must be true in order for the loop to execute. The drop-down list contains all boolean variables defined in the template. Select the variable you want to use, then type the condition directly into the field.
  4. Use the Increment field to specify the method of incrementing the value of the counter variable.
  5. Click Apply.

After you have defined an iterator's properties, you must edit its activity diagram to define what the iterator does for each attribute or business object it processes. Open an iterator's activity diagram by double-clicking the iterator name in the template tree view of Process Designer Express.

Adding a break

A break can be added to an iterator's activity diagram to force premature termination of the iteration. When the iterator's execution path reaches the break symbol, the iterator terminates and control is passed back to the parent diagram. Breaks can be used with all types of iterators.

Place a break symbol in an iterator's activity diagram as follows:

  1. Click the Break button in the Symbols toolbar.
  2. In the activity diagram, position your cursor where you want to place the break, and then click. The break symbol is added to the diagram.

    Figure 41. Break symbol


Optionally, you can add a label and description to a break symbol. Double-click the break symbol in an activity diagram to open its Break Properties dialog box and edit the properties as desired.

Copyright IBM Corp. 2003, 2004