<?php

/*

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 *

 * This software consists of voluntary contributions made by many individuals

 * and is licensed under the LGPL. For more information, see

 * <http://www.doctrine-project.org>.

 */

namespace Doctrine\ORM;

use Doctrine\DBAL\Types\Type,

    Doctrine\ORM\Query\QueryException;

/**

 * Base contract for ORM queries. Base class for Query and NativeQuery.

 *

 * @license http://www.opensource.org/licenses/lgpl-license.php LGPL

 * @link    www.doctrine-project.org

 * @since   2.0

 * @version $Revision$

 * @author  Benjamin Eberlei <kontakt@beberlei.de>

 * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>

 * @author  Jonathan Wage <jonwage@gmail.com>

 * @author  Roman Borschel <roman@code-factory.org>

 * @author  Konsta Vesterinen <kvesteri@cc.hut.fi>

 */

abstract class AbstractQuery

{

    /* Hydration mode constants */

    /**

     * Hydrates an object graph. This is the default behavior.

     */

    const HYDRATE_OBJECT = 1;

    /**

     * Hydrates an array graph.

     */

    const HYDRATE_ARRAY = 2;

    /**

     * Hydrates a flat, rectangular result set with scalar values.

     */

    const HYDRATE_SCALAR = 3;

    /**

     * Hydrates a single scalar value.

     */

    const HYDRATE_SINGLE_SCALAR = 4;

    /**

     * Very simple object hydrator (optimized for performance).

     */

    const HYDRATE_SIMPLEOBJECT = 5;

    /**

     * @var array The parameter map of this query.

     */

    protected $_params = array();

    /**

     * @var array The parameter type map of this query.

     */

    protected $_paramTypes = array();

    /**

     * @var ResultSetMapping The user-specified ResultSetMapping to use.

     */

    protected $_resultSetMapping;

    /**

     * @var Doctrine\ORM\EntityManager The entity manager used by this query object.

     */

    protected $_em;

    /**

     * @var array The map of query hints.

     */

    protected $_hints = array();

    /**

     * @var integer The hydration mode.

     */

    protected $_hydrationMode = self::HYDRATE_OBJECT;

    /**

     * The locally set cache driver used for caching result sets of this query.

     *

     * @var CacheDriver

     */

    protected $_resultCacheDriver;

    /**

     * Boolean flag for whether or not to cache the results of this query.

     *

     * @var boolean

     */

    protected $_useResultCache;

    /**

     * @var string The id to store the result cache entry under.

     */

    protected $_resultCacheId;

    /**

     * @var boolean Boolean value that indicates whether or not expire the result cache.

     */

    protected $_expireResultCache = false;

    /**

     * @var int Result Cache lifetime.

     */

    protected $_resultCacheTTL;

    /**

     * Initializes a new instance of a class derived from <tt>AbstractQuery</tt>.

     *

     * @param Doctrine\ORM\EntityManager $entityManager

     */

    public function __construct(EntityManager $em)

    {

        $this->_em = $em;

    }

    /**

     * Retrieves the associated EntityManager of this Query instance.

     *

     * @return Doctrine\ORM\EntityManager

     */

    public function getEntityManager()

    {

        return $this->_em;

    }

    /**

     * Frees the resources used by the query object.

     *

     * Resets Parameters, Parameter Types and Query Hints.

     *

     * @return void

     */

    public function free()

    {

        $this->_params = array();

        $this->_paramTypes = array();

        $this->_hints = array();

    }

    /**

     * Get all defined parameters.

     *

     * @return array The defined query parameters.

     */

    public function getParameters()

    {

        return $this->_params;

    }

    /**

     * Gets a query parameter.

     *

     * @param mixed $key The key (index or name) of the bound parameter.

     * @return mixed The value of the bound parameter.

     */

    public function getParameter($key)

    {

        return isset($this->_params[$key]) ? $this->_params[$key] : null;

    }

    /**

     * Gets the SQL query that corresponds to this query object.

     * The returned SQL syntax depends on the connection driver that is used

     * by this query object at the time of this method call.

     *

     * @return string SQL query

     */

    abstract public function getSQL();

    /**

     * Sets a query parameter.

     *

     * @param string|integer $key The parameter position or name.

     * @param mixed $value The parameter value.

     * @param string $type The parameter type. If specified, the given value will be run through

     *                     the type conversion of this type. This is usually not needed for

     *                     strings and numeric types.

     * @return Doctrine\ORM\AbstractQuery This query instance.

     */

    public function setParameter($key, $value, $type = null)

    {

        if ($type === null) {

            $type = Query\ParameterTypeInferer::inferType($value);

        }

        $this->_paramTypes[$key] = $type;

        $this->_params[$key] = $value;

        return $this;

    }

    /**

     * Sets a collection of query parameters.

     *

     * @param array $params

     * @param array $types

     * @return Doctrine\ORM\AbstractQuery This query instance.

     */

    public function setParameters(array $params, array $types = array())

    {

        foreach ($params as $key => $value) {

            if (isset($types[$key])) {

                $this->setParameter($key, $value, $types[$key]);

            } else {

                $this->setParameter($key, $value);

            }

        }

        return $this;

    }

    /**

     * Sets the ResultSetMapping that should be used for hydration.

     *

     * @param ResultSetMapping $rsm

     * @return Doctrine\ORM\AbstractQuery

     */

    public function setResultSetMapping(Query\ResultSetMapping $rsm)

    {

        $this->_resultSetMapping = $rsm;

        return $this;

    }

    /**

     * Defines a cache driver to be used for caching result sets.

     *

     * @param Doctrine\Common\Cache\Cache $driver Cache driver

     * @return Doctrine\ORM\AbstractQuery

     */

