<?php
/**
 * The mapped interface provides a consistant mechanism for mapping database
 * data into an object.
 * 
 * @author Cory Marsh
 * @license http://www.opensource.org/licenses/bsd-license.php BSD License
 */
interface Mapped
{
	/**
     * map a database row into this model, this bypasses all setters and
     * constraints.  It is intended for database mappings.
     * @return Entity $this class reference
	 * @param array $row the database row
     * <code>
	 * TODO: FIX THIS DOCUMENTATION
     * $sql = "SELECT a.col1 AS a_col1 FROM AlphaTable AS a"
     * // produces an array of the form.
     * $row = array ( array ('a_col1' => 'some value'));
     * // in this case, 'a' is the $prefix
     * $entity->mapFromArray($row, 'a');
     * </code>
	 */
    public function mapFromArray(array $row);


    /**
     * map an array of data into the model.  This method calls all of the
     * setters and validates all constraints.  Use this method for mapping
     * user submitted data.
     * @return Entity $this class reference
     * @param array $row maps a database row into the model
     * @param string $quoteStyle the PHP quote style to set for string
     *   based setters.  null disables htmlspecialchars. possible
     *   quote styes are ENT_QUOTES, ENT_NOQUOTES and ENT_COMPAT
     */
    public function setFromArray(array $row, $quoteStyle = QUOTE_STYLE);
}

/**
 * serialize an object for persietance.  To unserialize the object, pass the returned array to the Mapped
 * interface.
 */
interface Cereal
{
    /**
     * $return array an array reference suitable for passing to a mapped entity.  This should be equivelant
     * to a database row from the database
     */
    public function serialize();
}

/**
 * any class that provides object persistence must implement these methods
 */
interface Persistence
{
    /**
     * load entities by id
     * @param integer $id the id to load the entity for
     * @param boolean $loadForEdit true if we need to load constraints
     * @return ProductDetails a single instance loaded from the database,
     *  or null if it could not be loaded
     * @throws SQLExcetion if the a database error occurs
     */
    public function getByEntityId($id, $loadForEdit = false);


   /**
     * save new or updated productDetailss to the databas
     * @param ProductDetails $productDetails the object to save to
     *  the database (handles updates and inserts)
     * @throws SQLException if an error occurs saving to the database
     */
    public function save(Entity $entity);
}

/**
 * a generic interface that may be implemented to describe how a class should
 * should implement cacheing.
 */
interface Cacheable
{
    /**
     * @return string the name of the cache method 'NETWORK', 'LOCAL'
     */
    public function getCacheMethod();

    /**
     * @return integer number of seconds that the data should be cached for
     */
    public function getCacheLength();
}