Travailler avec des Objets de Données en Séquence

Des objets de données en Séquence sont des SDOs peuvent tracer l'ordre des propriétés à travers les propriétés des objets de données. Ils peuvent aussi contenir des éléments de texte non structuré (élément de texte qui n'appartient à aucune des propriétés SDO). Des objets de données en Séquence sont utiles pour travailler avec des documents XML qui permettent du texte non structuré (c'est-à-dire mixed=true) ou si les éléments peuvent être intercalée (

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

). Ceci peut se produire par exemple lorsque le schéma définit maxOccurs>1 sur un élément qui est un complexType avec un choix de l'ordre.

Les exemples ci-dessous assument qu'un SDO est créé avec le schéma et l'information de l'instance montrée ci-dessous, en utilisant le Service d'Accès de Données.

Le schéma ci-dessous décrit le format d'une lettre. La lettre peut optionnellement contenir trois propriétés; date, prenom et nomFamille. Le schéma indique mixed="true" qui signifie que le texte non structuré peut être entremêlé entre les trois propriétés.

<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>

L'exemple suivant est une instance du document lettre. Il contient les trois propriétés de la lettre; date, prenom et nomFamille, et a des éléments de texte non structuré pour l'adresse et le corps de la lettre.

<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>

Lorsque chargé, l'objet de données de lettre aura la séquence et les indices montrés dans la table ci-dessous :

Index de Séquence	Index:Nom	Valeur
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.

Pour s'assurer que la séquence des indices soit maintenue, les objets de données en séquence devraient être manipulés à travers de l'interface SDO_Sequence. Ceci permet à l'instance de l'objet de données à être manipulée en tant qu'index de séquence plutôt qu'avec un index de propriété (montré dans la table ci-dessus). Les exemples suivants assument que l'instance de la lettre a été chargée dans l'objet de données référencé par la variable $lettre.

Exemple #1 Récupération de l'interface SDO_Sequence

Nous obtenons la séquence de l'objet de données en utilisant la méthode getSequence(). La suite récupère la séquence pour l'objet de données de la lettre.


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

Tous les exemples suivants assument que la variable $lettre_seq a été assigné de la séquence pour l'objet de données de la lettre.

Exemple #2 Récupère/Fixe des valeurs de séquence

Nous pouvons récupérer et fixer des valeurs individuelles (en incluant le texte non structuré) en utilisant les index de séquence. L'exemple suivant fixe le prenom à "Snappy" et récupère la dernière valeur de séquence (le texte non structuré, "Votre prime est passée date.").


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

Exemple #3 Itération de Séquence

Nous pouvons itérer à travers des valeurs de séquence individuellement en utilisant foreach. L'exemple suivant passe au travers des valeurs individuelles dans l'ordre séquentiel.


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

Exemple #4 Séquence versus Objet de Données

Fixer des valeurs à travers l'interface d'objet de données peut amener à ce que les valeurs ne fassent pas partie de la séquence. Une valeur fixée avec un objet de données sera seulement accessible avec la séquence si la propriété était déjà une partie de la séquence. L'exemple suivant fixe le nomFamille à travers de l'objet de données et le récupère par la séquence. Ceci est correct puisque nomFamille existe déjà dans la séquence. S'il n'avait pas été fixé, alors nomFamille devrait être fixé à "Smith", mais ne devrait pas faire partie de la séquence.


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

Exemple #5 Ajout à une séquence

Nous pouvons ajouter de nouvelles valeurs à une séquence en utilisant la méthode SDO_Sequence::insert(). Les exemples suivants assument que les propriétés "prenom" et "nomFamille" sont non fixées.


<?php
  // Ajoute une valeur prenom à la séquence
  // valeur : 'Smith'
  // index séquence : NULL (ajout)
  // identifiant de propriété : 1 (index propriété prenom)
  $lettre_seq->insert('Smith', NULL, 1);

  // Ajoute une valeur nomFamille à la séquence
  // valeur : 'Jones'
  // index séquence : NULL (ajout)
  // identifiant de propriété : 'nomFamille' (nom propriété nomFamille)
  $lettre_seq->insert('Jones', NULL, 'nomFamille');

  // Ajoute du texte non structuré
  // valeur : 'Annule Inscription.'
  // index séquence : absent (ajout)
  // identifiant de propriété : absent (texte non structuré)
  $lettre_seq->insert('Annule Inscription.');

  // Ajoute du nouveau texte non structuré. Les séquence valeurs suivantes
  // d'ordre sont décalées vers le haut
  // valeur : 'À l'attention de :'
  // index séquence : 1 (insert comme second élément)
  // identifiant de propriété : absent (texte non structuré)
  $lettre_seq->insert('À l'attention de :', 1);
?>

Exemple #6 Suppression d'une séquence

Nous pouvons utiliser les fonctions isset() et unset() pour tester et supprimer des items de la séquence (Note : unset() laisse actuellement les valeurs dans l'objet de données, mais ce comportement est devrait changer et supprimer les données de l'objet de données). Une séquence se comporte comme une liste contiguë; donc, la suppression d'un item au milieu de la liste décalera les entrées d'un indice plus haut vers le bas. L'exemple suivant teste pour vérifier si la première séquence d'élément est fixé et la détruit si elle l'est.


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