1 <?php

     2 /**

     3  * LICENSE

     4  *

     5  * This source file is subject to the new BSD license that is bundled

     6  * with this package in the file LICENSE.txt.

     7  * It is also available through the world-wide-web at this URL:

     8  * http://framework.zend.com/license/new-bsd

     9  * If you did not receive a copy of the license and are unable to

    10  * obtain it through the world-wide-web, please send an email

    11  * to license@zend.com so we can send you a copy immediately.

    12  *

    13  * @category   Zend

    14  * @package    Zend_Cloud

    15  * @subpackage DocumentService

    16  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

    17  * @license    http://framework.zend.com/license/new-bsd     New BSD License

    18  */

    19 

    20 require_once 'Zend/Cloud/DocumentService/Adapter/AbstractAdapter.php';

    21 require_once 'Zend/Cloud/DocumentService/Adapter/WindowsAzure/Query.php';

    22 require_once 'Zend/Cloud/DocumentService/Exception.php';

    23 require_once 'Zend/Service/WindowsAzure/Storage/DynamicTableEntity.php';

    24 require_once 'Zend/Service/WindowsAzure/Storage/Table.php';

    25 

    26 /**

    27  * SimpleDB adapter for document service.

    28  *

    29  * @category   Zend

    30  * @package    Zend_Cloud

    31  * @subpackage DocumentService

    32  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

    33  * @license    http://framework.zend.com/license/new-bsd     New BSD License

    34  */

    35 class Zend_Cloud_DocumentService_Adapter_WindowsAzure 

    36     extends Zend_Cloud_DocumentService_Adapter_AbstractAdapter

    37 {

    38     /*

    39      * Options array keys for the Azure adapter.

    40      */

    41     const ACCOUNT_NAME          = 'storage_accountname';

    42     const ACCOUNT_KEY           = 'storage_accountkey';

    43     const HOST                  = "storage_host";

    44     const PROXY_HOST            = "storage_proxy_host";

    45     const PROXY_PORT            = "storage_proxy_port";

    46     const PROXY_CREDENTIALS     = "storage_proxy_credentials";

    47     const DEFAULT_PARTITION_KEY = "default_partition_key";

    48 

    49     const PARTITION_KEY         = 'PartitionKey';

    50     const ROW_KEY               = 'RowKey';

    51     const VERIFY_ETAG           = "verify_etag";

    52     const TIMESTAMP_KEY         = "Timestamp";

    53     

    54     const DEFAULT_HOST          = Zend_Service_WindowsAzure_Storage::URL_CLOUD_TABLE;

    55     const DEFAULT_QUERY_CLASS   = 'Zend_Cloud_DocumentService_Adapter_WindowsAzure_Query';

    56 

    57     /**

    58      * Azure  service instance.

    59      * 

    60      * @var Zend_Service_WindowsAzure_Storage_Table

    61      */

    62     protected $_storageClient;

    63 

    64     /**

    65      * Class to utilize for new query objects

    66      * 

    67      * @var string

    68      */

    69     protected $_queryClass = 'Zend_Cloud_DocumentService_Adapter_WindowsAzure_Query';

    70 

    71     /**

    72      * Partition key to use by default when constructing document identifiers

    73      * @var string

    74      */

    75     protected $_defaultPartitionKey;

    76 

    77     /**

    78      * Constructor

    79      * 

    80      * @param array $options 

    81      * @return void

    82      */

    83     public function __construct($options = array()) 

    84     {

    85         if ($options instanceof Zend_Config) {

    86             $options = $options->toArray();

    87         }

    88 

    89         if (empty($options)) {

    90             $options = array();

    91         }

    92 

    93         if (!is_array($options)) {

    94             throw new Zend_Cloud_DocumentService_Exception('Invalid options provided');

    95         }

    96 

    97         if (isset($options[self::DOCUMENT_CLASS])) {

    98             $this->setDocumentClass($options[self::DOCUMENT_CLASS]);

    99         }

   100 

   101         if (isset($options[self::DOCUMENTSET_CLASS])) {

   102             $this->setDocumentSetClass($options[self::DOCUMENTSET_CLASS]);

   103         }

   104 

   105         if (isset($options[self::QUERY_CLASS])) {

   106             $this->setQueryClass($options[self::QUERY_CLASS]);

   107         }

   108 

   109         // Build Zend_Service_WindowsAzure_Storage_Blob instance

   110         if (!isset($options[self::HOST])) {

   111             $host = self::DEFAULT_HOST;

   112         } else {

   113             $host = $options[self::HOST];

   114         }

   115 

   116         if (! isset($options[self::ACCOUNT_NAME])) {

   117             throw new Zend_Cloud_DocumentService_Exception('No Windows Azure account name provided.');

   118         }

   119 

   120         if (! isset($options[self::ACCOUNT_KEY])) {

   121             throw new Zend_Cloud_DocumentService_Exception('No Windows Azure account key provided.');

   122         }

   123 

   124         // TODO: support $usePathStyleUri and $retryPolicy

   125         try {

   126             $this->_storageClient = new Zend_Service_WindowsAzure_Storage_Table(

   127                     $host, $options[self::ACCOUNT_NAME], $options[self::ACCOUNT_KEY]);

   128             // Parse other options

   129             if (! empty($options[self::PROXY_HOST])) {

   130                 $proxyHost = $options[self::PROXY_HOST];

   131                 $proxyPort = isset($options[self::PROXY_PORT]) ? $options[self::PROXY_PORT] : 8080;

   132                 $proxyCredentials = isset($options[self::PROXY_CREDENTIALS]) ? $options[self::PROXY_CREDENTIALS] : '';

   133                 $this->_storageClient->setProxy(true, $proxyHost, $proxyPort, $proxyCredentials);

   134             }

   135             if (isset($options[self::HTTP_ADAPTER])) {

   136                 $this->_storageClient->setHttpClientChannel($options[self::HTTP_ADAPTER]);

   137             }

   138         } catch(Zend_Service_WindowsAzure_Exception $e) {

   139             throw new Zend_Cloud_DocumentService_Exception('Error on document service creation: '.$e->getMessage(), $e->getCode(), $e);

   140         }

   141     }

   142 

   143     /**

   144      * Set the default partition key

   145      * 

   146      * @param  string $key 

   147      * @return Zend_Cloud_DocumentService_Adapter_WindowsAzure

   148      */

   149     public function setDefaultPartitionKey($key)

   150     {

   151         $this->_validateKey($key);

   152         $this->_defaultPartitionKey = $key;

   153         return $this;

   154     }

   155 

   156     /**

   157      * Retrieve default partition key

   158      * 

   159      * @return null|string

   160      */

   161     public function getDefaultPartitionKey()

   162     {

   163         return $this->_defaultPartitionKey;

   164     }

   165 

   166     /**

   167      * Create collection.

   168      *

   169      * @param  string $name

   170      * @param  array  $options

   171      * @return boolean

   172      */

   173     public function createCollection($name, $options = null) 

   174     {

   175         if (!preg_match('/^[A-Za-z][A-Za-z0-9]{2,}$/', $name)) {

   176             throw new Zend_Cloud_DocumentService_Exception('Invalid collection name; Windows Azure collection names must consist of alphanumeric characters only, and be at least 3 characters long');

   177         }

   178         try {

   179             $this->_storageClient->createTable($name);

   180         } catch(Zend_Service_WindowsAzure_Exception $e) {

   181             if (strpos($e->getMessage(), "table specified already exists") === false) {

   182                 throw new Zend_Cloud_DocumentService_Exception('Error on collection creation: '.$e->getMessage(), $e->getCode(), $e);

   183             }

   184         }

   185         return true;

   186     }

   187 

   188     /**

   189      * Delete collection.

   190      *

   191      * @param  string $name

   192      * @param  array  $options

   193      * @return boolean

   194      */

   195     public function deleteCollection($name, $options = null) 

   196     {

   197         try {

   198             $this->_storageClient->deleteTable($name);

   199         } catch(Zend_Service_WindowsAzure_Exception $e) {

   200             if (strpos($e->getMessage(), "does not exist") === false) {

   201                 throw new Zend_Cloud_DocumentService_Exception('Error on collection deletion: '.$e->getMessage(), $e->getCode(), $e);

   202             }

   203         }

   204         return true;

   205     }

   206 

   207     /**

   208      * List collections.

   209      *

   210      * @param  array  $options

   211      * @return array

   212      */

   213     public function listCollections($options = null) 

   214     {

   215         try {

   216             $tables = $this->_storageClient->listTables();

   217             $restables = array();

   218             foreach ($tables as $table) {

   219                 $restables[] = $table->name;

   220             }

   221             return $restables;

   222         } catch(Zend_Service_WindowsAzure_Exception $e) {

   223             throw new Zend_Cloud_DocumentService_Exception('Error on collection list: '.$e->getMessage(), $e->getCode(), $e);

   224         }

   225 

   226         return $tables;

   227     }

   228 

   229     /**

   230      * Create suitable document from array of fields

   231      * 

   232      * @param  array $document

   233      * @param  null|string $collectionName Collection to which this document belongs

   234      * @return Zend_Cloud_DocumentService_Document

   235      */

   236     protected function _getDocumentFromArray($document, $collectionName = null)

   237     {

   238         $key = null;

   239         if (!isset($document[Zend_Cloud_DocumentService_Document::KEY_FIELD])) {

   240             if (isset($document[self::ROW_KEY])) {

   241                 $rowKey = $document[self::ROW_KEY];

   242                     unset($document[self::ROW_KEY]);

   243                 if (isset($document[self::PARTITION_KEY])) {

   244                     $key = array($document[self::PARTITION_KEY], $rowKey);

   245                     unset($document[self::PARTITION_KEY]);

   246                 } elseif (null !== ($partitionKey = $this->getDefaultPartitionKey())) {

   247                     $key = array($partitionKey, $rowKey);

   248                 } elseif (null !== $collectionName) {

   249                     $key = array($collectionName, $rowKey);

   250                 }

   251             }

   252         } else {

   253             $key = $document[Zend_Cloud_DocumentService_Document::KEY_FIELD];

   254             unset($document[Zend_Cloud_DocumentService_Document::KEY_FIELD]);

   255         }

   256 

   257         $documentClass = $this->getDocumentClass();

   258         return new $documentClass($document, $key);

   259     }

   260     

   261     /**

   262      * List all documents in a collection

   263      * 

   264      * @param  string $collectionName 

   265      * @param  null|array $options 

   266      * @return Zend_Cloud_DocumentService_DocumentSet

   267      */

   268     public function listDocuments($collectionName, array $options = null)

   269     {

   270         $select = $this->select()->from($collectionName);

   271         return $this->query($collectionName, $select);

   272     }

   273 

   274     /**

   275      * Insert document

   276      *

   277      * @param  array|Zend_Cloud_DocumentService_Document $document

   278      * @param  array                         $options

   279      * @return boolean

   280      */

   281     public function insertDocument($collectionName, $document, $options = null)

   282     {

   283         if (is_array($document)) {

   284             $document =  $this->_getDocumentFromArray($document, $collectionName);

   285         } 

   286         

   287         if (!$document instanceof Zend_Cloud_DocumentService_Document) {

   288             throw new Zend_Cloud_DocumentService_Exception('Invalid document supplied');

   289         }

   290         

   291         $key = $this->_validateDocumentId($document->getId(), $collectionName);

   292         $document->setId($key);

   293         

   294         $this->_validateCompositeKey($key);

   295         $this->_validateFields($document);

   296         try {

   297         

   298             $entity = new Zend_Service_WindowsAzure_Storage_DynamicTableEntity($key[0], $key[1]);

   299             $entity->setAzureValues($document->getFields(), true);

   300             $this->_storageClient->insertEntity($collectionName, $entity);

   301         } catch(Zend_Service_WindowsAzure_Exception $e) {

   302             throw new Zend_Cloud_DocumentService_Exception('Error on document insertion: '.$e->getMessage(), $e->getCode(), $e);

   303         }

   304     }

   305 

   306     /**

   307      * Replace document. 

   308      * 

   309      * The new document replaces the existing document.

   310      *

   311      * @param  Zend_Cloud_DocumentService_Document $document

   312      * @param  array                         $options

   313      * @return boolean

   314      */

   315     public function replaceDocument($collectionName, $document, $options = null)

   316     {

   317         if (is_array($document)) {

   318             $document = $this->_getDocumentFromArray($document, $collectionName);

   319         } 

   320         

   321         if (!$document instanceof Zend_Cloud_DocumentService_Document) {

   322             throw new Zend_Cloud_DocumentService_Exception('Invalid document supplied');

   323         }

   324         

   325         $key = $this->_validateDocumentId($document->getId(), $collectionName);

   326         $this->_validateFields($document);

   327         try {

   328             $entity = new Zend_Service_WindowsAzure_Storage_DynamicTableEntity($key[0], $key[1]);

   329             $entity->setAzureValues($document->getFields(), true);

   330             if (isset($options[self::VERIFY_ETAG])) {

   331                 $entity->setEtag($options[self::VERIFY_ETAG]);

   332             }

   333             

   334             $this->_storageClient->updateEntity($collectionName, $entity, isset($options[self::VERIFY_ETAG]));

   335         } catch(Zend_Service_WindowsAzure_Exception $e) {

   336             throw new Zend_Cloud_DocumentService_Exception('Error on document replace: '.$e->getMessage(), $e->getCode(), $e);

   337         }

   338     }

   339 

   340     /**

   341      * Update document. 

   342      * 

   343      * The new document is merged the existing document.

   344      *

   345      * @param  string $collectionName

   346      * @param  mixed|Zend_Cloud_DocumentService_Document $documentId Document identifier or document contaiing updates

   347      * @param  null|array|Zend_Cloud_DocumentService_Document Fields to update (or new fields))

   348      * @param  array $options

   349      * @return boolean

   350      */

   351     public function updateDocument($collectionName, $documentId, $fieldset = null, $options = null)

   352     {

   353         if (null === $fieldset && $documentId instanceof Zend_Cloud_DocumentService_Document) {

   354             $fieldset   = $documentId->getFields();

   355             $documentId = $documentId->getId();

   356         } elseif ($fieldset instanceof Zend_Cloud_DocumentService_Document) {

   357             if ($documentId == null) {

   358                 $documentId = $fieldset->getId();

   359             }

   360             $fieldset = $fieldset->getFields();

   361         }

   362 

   363         $this->_validateCompositeKey($documentId, $collectionName);

   364         $this->_validateFields($fieldset);

   365         try {

   366             $entity = new Zend_Service_WindowsAzure_Storage_DynamicTableEntity($documentId[0], $documentId[1]);

   367 

   368             // Ensure timestamp is set correctly

   369             if (isset($fieldset[self::TIMESTAMP_KEY])) {

   370                 $entity->setTimestamp($fieldset[self::TIMESTAMP_KEY]);

   371                 unset($fieldset[self::TIMESTAMP_KEY]);

   372             }

   373 

   374             $entity->setAzureValues($fieldset, true);

   375             if (isset($options[self::VERIFY_ETAG])) {

   376                 $entity->setEtag($options[self::VERIFY_ETAG]);

   377             }

   378             

   379             $this->_storageClient->mergeEntity($collectionName, $entity, isset($options[self::VERIFY_ETAG]));

   380         } catch(Zend_Service_WindowsAzure_Exception $e) {

   381             throw new Zend_Cloud_DocumentService_Exception('Error on document update: '.$e->getMessage(), $e->getCode(), $e);

   382         }

   383     }

   384     

   385     /**

   386      * Delete document.

   387      *

   388      * @param  mixed  $document Document ID or Document object.

   389      * @param  array  $options

   390      * @return void

   391      */

   392     public function deleteDocument($collectionName, $documentId, $options = null)

   393     {

   394         if ($documentId instanceof Zend_Cloud_DocumentService_Document) {

   395             $documentId = $documentId->getId();

   396         }

   397 

   398         $documentId = $this->_validateDocumentId($documentId, $collectionName);

   399 

   400         try {

   401             $entity = new Zend_Service_WindowsAzure_Storage_DynamicTableEntity($documentId[0], $documentId[1]);

   402             if (isset($options[self::VERIFY_ETAG])) {

   403                 $entity->setEtag($options[self::VERIFY_ETAG]);

   404             }

   405             $this->_storageClient->deleteEntity($collectionName, $entity, isset($options[self::VERIFY_ETAG]));

   406         } catch(Zend_Service_WindowsAzure_Exception $e) {

   407             if (strpos($e->getMessage(), "does not exist") === false) {

   408                 throw new Zend_Cloud_DocumentService_Exception('Error on document deletion: '.$e->getMessage(), $e->getCode(), $e);

   409             }

   410         }

   411     }

   412 

   413     /**

   414      * Fetch single document by ID

   415      * 

   416      * @param  string $collectionName Collection name

   417      * @param  mixed $documentId Document ID, adapter-dependent

   418      * @param  array $options

   419      * @return Zend_Cloud_DocumentService_Document

   420      */

   421     public function fetchDocument($collectionName, $documentId, $options = null)

   422     {

   423         $documentId = $this->_validateDocumentId($documentId, $collectionName);

   424         try {

   425             $entity = $this->_storageClient->retrieveEntityById($collectionName, $documentId[0], $documentId[1]);

   426             $documentClass = $this->getDocumentClass();

   427             return new $documentClass($this->_resolveAttributes($entity), array($entity->getPartitionKey(), $entity->getRowKey()));

   428         } catch (Zend_Service_WindowsAzure_Exception $e) {

   429             if (strpos($e->getMessage(), "does not exist") !== false) {

   430                 return false;

   431             }

   432             throw new Zend_Cloud_DocumentService_Exception('Error on document fetch: '.$e->getMessage(), $e->getCode(), $e);

   433         }

   434     }

   435     

   436     /**

   437      * Query for documents stored in the document service. If a string is passed in

   438      * $query, the query string will be passed directly to the service.

   439      *

   440      * @param  string $collectionName Collection name

   441      * @param  string|Zend_Cloud_DocumentService_Adapter_WindowsAzure_Query $query

   442      * @param  array $options

   443      * @return array Zend_Cloud_DocumentService_DocumentSet

   444      */

   445     public function query($collectionName, $query, $options = null)

   446     {

   447         try {

   448             if ($query instanceof Zend_Cloud_DocumentService_Adapter_WindowsAzure_Query) {

   449                 $entities = $this->_storageClient->retrieveEntities($query->assemble());

   450             } else {

   451                 $entities = $this->_storageClient->retrieveEntities($collectionName, $query);

   452             }

   453 

   454             $documentClass = $this->getDocumentClass();

   455             $resultSet     = array();

   456             foreach ($entities as $entity) {

   457                 $resultSet[] = new $documentClass(

   458                     $this->_resolveAttributes($entity),

   459                     array($entity->getPartitionKey(), $entity->getRowKey())

   460                 );

   461             }

   462         } catch(Zend_Service_WindowsAzure_Exception $e) {

   463             throw new Zend_Cloud_DocumentService_Exception('Error on document query: '.$e->getMessage(), $e->getCode(), $e);

   464         }

   465 

   466         $setClass = $this->getDocumentSetClass();

   467         return new $setClass($resultSet);

   468     }

   469     

   470     /**

   471      * Create query statement

   472      *

   473      * @return Zend_Cloud_DocumentService_Query

   474      */

   475     public function select($fields = null)

   476     {

   477         $queryClass = $this->getQueryClass();

   478         if (!class_exists($queryClass)) {

   479             require_once 'Zend/Loader.php';

   480             Zend_Loader::loadClass($queryClass);

   481         }

   482 

   483         $query = new $queryClass();

   484         $defaultClass = self::DEFAULT_QUERY_CLASS;

   485         if (!$query instanceof $defaultClass) {

   486             throw new Zend_Cloud_DocumentService_Exception('Query class must extend ' . self::DEFAULT_QUERY_CLASS);

   487         }

   488 

   489         $query->select($fields);

   490         return $query;        

   491     }

   492     

   493     /**

   494      * Get the concrete service client

   495      *

   496      * @return Zend_Service_WindowsAzure_Storage_Table

   497      */

   498     public function getClient()

   499     {

   500         return $this->_storageClient;

   501     }

   502     

   503     /**

   504      * Resolve table values to attributes

   505      * 

   506      * @param  Zend_Service_WindowsAzure_Storage_TableEntity $entity 

   507      * @return array

   508      */

   509     protected function _resolveAttributes(Zend_Service_WindowsAzure_Storage_TableEntity $entity)

   510     {

   511         $result = array();

   512         foreach ($entity->getAzureValues() as $attr) {

   513             $result[$attr->Name] = $attr->Value;

   514         }

   515         return $result;

   516     }

   517     

   518 

   519     /**

   520      * Validate a partition or row key

   521      * 

   522      * @param  string $key 

   523      * @return void

   524      * @throws Zend_Cloud_DocumentService_Exception

   525      */

   526     protected function _validateKey($key)

   527     {

   528         if (preg_match('@[/#?' . preg_quote('\\') . ']@', $key)) {

   529             throw new Zend_Cloud_DocumentService_Exception('Invalid partition or row key provided; must not contain /, \\,  #, or ? characters');

   530         }

   531     }

   532 

   533     /**

   534      * Validate a composite key

   535      * 

   536      * @param  array $key 

   537      * @return throws Zend_Cloud_DocumentService_Exception

   538      */

   539     protected function _validateCompositeKey(array $key)

   540     {

   541         if (2 != count($key)) {

   542             throw new Zend_Cloud_DocumentService_Exception('Invalid document key provided; must contain exactly two elements: a PartitionKey and a RowKey');

   543         }

   544         foreach ($key as $k) {

   545             $this->_validateKey($k);

   546         }

   547     }

   548 

   549     /**

   550      * Validate a document identifier

   551      *

   552      * If the identifier is an array containing a valid partition and row key, 

   553      * returns it. If the identifier is a string:

   554      * - if a default partition key is present, it creates an identifier using 

   555      *   that and the provided document ID

   556      * - if a collection name is provided, it will use that for the partition key

   557      * - otherwise, it's invalid

   558      * 

   559      * @param  array|string $documentId 

   560      * @param  null|string $collectionName 

   561      * @return array

   562      * @throws Zend_Cloud_DocumentService_Exception

   563      */

   564     protected function _validateDocumentId($documentId, $collectionName = false)

   565     {

   566         if (is_array($documentId)) {

   567             $this->_validateCompositeKey($documentId);

   568             return $documentId;

   569         }

   570         if (!is_string($documentId)) {

   571             throw new Zend_Cloud_DocumentService_Exception('Invalid document identifier; must be a string or an array');

   572         }

   573 

   574         $this->_validateKey($documentId);

   575 

   576         if (null !== ($partitionKey = $this->getDefaultPartitionKey())) {

   577             return array($partitionKey, $documentId);

   578         }

   579         if (null !== $collectionName) {

   580             return array($collectionName, $documentId);

   581         }

   582         throw new Zend_Cloud_DocumentService_Exception('Cannot determine partition name; invalid document identifier');

   583     }

   584 

   585     /**

   586      * Validate a document's fields for well-formedness

   587      *

   588      * Since Azure uses Atom, and fieldnames are included as part of XML 

   589      * element tag names, the field names must be valid XML names.

   590      *

   591      * @param  Zend_Cloud_DocumentService_Document|array $document

   592      * @return void

   593      * @throws Zend_Cloud_DocumentService_Exception

   594      */

   595     public function _validateFields($document)

   596     {

   597         if ($document instanceof Zend_Cloud_DocumentService_Document) {

   598             $document = $document->getFields();

   599         } elseif (!is_array($document)) {

   600             throw new Zend_Cloud_DocumentService_Exception('Cannot inspect fields; invalid type provided');

   601         }

   602 

   603         foreach (array_keys($document) as $key) {

   604             $this->_validateFieldKey($key);

   605         }

   606     }

   607 

   608     /**

   609      * Validate an individual field name for well-formedness

   610      *

   611      * Since Azure uses Atom, and fieldnames are included as part of XML 

   612      * element tag names, the field names must be valid XML names.

   613      *

   614      * While we could potentially normalize names, this could also lead to 

   615      * conflict with other field names -- which we should avoid. As such,

   616      * invalid field names will raise an exception.

   617      *

   618      * @param  string $key

   619      * @return void

   620      * @throws Zend_Cloud_DocumentService_Exception

   621      */

   622     public function _validateFieldKey($key)

   623     {

   624         if (!preg_match('/^[_A-Za-z][-._A-Za-z0-9]*$/', $key)) {

   625             throw new Zend_Cloud_DocumentService_Exception('Field keys must conform to XML names (^[_A-Za-z][-._A-Za-z0-9]*$); key "' . $key . '" does not match');

   626         }

   627     }

   628 }