diff options
Diffstat (limited to 'framework/Caching/TCache.php')
| -rw-r--r-- | framework/Caching/TCache.php | 200 |
1 files changed, 159 insertions, 41 deletions
diff --git a/framework/Caching/TCache.php b/framework/Caching/TCache.php index d246b9d0..859180c9 100644 --- a/framework/Caching/TCache.php +++ b/framework/Caching/TCache.php @@ -1,22 +1,105 @@ <?php
+/**
+ * TCache class file.
+ *
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @link http://www.pradosoft.com/
+ * @copyright Copyright © 2005 PradoSoft
+ * @license http://www.pradosoft.com/license/
+ * @version $Revision: $ $Date: $
+ * @package System.Web
+ */
/**
- * ICache interface.
+ * TCache class
+ *
+ * TCache is the base class for cache classes with different cache storage implementation.
+ *
+ * TCache implements the interface {@link ICache} with the following methods,
+ * - {@link get} : retrieve the value with a key (if any) from cache
+ * - {@link set} : store the value with a key into cache
+ * - {@link add} : store the value only if cache does not have this key
+ * - {@link delete} : delete the value with the specified key from cache
+ * - {@link flush} : delete all values from cache
+ *
+ * Each value is associated with an expiration time. The {@link get} operation
+ * ensures that any expired value will not be returned. The expiration time by
+ * the number of seconds. A expiration time 0 represents never expire.
*
- * This interface must be implemented by cache managers.
+ * By definition, cache does not ensure the existence of a value
+ * even if it never expires. Cache is not meant to be an persistent storage.
+ *
+ * Child classes must implement the following methods:
+ * - {@link getValue}
+ * - {@link setValue}
+ * - {@link addValue}
+ * - {@link deleteValue}
+ * and optionally {@link flush}
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @version $Revision: $ $Date: $
* @package System.Caching
* @since 3.0
*/
-interface ICache
+abstract class TCache extends TModule implements ICache
{
+ private $_prefix=null;
+
+ /**
+ * Initializes the cache module.
+ * This method initializes the cache key prefix and registers the cache module
+ * with the application.
+ * @param TXmlElement the module configuration
+ */
+ public function init($config)
+ {
+ if($this->_prefix===null)
+ $this->_prefix=$this->getApplication()->getUniqueID();
+ $this->getApplication()->setCache($this);
+ }
+
+ /**
+ * @return string a unique prefix for the keys of cached values.
+ * If it is not explicitly set, it will take the value of {@link TApplication::getUniqueID}.
+ */
+ public function getPrefix()
+ {
+ return $this->_prefix;
+ }
+
+ /**
+ * @param string a unique prefix for the keys of cached values
+ */
+ public function setPrefix($value)
+ {
+ $this->_prefix=$value;
+ }
+
+ /**
+ * @param string a key identifying a value to be cached
+ * @return sring a key generated from the provided key which ensures the uniqueness across applications
+ */
+ protected function generateUniqueKey($key)
+ {
+ return md5($this->_prefix.$key);
+ }
+
/**
* Retrieves a value from cache with a specified key.
+ * @param string a key identifying the cached value
* @return mixed the value stored in cache, false if the value is not in the cache or expired.
*/
- public function get($id);
+ public function get($id)
+ {
+ if(($value=$this->getValue($this->generateUniqueKey($id)))!==false)
+ {
+ $data=unserialize($value);
+ if(!($data[1] instanceof ICacheDependency) || !$data[1]->getHasChanged())
+ return $data[0];
+ }
+ return false;
+ }
+
/**
* Stores a value identified by a key into cache.
* If the cache already contains such a key, the existing value and
@@ -24,65 +107,100 @@ interface ICache *
* @param string the key identifying the value to be cached
* @param mixed the value to be cached
- * @param integer the expiration time of the value,
- * 0 means never expire,
- * a number less or equal than 60*60*24*30 means the number of seconds that the value will remain valid.
- * a number greater than 60*60*24*30 means a UNIX timestamp after which the value will expire.
+ * @param integer the number of seconds in which the cached value will expire. 0 means never expire.
+ * @param ICacheDependency dependency of the cached item. If the dependency changes, the item is labelled invalid.
* @return boolean true if the value is successfully stored into cache, false otherwise
*/
- public function set($id,$value,$expire=0);
+ public function set($id,$value,$expire=0,$dependency=null)
+ {
+ $data=array($value,$dependency);
+ $expire=($expire<=0)?0:time()+$expire;
+ return $this->setValue($this->generateUniqueKey($id),serialize($data),$expire);
+ }
+
/**
* Stores a value identified by a key into cache if the cache does not contain this key.
* Nothing will be done if the cache already contains the key.
* @param string the key identifying the value to be cached
* @param mixed the value to be cached
- * @param integer the expiration time of the value,
- * 0 means never expire,
- * a number less or equal than 60*60*24*30 means the number of seconds that the value will remain valid.
- * a number greater than 60*60*24*30 means a UNIX timestamp after which the value will expire.
+ * @param integer the number of seconds in which the cached value will expire. 0 means never expire.
+ * @param ICacheDependency dependency of the cached item. If the dependency changes, the item is labelled invalid.
* @return boolean true if the value is successfully stored into cache, false otherwise
*/
- public function add($id,$value,$expire=0);
- /**
- * Stores a value identified by a key into cache only if the cache contains this key.
- * The existing value and expiration time will be overwritten with the new ones.
- * @param string the key identifying the value to be cached
- * @param mixed the value to be cached
- * @param integer the expiration time of the value,
- * 0 means never expire,
- * a number less or equal than 60*60*24*30 means the number of seconds that the value will remain valid.
- * a number greater than 60*60*24*30 means a UNIX timestamp after which the value will expire.
- * @return boolean true if the value is successfully stored into cache, false otherwise
- */
- public function replace($id,$value,$expire=0);
+ public function add($id,$value,$expire=0,$dependency=null)
+ {
+ $data=array($value,$dependency);
+ $expire=($expire<=0)?0:time()+$expire;
+ return $this->addValue($this->generateUniqueKey($id),serialize($data),$expire);
+ }
+
/**
* Deletes a value with the specified key from cache
* @param string the key of the value to be deleted
* @return boolean if no error happens during deletion
*/
- public function delete($id);
+ public function delete($id)
+ {
+ return $this->deleteValue($this->generateUniqueKey($id));
+ }
+
/**
* Deletes all values from cache.
* Be careful of performing this operation if the cache is shared by multiple applications.
+ * Child classes may implement this method to realize the flush operation.
+ * @throws TNotSupportedException if this method is not overriden by child classes
*/
- public function flush();
-}
-
-interface IDependency
-{
+ public function flush()
+ {
+ throw new TNotSupportedException('cache_flush_unsupported');
+ }
-}
+ /**
+ * Retrieves a value from cache with a specified key.
+ * This method should be implemented by child classes to store the data
+ * in specific cache storage. The uniqueness and dependency are handled
+ * in {@link get()} already. So only the implementation of data retrieval
+ * is needed.
+ * @param string a unique key identifying the cached value
+ * @return string the value stored in cache, false if the value is not in the cache or expired.
+ */
+ abstract protected function getValue($key);
-class TTimeDependency
-{
-}
+ /**
+ * Stores a value identified by a key in cache.
+ * This method should be implemented by child classes to store the data
+ * in specific cache storage. The uniqueness and dependency are handled
+ * in {@link set()} already. So only the implementation of data storage
+ * is needed.
+ *
+ * @param string the key identifying the value to be cached
+ * @param string the value to be cached
+ * @param integer the number of seconds in which the cached value will expire. 0 means never expire.
+ * @return boolean true if the value is successfully stored into cache, false otherwise
+ */
+ abstract protected function setValue($key,$value,$expire);
-class TFileDependency
-{
-}
+ /**
+ * Stores a value identified by a key into cache if the cache does not contain this key.
+ * This method should be implemented by child classes to store the data
+ * in specific cache storage. The uniqueness and dependency are handled
+ * in {@link add()} already. So only the implementation of data storage
+ * is needed.
+ *
+ * @param string the key identifying the value to be cached
+ * @param string the value to be cached
+ * @param integer the number of seconds in which the cached value will expire. 0 means never expire.
+ * @return boolean true if the value is successfully stored into cache, false otherwise
+ */
+ abstract protected function addValue($key,$value,$expire);
-class TDirectoryDependency
-{
+ /**
+ * Deletes a value with the specified key from cache
+ * This method should be implemented by child classes to delete the data from actual cache storage.
+ * @param string the key of the value to be deleted
+ * @return boolean if no error happens during deletion
+ */
+ abstract protected function deleteValue($key);
}
?>
\ No newline at end of file |