La interfaz Zend_Cloud_DocumentService_Adapter define los métodos que implementa cada adaptador concreto de servicio de documentos. Los siguientes adaptadores se distribuyen con la API SimpleCloud:

Para instanciar un adaptador de servicio de documentos, utilice el método estático Zend_Cloud_DocumentService_Factory::getAdapter(), que acepta un array de configuración o un objeto Zend_Config. La clave document_adapter debe especificar el nombre de la clase del adaptador concreto. También pueden pasarse en este parámetro de configuración claves específicas del adaptador.

$adapterClass = 'Zend_Cloud_DocumentService_Adapter_SimpleDb';
$documents = Zend_Cloud_DocumentService_Factory::getAdapter(array(
    Zend_Cloud_DocumentService_Factory::DOCUMENT_ADAPTER_KEY    => $adapterClass,
    Zend_Cloud_DocumentService_Adapter_SimpleDb::AWS_ACCESS_KEY => $amazonKey,
    Zend_Cloud_DocumentService_Adapter_SimpleDb::AWS_SECRET_KEY => $amazonSecret
));

Cada servicio y base de datos orientados a documentos utiliza su propia terminología y construcciones en su API. La API SimpleCloud identifica y abstrae una serie de conceptos y operaciones comunes que se comparten entre los proveedores.

El almacenamiento de documentos consiste en varias colecciones, que son unidades de almacenamiento lógicas análogas a las tablas de bases de datos en el mundo SQL. Las colecciones contienen documentos, que son esencialmente un conjunto de pares clave-valor, junto con algunos metadatos específicos del motor de almacenamiento, y se identifican mediante un ID de documento único.

Cada documento tiene su propia estructura (conjunto de campos) que no necesariamente debe coincidir con la estructura de ningún otro documento, incluso dentro de la misma colección. De hecho, puede cambiar esta estructura después de que el documento haya sido creado.

Los documentos pueden recuperarse por ID o mediante una consulta a una colección.

Los documentos se representan mediante la clase Zend_Cloud_DocumentService_Document. Tenga en cuenta que la clase de documento no valida los ID y datos suministrados, y no impone la compatibilidad con los requisitos de cada adaptador.

Se puede acceder a los campos del documento usando las claves como propiedades de objeto y como elementos de array.

La interfaz básica de Zend_Cloud_DocumentService_Document es la siguiente:

/**
 * ArrayAccess allows accessing fields by array key:
 *    $doc['fieldname']
 *
 * IteratorAggregate allows iterating over all fields:
 *    foreach ($document as $field => $value) {
 *        echo "$field: $value\n";
 *    }
 *
 * Countable provides a count of all fields:
 *    count($document)
 */
