IBM BPM, V8.0.1, All platforms > Programming IBM BPM > Business objects programming > Programming techniques

Arrays in business objects

You can define arrays for an element in a business object so that the element can contain more than one instance of data.

You can use a List type to create an array for a single named element in a business object. This will allow you to use that element to contain multiple instances of data.

For example, you can use an array to store several telephone numbers within an element named telephone that is defined as a string in its business object wrapper. You can also define the size of the array by specifying the number of data instances using the maxOccurs value. The following example code shows how you would create such an array that will hold three instances of data for that element:

<xsd:element name="telephone" type="xsd:string" maxOccurs="3"/>

This will create a list index for the element telephone that can hold up to three data instances. You may also use the value minOccurs if you are only planning to have one item in the array.

The resulting array consists of two items:

• the contents of the array
• the array itself.

In order to create this array, however, you need perform an intermediate step by defining a wrapper. This wrapper, in effect, replaces the property of the element with an array object. In the previous example, you can create an ArrayOfTelephone object to define the element telephone as an array. The following code example shows how you accomplish this task:

<?xml version="1.0" encoding="UTF-8"?>
 	<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 	 	  <xsd:element name="Customer">
 	    <xsd:complexType>
 	      <xsd:sequence>
 	        <xsd:element name="name" type="xsd:string"/>
 	        <xsd:element name="ArrayOfTelephone" type="ArrayOfTelephone"/>
 	      </xsd:sequence>
 	    </xsd:complexType>
 	  </xsd:element>

 	  <xsd:complexType name="ArrayOfTelephone">
 	    <xsd:sequence maxOccurs="3">
 	      <xsd:element name="telephone" type="xsd:string" nillable="true"/>
 	    </xsd:sequence>
 	  </xsd:complexType> 
	</xsd:schema>

The telephone element now appears as a child of the ArrayOfTelephone wrapper object.

If that in the previous example, the telephone element contains a property named nillable. You can set this property to true if you want to certain items in the array index to contain no data. The following example code shows how the data in an array may be represented:

<Customer>
	  <name>Bob</name>
	  <ArrayOfTelephone>
	    <telephone>111-1111</telephone>
	    <telephone xsi:nil="true"/>
	    <telephone>333-3333</telephone>
	  </ArrayOfTelephone>
	</Customer>

In this case, the first and third items in the array index for the telephone element contain data, while the second item does not contain any data. If you had not used the nillable property for the telephone element, then you would have had to have the first two elements contain data.

You can use the Service Data Object (SDO) Sequence APIs in IBM BPM as an alternative method to handle sequences in business object arrays. The following example code creates an array for the telephone element with data identical to that shown in the previous example:

DataObject customer = ...
	customer.setString("name", "Bob");
	 
	DataObject tele_array = customer.createDataObject("ArrayOfTelephone");
	Sequence seq = tele_array.getSequence();  // The array is sequenced
	seq.add("telephone", "111-1111");
	seq.add("telephone", null);
	seq.add("telephone", "333-3333");

You can return the data for a given element array index by using code similar to the example below:

String tele3 = tele_array.get("telephone[3]");  // tele3 = "333-3333"

In this example, a string named tele3 will return the data "333-3333".

You can enter the data items for the array in the list index by using fixed width or delimited data placed in a JMS or MQ message queue. You can also accomplish this task by using a flat text file that contains the properly formatted data

Programming techniques