<?php

/**
 * This interface centralize use of database.
 * 
 * This interface defines the methods that Orm needs from the database layer.
 * You can do your own implementation using any other classes, abstraction 
 * layer, PDO, or direct database funciontions.
 * 
 * Methods here could be grouped in several categories, to ease understanding:
 * <dl>
 * <dt>Basic methods</dt>
 * <dd>This methods include constructor, basic getters and setters, and a 
 * special method to map standard fetch modes to the ones from specific 
 * implementations. 
 * <em>__construct</em>, <em>getConn</em>,  <em>setConn</em>, <em>getDsn</em>, 
 * <em>setDsn</em>, and <em>mapFetchmode</em>.</dd>
 * <dt>Connection handling</dt>
 * <dd>This methods handles database connection and disconnection. Note that 
 * you have an special code for errors: OrmException::CODE_DB_CONNECTION_ERROR.
 * <em>connect</em>, and <em>disconnect</em></dd>
 * <dt>Query methods</dt>
 * <dd>This methods should give you two options at same time: handle all querys 
 * in one place with <em>runQuery</em>, or handle them separately, with 
 * <em>select</em>, <em>insert</em>, <em>delete</em>, and <em>update</em>.</dd>
 * <dt>Transaction management</dt>
 * <dd>This methods gives you the option to handle database transactions, and 
 * follows it's state: <em>beginTransaction</em>, <em>commit</em>, 
 * <em>rollback</em>, and <em>getTransactionBlock</em>.</dd>
 * <dt>Traverse method</em>
 * <dd>The <em>traverse</em> method iterates over resultsets, calling a 
 * callback method for each row, so outside code doesn't need to handle 
 * database resultsets at all.</dd>
 * <dt>PK generation</dt>
 * <dd>This methods gives you the hability to handle PK generation at two 
 * different moments: before insert, with <em>getCalculatedPK</em>, or after, 
 * with <em>getCreatedPK</em>.</dd>
 * <dt>Query object creation</dt>
 * <dd>Methods <em>createSqlDelete</em>, <em>createSqlInsert</em>, 
 * <em>createSqlSelect</em>, and <em>createSqlUpdate</em>, gives you an easy 
 * point to handle customization of this objects, and the ability to change 
 * the implementation.</dd>
 * <em></em>,
 * </dl>
 * You should see @docs for a full understanding of this layer, as it's really 
 * important to the whole process.
 * Class OrmBaseDb provides a parcial implementation of this interface, making 
 * easier to do your own.
 * 
 * @see     OrmBaseDb
 * @author  $Author: pruna $
 * @package orm
 * @version $Revision: 1.3 $
 * @created 19-Apr-2006
 * @modified $Date: 2005/12/06 02:56:45 $
 */
interface OrmIDb {
    
    /**
     * @const
     */
    const FETCHMODE_MAP = 1;
    
    /**
     * @const
     */
    const FETCHMODE_LIST = 2;
    
    /**
     * @const
     */
    const FETCHMODE_OBJ = 3;
    
    /**
     * Constructor. If receives a new DSN, it creates a database connection.
     *
     * @access  public
     * @param   string   $dsn        DSN info for database connection
     */
    public function __construct($dsn = null);
    
    /**
     * Starts a database transaction, and returns a transaction identifier.
     * 
     * @access  public
     * @return  mixed
     */
    public function beginTransaction();
    
    /**
     * Connects to database.
     * 
     * It creates a new database connection. It uses <em>dsn</em> if provided,
     * else call <em>getDsn</em>. If fail, throw an <em>OrmException</em>.
     * It's expected that you can also create a connection (getting this method 
     * called) by invoking <em>setDsn</em> with a not null parameter.
     * 
     * @access  public
     * @param   string   $dsn        DSN info for database connection
     * @throws  OrmException
     */
    public function connect($dsn = null);
    
    /**
     * Commits a database transaction.
     * 
     * @access  public
     * @param   mixed     $blockId     Transaction block identifier
     * @return  void
     */
    public function commit($blockId = null);
    
    /**
     * Creates a SQL 'delete' object.
     * 
     * @access public
     * @return OrmSqlDelete
     */
    public function createSqlDelete();
    
    /**
     * Creates a SQL 'insert' object.
     * 
     * @access public
     * @return OrmSqlInsert
     */
    public function createSqlInsert();
    
    /**
     * Creates a SQL 'select' object.
     * 
     * @access public
     * @return OrmSqlSelect
     */
    public function createSqlSelect();
    
    /**
     * Creates a SQL 'update' object.
     * 
     * @access public
     * @return OrmSqlUpdate
     */
    public function createSqlUpdate();
    
    /**
     * SQL delete method.
     * 
     * This method is provided as a stub to filter 'delete' calls to 
     * <em>runQuery</em> method.
     * 
     * @access  public
     * @param   mixed       $sql      OrmSql or sql's string
     * @param   array       $vars     Variables to use in query
     * @return  resultset
     */
    public function delete($sql, $vars = null);
    
