List Element Types

List Element Types

In the SICS API Server XSD’s three different types of lists are used:

  • ReplaceAllList
  • CreateList/AddList
  • UpdateList

In the following we will use the example where: ‘Master’ is a domain object. It has 1:M relationship with ‘DetailA’ and ‘DetailB’ objects.

ReplaceAllList #

  • This type of ‘List’ is used to perform ‘replaceAll’ operation.
  • The ‘replaceAll’ operation will replace all the existing elements in the collection and add new ones present in the list.
  • Generally, ‘replaceAllList’ is used where the objects in the collection, cannot be modified.

Example #

‘DetailBList’ contains ‘detailB’ objects. On ‘replaceAll’ operation, new elements in the list will replace all the existing elements of ‘detailB’ in ‘Master’.

XSD Structure # 

<xsd:complexType name="detailBList">
   <xsd:complexContent>
      <xsd:extension base="ct:ReplaceAllList">
         <xsd:sequence>
            <xsd:element name="detailB" 
                    minOccurs="0" 
                    maxOccurs="unbounded"
                    type="ref:DetailB"/>
         </xsd:sequence>
      </xsd:extension>
   </xsd:complexContent>
</xsd:complexType>

Structure of Sample SOAP #

Assume the detailBList contains one element with attrB1 = “Alan” and attrB2 = “Singer” and the following SOAP is sent:

<detailBList>
   <detailB>
      <attrB1>John</attrB1>
      <attrB2>Smith</attrB2>
   </detailB>
   <detailB>
      <attrB1>Peter</attrB1>
      <attrB2>Gabriel</attrB2>
   </detailB>
</detailBList>

The list will now contain two elements: “John Smith” and “Peter Gabriel”.

Add/CreateList #

  • ‘List’ is used to perform Add/Create operation. New elements in the list will be created (if relevant and/or necessary) and added to the existing collection of objects in domain object.
  • Previous elements of collection will be retained.

Example #

‘DetailAList’ contains ‘detailA’ objects. On ‘Add/Create’ operation, new elements in the list will be added to the existing elements of ‘detailB’ in ‘Master’.

XSD Structure # 

<xsd:complexType name="detailAList">
    <xsd:sequence>
       <xsd:element name="detailA" 
           minOccurs="0" maxOccurs="unbounded" 
           type="ref:DetailA"/>
    </xsd:sequence>
</xsd:complexType>

Structure of Sample SOAP #

Assume the detailAList contains one element “Alan Singer” (i.e. with attrA1 = “Alan” and attrA2 = “Singer”) and the following SOAP is sent:

<detailAList>
    <detailA>
       <attrA1>George</attrA1>
       <attrA2>Harrison</attrA2>
    </detailA>
    <detailA>
       <attrA1>Rebecca</attrA1>
       <attrA2>West</attrA2>
    </detailA>
</detailAList>

The list will now contain three elements: “Alan Singer”, “George Harrison” and “Rebecca West”.

UpdateList #

  • ‘UpdateList’ is used to perform ‘update/delete/deleteAll’ operation on object’s collection.
  • It is assumed that the object, on which operation will be performed, exists in the collection.
  • The “updateList” has an extra level of elements compared to the “List”, that is “Key”. Purpose of this “Key” element is to identify element into collection against to that ‘update\delete\deleteAll’ operation will perform.
  • Uniqueness of key may not be enforced in SICS but key may be valid.

XSD Structure # 

<xsd:complexType name="DetailAListUpdate">
    <xsd:complexContent>
       <xsd:extension base="ct:ListUpdate">
         <xsd:sequence>
            <xsd:element name="detailAUpdate" 
                minOccurs="0" 
                maxOccurs="unbounded" 
                type="ref:DetailAUpdateElement"/>
         </xsd:sequence>
       </xsd:extension>
    </xsd:complexContent>
</xsd:complexType>
<xsd:complexType name=" DetailAUpdateElement ">
    <xsd:complexContent>
       <xsd:extension base="ct:ListUpdateElement">
           <xsd:sequence>
               <xsd:element name="detailAKey" 
                  type="ref:DetailAKey"/>
               <xsd:element name="attr1" 
                  minOccurs="0" 
                  type="ref:Attr1 "/>
               <xsd:element name="attr2" 
                  minOccurs="0" 
                  type="ref:Attr2 "/>
           </xsd:sequence>
      </xsd:extension>
    </xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="DetailAKey">
   <xsd:sequence>
     <xsd:element name="aKey" 
       minOccurs="0" 
       type="ref:DetailAReference"/>
   </xsd:sequence>
</xsd:complexType>

Note:
XSD structure is same for update, delete or deleteAll operations.

Structure of Sample SOAP #

‘Update’ Operation #

Assume the detailAList contains two elements:

  1. “President: Barak Obama”
    (i.e. with key=“President”, attrA1 = “Barak” and attrA2 = “Obama”)
  2. “Vice President: Joe Biden”
    (i.e. with key=“Vice President”, attrA1 = “Joe” and attrA2 = “Biden”)

and the following SOAP is sent:

<detailAListUpdate>
   <detailAUpdate>
      <detailAKey>
         <aKey>President</aKey>
      </detailAKey>
      <detailA>
         <attrA1>Donald</attr1>
         <attrA2>Trump</attr2>
      </detailA>
   </detailAUpdate>
   <detailAUpdate>
      <detailAKey>
         <aKey>Vice President</aKey>
      </detailAKey>
      <detailA>
         <attrA1>Hillary</attr1>
         <attrA2>Clintonn</attr2>
      </detailA>
   </detailAUpdate>
</detailAListUpdate>

The list will now contain the two elements: “President Donald Trump” and “Vice President Hillary Clinton”.

‘Delete’ operation #

  • There is one boolean field <isToBeDeleted > on element level, tells whether ‘delete’ operation will perform or not.
  • If tag <isToBeDeleted> is set to be true then that element will be deleted from the collection and if it if false or not given then that element is used for update operation. By default it if false.

Assume the detailAList contains “Oranges” (detailAKey=“Oranges”), “Apples” and “Pears” and the following SOAP is sent:

<detailAListUpdate>
   <detailAUpdate>
     <isToBeDeleted>true</isToBeDeleted>
     <detailAKey>
       <aKey>Oranges</aKey>
     </detailAKey>
   </detailAUpdate>

   <detailAUpdate>
     <isToBeDeleted>true</isToBeDeleted>
     <detailAKey>
       <aKey>Pears</aKey>
     </detailAKey>
   </detailAUpdate>
</detailAListUpdate>

The detailAList now only contains “Apples” (detailAKey=“Apples”).

‘DeleteAll’ operation #

  • SOAP contains a boolean field <deleteAll> on List level, which tells whether ‘deleteAll’ operation will perform or not.
  • If <deleteAll> is set to “true” then all elements will be deleted. By default it if false.
<detailAListUpdate>
    <deleteAll>true</deleteAll>
</detailAListUpdate>