[Sommaire] [Imprimer]

   1  <?php
   2  /**
   3   * TCache class file.
   4   *
   5   * @author Qiang Xue <qiang.xue@gmail.com>
   6   * @link http://www.pradosoft.com/
   7   * @copyright Copyright &copy; 2005 PradoSoft
   8   * @license http://www.pradosoft.com/license/
   9   * @version $Id: TCache.php 1397 2006-09-07 07:55:53Z wei $
  10   * @package System.Caching
  11   */
  12  
  13  /**
  14   * TCache class
  15   *
  16   * TCache is the base class for cache classes with different cache storage implementation.
  17   *
  18   * TCache implements the interface {@link ICache} with the following methods,
  19   * - {@link get} : retrieve the value with a key (if any) from cache
  20   * - {@link set} : store the value with a key into cache
  21   * - {@link add} : store the value only if cache does not have this key
  22   * - {@link delete} : delete the value with the specified key from cache
  23   * - {@link flush} : delete all values from cache
  24   *
  25   * Each value is associated with an expiration time. The {@link get} operation
  26   * ensures that any expired value will not be returned. The expiration time by
  27   * the number of seconds. A expiration time 0 represents never expire.
  28   *
  29   * By definition, cache does not ensure the existence of a value
  30   * even if it never expires. Cache is not meant to be an persistent storage.
  31   *
  32   * Child classes must implement the following methods:
  33   * - {@link getValue}
  34   * - {@link setValue}
  35   * - {@link addValue}
  36   * - {@link deleteValue}
  37   * and optionally {@link flush}
  38   *
  39   * @author Qiang Xue <qiang.xue@gmail.com>
  40   * @version $Id: TCache.php 1397 2006-09-07 07:55:53Z wei $
  41   * @package System.Caching
  42   * @since 3.0
  43   */
  44  abstract class TCache extends TModule implements ICache
  45  {
  46      private $_prefix=null;
  47  
  48      /**
  49       * Initializes the cache module.
  50       * This method initializes the cache key prefix and registers the cache module
  51       * with the application.
  52       * @param TXmlElement the module configuration
  53       */
  54  	public function init($config)
  55      {
  56          if($this->_prefix===null)
  57              $this->_prefix=$this->getApplication()->getUniqueID();
  58          $this->getApplication()->setCache($this);
  59      }
  60  
  61      /**
  62       * @return string a unique prefix for the keys of cached values.
  63       * If it is not explicitly set, it will take the value of {@link TApplication::getUniqueID}.
  64       */
  65  	public function getKeyPrefix()
  66      {
  67          return $this->_prefix;
  68      }
  69  
  70      /**
  71       * @param string a unique prefix for the keys of cached values
  72       */
  73  	public function setKeyPrefix($value)
  74      {
  75          $this->_prefix=$value;
  76      }
  77  
  78      /**
  79       * @param string a key identifying a value to be cached
  80       * @return sring a key generated from the provided key which ensures the uniqueness across applications
  81       */
  82  	protected function generateUniqueKey($key)
  83      {
  84          return md5($this->_prefix.$key);
  85      }
  86  
  87      /**
  88       * Retrieves a value from cache with a specified key.
  89       * @param string a key identifying the cached value
  90       * @return mixed the value stored in cache, false if the value is not in the cache or expired.
  91       */
  92  	public function get($id)
  93      {
  94          if(($value=$this->getValue($this->generateUniqueKey($id)))!==false)
  95          {
  96              $data=unserialize($value);
  97              if(!($data[1] instanceof ICacheDependency) || !$data[1]->getHasChanged())
  98                  return $data[0];
  99          }
 100          return false;
 101      }
 102  
 103      /**
 104       * Stores a value identified by a key into cache.
 105       * If the cache already contains such a key, the existing value and
 106       * expiration time will be replaced with the new ones.
 107       *
 108       * @param string the key identifying the value to be cached
 109       * @param mixed the value to be cached
 110       * @param integer the number of seconds in which the cached value will expire. 0 means never expire.
 111       * @param ICacheDependency dependency of the cached item. If the dependency changes, the item is labelled invalid.
 112       * @return boolean true if the value is successfully stored into cache, false otherwise
 113       */
 114  	public function set($id,$value,$expire=0,$dependency=null)
 115      {
 116          $data=array($value,$dependency);
 117          $expire=($expire<=0)?0:time()+$expire;
 118          return $this->setValue($this->generateUniqueKey($id),serialize($data),$expire);
 119      }
 120  
 121      /**
 122       * Stores a value identified by a key into cache if the cache does not contain this key.
 123       * Nothing will be done if the cache already contains the key.
 124       * @param string the key identifying the value to be cached
 125       * @param mixed the value to be cached
 126       * @param integer the number of seconds in which the cached value will expire. 0 means never expire.
 127       * @param ICacheDependency dependency of the cached item. If the dependency changes, the item is labelled invalid.
 128       * @return boolean true if the value is successfully stored into cache, false otherwise
 129       */
 130  	public function add($id,$value,$expire=0,$dependency=null)
 131      {
 132          $data=array($value,$dependency);
 133          $expire=($expire<=0)?0:time()+$expire;
 134          return $this->addValue($this->generateUniqueKey($id),serialize($data),$expire);
 135      }
 136  
 137      /**
 138       * Deletes a value with the specified key from cache
 139       * @param string the key of the value to be deleted
 140       * @return boolean if no error happens during deletion
 141       */
 142  	public function delete($id)
 143      {
 144          return $this->deleteValue($this->generateUniqueKey($id));
 145      }
 146  
 147      /**
 148       * Deletes all values from cache.
 149       * Be careful of performing this operation if the cache is shared by multiple applications.
 150       * Child classes may implement this method to realize the flush operation.
 151       * @throws TNotSupportedException if this method is not overriden by child classes
 152       */
 153  	public function flush()
 154      {
 155          throw new TNotSupportedException('cache_flush_unsupported');
 156      }
 157  
 158      /**
 159       * Retrieves a value from cache with a specified key.
 160       * This method should be implemented by child classes to store the data
 161       * in specific cache storage. The uniqueness and dependency are handled
 162       * in {@link get()} already. So only the implementation of data retrieval
 163       * is needed.
 164       * @param string a unique key identifying the cached value
 165       * @return string the value stored in cache, false if the value is not in the cache or expired.
 166       */
 167      abstract protected function getValue($key);
 168  
 169      /**
 170       * Stores a value identified by a key in cache.
 171       * This method should be implemented by child classes to store the data
 172       * in specific cache storage. The uniqueness and dependency are handled
 173       * in {@link set()} already. So only the implementation of data storage
 174       * is needed.
 175       *
 176       * @param string the key identifying the value to be cached
 177       * @param string the value to be cached
 178       * @param integer the number of seconds in which the cached value will expire. 0 means never expire.
 179       * @return boolean true if the value is successfully stored into cache, false otherwise
 180       */
 181      abstract protected function setValue($key,$value,$expire);
 182  
 183      /**
 184       * Stores a value identified by a key into cache if the cache does not contain this key.
 185       * This method should be implemented by child classes to store the data
 186       * in specific cache storage. The uniqueness and dependency are handled
 187       * in {@link add()} already. So only the implementation of data storage
 188       * is needed.
 189       *
 190       * @param string the key identifying the value to be cached
 191       * @param string the value to be cached
 192       * @param integer the number of seconds in which the cached value will expire. 0 means never expire.
 193       * @return boolean true if the value is successfully stored into cache, false otherwise
 194       */
 195      abstract protected function addValue($key,$value,$expire);
 196  
 197      /**
 198       * Deletes a value with the specified key from cache
 199       * This method should be implemented by child classes to delete the data from actual cache storage.
 200       * @param string the key of the value to be deleted
 201       * @return boolean if no error happens during deletion
 202       */
 203      abstract protected function deleteValue($key);
 204  }
 205  
 206  ?>