    /**
     * Close the database connection, if it still open.
     * 
     * This method try to close database connection silently. Usually, PHP 
     * handles all resources disposition, so it's preferred not to fire any 
     * error if this method fails.
     * 
     * @access  public
     * @return  void
     */
    public function disconnect();
    
    /**
     * This method calculates a primary key before insert is intended. This 
     * method is useful when you need to get the id from another table, from 
     * a sequence, or any other source.
     * If you don't want to generate the PK here, just return null.
     * You can see @docs for a complete explanation about PK creation.
     * 
     * @access  public
     * @param   Bean          $bean   Bean that is being inserted in DB
     * @param   OrmCore       $dao    OrmCore that is performing the operation
     * @see     getCreatedPK
     * @return  mixed
     */
    public function getCalculatedPK($bean, $dao);
    
    /**
     * Returns the connection handler.
     * 
     * This connection could be a resource, an object, or any other thing, 
     * depending on your implementation. However, an object is the preferred 
     * solution.
     * 
     * @access  public
     * @return  mixed
     */
    public function getConn();
    
    /**
     * This method looks for the primary key created automatically by the DB
     * after insert is performed. This is useful when you need to get the id 
     * created by a trigger, auto increment column, or any other source.
     * If you don't want to look for the created PK here, just return null.
     * You can see @docs for a complete explanation about PK creation.
     * 
     * @access  public
     * @param   Bean          $bean   Bean that is being inserted in DB
     * @param   OrmCore       $dao    OrmCore that is performing the operation
     * @see     getCalculatedPK
     * @return  mixed
     */
    public function getCreatedPK($bean, $dao);
    
    /**
     * Returns stored <em>Dsn</em> string.
     *
     * @access  public
     * @return  string
     */
    public function getDsn();
    
    /**
     * Returns the identifier for the transaction that is currently active.
     * A null value means no transaction in progress.
     *
     * @access  public
     * @return  mixed
     */
    public function getTransactionBlock();
    
    /**
     * SQL insert method.
     * 
     * This method is provided as a stub to filter 'insert' calls to 
     * <em>runQuery</em> method.
     * 
     * @access  public
     * @param   mixed       $sql      OrmSql or sql's string
     * @param   array       $vars     Variables to use in query
     * @return  resultset
     */
    public function insert($sql, $vars = null);
    
    /**
     * This method maps fetch mode from standard ones defined in 
     * <em>OrmIDb</em> to the ones from the specific implementation.
     * 
     * @access  public
     * @param   int       $ormFetchmode      Orm's standard fetch mode
     * @return  mixed
     */
    public function mapFetchmode($ormFetchmode);
    
    /**
     * Rollbacks a database transaction.
     * 
     * @access  public
     * @param   mixed     $blockId     Transaction block identifier
     * @return  void
     */
    public function rollback($blockId = null);
    
    /**
     * Main SQL execution method.
     * 
     * @access  public
     * @param   mixed       $sql      OrmSql or sql's string
     * @param   array       $vars     Variables to use in query
     * @return  resultset
     */
    public function runQuery($sql, $vars = null);
    
    /**
     * SQL select method.
     * 
     * This method is provided as a stub to filter 'select' calls to 
     * <em>runQuery</em> method.
     * 
     * @access  public
     * @param   mixed       $sql      OrmSql or sql's string
     * @param   array       $vars     Variables to use in query
     * @return  resultset
     */
    public function select($sql, $vars = null);
    
    /**
     * Connection setter.
     * 
     * @access  public
     * @param   mixed     $conn       Connection
     * @see     getConn
     */
    public function setConn($conn);
    
    /**
     * DSN setter. 
     * <strong>Important:</strong> If receives a not null DSN, it should  
     * create a new database connection. If receives a null DSN, it should 
     * try to close connection if enabled.
     *
     * @access  public
     * @param   string   $dsn        DSN info for database connection
     */
    public function setDsn($dsn);
    
    /**
     * Special method to traverse results.
     * 
     * This method aims to avoid that your code needs to iterate over the 
     * resultset. So this method does the iteration, calling the 
     * <em>callback</em> method for each row, passing the row data as 
     * specified by <em>mode</em> parameter, and with optional <em>params</em>.
     * 
     * @access  public
     * @param   $object    Object to call
     * @param   $callback  Method to call in object
     * @param   $rs        Resultset to iterate
     * @param   $params    Optional params to pass to callback with row data
     * @param   $mode      Mode for data in row passed to callback method
     */
    public function traverse($object, $callback, $rs = null, $params = null, 
            $mode = self::FETCHMODE_MAP);
    
    /**
     * SQL update method.
     * 
     * This method is provided as a stub to filter 'update' calls to 
     * <em>runQuery</em> method.
     * 
     * @access  public
     * @param   mixed       $sql      OrmSql or sql's string
     * @param   array       $vars     Variables to use in query
     * @return  resultset
     */
    public function update($sql, $vars = null);
    
}

?>