Using Arrays in BPEL Processes
Introduction
Defining an Array Type
Accessing Array Elements
Deploying the Process
Running the Process
Things to Note

Using Arrays in BPEL Processes

Introduction

You can use arrays within a BPEL process, as well as send and receive messages containing arrays to and from BPEL Web Services. Using arrays isn't an intuitive process, The key is to define an array type in WSDL and then apply your knowledge of XPath query structure (or other query language) to help you get arrays into and out of a BPEL process's Web Service invocation.

The sample process is illustrated below.

The initial pick accepts any of the three types of conversion request messages this process supports: integer, int, or string arrays. The incoming message is the same, but it comes in via one of three different operation names on the same port. The message contains a string that will be turned into an array. Each character in the string is turned into a single element in the array. (For integer and int arrays, this implies that the input string must consist of only digits.)
The following assign activity sets the index counter to 1 (arrays are 1, not 0-based), initializes the array data structure (complex parts must be initialized before use), and transfers the incoming string for parsing.
The switch looks at the incoming request, sets the arrayMode variable, and initializes the response message. To differentiate between integer and int inputs, the switch looks for a '0' as the first character of the input string. If that is the case, it uses integer; if not, it uses int. (This differentiation could also have been made in the initial pick by setting arrayMode there instead.)
The while loop iterates over each character in the input, copying each into the output array as the proper type (based on arrayMode).
The final switch returns the correct reply, based on the type of the arrayMode variable.

Defining an Array Type in WSDL

Arrays of XML Schema simple types can be included as parts in a WSDL message. Array definitions are placed into the types section of the WSDL definition.

The Schema

One of the simplest ways to define an array of some XML Schema simple type, like xsd:string, is:

WSDL Message Definition

Messages containing parts that are (or include) arrays are defined in the same way as parts comprising simple types. An example of a WSDL message with a single part defined as the type above would look like the following:

This message can then be used in a WSDL operation, as shown in the following example:

Accessing Array Elements in BPEL

Array elements in an array are accessed using a query expression. Note that access to individual array elements in BPEL requires an index that is 1-based, not 0-based. That is, the first element in an array has an index of 1, not zero.

Querying Array Elements

In general, the query expression used to access an array element is constructed as follows:

/partName/arrayElementName[index]

So for the array defined above, the expression needed to access an element in the stringArray part in message stringArrayResponse would be written:

/stringArray/item[index]

where stringArray is the name of the part defined in the WSDL message, item is the name used to identify elements in the array and index is the 1-based numeric index into the array. The name "item" is a convention, not a syntactical rule. You can call it anything.

To copy an array element from this array into a variable of type xsd:string, you use the following assign / copy operation:

<assign>
<copy>
   <from variable="StringArrayResponse" part="stringArray">
      <query>item[ $indexCounter ]</query>
   </from>
   <to variable="myString"/>
</copy>

Assigning Array Elements

Query expressions are used in a similar manner to identify the array element that is the target of a value assignment. Given the type and message defined above, the assign / copy operation used to assign a value to an array element would be:

<assign>
<copy>
   <from variable="myString"/>
   <to variable="StringArrayResponse" part="stringArray">
      <query>item[ $indexCounter ]</query>
   </to>
</copy>

Deploying the Process

See Deploying the Samples. The BPEL and PDD files are named "makeArrayFromString" instead of "arrays".

Running the Process

See Running the Samples. The service name to use is ArrayCreationPLTService. There are three sample data files that can be used as input for this example: arrays_int.xml, arrays_integer.xml, and arrays_string.xml.

Things to Note

Remember that accessing array elements within BPEL (e.g., via XPath query expressions) requires a 1-based index, as opposed to the 0-based index used in most programming languages.

Normally, XML Schema simple types like xsd:int and xsd:boolean correspond to native Java types such as int and boolean. However, if the sequence element definition in the WSDL for a given value has an attribute of nillable='true',

this means that the value can take on the null value. Since a null value is not valid for a native type like int, you should use a Java class to represent it, such as Integer.

Arrays used in BPEL must be initialized in a manner similar to most other languages, such that the storage needs to be allocated when the variable containing the array part is initialized. Because this initiailization can be problematic for large arrays, it may be useful to send an "empty" array of the appropriate size as one of the request message parts. Some BPEL engine implementations also provide custom functions to append array elements onto existing arrays.