Zend Framework: Zend_Cloud_Storage Component Proposal

Proposed Component Name	Zend_Cloud_Storage
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Cloud_Storage
Proposers	Wil Sinclair
Zend Liaison	TBD
Revision	0.2 -16 October 2009: Initial Draft. (wiki revision: 10)

Zend_Cloud_Storage is a component in the Simple Cloud API that provides a common API for cloud application storage services, such as Amazon S3, Windows Azure Blob Storage, or Nirvanix. The design goals of this API include simplicity, portability across cloud storage services, stability, and extensibility for future expansion.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

This component must support uploading strings as files.
This component must support downloading files as strings.
This component should support uploading streams as files.
This component should support downloading files as streams.
This component must support deleting files.
This component should support listing files by namespace.
It would be nice if this component provides a simple directory system.
It would be nice if this component provides support for handling containers and buckets.
This component should support fetching file metadata.
It would be nice if this component supports putting metadata.
It would be nice if this component supports deleting metadata.
This component should provide a download URL for unauthenticated and/or shared-access users.
It would be nice if this component supports access control on a file level.
It would be nice if this component supports access control on a directory level.
This component must provide consistent error handling for all adapters.
This component should handle errors identically for common error conditions at the client library level.
This component must provide an interface that can be implemented by adapters- whether they ship with Zend Framework or not.
This component should provide adapters for all cloud storage client libraries that ship with Zend Framework.
Zend_Session.

4. Dependencies on Other Framework Components

Zend_Exception
Cloud storage client libraries under the Zend_Service namespace.
Zend_Http_Client

5. Theory of Operation

Although there are some differences in the storage APIs offered by cloud vendors, there is a set of common runtime operations that can be supported by a unified API. Note that unique value-add offerings such as the media operations in Nirvanix and the sharing features in Box.net are not supported. Azure also offers value-add features, including support for management of large files, that are not supported in this API.
The API follows a more 'functional' model, as opposed to an OOP paradigm, to more easily model services available via RESTful, SOAP, and RPC interfaces. Such an API will also negligibly affect performance, while allowing users to build their own object-oriented data access libraries on top of the simple methods it exposes.
This proposal covers only components implemented for Zend Framework, but these interfaces and classes have been designed to be implementable in other languages and/or package structures.
Open issue: Should we support access control in the API?
Open issue: Zend_Http_Client does not currently support streaming. This functionality must be added.

6. Milestones / Tasks

Milestone 1: [DONE] Simple Cloud API project launched.
Milestone 2: Community review sufficient to submit proposal for recommendation.
Milestone 3: Implement API and adapters in Zend Framework trunk.
Milestone 4: Document API.
Milestone 5: Address issues as necessary for production release.

7. Class Index

Zend_Cloud_StorageService
Zend_Cloud_Storage_Factory
Zend_Cloud_Storage_Exception
Zend_Cloud_Storage_Adapter_S3
Zend_Cloud_Storage_Adapter_Azure
Zend_Cloud_Storage_Adapter_Nirvanix
Zend_Cloud_Storage_Adapter_Rackspace
Zend_Cloud_Storage_Adapter_FileSystem

8. Use Cases

UC-01 - Get instance of adapter

Call static method on factory class
Use it

UC-02 - Upload file

UC-01 - Get instance of adapter
Call store file with data in string
Store request ID if necessary

UC-03 - Store file

UC-01 - Get instance of adapter
Call fetch file and save as a string
Store string

UC-04 - Delete file

UC-01 - Get instance of adapter
Call delete string
Store request ID if necessary

9. Class Skeletons

/**
 * LICENSE
 *
 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://framework.zend.com/license/new-bsd
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to license@zend.com so we can send you a copy immediately.
 *
 * @category   Zend
 * @package    Zend_Cloud
 * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */

