For Each Activity
Introduction
The For Each Activity
The Continue and Break Activities
Deploying the Process
Running the Process

Using ActiveBPEL Designer's extension activities for BPEL4WS 1.1 (forEach, break, and continue)

Introduction

There are two samples included that are intended to demonstrate the use of the forEach, break, and continue activities. It is important to note that these activities are not part of the BPEL4WS 1.1 specification; they are ActiveBPEL extensions. The forEach activity will be part of the upcoming WSBPEL 2.0 specification and the syntax that is being used is the same syntax that has been approved by the WSBPEL technical committee at the time of this implementation. The break and continue activities have proposals for inclusion in the WSBPEL specification but these have not been approved. The implementation of these activities follow the proposals as closely as possible. Information on the syntax and symantics of these activities can be found both later in this document as well as in the documentation included with ActiveBPEL Designer.

Example 1

In this example, a forEach activity is used to traverse a sequence of order detail elements. The process consists of:

A receive/reply pair that accepts the order and returns a response.
An assign that initializes the following variables:
- numberOfDetails - the number of order detail elements in the received message using the XPath count function
- numberOfCountedDetails - intialized to zero
- totalOrderValue - intialized to zero
A forEach activity that traverses the order detail elements. Within the for each activity is a scope (this is required) that contains the following:
- A sequence activity
- An assign activity that:
  - Adds 1 to the counter of order detail elements traversed
  - Adds the total cost child element of order deatils to the total order value
An assign that creates the response message that concatinates both variable and text together creating a response message that should look like this :
- The order contains N detail elements and the proceess traversed M detail elements. The total calculated order value = $Y

The diagram below is a visual representation of the process. The process is instantiated when an order message is received and the response is sent after the execution of the forEach activity.

for each example

The easiest way to visulaize the effects of executing in paralell or in sequence is to view the execution via simaultion or remote debugging using ActiveBPEL Designer. The pictures below show the debug view when executing in paralell and in sequence

for each with break and continue example

Example 2

In this example, a forEach activity is used to traverse the same set of order detail elements but in this case we introduce the new break and continue activities. The process consists of:

A receive/reply pair that accepts the order and returns a response
An assign that initializes the following variables:

numberOfDetails - the number of order detail elements in the received message using the XPath count function
numberOfCountedDetails - intialized to zero
totalOrderValue - intialized to zero

A forEach activity that traverses the order detail elements. Within the for each activity is a scope (this is required) that contains the following:

A sequence activity that contains the following activities:

A wait activity that uses an expression to set the period of time to wait Note: This is done to simulate the effect of an invoke occuring in each of the iterations of the forEach activity
A switch that tests the following conditions:

If the value of the counter variable is equal to one performs the following steps:

Execute the continue activity which:

Forces the termination of any running activities in the iteration
Completes the Scope normally
Either continues with the next iteration(sequential execution) or allows all other iterations to continue (paralell execution)

If the value of the counter variable is equal to ten performs the following steps:

Execute the break activity which:

Forces the termination of any running activities in the iteration
Completes the Scope normally
Either completes the forEach activity without performing any outstanding iterations (sequential execution) or forces the termination of all running iterations (paralell execution)

An assign activity that:

Adds 1 to the counter of order detail elements traversed
Adds the total cost child element of order deatils to the total order value

An assign that creates the response message that concatinates both variable and text together creating a response message that should look like the following:

The order contains N detail elements and the proceess traversed M detail elements. The total calculated order value = $Y

The behavior of the break and continue activities described above causes the results from executing this process will differ significantly from the first example. When executing this process the number of detail elements remains the same as the in example oneThe order contains value will remain the same however, the values of the traversed andf calculated order value will less. The number of elements traversed will always be 8 (using the provided sample) and the total value will copntain the values of the 1st element pluse elements 3 through 9.

The diagram below is a visual representation of the process. The process is instantiated when an order message is received and the response is sent after the execution of the forEach activity.

The forEach Activity

The forEach activity must contain a scope activity and executes the scope and enclosed activities for the number of times calculated as the difference betwen the value of the startcounter attribute and the endcounter attribute + 1 (i.e., finish - start) + 1. These executions may occur in parallel or in sequence.

Note: A scope variable a variable of type xs:unsignedint is automatically created with the name specified in the counterName attribute of the forEach activity. The value of the variable at the start of an iteration is set to the iteration number.

The forEach activity can be used to "fan out" partner requests. Using a parallel for each with a break allows for an N-of-M pattern; an inner serializable scope can increment a "success" counter, and when it reaches N the break is executed.

XML Syntax and Semantics

<forEach counterName="ncname" parallel="yes|no" 
     standard-attributes>
     standard-elements
     <startCounterValue>
        ...
     </startCounterValue>
     <finalCounterValue>
        ...
     </finalCounterValue>
     Activity
</forEach>

The forEach element is in the namespace "http://www.activebpel.org/bpel/extension", so it will appear in your BPEL something like this:

<process...>
  <forEach counterName="counter" name="forEachLineItem" parallel="no">
         <startCounterValue>1</startCounterValue>
         <finalCounterValue>$numberOfDetails</finalCounterValue>
    <scope...>
      ...
    </scope>
  </forEach>
  ...  
</process>

The only child activity allowed within the forEach element is a scope. The scope has access to the counter variable declared by the forEach as described above.

If the start counter value is larger than the final counter value, then the activity is never executed.

The Continue and Break Activities

Continue

The continue activity starts a new iteration of the nearest enclosing while, until, or for each activity. When multiple while, until or for each activities are nested within each other, a continue activity applies only to the innermost activity.

<continue standard-attributes>
  standard-elements
</continue>

A continue activity is executed as follows:

Currently executing activities within the target of the continue activity are terminated. This includes the container of the continue activity and its parents up to the root activity of the target. If the root activity of the target is a scope then it completes normally upon termination of its child activities without running its termination handler. This exclusion prevents child scopes which completed normally in the iteration from being inadvertently compensated at the continue point. Note that in a for each with the parallel option set to true (parallel for each), the currently executing activities only apply to the current iteration's scope not the scopes of the other iterations.
Control is transferred to the target of the continue activity. The target then proceeds with its next iteration processing. Note that in a parallel forEach the iterations have already been created so this essentially notifies the forEach that this iteration has completed.

Because a continue statement unconditionally transfers control elsewhere, the completion point of the continue activity is never reachable. Therefore continue activities should not be used as a source for links or directly within a sequence activity with additional activities following it.

Break

The break activity exits the nearest enclosing while or forEach activity. When multiple while or forEach activities are nested within each other, a break activity applies only to the innermost activity.

<break; standard-attributes>
  standard-elements
</break;>

A break activity is executed as follows:

Currently executing activities within the target of the break activity are terminated. This includes the container of the break activity and its parents up to the root activity of the target. If the root activity of the target is a scope then it completes normally upon termination of its child activity without running its termination handler. This exclusion prevents child scopes which completed normally in the iteration from being inadvertently compensated at the break point. Note that in a parallel for each the currently executing activities apply to all currently executing iterations which process the termination in the same manner.
Control is transferred to the target of the break activity. The target does not execute any further iterations and completes normally.

Because a break statement unconditionally transfers control elsewhere, the completion point of the break activity is never reachable. Therefore break activities should not be used as a source for links or directly within a sequence activity with additional activities following it.

Deploying the Process

See Deploying the Samples.

Running the Process

See Running the Samples. The service name to use is foreachProcessService. The sample data file orderMessage.xml can be used as input for this example.