<?php
/**
 * File containing the ezcCacheStorage class.
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 * @package Cache
 * @version //autogentag//
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
 * @filesource
 */

/**
 * This is the abstract base class for all cache storages. It provides
 * the interface to be implemented by a cache backend as abstract methods.
 * For your convenience it contains some methods you can utilize to create your
 * own storage implementation (e.g. for storing cache data into a database).
 *
 * Implementations of ezcCacheStorage can be used with the
 * {@link ezcCacheManager} or on their own. If you want to implement a cache
 * storage backend that stores cache data in a file on your harddisk, there
 * is an extended version of ezcCacheStorage, {@link ezcCacheStorageFile},
 * which already implements large parts of the API and leaves only
 * very few work for you to do. The descendant class {@link ezcCacheStorageMemory}
 * is a base class for storage using memory.
 *
 * For example code of using a cache storage, see {@link ezcCacheManager}.
 *
 * The Cache package already contains several implementations of
 * {@link ezcCacheStorageFile}:
 *
 * - {@link ezcCacheStorageFileArray}
 * - {@link ezcCacheStorageFileEvalArray}
 * - {@link ezcCacheStorageFilePlain}
 *
 * Implementations of {@link ezcCacheStorageMemory}:
 *
 * - {@link ezcCacheStorageMemcachePlain}
 * - {@link ezcCacheStorageApcPlain}
 * - {@link ezcCacheStorageFileApcArray}
 *
 * @property ezcCacheStorageOptions $options
 *           Options for the cache storage. Which options are
 *           supported depends on the specific implementation of the
 *           ezcCacheStorage.
 * @property string $location
 *           The location the cache resides in.
 *
 * @package Cache
 * @version //autogentag//
 */
abstract class ezcCacheStorage
{
    /**
     * Container to hold the properties
     *
     * @var array(string=>mixed)
     */
    protected $properties;

    /**
     * Creates a new cache storage in the given location.
     * Creates a new cache storage for a given location. The location can
     * differ for each ezcCacheStorage implementation, but will most likely
     * be a filesystem path to a directory where cache data is stored in. The
     * location is null for memory storage and an existing writeable path
     * for file or memory/file storage.
     *
     * Per default there is only 1 common option for all ezcCacheStorage
     * classes, which is the 'ttl' ( Time-To-Life ). This is per default set
     * to 1 day. Specific ezcCacheStorage implementations can have
     * additional options.
     *
     * @param string $location               Path to the cache location. Null for
     *                                       memory-based storage and an existing
     *                                       writeable path for file or memory/file
     *                                       storage.
     * @param array(string=>string) $options Options for the cache.
     *
     * @throws ezcBaseFileNotFoundException
     *         If the storage location does not exist. This should usually not
     *         happen, since {@link ezcCacheManager::createCache()} already
     *         performs sanity checks for the cache location. In case this
     *         exception is thrown, your cache location has been corrupted
     *         after the cache was configured.
     * @throws ezcBaseFileNotFoundException
     *         If the storage location is not a directory. This should usually
     *         not happen, since {@link ezcCacheManager::createCache()} already
     *         performs sanity checks for the cache location. In case this
     *         exception is thrown, your cache location has been corrupted
     *         after the cache was configured.
     * @throws ezcBaseFilePermissionException
     *         If the storage location is not writeable. This should usually not
     *         happen, since {@link ezcCacheManager::createCache()} already
     *         performs sanity checks for the cache location. In case this
     *         exception is thrown, your cache location has been corrupted
     *         after the cache was configured.
     * @throws ezcBasePropertyNotFoundException
     *         If you tried to set a non-existent option value. The accepted
     *         options depend on the ezcCacheStorage implementation and may
     *         vary.
     */
    public function __construct( $location, $options = array() )
    {
        $this->properties['location'] = ( substr( $location, -1 ) === '/' ) ? $location : $location . '/';
        $this->validateLocation();
        $this->properties['options'] = new ezcCacheStorageOptions( $options );
    }