/**
 * Common interface for unstructured cloud storage.
 *
 * @category   Zend
 * @package    Zend_Cloud
 * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
interface Zend_Cloud_StorageService
{
    /**
     * Get an item from the storage service.
     *
     * @param  string $path
     * @param  array $options
     * @return mixed
     */
    public function fetchItem($path, $options = null);
    
    /**
     * Store an item in the storage service.
     * WARNING: This operation overwrites any item that is located at 
     * $destinationPath.
     * @param mixed  $data
     * @param string $destinationPath
     * @param  array $options
     * @return boolean
     */
    public function storeItem($data,
                              $destinationPath,
                              $options = null);
    
    /**
     * Delete an item in the storage service.
     *
     * @param  string $path
     * @param  array $options
     * @return void
     */
    public function deleteItem($path, $options = null);
    
    /**
     * Copy an item in the storage service to a given path.
     * 
     * The $destinationPath must be a directory.
     *
     * @param  string $sourcePath
     * @param  string $destination path
     * @param  array $options
     * @return void
     */
    public function copyItem($sourcePath, $destinationPath, $options = null);
    
    /**
     * Move an item in the storage service to a given path.
     * 
     * The $destinationPath must be a directory.
     *
     * @param  string $sourcePath
     * @param  string $destination path
     * @param  array $options
     * @return void
     */
    public function moveItem($sourcePath, $destinationPath, $options = null);
    
    /**
     * Rename an item in the storage service to a given name.
     *
     *
     * @param  string $path
     * @param  string $name
     * @param  array $options
     * @return void
     */
    public function renameItem($path, $name, $options = null);
    
    /**
     * List items in the given directory in the storage service
     * 
     * The $path must be a directory
     *
     *
     * @param  string $path Must be a directory
     * @param  array $options
     * @return array A list of item names
     */
    public function listItems($path, $options = null);
    
    /**
     * Get a key/value array of metadata for the given path.
     *
     * @param  string $path
     * @param  array $options
     * @return array
     */
    public function fetchMetadata($path, $options = null);
    
    /**
     * Store a key/value array of metadata at the given path.
     * WARNING: This operation overwrites any metadata that is located at 
     * $destinationPath.
     *
     * @param  string $path
     * @param  array $options
     * @return void
     */
    public function storeMetadata($metadata, $destinationPath, $options = null);
    
    /**
     * Delete a key/value array of metadata at the given path.
     *
     * @param  string $path
     * @param  array $options
     * @return void
     */
    public function deleteMetadata($path);
}

/**
 * Zend Framework
 *
 * LICENSE
 *
 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://framework.zend.com/license/new-bsd
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to license@zend.com so we can send you a copy immediately.
 *
 * @category   Zend
 * @package    Zend_Cloud_Storage
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */

abstract class Zend_Cloud_Storage_Factory
{
    const STORAGE_ADAPTER_KEY = 'storage_adapter';
    
    public static function getAdapter($options = array()) {
        if($options instanceof Zend_Config) {
            $options = $options->toArray();
        }
        
        if(array_key_exists(self::STORAGE_ADAPTER_KEY, $options)) {
            $classname = $options[self::STORAGE_ADAPTER_KEY];
            unset($options[self::STORAGE_ADAPTER_KEY]);
            Zend_Loader::loadClass($classname);
            return new $classname($options);
        } else {
            throw new Zend_Cloud_Storage_Exception('Class must be specified using the \'' .
            self::STORAGE_ADAPTER_KEY . '\' key.');
        }
    }
}

/**
 * Zend Framework
 *
 * LICENSE
 *
 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://framework.zend.com/license/new-bsd
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to license@zend.com so we can send you a copy immediately.
 *
 * @category   Zend
 * @package    Zend_Cloud_Storage
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
abstract class Zend_Cloud_Storage_Factory
{
    const STORAGE_ADAPTER_KEY = 'storage_adapter';
    
    public static function getAdapter($options = array());
}

/**
 * @category   Zend
 * @package    Zend_Cloud_Storage
 * @copyright  Copyright (c) 2005-2008 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Cloud_Storage_Exception extends Zend_Cloud_Exception
{}

Page Operations

Browse Space

Zend_Cloud_Storage - Wil Sinclair

Labels