<?php
/**
 * A general crtieria class
 *
 * @author		Roland Haeder <webmaster@ship-simu.org>
 * @version		0.0.0
 * @copyright	Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2012 Core Developer Team
 * @license		GNU GPL 3.0 or any newer version
 * @link		http://www.ship-simu.org
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
class BaseCriteria extends BaseFrameworkSystem implements Criteria {
	/**
	 * Wrapper class name stored in config entry
	 */
	private $wrapperConfigEntry = '';

	/**
	 * Protected constructor
	 *
	 * @param	$className	Name of the class
	 * @return	void
	 */
	protected function __construct ($className) {
		// Call parent constructor
		parent::__construct($className);
	}

	/**
	 * Checks whether given key is set
	 *
	 * @param	$criteriaType	Type of this criteria, can be one of 'default' (default), 'choice' or 'exclude'
	 * @param	$criteriaKey	Criteria key
	 * @return	$isSet			Whether key is set
	 */
	public function isKeySet ($criteriaType, $criteriaKey) {
		// Make sure no 'my-' or 'my_' passes this point
		assert((strpos($criteriaKey, 'my-') === FALSE) && (strpos($criteriaKey, 'my_') === FALSE));

		// Determine it
		$isSet = $this->isGenericArrayKeySet('criteria', $criteriaType, $criteriaKey);

		// Return it
		return $isSet;
	}

	/**
	 * Checks whether given key is set for 'choice' type
	 *
	 * @param	$criteriaKey	Criteria key
	 * @return	$isSet			Whether key is set
	 */
	public function isChoiceKeySet ($criteriaKey) {
		// Call inner method
		return $this->isKeySet('choice', $criteriaKey);
	}

	/**
	 * Checks whether given key is set for 'exclude' type
	 *
	 * @param	$criteriaKey	Criteria key
	 * @return	$isSet			Whether key is set
	 */
	public function isExcludeKeySet ($criteriaKey) {
		// Call inner method
		return $this->isKeySet('exclude', $criteriaKey);
	}

	/**
	 * Setter for wrapper class name
	 *
	 * @param	$wrapperConfigEntry		Configuration entry which hold the wrapper class' name
	 * @return	void
	 */
	public final function setWrapperConfigEntry ($wrapperConfigEntry) {
		$this->wrapperConfigEntry = (string) $wrapperConfigEntry;
	}

	/**
	 * Getter for wrapper class name
	 *
	 * @return	$wrapperConfigEntry		Configuration entry which hold the wrapper class' name
	 */
	public final function getWrapperConfigEntry () {
		return $this->wrapperConfigEntry;
	}

	/**
	 * Getter for criteria array
	 *
	 * @param	$criteriaType	Type of this criteria, can be one of 'default' (default), 'choice' or 'exclude'
	 * @return	$criteria
	 */
	public final function getCriteriaArray ($criteriaType = 'default') {
		return $this->getGenericSubArray('criteria', $criteriaType);
	}

	/**
	 * Getter for criteria array 'choice' type
	 *
	 * @return	$criteria
	 */
	public final function getCriteriaChoiceArray () {
		return $this->getCriteriaArray('choice');
	}

	/**
	 * Getter for criteria array 'exclude' type
	 *
	 * @return	$criteria
	 */
	public final function getCriteriaExcludeArray () {
		return $this->getCriteriaArray('exclude');
	}

	/**
	 * Unsets a criteria key from all criteria types
	 *
	 * @param	$criteriaKey	Criteria key to unset
	 * @return	void
	 */
	public final function unsetCriteria ($criteriaKey) {
		// Make sure no 'my-' or 'my_' passes this point
		assert((strpos($criteriaKey, 'my-') === FALSE) && (strpos($criteriaKey, 'my_') === FALSE));

		// Convert dashes to underscore
		$criteriaKey = $this->convertDashesToUnderscores($criteriaKey);

		// "Walk" through all criterias
		foreach ($this->getGenericArray('criteria') as $criteriaType => $dummy) {
			// Remove it
			$this->unsetGenericArrayElement('criteria', $criteriaType, $criteriaKey);
		} // END - foreach
	}

	/**
	 * Add criteria, this method converts dashes to underscores because dashes
	 * are not valid for criteria keys.
	 *
	 * @param	$criteriaKey	Criteria key
	 * @param	$criteriaValue	Criteria value
	 * @param	$criteriaType	Type of this criteria, can be one of 'default' (default), 'choice' or 'exclude'
	 * @return	void
	 */
	public final function addCriteria ($criteriaKey, $criteriaValue, $criteriaType = 'default') {
		// Make sure no 'my-' or 'my_' passes this point
		assert((strpos($criteriaKey, 'my-') === FALSE) && (strpos($criteriaKey, 'my_') === FALSE) && (!is_bool($criteriaValue)));

		// Convert dashes to underscore
		$criteriaKey = $this->convertDashesToUnderscores($criteriaKey);

		// Debug message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(strtoupper($criteriaType) . '(' . $this->__toString() . ')-CRITERIA[' . __LINE__ . ']: criteriaKey=' . $criteriaKey . ',criteriaValue=' . $criteriaValue);

		// Append it
		$this->appendStringToGenericArrayElement('criteria', $criteriaType, $criteriaKey, $criteriaValue);
	}

	/**
	 * Add "choice" criteria, this method converts dashes to underscores because
	 * dashes are not valid for criteria keys.
	 *
	 * @param	$criteriaKey	Criteria key
	 * @param	$criteriaValue	Criteria value
	 * @return	void
	 */
	public final function addChoiceCriteria ($criteriaKey, $criteriaValue) {
		// Make sure no 'my-' or 'my_' passes this point
		assert((strpos($criteriaKey, 'my-') === FALSE) && (strpos($criteriaKey, 'my_') === FALSE) && (!is_bool($criteriaValue)));

		// Debug message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(strtoupper($criteriaType) . '(' . $this->__toString() . ')-CRITERIA[' . __LINE__ . ']: criteriaKey=' . $criteriaKey . ',criteriaValue=' . $criteriaValue);

		// Add it
		$this->pushValueToGenericArrayElement('criteria', 'choice', $this->convertDashesToUnderscores($criteriaKey), (string) $criteriaValue);
	}

	/**
	 * Add "exclude" criteria, this method converts dashes to underscores because
	 * dashes are not valid for criteria keys.
	 *
	 * @param	$criteriaKey	Criteria key
	 * @param	$criteriaValue	Criteria value
	 * @return	void
	 */
	public final function addExcludeCriteria ($criteriaKey, $criteriaValue) {
		// Add it with generic method
		$this->addCriteria($criteriaKey, $criteriaValue, 'exclude');
	}

	/**
	 * Add configured criteria
	 *
	 * @param	$criteriaKey	Criteria key
	 * @param	$configEntry	Configuration entry
	 * @param	$criteriaType	Type of this criteria, can be one of 'default' (default), 'choice' or 'exclude'
	 * @return	void
	 */
	public final function addConfiguredCriteria ($criteriaKey, $configEntry, $criteriaType = 'default') {
		// Add the configuration entry as a criteria
		$value = $this->getConfigInstance()->getConfigEntry($configEntry);
		$this->addCriteria($criteriaKey, $value, $criteriaType);
	}

	/**
	 * Get criteria element or FALSE if not found
	 *
	 * @param	$criteriaKey	The requested criteria key
	 * @param	$criteriaType	Type of this criteria, can be one of 'default' (default), 'choice' or 'exclude'
	 * @return	$value			Whether the value of the critera or FALSE
	 */
	public function getCriteriaElemnent ($criteriaKey, $criteriaType = 'default') {
		// Make sure no 'my-' or 'my_' passes this point
		assert((strpos($criteriaKey, 'my-') === FALSE) && (strpos($criteriaKey, 'my_') === FALSE));

		// Convert dashes to underscore
		$criteriaKey = $this->convertDashesToUnderscores($criteriaKey);

		// Debug message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(strtoupper($criteriaType) . '-CRITERIA[' . __LINE__ . ']: criteriaKey=' . $criteriaKey . ',criteria()=' . $this->countGenericArrayGroup('criteria', $criteriaType)));

		// Default is not found
		$value = FALSE;

		// Is the criteria there?
		if ($this->isKeySet($criteriaType, $criteriaKey)) {
			// Then use it
			$value = $this->getGenericArrayKey('criteria', $criteriaType, $criteriaKey);
		} // END - if

		// Return the value
		return $value;
	}

	/**
	 * Get criteria element or FALSE if not found for 'choice' type
	 *
	 * @param	$criteriaKey	The requested criteria key
	 * @return	$value			Whether the value of the critera or FALSE
	 */
	public function getCriteriaChoiceElemnent ($criteriaKey) {
		// Call inner method
		return $this->getCriteriaElemnent($criteriaKey, 'choice');
	}

	/**
	 * Get criteria element or FALSE if not found for 'exclude' type
	 *
	 * @param	$criteriaKey	The requested criteria key
	 * @return	$value			Whether the value of the critera or FALSE
	 */
	public function getCriteriaExcludeElemnent ($criteriaKey) {
		// Call inner method
		return $this->getCriteriaElemnent($criteriaKey, 'exclude');
	}

	/**
	 * Checks whether given array entry matches
	 *
	 * @param	$entryArray		Array with the entries to find
	 * @param	$criteriaType	Type of this criteria, can be one of 'default' (default), 'choice' or 'exclude'
	 * @return	$matches		Whether the entry matches or not
	 */
	public function ifEntryMatches (array $entryArray, $criteriaType = 'default') {
		// First nothing matches and nothing is counted
		$matches = FALSE;
		$counted = 0;

		// Walk through all entries
		foreach ($entryArray as $key => $entry) {
			// Make sure no 'my-' or 'my_' passes this point
			assert((strpos($key, 'my-') === FALSE) && (strpos($key, 'my_') === FALSE));

			// Convert dashes to underscore
			$key = $this->convertDashesToUnderscores($key);

			// Then walk through all search criteria
			foreach ($this->getGenericSubArray('criteria', $criteriaType) as $criteriaKey => $criteriaValue) {
				// Make sure no 'my-' or 'my_' passes this point
				assert((strpos($criteriaKey, 'my-') === FALSE) && (strpos($criteriaKey, 'my_') === FALSE) && (!is_bool($criteriaValue)));

				// Convert dashes to underscore
				$criteriaKey = $this->convertDashesToUnderscores($criteriaKey);

				// Is the element found and does it match?
				if (($key == $criteriaKey) && ($criteriaValue == $entry)) {
					// Then count this one up
					$counted++;
				} // END - if
			} // END - foreach
		} // END - foreach

		// Now check if expected criteria counts match
		$matches = ($counted == $this->countGenericArrayGroup('criteria', $criteriaType));

		// Return the result
		return $matches;
	}

	/**
	 * Checks whether given array 'choice' entry matches
	 *
	 * @param	$entryArray		Array with the entries to find
	 * @return	$matches		Whether the entry matches or not
	 */
	public function ifChoiceMatches (array $entryArray) {
		// Call inner method
		return $this->ifEntryMatches($entryArray, 'choice');
	}

	/**
	 * Checks whether given array 'exclude' entry matches
	 *
	 * @param	$entryArray		Array with the entries to find
	 * @return	$matches		Whether the entry matches or not
	 */
	public function ifExcludeMatches (array $entryArray) {
		// Call inner method
		return $this->ifEntryMatches($entryArray, 'exclude');
	}

	/**
	 * "Getter" for a cache key
	 *
	 * @param	$onlyKeys	Only use these keys for a cache key
	 * @param	$criteriaType	Type of this criteria, can be one of 'default' (default), 'choice' or 'exclude'
	 * @return	$cacheKey	The key suitable for the cache system
	 */
	public function getCacheKey ($onlyKeys = array(), $criteriaType = 'default') {
		// Debug message
		//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput($this->__toString() . ': criteriaType=' . $criteriaType . ',count()=' . $this->countGenericArray('criteria')));

		// Make sure the criteria is there
		assert($this->isValidGenericArrayGroup('criteria', $criteriaType));

		// Initialize the key
		$cacheKey = '';

		// Now walk through all criterias
		foreach ($this->getGenericSubArray('criteria', $criteriaType) as $criteriaKey => $criteriaValue) {
			// Make sure no 'my-' or 'my_' passes this point
			assert((strpos($criteriaKey, 'my-') === FALSE) && (strpos($criteriaKey, 'my_') === FALSE) && (!is_bool($criteriaValue)));

			// Convert dashes to underscore
			$criteriaKey = $this->convertDashesToUnderscores($criteriaKey);

			// Is the value in array or is $onlyKeys empty?
			if ((isset($onlyKeys[$criteriaKey])) || (count($onlyKeys) == 0)) {
				// Add the value URL encoded to avoid any trouble with special characters
				$cacheKey .= sprintf("%s=%s;",
					$criteriaKey,
					urlencode($criteriaValue)
				);
			} // END - if
		} // END - foreach

		// Remove last semicolon
		$cacheKey = substr($cacheKey, 0, -1);

		// Is the instance SearchCriteria?
		if ($this instanceof SearchCriteria) {
			// Check if 'limit' and 'skip' are in
			if (((isset($onlyKeys['limit'])) && (isset($onlyKeys['skip']))) || (count($onlyKeys) == 0)) {
				// Add limit and skip values
				$cacheKey .= sprintf(";%%limit%%=%s;%%skip%%=%s",
					$this->getLimit(),
					$this->getSkip()
				);
			} // END - if
		} // END - if

		// Return the cache key
		return $cacheKey;
	}

	/**
	 * "Getter" for a cache key ('choice' type)
	 *
	 * @param	$onlyKeys	Only use these keys for a cache key
	 * @return	$cacheKey	The key suitable for the cache system
	 */
	public function getCacheKeyChoice ($onlyKeys = array()) {
		// Call inner method
		return $this->getCacheKey($onlyKeys, 'choice');
	}

	/**
	 * "Getter" for a cache key ('exclude' type)
	 *
	 * @param	$onlyKeys	Only use these keys for a cache key
	 * @return	$cacheKey	The key suitable for the cache system
	 */
	public function getCacheKeyExclude ($onlyKeys = array()) {
		// Call inner method
		return $this->getCacheKey($onlyKeys, 'exclude');
	}

	/**
	 * Count the criteria, e.g. useful to find out if a database query has no
	 * limitation (search criteria).
	 *
	 * @param	$criteriaType	Type of this criteria, can be one of 'default' (default), 'choice' or 'exclude'
	 * @return	$count	Count of all criteria entries
	 */
	public final function count ($criteriaType = 'default') {
		// Return it
		return $this->countGenericArrayGroup('criteria', $criteriaType);
	}

	/**
	 * Count 'choice' criteria, e.g. useful to find out if a database query
	 * has no limitation (search criteria).
	 *
	 * @return	$count	Count of all criteria entries
	 */
	public final function countChoice () {
		return $this->count('choice');
	}

	/**
	 * Count 'exclude' criteria, e.g. useful to find out if a database query
	 * has no limitation (search criteria).
	 *
	 * @return	$count	Count of all criteria entries
	 */
	public final function countExclude () {
		return $this->count('exclude');
	}
}

// [EOF]
?>