    /**
     * Store data to the cache storage.
     * This method stores the given cache data into the cache, assigning the
     * ID given to it.
     *
     * The type of cache data which is expected by a ezcCacheStorage depends on
     * its implementation. In most cases strings and arrays will be accepted,
     * in some rare cases only strings might be accepted.
     *
     * Using attributes you can describe your cache data further. This allows
     * you to deal with multiple cache data at once later. Some ezcCacheStorage
     * implementations also use the attributes for storage purposes. Attributes
     * form some kind of "extended ID".
     *
     * @param string $id                        The item ID.
     * @param mixed $data                       The data to store.
     * @param array(string=>string) $attributes Attributes that describe the
     *                                          cached data.
     *
     * @return string           The ID of the newly cached data.
     *
     * @throws ezcBaseFilePermissionException
     *         If an already existsing cache file could not be unlinked to
     *         store the new data (may occur, when a cache item's TTL
     *         has expired and the file should be stored with more actual
     *         data). This exception means most likely that your cache directory
     *         has been corrupted by external influences (file permission
     *         change).
     * @throws ezcBaseFilePermissionException
     *         If the directory to store the cache file could not be created.
     *         This exception means most likely that your cache directory
     *         has been corrupted by external influences (file permission
     *         change).
     * @throws ezcBaseFileIoException
     *         If an error occured while writing the data to the cache. If this
     *         exception occurs, a serious error occured and your storage might
     *         be corruped (e.g. broken network connection, file system broken,
     *         ...).
     * @throws ezcCacheInvalidDataException
     *         If the data submitted can not be handled by the implementation
     *         of {@link ezcCacheStorage}. Most implementations can not
     *         handle objects and resources.
     */
    abstract public function store( $id, $data, $attributes = array() );

    /**
     * Restore data from the cache.
     * Restores the data associated with the given cache and
     * returns it. Please see {@link ezcCacheStorage::store()}
     * for more detailed information of cachable datatypes.
     *
     * During access to cached data the caches are automatically
     * expired. This means, that the ezcCacheStorage object checks
     * before returning the data if it's still actual. If the cache
     * has expired, data will be deleted and false is returned.
     *
     * You should always provide the attributes you assigned, although
     * the cache storages must be able to find a cache ID even without
     * them. BEWARE: Finding cache data only by ID can be much
     * slower than finding it by ID and attributes.
     *
     * @param string $id                        The item ID.
     * @param array(string=>string) $attributes Attributes that describe the
     *                                          cached data.
     * @param bool $search                      Whether to search for items
     *                                          if not found directly. Default is
     *                                          false.
     *
     * @return mixed The cached data on success, otherwise false.
     *
     * @throws ezcBaseFilePermissionException
     *         If an already existsing cache file could not be unlinked.
     *         This exception means most likely that your cache directory
     *         has been corrupted by external influences (file permission
     *         change).
     */
    abstract public function restore( $id, $attributes = array(), $search = false );

    /**
     * Delete data from the cache.
     * Purges the cached data for a given ID and or attributes. Using an ID
     * purges only the cache data for just this ID.
     *
     * Additional attributes provided will matched additionally. This can give
     * you an immense speed improvement against just searching for ID ( see
     * {@link ezcCacheStorage::restore()} ).
     *
     * If you only provide attributes for deletion of cache data, all cache
     * data matching these attributes will be purged.
     *
     * @param string $id                        The item ID.
     * @param array(string=>string) $attributes Attributes that describe the
     *                                          cached data.
     * @param bool $search                      Whether to search for items
     *                                          if not found directly. Default is
     *                                          false.
     *
     * @throws ezcBaseFilePermissionException
     *         If an already existsing cache file could not be unlinked.
     *         This exception means most likely that your cache directory
     *         has been corrupted by external influences (file permission
     *         change).
     */
    abstract public function delete( $id = null, $attributes = array(), $search = false );

    /**
    * Return the number of items in the cache matching a certain criteria.
    * This method determines if cache data described by the given ID and/or
    * attributes exists. It returns the number of cache data items found.
    *
    * @param string $id                        The item ID.
    * @param array(string=>string) $attributes Attributes that describe the item
    * @return int The number of cache data items found matching the criteria
    */
    abstract public function countDataItems( $id = null, $attributes = array() );

