<?php

/**
 * PHPStopFlood_Container class definition
 * @package Containers
 * 
 */


/**
 * Abstract container class that is responsible for reading and writting data, 
 * PHPStopFlood stores during it's work. All custom containers should inherit from it
 * 
 *
 * @package  PHPStopFlood
 * @subpackage Containers
 * @author   Vladislav Rastrusny <hide@address.com>
 * @license  http://www.gnu.org/licenses/lgpl.html  GNU Lesser General Public License
 * @link     http://pear.php.net/package/HTTP_FloodControl
 */

abstract class PHPStopFlood_Container {

	/**
	 * Additional options for the container object
	 *
	 * @internal
	 * @var    array
	 */
	protected $_options = null;

	/**
	 * Constructor
	 * 
	 * @param  mixed  $options  Additional options for the container object. Concrete
	 * 							set of options depends on container
	 * @return void
	 */
	public function __construct(array $options) {
		$this->_setDefaults();
		$this->_parseOptions($options);
		$this->_initialize();
	}

	/**
	 * Function should set internal @see $_options array to it's default values
	 *
	 * Has to be overwritten by each container class.
	 *
	 * @internal
	 * @return void
	 */
	abstract protected function _setDefaults();

	/**
	 * Default option parsing routine. Just sets internal options array to passed values
	 *
	 * Can be overwritten by container class.
	 *
	 * @internal
	 * @param array $option	Associative options array like array('mysetting1' => 'value1');
	 * @return void
	 */
	protected function _parseOptions(array $options) {
		foreach ( $options as $option => $value ) {
			$this->_options [$option] = $value;
		}
	}

	/**
	 * Container initialization function. It is called right after constructor
	 * and options parsing.
	 *
	 * Has to be overwritten by each container class.
	 *
	 * @internal
	 * @return void
	 */
	abstract protected function _initialize();

	/**
	 * Reads data associated with a given unique ID
	 *
	 * Has to be overwritten by each container class.
	 *
	 * @internal
	 * @param  string  $uniqueId  IP address or other unique ID.
	 * @return array   	An array of data associated with a given unique ID, 
	 * 					false in case of incorrect data format or empty 
	 * 					array if no data available 
	 * @throws PHPStopFlood_Exception in case of problems
	 */
	abstract public function read($uniqueId);

	/**
	 * Writes data associated with a given unique ID to container
	 *
	 * Has to be overwritten by each container class
	 *
	 * @internal
	 * @param  string  $uniqueId  IP address or other unique ID.
	 * @param  array   $data      The data associated with a given unique ID.
	 * @return void
	 * @throws PHPStopFlood_Exception in case of problems
	 */
	abstract public function write($uniqueId, array $data);

	/**
	 * Garbage collector function
	 *
	 * This function is responsible for garbage collection (deleting old counter logs).
	 *
	 * Has to be overwritten by each container class
	 *
	 * @internal
	 * @param  int     $lifetime  Maximum lifetime of counter logs in seconds
	 * @return void
	 * @throws PHPStopFlood_Exception in case of problems
	 */
	abstract public function gc($lifetime);

}

?>