    public function setResultCacheDriver($resultCacheDriver = null)

    {

        if ($resultCacheDriver !== null && ! ($resultCacheDriver instanceof \Doctrine\Common\Cache\Cache)) {

            throw ORMException::invalidResultCacheDriver();

        }

        $this->_resultCacheDriver = $resultCacheDriver;

        if ($resultCacheDriver) {

            $this->_useResultCache = true;

        }

        return $this;

    }

    /**

     * Returns the cache driver used for caching result sets.

     *

     * @return Doctrine\Common\Cache\Cache Cache driver

     */

    public function getResultCacheDriver()

    {

        if ($this->_resultCacheDriver) {

            return $this->_resultCacheDriver;

        } else {

            return $this->_em->getConfiguration()->getResultCacheImpl();

        }

    }

    /**

     * Set whether or not to cache the results of this query and if so, for

     * how long and which ID to use for the cache entry.

     *

     * @param boolean $bool

     * @param integer $timeToLive

     * @param string $resultCacheId

     * @return Doctrine\ORM\AbstractQuery This query instance.

     */

    public function useResultCache($bool, $timeToLive = null, $resultCacheId = null)

    {

        $this->_useResultCache = $bool;

        if ($timeToLive) {

            $this->setResultCacheLifetime($timeToLive);

        }

        if ($resultCacheId) {

            $this->_resultCacheId = $resultCacheId;

        }

        return $this;

    }

    /**

     * Defines how long the result cache will be active before expire.

     *

     * @param integer $timeToLive How long the cache entry is valid.

     * @return Doctrine\ORM\AbstractQuery This query instance.

     */

    public function setResultCacheLifetime($timeToLive)

    {

        if ($timeToLive !== null) {

            $timeToLive = (int) $timeToLive;

        }

        $this->_resultCacheTTL = $timeToLive;

        return $this;

    }

    /**

     * Retrieves the lifetime of resultset cache.

     *

     * @return integer

     */

    public function getResultCacheLifetime()

    {

        return $this->_resultCacheTTL;

    }

    /**

     * Defines if the result cache is active or not.

     *

     * @param boolean $expire Whether or not to force resultset cache expiration.

     * @return Doctrine\ORM\AbstractQuery This query instance.

     */

    public function expireResultCache($expire = true)

    {

        $this->_expireResultCache = $expire;

        return $this;

    }

    /**

     * Retrieves if the resultset cache is active or not.

     *

     * @return boolean

     */

    public function getExpireResultCache()

    {

        return $this->_expireResultCache;

    }

    /**

     * Change the default fetch mode of an association for this query.

     *

     * $fetchMode can be one of ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY

     *

     * @param  string $class

     * @param  string $assocName

     * @param  int $fetchMode

     * @return AbstractQuery

     */

    public function setFetchMode($class, $assocName, $fetchMode)

    {

        if ($fetchMode !== Mapping\ClassMetadata::FETCH_EAGER) {

            $fetchMode = Mapping\ClassMetadata::FETCH_LAZY;

        }

        $this->_hints['fetchMode'][$class][$assocName] = $fetchMode;

        return $this;

    }

    /**

     * Defines the processing mode to be used during hydration / result set transformation.

     *

     * @param integer $hydrationMode Doctrine processing mode to be used during hydration process.

     *                               One of the Query::HYDRATE_* constants.

     * @return Doctrine\ORM\AbstractQuery This query instance.

     */

    public function setHydrationMode($hydrationMode)

    {

        $this->_hydrationMode = $hydrationMode;

        return $this;

    }

    /**

     * Gets the hydration mode currently used by the query.

     *

     * @return integer

     */

    public function getHydrationMode()

    {

        return $this->_hydrationMode;

    }

    /**

     * Gets the list of results for the query.

     *

     * Alias for execute(array(), $hydrationMode = HYDRATE_OBJECT).

     *

     * @return array

     */

    public function getResult($hydrationMode = self::HYDRATE_OBJECT)

    {

        return $this->execute(array(), $hydrationMode);

    }

    /**

     * Gets the array of results for the query.

     *

     * Alias for execute(array(), HYDRATE_ARRAY).

     *

     * @return array

     */

    public function getArrayResult()

    {

        return $this->execute(array(), self::HYDRATE_ARRAY);

    }

    /**

     * Gets the scalar results for the query.

     *

     * Alias for execute(array(), HYDRATE_SCALAR).

     *

     * @return array

     */

    public function getScalarResult()

    {

        return $this->execute(array(), self::HYDRATE_SCALAR);

    }

    /**

     * Get exactly one result or null.

     *

     * @throws NonUniqueResultException

     * @param int $hydrationMode

     * @return mixed

     */

    public function getOneOrNullResult($hydrationMode = null)

    {

        $result = $this->execute(array(), $hydrationMode);

        if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {

            return null;

        }

        if (is_array($result)) {

            if (count($result) > 1) {

                throw new NonUniqueResultException;

            }

            return array_shift($result);

        }

        return $result;

    }

    /**

     * Gets the single result of the query.

     *

     * Enforces the presence as well as the uniqueness of the result.

     *

     * If the result is not unique, a NonUniqueResultException is thrown.

     * If there is no result, a NoResultException is thrown.

     *

     * @param integer $hydrationMode

     * @return mixed

     * @throws NonUniqueResultException If the query result is not unique.

     * @throws NoResultException If the query returned no result.

     */

    public function getSingleResult($hydrationMode = null)

    {

        $result = $this->execute(array(), $hydrationMode);

        if ($this->_hydrationMode !== self::HYDRATE_SINGLE_SCALAR && ! $result) {

            throw new NoResultException;

        }