Creating multiple instances of nested business objects

Use the setWithCreate function to create a multiple instances of nested business object.

Before you begin

The following example XSD file contains nested objects one (child) and two (grandchild) levels below the top (parent) business object:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <xsd:complexType name="Parent">
    <xsd:sequence>
      <xsd:element name="name" type="xsd:string"/>
      <xsd:element name="child" type="Child" maxOccurs="5"/>
    </xsd:sequence>
  </xsd:complexType>

  <xsd:complexType name="Child">
    <xsd:sequence>
      <xsd:element name="name" type="xsd:string"/>
      <xsd:element name="grandChild" type="GrandChild"/>
    </xsd:sequence>
  </xsd:complexType>

  <xsd:complexType name="GrandChild">
    <xsd:sequence>
      <xsd:element name="name" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
  
</xsd:schema>

Note that the parent object can have up to five child objects, as specified in the maxOccurs value.

About this task

You can create a list with a more stringent policy that will not allow for missing sequences in an array. You can use the setWithGet method, and at the same time specify the data that will appear in a particular list index item:

DataObject parent = ...
parent.setString("child[3]/grandchild/name", "Bob");

In this case, the resulting array would be of size three, but the values for child[1] and child[2] list index items are undefined. You may want the items to either be a null value or have an associated data value. In the scenario above, an exception will be thrown because the values for the first two array index items are undefined.

You can remedy this situation by defining the values in the index of the list. If the index item refers to an existing element in the array and if that element is not null (that is, it contains data), it will be used. If it is null, it will be created and used. If the index of the list is one greater than the size of the list, a new value will be created and added. The following example code shows what will happen in a list that of size two, where child[1] is designated null and child[2] contains data:

DataObject parent = ...
// child[1] = null
// child[2] = existing Child
// This code will work because child[1] is null and will be created.
parent.setString("child[1]/grandchild/name", "Bob");

// This code will work because child[2] exists and will be used.
parent.setString("child[2]/grandchild/name", "Dan");

// This code will work because the child list is of size 2, and adding
// one more list item will increase the list size.
parent.setString("child[3]/grandchild/name", "Sam");

Results

You have overridden the values for the two existing items and added a third item to the list index. If, however, you then add another item that is not of size four, or which is greater than the size specified in maxOccurs, then an exception will be thrown. The more stringent policy of this method is demonstrated in the following example code.

Note: The following code is assumed to be appended to the existing code shown in the "About this task" section:

// This code will throw an exception because the list is of size 3
// and you have not created an item to increase the size to 4.
parent.setString("child[5]/grandchild/name", "Billy");