merge from 1.5.3 (~r10943)

git-svn-id: http://xe-core.googlecode.com/svn/trunk@10951 201d5d3c-b55e-5fd7-737f-ddc643e51545

classes/cache/CacheHandler.class.php

@@ -1,15 +1,30 @@
 <?php
 /**
- * @class CacheHandler
+ * CacheHandler
+ *
  * @author NHN (developer@xpressengine.com)
- * @brief Cache Handler
- * @version 0.1
  **/
-
 class CacheHandler extends Handler {
+	/**
+	 * instance of cache handler
+	 * @var CacheBase
+	 */
 	var $handler = null;
+
+	/**
+	 * Version of key group
+	 * @var int
+	 */
 	var $keyGroupVersions = null;
 
+	/**
+	 * Get a instance of CacheHandler(for singleton)
+	 *
+	 * @param string $target type of cache (object|template)
+	 * @param object $info info. of DB
+	 * @param boolean $always_use_file If set true, use a file cache always
+	 * @return CacheHandler
+	 */
 	function &getInstance($target = 'object', $info = null, $always_use_file = false) {
 		$cache_handler_key = $target . ($always_use_file ? '_file' : '');
 		if(!$GLOBALS['__XE_CACHE_HANDLER__'][$cache_handler_key]) {
@@ -18,6 +33,17 @@ class CacheHandler extends Handler {
 		return $GLOBALS['__XE_CACHE_HANDLER__'][$cache_handler_key];
 	}
 
+	/**
+	 * Constructor.
+	 *
+	 * Do not use this directly. You can use getInstance() instead.
+	 *
+	 * @see CacheHandler::getInstance
+	 * @param string $target type of cache (object|template)
+	 * @param object $info info. of DB
+	 * @param boolean $always_use_file If set true, use a file cache always
+	 * @return CacheHandler
+	 */
 	function CacheHandler($target, $info = null, $always_use_file = false) {
 		if(!$info) $info = Context::getDBInfo();
 		if($info){
@@ -50,31 +76,73 @@ class CacheHandler extends Handler {
 		}
 	}
 
+	/**
+	 * Return whether support or not support cache
+	 *
+	 * @return boolean
+	 */
 	function isSupport(){
 		if($this->handler && $this->handler->isSupport()) return true;
 		return false;
 	}
 
+	/**
+	 * Get cached data
+	 *
+	 * @param string $key Cache key
+	 * @param int $modified_time 	Unix time of data modified.
+	 *								If stored time is older then modified time, return false.
+	 * @return false|mixed Return false on failure or older then modified time. Return the string associated with the $key on success.
+	 */
 	function get($key, $modified_time = 0){
 		if(!$this->handler) return false;
 		return $this->handler->get($key, $modified_time);
 	}
 
+	/**
+	 * Put data into cache
+	 *
+	 * @param string $key Cache key
+	 * @param mixed $obj	Value of a variable to store. $value supports all data types except resources, such as file handlers.
+	 * @param int $valid_time	Time for the variable to live in the cache in seconds.
+	 *							After the value specified in ttl has passed the stored variable will be deleted from the cache.
+	 *							If no ttl is supplied, use the default valid time.
+	 * @return bool|void Returns true on success or false on failure. If use CacheFile, returns void.
+	 */
 	function put($key, $obj, $valid_time = 0){
 		if(!$this->handler) return false;
 		return $this->handler->put($key, $obj, $valid_time);
 	}
 
+	/**
+	 * Delete Cache
+	 *
+	 * @param string $key Cache key
+	 * @return void
+	 */
 	function delete($key){
 		if(!$this->handler) return false;
 		return $this->handler->delete($key);
 	}
 
+	/**
+	 * Return whether cache is valid or invalid
+	 *
+	 * @param string $key Cache key
+	 * @param int $modified_time 	Unix time of data modified.
+	 *								If stored time is older then modified time, the data is invalid.
+	 * @return bool Return true on valid or false on invalid.
+	 */
 	function isValid($key, $modified_time){
 		if(!$this->handler) return false;
 		return $this->handler->isValid($key, $modified_time);
 	}
 
+	/**
+	 * Truncate all cache
+	 *
+	 * @return bool|void Returns true on success or false on failure. If use CacheFile, returns void.
+	 */
 	function truncate(){
 		if(!$this->handler) return false;
 		return $this->handler->truncate();
@@ -91,6 +159,10 @@ class CacheHandler extends Handler {
 	 *
 	 * The new key will be 2:document:123, thus forcing the document
 	 * to be reloaded from the database.
+	 *
+	 * @param string $keyGroupName Group name
+	 * @param string $key Cache key
+	 * @return string
 	 */
 	function getGroupKey($keyGroupName, $key){
 		if(!$this->keyGroupVersions[$keyGroupName]){
@@ -101,29 +173,77 @@ class CacheHandler extends Handler {
 		return $this->keyGroupVersions[$keyGroupName] . ':' . $keyGroupName . ':' . $key;
 	}
 
+	/**
+	 * Make invalid group key (like delete group key)
+	 *
+	 * @param string $keyGroupName Group name
+	 * @return void
+	 */
 	function invalidateGroupKey($keyGroupName){
 		$this->keyGroupVersions[$keyGroupName]++;
 		$this->handler->put('key_group_versions', $this->keyGroupVersions, 0);
 	}
 }
 
+/**
+ * Base class of Cache
+ *
+ * @author NHN (developer@xpressengine.com)
+ */
 class CacheBase{
+
+	/**
+	 * Get cached data
+	 *
+	 * @param string $key Cache key
+	 * @param int $modified_time 	Unix time of data modified.
+	 *								If stored time is older then modified time, return false.
+	 * @return false|mixed Return false on failure or older then modified time. Return the string associated with the $key on success.
+	 */
 	function get($key, $modified_time = 0){
 		return false;
 	}
 
+	/**
+	 * Put data into cache
+	 *
+	 * @param string $key Cache key
+	 * @param mixed $obj	Value of a variable to store. $value supports all data types except resources, such as file handlers.
+	 * @param int $valid_time	Time for the variable to live in the cache in seconds.
+	 *							After the value specified in ttl has passed the stored variable will be deleted from the cache.
+	 *							If no ttl is supplied, use the default valid time.
+	 * @return bool|void Returns true on success or false on failure. If use CacheFile, returns void.
+	 */
 	function put($key, $obj, $valid_time = 0){
 		return false;
 	}
 
+	/**
+	 * Return whether cache is valid or invalid
+	 *
+	 * @param string $key Cache key
+	 * @param int $modified_time 	Unix time of data modified.
+	 *								If stored time is older then modified time, the data is invalid.
+	 * @return bool Return true on valid or false on invalid.
+	 */
 	function isValid($key, $modified_time = 0){
 		return false;
 	}
 
+	/**
+	 * Return whether support or not support cache
+	 *
+	 * @return boolean
+	 */
 	function isSupport(){
 		return false;
 	}
 
+	/**
+	 * Truncate all cache
+	 *
+	 * @return bool|void Returns true on success or false on failure. If use CacheFile, returns void.
+	 */
 	function truncate(){
 		return false;
 	}