    /**
     * Returns the time ( in seconds ) that remains for a cache object,
     * before it gets outdated. In case the cache object is already
     * outdated or does not exist, this method returns 0.
     *
     * @param string $id                        The item ID.
     * @param array(string=>string) $attributes Attributes that describe the
     * @access public
     * @return int The remaining lifetime ( 0 if nonexists or outdated ).
     */
    abstract public function getRemainingLifetime( $id, $attributes = array() );

    /**
     * Checks if the location property is valid.
     */
    abstract protected function validateLocation();

    /**
     * Returns the location.
     *
     * Returns the location the current storage resides in. The
     * $location attribute has no setter, since it can only be set during
     * construction.
     *
     * @return string The location of this storage.
     *
     * @apichange Use $stack->location instead.
     */
    public function getLocation()
    {
        return $this->properties['location'];
    }

    /**
     * Return the currently set options.
     *
     * Return the currently set options. The options are returned on an array
     * that has the same format as the one passed to
     * {@link ezcCacheStorage::setOptions()}. The possible options for a storage
     * depend on its implementation.
     *
     * @return ezcCacheStorageOptions The options
     *
     * @apichange Use $storage->options instead.
     */
    public function getOptions()
    {
        return $this->properties['options'];
    }

    /**
     * Set new options.
     *
     * This method allows you to change the options of a cache storage. Change
     * of options take effect directly after this method has been called. The
     * available options depend on the ezcCacheStorage implementation. All
     * implementations have to offer the following options:
     *
     * - ttl        The time-to-life. After this time span, a cache item becomes
     *              invalid and will be purged. The
     *              {@link ezcCacheStorage::restore()} method will then return
     *              false.
     * - extension  The "extension" for your cache items. This is usually the
     *              file name extension, when you deal with file system based
     *              caches or e.g. a database ID extension.
     *
     * @param ezcCacheStorageOptions $options The options to set.
     *
     * @throws ezcBasePropertyNotFoundException
     *         If you tried to set a non-existent option value. The accepted
     *         options depend on the ezcCacheStorage implementation and may
     *         vary.
     * @throws ezcBaseValueException
     *         If the value is not valid for the desired option.
     * @throws ezcBaseValueException
     *         If you submit neither an array nor an instance of
     *         ezcCacheStorageOptions.
     *
     * @apichange Use $storage->options instead.
     */
    public function setOptions( $options )
    {
        if ( is_array( $options ) )
        {
            $this->properties['options']->merge( $options );
        }
        else if ( $options instanceof ezcCacheStorageOptions )
        {
            $this->properties['options'] = $options;
        }
        else
        {
            throw new ezcBaseValueException( "options", $options, "instance of ezcCacheStorageOptions" );
        }
    }


    /**
     * Property read access.
     *
     * @throws ezcBasePropertyNotFoundException
     *         If the the desired property is not found.
     *
     * @param string $propertyName Name of the property.
     * @return mixed Value of the property or null.
     * @ignore
     */
    public function __get( $propertyName )
    {
        if ( $this->__isset( $propertyName ) )
        {
            return $this->properties[$propertyName];
        }
        throw new ezcBasePropertyNotFoundException( $propertyName );
    }

    /**
     * Property write access.
     *
     * @param string $propertyName Name of the property.
     * @param mixed $val  The value for the property.
     *
     * @throws ezcBaseValueException
     *         If the value for the property options is not an instance of
     *         ezcCacheStorageOptions.
     * @ignore
     */
    public function __set( $propertyName, $val )
    {
        switch ( $propertyName )
        {
            case 'options':
                if ( !( $val instanceof ezcCacheStorageOptions ) )
                {
                    throw new ezcBaseValueException( $propertyName, $val, 'instance of ezcCacheStorageOptions' );
                }
                break;
            case 'location':
                throw new ezcBasePropertyPermissionException(
                    $propertyName,
                    ezcBasePropertyPermissionException::READ
                );
            default:
                throw new ezcBasePropertyNotFoundException( $propertyName );
        }
        $this->properties[$propertyName] = $val;
    }

    /**
     * Property isset access.
     *
     * @param string $propertyName Name of the property.
     * @return bool True is the property is set, otherwise false.
     * @ignore
     */
    public function __isset( $propertyName )
    {
        return array_key_exists( $propertyName, $this->properties );
    }
}
?>