sdo-php-sample-php-sequence-5

  • Examples
  • Working with Sequenced Data Objects

  • Working with Sequenced Data Objects
  • Working with Sequenced Data Objects

    Working with Sequenced Data Objects

    Sequenced data objects are SDOs which can track
    property ordering across the properties of a data object. They can
    also contain unstructured text elements (text element which do not
    belong to any of the SDO’s properties). Sequenced data objects are
    useful for working with XML documents which allow unstructured text
    (i.e. mixed=true) or if the elements can be interleaved (

    <A/><B/><A/>
    

    ). This can occur for example when the schema defines
    maxOccurs>1 on a element which is a complexType with a choice
    order indicator.

    The examples below assume an SDO created with the
    following schema and instance information, using the XML Data
    Access Service.

    The schema below describes the format of a letter.
    The letter can optionally contain three properties; date,
    firstName, and lastName. The schema states mixed=”true” which means that unstructured text
    can be interspersed between the three properties.

    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:letter="http://letterSchema"
      targetNamespace="http://letterSchema">
      <xsd:element name="letters" type="letter:FormLetter"/>
      <xsd:complexType name="FormLetter" mixed="true">
        <xsd:sequence>
          <xsd:element name="date" minOccurs="0" type="xsd:string"/>
          <xsd:element name="firstName" minOccurs="0" type="xsd:string"/>
          <xsd:element name="lastName" minOccurs="0" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:schema>
    

    The following is an instance letter document. It
    contains the three letter properties; date, firstName and lastName,
    and has unstructured text elements for the address and letter
    body.

    <letter:letters xmlns:letter="http://letterSchema">
      <date>March 1, 2005</date>
      Mutual of Omaha
      Wild Kingdom, USA
      Dear
      <firstName>Casy</firstName>
      <lastName>Crocodile</lastName>
      Please buy more shark repellent.
      Your premium is past due.
    </letter:letters>
    

    When loaded, the letter data object will have the
    sequence and property indices shown in the table below:

    Sequence Index Property Index:Name Value
    0 0:date March 1, 2005
    1 Mutual of Omaha
    2 Wild Kingdom, USA
    3 Dear
    4 1:firstName Casy
    5 2:lastName Crocodile
    6 Please buy more shark repellent.
    7 Your premium is past due.

    To ensure sequence indices are maintained,
    sequenced data objects should be manipulated through the
    SDO_Sequence interface. This allows the data object’s instance data
    to be manipulated in terms of the sequence index as opposed to the
    property index (shown in the table above). The following examples
    assume the letter instance has been loaded into a data object
    referenced by the variable $letter.

    Example #1 Getting the SDO_Sequence
    interface

    We obtain a data object’s sequence using the getSequence() method. The follow
    gets the sequence for the letter data object.

    <?php
      $letter_seq 
    $letter->getSequence();
    ?>

    All subsequent examples assume that the
    $letter_seq variable has been
    assigned the sequence for the letter data object.

    Example #2 Get/set sequence values

    We can get and set individual values (including unstructured
    text) using the sequence index. The following sets the firstName to
    ‘Snappy’ and gets the last sequence values (the unstructured text,
    ‘Your premium is past due.’).

    <?php
      $letter_seq
    [4] = 'Snappy';
      
    $text $letter_seq[count($letter_seq) - 1];
    ?>

    Example #3 Sequence iteration

    We can iterate through the individual sequence values using
    foreach.
    The following runs through the individual values in sequence
    order.

    <?php
    foreach ($letter->getSequence() as $value) {
        
    // ...
    }
    ?>

    Example #4 Sequence versus Data Object

    Setting values through the data object interface may result in
    the value not being part of the sequence. A value set through the
    data object will only be accessible through the sequence if the
    property was already part of the sequence. The following example
    sets the lastName through the data object and gets it through the
    sequence. This is fine because lastName already exists in the
    sequence. If it had not previously been set, then lastName would be
    set to ‘Smith’, but would not be part of the sequence.

    <?php
      $letter
    [2] = 'Smith';
      
    $last_name $letter_seq[5];
    ?>

    Example #5 Adding to a sequence

    We can add new values to a sequence using the SDO_Sequence::insert() method. The following
    examples assume that the ‘firstName’ and ‘lastName’ properties are
    initially unset.

    <?php
      
    // Append a firstName value to the sequence
      // value: 'Smith'
      // sequence index: NULL (append)
      // propertyIdentifier: 1 (firtName property index)
      
    $letter_seq->insert('Smith'NULL1);

      // Append a lastName value to the sequence
      // value: 'Jones'
      // sequence index: NULL (append)
      // propertyIdentifier: 'lastName' (lastName property name)
      
    $letter_seq->insert('Jones'NULL'lastName');

      // Append unstructured text
      // value: 'Cancel Subscription.'
      // sequence index: absent (append)
      // propertyIdentifier: absent (unstructured text)
      
    $letter_seq->insert('Cancel Subscription.');

      // Insert new unstructured text.  Subsequent sequence values
      // are shifted up.                                       
      // value: 'Care of:'
      // sequence index: 1 (insert as second element)
      // propertyIdentifier: absent (unstructured text)
      
    $letter_seq->insert('Care of:'1);
    ?>

    Example #6 Removing from a sequence

    We can use the isset() and
    unset() functions to test and remove items
    from the sequence (Note: unset() currently
    leaves the values in the data object, but this behaviour is likely
    to change to also remove the data from the data object). A sequence
    behaves like a contiguous list; therefore, removing items from the
    middle will shift entries at higher indices down. The following
    example tests to see if the first sequence element is set and
    unsets it if is.

    <?php
      
    if (isset($letter_seq[0])) {
        unset(
    $letter_seq[0]);
      }
    ?>