/**
 * Cache()
 *
 * Used to instantiate new objects used to cache client-side
 * information in the project database.
 *
 * @author   Sean McCann
 * @version  1.1.1
 * @date     2005.08.08
 *
 * Changelog
 * - 2005.08.08:  Removed references to non-existant options. (Sean McCann)
 * - 2005.07.28:  Added support for instance-specific options.  'allow_overwrite' is the only available option at this time (Sean McCann)
 * - 2005.05.20:  Official release.  Added some documentation.  Removed debugging info.  (McCann)
 * - 2005.05.03:  Uncommented debugging info (McCann)
 * - 2005.04.28:  Added __CLASS__ constant (McCann)
 * - 2005.04.22:  Initial release.  saveData() and retrieveData() methods are supported (McCann)
 */

/**
 * Creates a new cache
 */
function Cache()
{
	/**
	 * Storage structure for each piece of cached data
	 * @access private
	 */
	this.cache_obj = new Object();

	/**
	 * Any optional settings for the cache itself
	 * @access private
	 */
	this.options = new Object();

	// Set default values for our object
	this.options['allow_overwrite'] = false;
}
Cache.prototype.__CLASS__ = 'Cache';
Cache.prototype.saveData = CacheSaveData;
Cache.prototype.retrieveData = CacheRetrieveData;
Cache.prototype.getOption = CacheGetOption;
Cache.prototype.setOption = CacheSetOption;


/**
 * Saves a piece of data in the cache
 *
 * saveData() is used to store new data in the cache so that it may be retrieved for future use.  For each piece of data, a unique look-up key must be provided.  This key may then passed to retrieveData() to obtain the desired piece of data from the Cache.
 *
 * @param string key    the unique key associated with a particular piece of cached data
 * @param mixed data    the data being saved for later use
 * @return bool
 */
function CacheSaveData( key, data )
{
	if (this.options['allow_overwrite'] || typeof this.cache_obj[key] == 'undefined')
	{
		this.cache_obj[key] = data;

		return true;
	}
	else return false;
}


/**
 * Retrieves previously cached data for a given key
 *
 * @param string key    the key associated with a particular piece of cached data
 * @return mixed  Returns the cached data for a given key, or false if no data was cached for that key
 */
function CacheRetrieveData( key )
{
	if (typeof this.cache_obj[key]  != 'undefined')
	{
		return this.cache_obj[key];
	}
	else
	{
		return false;
	}
}

/**
 * Gets the value of a Cache configuration option
 * Throws an exception if a non-existant option is given
 * @param string option_name   the option that we want to know about
 * @return mixed
 */
function CacheGetOption( option_name )
{
	try
	{
		if (typeof this.options[option_name] == 'undefined')
		{
			throw new Error("This Cache does not have the '" + option_name + "' option ");
		}

		return this.options[option_name];
	}
	catch(e)
	{
		error_message(e, "Cache.js", 'Cache::getOption');
		return false;
	}
}

/**
 * Sets the value of a Cache configuration option
 *
 * @param string option_name   the option that we want to change
 * @param mixed  value         the new value for our option
 */
function CacheSetOption( option_name, value )
{
	try
	{
		if (typeof this.options[option_name] == 'undefined')
		{
			throw new Error("This Cache does not have the '" + option_name + "' option ");
		}

		this.options[option_name] = value;
		return true;
	}
	catch(e)
	{
		error_message(e, "Cache.js", 'Cache::setOption');
		return false;
	}
}