<?php
/* $Id$ */
namespace Mammut\DB;

(defined('MAMMUT') && (basename(__FILE__) != basename($_SERVER['PHP_SELF']))) or die('ACCESS DENIED');

/**
 * A interface which defines methods tables, views and other data objects in the database.
 *
 * @author Stefan Daurer <s.daurer@q-spot.org>
 * @package Mammut\DB
 */
interface iDatastore extends \Countable {

	/**
	 *
	 * @return string the name of the datastore object (table/view/...)
	 */
	public function getName();

	/**
	 * Inserts an object or an array
	 *
	 * @param mixed $data
	 *        	values that should be added
	 * @param array $ignore
	 *        	of the array or object which should be ignored
	 */
	public function insert($data, array $ignore = array());

	/**
	 * Inserts an object or an array if a basic dataset is not found.
	 * If the dataset exists already, it will be updated instead.
	 *
	 * @param mixed $base
	 *        	value that will be searched in the table
	 * @param mixed $insert
	 *        	values which will be merged into base before inserting
	 * @param mixed $update
	 *        	which will be used to update existing rows
	 */
	public function insertOrUpdate($base, $insert, $update);

	/**
	 * Selects data and creates an result object that can be used to fetch the rows.
	 * Prefix an order field with ! to order descenting
	 *
	 * @param array $limiter        	
	 * @param array $order
	 *        	an field name list
	 * @param array $fields
	 *        	the fields that should be returned (and their order), false for all
	 * @return Result
	 */
	public function select($limiter = false, $order = false, $fields = false);

	/**
	 * Fechtes a single row.
	 *
	 * @param string $limiter        	
	 * @param string $order        	
	 * @return array
	 */
	public function getRow($limiter = false, $order = false);

	/**
	 * Fechtes a single row.
	 *
	 * @param string $limiter        	
	 * @param string $order        	
	 * @return array
	 */
	public function getArray($limiter = false, $order = false);

	/**
	 * Fetches a single row as an object.
	 *
	 * This method returns the first row found in the database. No exception will be thrown if multiple rows exist.
	 *
	 * @param array $limiter
	 *        	limits the selection
	 * @param array $order
	 *        	order of the dataset
	 * @param string $classname
	 *        	class name of the object
	 * @param array $param
	 *        	parameters which are used in the constructor
	 * @return \stdClass the row object
	 */
	public function getObject($limiter = false, $order = false, $classname = false, array $param = array());

	/**
	 * Fetches all rows as arrays
	 *
	 * @param array $limiter
	 *        	limits the selection
	 * @param array $order
	 *        	order of the dataset
	 * @return array
	 */
	public function getRowList($limiter = false, $order = false);

	/**
	 * Fetches all rows of this table as arrays
	 *
	 * @param array $limiter
	 *        	limits the selection
	 * @param array $order
	 *        	order of the dataset
	 * @return array
	 */
	public function getArrayList($limiter = false, $order = false);

	/**
	 * Fetches all rows of this table as objects.
	 *
	 * This method returns the rows found in the database. No exception will be thrown if no rows exist, only an empty array is returned.
	 *
	 * @param array $limiter
	 *        	limits the selection
	 * @param array $order
	 *        	order of the dataset
	 * @param string $classname
	 *        	class name of the object
	 * @param array $param
	 *        	parameters which are used in the constructor
	 * @return array the row object array
	 */
	public function getObjectList($limiter = false, $order = false, $classname = false, array $param = array());

	/**
	 * Updates fields based on a array or object, and a key array
	 *
	 * @param $data mixed
	 *        	the data which should be set
	 * @param $key array
	 *        	the key which is used to get the dataset
	 * @param $exclude array
	 *        	a list of field which should be ignored in the $data param
	 * @return int the number of affected fields
	 */
	public function update($data, array $key, array $exclude = array());
	
	/**
	 * Deletes data
	 *
	 * @param array $data        	
	 */
	public function delete(array $data);

	/**
	 * Counts the numbers of rows.
	 * 
	 * @param array $condition        	
	 * @return int The number of rows
	 */
	public function size(array $condition = array());

}