Trabajar con objetos de datos secuenciados

Los objetos de datos sencuenciados son SDOs que pueden rastrear el orden de las propiedades de un objeto de datos. También pueden contener elementos de texto no estructurado (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 estar intercalados (

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

). Esto puede ocurrir, por ejemplo, cuando el esquema define maxOccurs>1 en un elemento que es de 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 ejemplo, usando el Servicio de Acceso a Datos 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 intercalar 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 un documento carta de ejemplo. 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>1 de marzo de 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	1 de marzo de 2005
1	-	Mutual of Omaha
2	-	Wild Kingdom, USA
3	-	Querida
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 instancias de objetos de datos sean manipulados en términos de índice de secuencia en lugar de índice de propiedad (mostrado en la tabla de arriba). En los siguientes ejemplos se asume que la carta de ejemplo ha sido cargada en un objeto de datos al que hace referencia la variable $carta.

Ejemplo #1 Obtener la interfaz SDO_Sequence

Se obtiene una 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 secuencias

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

Se pueden recorrer valores individuales de la secuencia usando foreach. Lo siguiente recorre los valores individuales en el orden de la 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 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 es probable que se cambie para que tambíen se eliminen los datos del mismo). 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, en cuyo caso los desestablece.


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