<?php
/**
 * An interface for criterias
 *
 * @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/>.
 */
interface Criteria extends FrameworkInterface {
	/**
	 * Setter for wrapper class name
	 *
	 * @param	$wrapperConfigEntry		Configuration entry which hold the wrapper class' name
	 * @return	void
	 */
	function setWrapperConfigEntry ($wrapperConfigEntry);

	/**
	 * Getter for wrapper class name
	 *
	 * @return	$wrapperConfigEntry		Configuration entry which hold the wrapper class' name
	 */
	function getWrapperConfigEntry ();

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

	/**
	 * Getter for criteria array 'choice' type
	 *
	 * @return	$criteria
	 */
	function getCriteriaChoiceArray ();

	/**
	 * Getter for criteria array 'exclude' type
	 *
	 * @return	$criteria
	 */
	function getCriteriaExcludeArray ();

	/**
	 * 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
	 */
	function addCriteria ($criteriaKey, $criteriaValue, $criteriaType = 'default');

	/**
	 * 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
	 */
	function addChoiceCriteria ($criteriaKey, $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
	 */
	function addExcludeCriteria ($criteriaKey, $criteriaValue);

	/**
	 * 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
	 */
	function addConfiguredCriteria ($criteriaKey, $configEntry, $criteriaType = 'default');

	/**
	 * Get criteria element or null 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 null
	 */
	function getCriteriaElemnent ($criteriaKey, $criteriaType = 'default');

	/**
	 * 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
	 */
	function ifEntryMatches (array $entryArray, $criteriaType = 'default');

	/**
	 * Checks whether given array 'choice' entry matches
	 *
	 * @param	$entryArray		Array with the entries to find
	 * @return	$matches		Whether the entry matches or not
	 */
	function ifChoiceMatches (array $entryArray);

	/**
	 * Checks whether given array 'exclude' entry matches
	 *
	 * @param	$entryArray		Array with the entries to find
	 * @return	$matches		Whether the entry matches or not
	 */
	function ifExcludeMatches (array $entryArray);

	/**
	 * "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
	 */
	function getCacheKey ($onlyKeys = array(), $criteriaType = 'default');

	/**
	 * "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
	 */
	function getCacheKeyChoice ($onlyKeys = array());

	/**
	 * "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
	 */
	function getCacheKeyExclude ($onlyKeys = array());

	/**
	 * "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
	 */
	function getCacheKeyChoice ($onlyKeys = array());

	/**
	 * 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
	 */
	function count ($criteriaType = 'default');

	/**
	 * 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
	 */
	function countChoice ();

	/**
	 * 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
	 */
	function countExclude ();
}

// [EOF]
?>