class Zend_Cloud_DocumentService_Document
    implements ArrayAccess, IteratorAggregate, Countable
{
    const KEY_FIELD = '_id';

    /**
     * $fields may be an array or an object implementing ArrayAccess.
     * If no $id is provided, it will look for a field matching KEY_FIELD to
     * use as the identifier.
     */
    public function __construct($fields, $id = null);

    public function setId($id);
    public function getId();
    public function getFields();
    public function getField($name);
    public function setField($name, $value);

    /**
     * These allow overloading, so you may access fields as if they were
     * native properties of the document
     */
    public function __get($name);
    public function __set($name, $value);

    /**
     * Alternately, you can acces fields as if via native getters and
     * setters:
     *     $document->setFoo($value);    // set "Foo" field to value
     *     $value = $document->getFoo(); // get "Foo" field value
    public function __call($name, $args);
}

Identificadores de documentos en Windows Azure

Windows Azure técnicamente requiere una combinación de dos campos para identificar de forma única los documentos: la PartitionKey y la RowKey, y como tal, las claves están completamente calificadas por la estructura array(PartitionKey, RowKey) -- lo que las hace no portables. En la mayoría de las situaciones, la PartitionKey no diferirá para los documentos de una única colección -- y potencialmente ni siquiera en toda su instancia de tabla. Como tal, el DocumentService ofrece varias opciones para especificar claves: Las claves de tipo array siempre funcionarán como se espera. Si se proporciona una clave de tipo string: Si se proporcionó el ajuste default_partition_key al constructor, o se pasó al método setDefaultPartitionKey(), ese valor se usará para la PartitionKey. En caso contrario, se usará el nombre de la colección sobre la que está operando. La conclusión es que puede utilizar claves de tipo string si desea maximizar la portabilidad de su aplicación. Solo tenga en cuenta que su registro contendrá unos pocos campos adicionales para denotar la clave (PartitionKey, RowKey, y el Timestamp del que no se había hablado antes) en caso de que alguna vez migre sus datos a otro servicio.

$document = new Zend_Cloud_DocumentService_Document(array(
    'key1' => 'value1',
    'key2' => 123,
    'key3' => 'thirdvalue',
), "DocumentId");
$document->otherkey = 'some more data';
echo "key 1: " . $document->key1   . "\n"; // object notation
echo "key 2: " . $document['key2'] . "\n"; // array notation

$document = $documents->fetchDocument("mydata", $id);
echo "Document ID: " . $document->getID() . "\n";
foreach ($document->getFields() as $key => $value) {
    echo "Field $key is $value\n";
}

Si ocurre algún error en el servicio de documentos, se lanza Zend_Cloud_DocumentService_Exception. Si la excepción fue causada por el controlador del servicio subyacente, puede usar el método getClientException() para recuperar la excepción original.

Dado que los diferentes proveedores en la nube implementan diferentes conjuntos de servicios, algunos controladores no implementan ciertas características. En este caso, se lanza la excepción Zend_Cloud_OperationNotAvailableException.

Se crea una nueva colección usando createCollection().

$documents->createCollection("mydata");

Si llama a createCollection() con un nombre de colección que ya existe, el servicio no hará nada y dejará la colección existente sin modificar.

Una colección se elimina llamando a deleteCollection().

$documents->deleteCollection("mydata");

Eliminar una colección elimina automáticamente todos los documentos contenidos en esa colección.

	Nota
	Eliminar una colección puede llevar un tiempo considerable en algunos servicios. No puede volver a crear una colección con el mismo nombre hasta que la colección y todos sus documentos se hayan eliminado por completo.

Eliminar una colección inexistente no tendrá ningún efecto.

Una lista de las colecciones existentes se devuelve mediante listCollections(). Este método devuelve un array con todos los nombres de las colecciones pertenecientes a la cuenta que especificó al crear el adaptador.

$list = $documents->listCollections();
foreach ($list as $collection) {
    echo "My collection: $collection\n";
}

Para insertar un documento, necesita proporcionar un objeto Zend_Cloud_DocumentService_Document o un array asociativo de datos, así como la colección en la que lo está insertando.

Muchos proveedores requieren que proporcione un ID de documento junto con su documento. Si usa un objeto Zend_Cloud_DocumentService_Document, puede especificarlo pasando el identificador al constructor al instanciar el objeto. Si usa un array asociativo, el nombre de la clave será específico del adaptador; por ejemplo, en Azure, el ID está compuesto por la PartitionKey y la RowKey; en Amazon SimpleDB, el ID es el ItemName; también puede especificar la clave en el campo _id para una mayor portabilidad.

Como tal, la forma más sencilla y compatible de especificar la clave es usar un objeto Document.

// Instantiating and creating the document
$document = new Zend_Cloud_DocumentService_Document(array(
    'key1' => 'value1',
    'key2' => 123,
    'key3' => 'thirdvalue',
), "DocumentID");

// inserting into the "mydata" collection
$documents->insertDocument("mydata", $document);

Reemplazar un documento significa eliminar todos los datos del documento asociados a una clave de documento en particular y sustituirlos por un nuevo conjunto de datos. A diferencia de actualizar, esta operación no fusiona los datos antiguos y nuevos, sino que reemplaza el documento en su totalidad. La operación de reemplazo, al igual que insertDocument(), acepta un documento Zend_Cloud_DocumentService_Document o un array de pares clave-valor que especifican los nombres y valores de los nuevos campos, y la colección en la que existe el documento.

	Se requiere el ID del documento
	Para reemplazar el documento, se requiere el ID del documento. Al igual que al insertar un documento, si usa un array asociativo para describir el documento, necesitará proporcionar una clave específica del proveedor que indique el ID del documento. Como tal, la forma más compatible de reemplazar un documento entre proveedores es utilizar un objeto Document, como se muestra en los ejemplos.

$document = new Zend_Cloud_DocumentService_Document(array(
    'key1' => 'value1',
    'key2' => 123,
    'key3' => 'thirdvalue',
), "DocumentID");

// Update the document as found in the "mydata" collection
$documents->replaceDocument("mydata", $document);

$docment->key4 = '4th value';

// Update the document as found in the "mydata" collection
$documents->replaceDocument("mydata", $document);

Actualizar un documento cambia los pares clave/valor en un documento existente. Esta operación no comparte la semántica de reemplazo; los valores de las claves que no se especifican en el conjunto de datos no se cambiarán. Debe proporcionar tanto una clave de documento como datos, ya sea mediante un documento Zend_Cloud_DocumentService_Document o un array, a este método. Si la clave es null y se proporciona un objeto documento, se usa la clave del documento.

// update one field
$documents->updateDocument("mydata", "DocumentID", array("key2" => "new value"));

// or with document; this could be a document already retrieved from the service
$document = new Zend_Cloud_DocumentService_Document(array(
    'key1' => 'value1',
    'key2' => 123,
    'key3' => 'thirdvalue',
), "DocumentID");
$documents->updateDocument("mydata", null, $document);

// copy document to another ID
$documents->updateDocument("mydata", "AnotherDocumentID", $document);

Amazon SimpleDB admite campos multivaluados, por lo que las actualizaciones de datos se fusionarán con el valor de clave anterior en lugar de reemplazarlo. La opción merge debe contener un array de nombres de campos a fusionar. El array debe ser pares clave/valor, donde la clave corresponde a la clave del campo, y el valor un valor booleano que indica el estado de fusión (booleano true fusionaría; false no lo haría). Cualquier clave no especificada en la opción merge se reemplazará en lugar de fusionarse.

// key2 is overwritten, key3 is merged
$documents->updateDocument('mydata', 'DocumentID',
    array('key2' => 'new value', 'key3' => 'additional value'),
    array('merge' => array('key3' => true))
);

Un documento puede eliminarse pasando su clave a deleteDocument(). Eliminar un documento inexistente no tiene ningún efecto.

$documents->deleteDocument("collectionName", "DocumentID");

Puede obtener un documento específico especificando su clave. fetchDocument() devuelve una instancia de Zend_Cloud_DocumentService_Document.

$document = $service->fetchDocument('collectionName', 'DocumentID');
echo "Document ID: " . var_export($document->getID(), 1) . "\n";
foreach ($document->getFields() as $key => $value) {
    echo "Field $key is $value\n";
}

Para encontrar documentos en la colección que cumplan ciertos criterios, use el método query(). Este método acepta ya sea una cadena que es una consulta dependiente del adaptador y se pasa tal cual al adaptador concreto, o una instancia de un objeto de consulta estructurada de Zend_Cloud_DocumentService_Query. El valor de retorno es un Zend_Cloud_DocumentService_DocumentSet, que contiene instancias de Zend_Cloud_DocumentService_Document que satisfacen la consulta. El objeto DocumentSet es iterable y contable.

$docs = $documents->query(
    "collectionName",
    "RowKey eq 'rowkey2' or RowKey eq 'rowkey2'"
);

foreach ($docs as $doc) {
    $id = $doc->getId();
    echo "Found document with ID: "
        . var_export($id, 1)
        . "\n";
}

Si usa un objeto de consulta estructurada, normalmente lo obtendrá mediante el método select(). Esto garantiza que el objeto de consulta sea específico de su adaptador, lo que asegura que se ensamble en una sintaxis que su adaptador entienda.

$query = $service->select();
$query->from('collectionName')
      ->where('year > ?', array(1945))
      ->limit(3);
$docs = $documents->query('collectionName', $query);

foreach ($docs as $doc) {
    $id = $doc->getId();
    echo "Found document with ID: "
        . var_export($id, 1)
        . "\n";
}

Las clases Zend_Cloud_DocumentService_Query no limitan qué cláusulas de consulta pueden usarse, pero la cláusula debe estar soportada por el adaptador concreto subyacente. Las cláusulas actualmente soportadas incluyen:

Para conveniencia del usuario, el método select() instancia un objeto de consulta específico del adaptador, y establece la cláusula SELECT para él.

$query = $documents->select()
                   ->from('collectionName')
                   ->where('year > ?', array(1945))
                   ->limit(3);
$docs = $documents->query('collectionName', $query);
foreach ($docs as $doc) {
    $id = $doc->getId();
    echo "Found document with ID: "
        . var_export($id, 1)
        . "\n";
}

En ocasiones es necesario recuperar el adaptador concreto para el servicio con el que está trabajando la API Document. Esto puede lograrse usando el método getAdapter().

	Nota
	Acceder al adaptador subyacente rompe la portabilidad entre servicios, por lo que debe reservarse solo para circunstancias excepcionales.

// Since SimpleCloud Document API doesn't support batch upload, use concrete adapter
$amazonSdb = $documents->getAdapter();
$amazonSdb->batchPutAttributes($items, 'collectionName');