Trabajar con Objetos de Datos Secuenciados

Los objetos de datos sencuenciados son SDOs que pueden rastrear el orden de propiedades de un objeto de datos. También pueden contener elementos de texto no estructurados (un elemento de texto que no pertenece a ninguna de las propiedades del SDO). Los objetos de datos secuenciados son útiles para trabajar con documentos XML que permiten texto no estructurado (es decir, mixed=true) o si los elementos pueden ser intercalados (

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

). Esto puede ocurrir, por ejemplo, cuando el esquema define maxOccurs>1 en un elemento que es un tipo complejo (complexType) con un indicador de orden de elección.

En los ejemplos de abajo se asume que existe un SDO creado con el siguiente esquema y la siguiente información de instancia, usando el Servicio de Acceso a Datos de XML.

El esquema de abajo describe el formato de una carta. La carta puede contener opcionalmente tres propiedades: fecha, nombre, y apellido. El estado del esquema es mixed="true", lo que significa que se puede interpretar texto no estructurado entre las tres propiedades.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:carta="http://esquemaCarta"
  targetNamespace="http://esquemaCarta">
  <xsd:element name="cartas" type="carta:ModeloCarta"/>
  <xsd:complexType name="ModeloCarta" mixed="true">
    <xsd:sequence>
      <xsd:element name="fecha" minOccurs="0" type="xsd:string"/>
      <xsd:element name="nombre" minOccurs="0" type="xsd:string"/>
      <xsd:element name="apellido" minOccurs="0" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

Lo siguiente es una instancia de un documento carta. Contiene las tres propiedades de la carta; fecha, nombre y apellido, y tiene elementos de texto no esctrucrado para la dirección y el cuerpo de la carta.

<carta:cartas xmlns:carta="http://esquemaCarta">
  <fecha>March 1, 2005</fecha>
  Mutual of Omaha
  Wild Kingdom, USA
  Querida
  <nombre>Casy</nombre>
  <apellido>Crocodile</apellido>
  Por favor, compre más repelente de tiburones.
  Su prima ha vencido.
</carta:cartas>

Cuando se carga, el objeto de datos carta tendrá la secuencia y los índices de propiedades mostrados en la tabla de abajo:

Índice de Secuencia	Índice de Propiedad:Nombre	Valor
0	0:fecha	March 1, 2005
1	-	Mutual of Omaha
2	-	Wild Kingdom, USA
3	-	Dear
4	1:nombre	Casy
5	2:apellido	Crocodile
6	-	Por favor, compre más repelente de tiburones.
7	-	Su prima ha vencido.

Para asegurarse de que los índices de secuencia se mantienen, los objetos de datos secuenciados deberían ser manipulados mediante la interfaz SDO_Sequence. Esto permite que los datos de instancia de los objetos de datos sean manipulados en términos del índice de secuencia en lugar de índice de propiedad (mostrado en la tabla de arriba). En los siguientes ejemplos se asume que la instancia de carta ha sido cargada en un objeto de datos referenciado por la variable $carta.

Ejemplo #1 Obtener la interfaz SDO_Sequence

Se obtiene la secuencia de objetos de datos usando el método getSequence(). Lo siguiente obtiene la secuencia para el objeto de datos carta.


<?php
  $secuencia_carta = $carta->getSequence();
?>

En todos los ejemplos subsiguientes se asume que la variable $secuencia_carta ha sido asignada a la secuencia del objeto de datos carta.

Ejemplo #2 Obtener/establecer valores de secuencia

Se pueden obtener y establecer valores individuales (incluyendo texto no estructurado) usando el índice de secuencia. Lo siguiente establece el nombre a 'Snappy' y obtiene los últimos valores de la secuencia (el texto no estructurado, 'Su prima ha vencido.').


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

Ejemplo #3 Iteración de secuencias

Se puede iterar a través de valores de secuencia individuales usando foreach. Lo siguiente recorre los valores individuales en el orden de secuencia.


<?php
foreach ($carta->getSequence() as $valor) {
    // ...
}
?>

Ejemplo #4 Secuencias contra Objetos de Datos

Al establecer valores a través de la interfaz del objeto de datos puede resultar en que el valor no sea parte de la secuencia. Un valor establecido a través del objeto de datos sólo será accesible a través de la secuencia si la propiedad ya era parte de la secuencia. El siguiente ejemplo establece el apellido a través del objeto de datos y lo obtiene a través de la secuencia. Esto es correcto ya que apellido ya existe en la secuencia. Si no se hubiera establecido anteriormente, apellido sería establecido a 'Smith', pero no sería parte de la secuencia.


<?php
  $carta[2] = 'Smith';
  $apellido = $secuencia_carta[5];
?>

Ejemplo #5 Añadir elementos a una secuencia

Se pueden añadir nuevos valores a una secuencia usando el método SDO_Sequence::insert(). En los siguientes ejemplos se asume que las propiedades 'nombre' y 'apellido' no estaban establecidas inicialmente.


<?php
  // Añadir un valor de nombre a la secuencia
  // valor: 'Smith'
  // índice de secuencia: NULL (añadido)
  // identificador de propiedad: 1 (índice de la propiedad nombre)
  $secuencia_carta->insert('Smith', NULL, 1);

  // Añadir un valor de apellido a la secuencia
  // valor: 'Jones'
  // índice de secuencia: NULL (añadido)
  // identificador de propiedad: 'apellido' (nombre de la propiedad apellido)
  $secuencia_carta->insert('Jones', NULL, 'apellido');

  // Añadir texto no estructurado
  // valor: 'Cancelar Suscripción.'
  // índice de secuencia: ausente (añadido)
  // identificador de propiedad: ausente (texto no estructurado)
  $secuencia_carta->insert('Cancelar Suscripción.');

  // Insertar nuevo texto no estructurado. Los valores de secuencia subsiguientes
  // son aumentados.                                       
  // valor: 'Por medio de:'
  // índice de secuencia: 1 (insertado como segundo elemento)
  // identificador de propiedad: ausente (texto no estructurado)
  $secuencia_carta->insert('Por medio de:', 1);
?>

Ejemplo #6 Eliminar elementos de una secuencia

Se pueden usar las funciones isset() y unset() para comprobar y eliminar elementos de una secuencia (Nota: unset() actualmente deja los valores del objeto de datos, pero este comportamiento puede cambiar para tambíen eliminar los datos del objeto de datos). Una secuencia se comporta como una lista contigua; por lo tanto, eliminar elementos de la mitad de la lista moverá hacia abajo las entradas en índices más altos. El siguiente ejemplo comprueba si el primer elemento de la secuencia está establecido y lo desestablece si lo está.


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