WebSVN – lars-tiefland.prado – /framework/Data/DataGateway/TDataGatewayCommand.php

<?php
/**
 * TDataGatewayCommand, TDataGatewayEventParameter and TDataGatewayResultEventParameter class file.
 *
 * @author Wei Zhuo <weizhuo[at]gmail[dot]com>
 * @link http://www.pradosoft.com/
 * @copyright Copyright &copy; 2005-2008 PradoSoft
 * @license http://www.pradosoft.com/license/
 * @version $Id$
 * @package System.Data.DataGateway
 */

/**
 * TDataGatewayCommand is command builder and executor class for
 * TTableGateway and TActiveRecordGateway.
 *
 * TDataGatewayCommand builds the TDbCommand for TTableGateway
 * and TActiveRecordGateway commands such as find(), update(), insert(), etc,
 * using the TDbCommandBuilder classes (database specific TDbCommandBuilder
 * classes are used).
 *
 * Once the command is built and the query parameters are binded, the
 * {@link OnCreateCommand} event is raised. Event handlers for the OnCreateCommand
 * event should not alter the Command property nor the Criteria property of the
 * TDataGatewayEventParameter.
 *
 * TDataGatewayCommand excutes the TDbCommands and returns the result obtained from the
 * database (returned value depends on the method executed). The
 * {@link OnExecuteCommand} event is raised after the command is executed and resulting
 * data is set in the TDataGatewayResultEventParameter object's Result property.
 *
 * @author Wei Zhuo <weizho[at]gmail[dot]com>
 * @version $Id$
 * @package System.Data.DataGateway
 * @since 3.1
 */
class TDataGatewayCommand extends TComponent
{
        private $_builder;

        /**
         * @param TDbCommandBuilder database specific database command builder.
         */
        public function __construct($builder)
        {
                $this->_builder = $builder;
        }

        /**
         * @return TDbTableInfo
         */
        public function getTableInfo()
        {
                return $this->_builder->getTableInfo();
        }

        /**
         * @return TDbConnection
         */
        public function getDbConnection()
        {
                return $this->_builder->getDbConnection();
        }

        /**
         * @return TDbCommandBuilder
         */
        public function getBuilder()
        {
                return $this->_builder;
        }

        /**
         * Executes a delete command.
         * @param TSqlCriteria delete conditions and parameters.
         * @return integer number of records affected.
         */
        public function delete($criteria)
        {
                $where = $criteria->getCondition();
                $parameters = $criteria->getParameters()->toArray();
                $command = $this->getBuilder()->createDeleteCommand($where, $parameters);
                $this->onCreateCommand($command,$criteria);
                $command->prepare();
                return $command->execute();
        }

        /**
         * Updates the table with new data.
         * @param array date for update.
         * @param TSqlCriteria update conditions and parameters.
         * @return integer number of records affected.
         */
        public function update($data, $criteria)
        {
                $where = $criteria->getCondition();
                $parameters = $criteria->getParameters()->toArray();
                $command = $this->getBuilder()->createUpdateCommand($data,$where, $parameters);
                $this->onCreateCommand($command,$criteria);
                $command->prepare();
                return $this->onExecuteCommand($command, $command->execute());
        }

        /**
         * @param array update for update
         * @param array primary key-value name pairs.
         * @return integer number of records affected.
         */
        public function updateByPk($data, $keys)
        {
                list($where, $parameters) = $this->getPrimaryKeyCondition((array)$keys);
                return $this->update($data, new TSqlCriteria($where, $parameters));
        }

        /**
         * Find one record matching the critera.
         * @param TSqlCriteria find conditions and parameters.
         * @return array matching record.
         */
        public function find($criteria)
        {
                $command = $this->getFindCommand($criteria);
                return $this->onExecuteCommand($command, $command->queryRow());
        }

        /**
         * Find one or more matching records.
         * @param TSqlCriteria $criteria
         * @return TDbDataReader record reader.
         */
        public function findAll($criteria)
        {
                $command = $this->getFindCommand($criteria);
                return $this->onExecuteCommand($command, $command->query());
        }

        /**
         * Build the find command from the criteria. Limit, Offset and Ordering are applied if applicable.
         * @param TSqlCriteria $criteria
         * @return TDbCommand.
         */
        protected function getFindCommand($criteria)
        {
                if($criteria===null)
                        return $this->getBuilder()->createFindCommand();
                $where = $criteria->getCondition();
                $parameters = $criteria->getParameters()->toArray();
                $ordering = $criteria->getOrdersBy();
                $limit = $criteria->getLimit();
                $offset = $criteria->getOffset();
                $command = $this->getBuilder()->createFindCommand($where,$parameters,$ordering,$limit,$offset);
                $this->onCreateCommand($command, $criteria);
                return $command;
        }

        /**
         * @param mixed primary key value, or composite key values as array.
         * @return array matching record.
         */
        public function findByPk($keys)
        {
                list($where, $parameters) = $this->getPrimaryKeyCondition((array)$keys);
                $command = $this->getBuilder()->createFindCommand($where, $parameters);
                $this->onCreateCommand($command, new TSqlCriteria($where,$parameters));
                return $this->onExecuteCommand($command, $command->queryRow());
        }

        /**
         * @param array multiple primary key values or composite value arrays
         * @return TDbDataReader record reader.
         */
        public function findAllByPk($keys)
        {
                $where = $this->getCompositeKeyCondition((array)$keys);
                $command = $this->getBuilder()->createFindCommand($where);
                $this->onCreateCommand($command, new TSqlCriteria($where,$keys));
                return $this->onExecuteCommand($command,$command->query());
        }

        public function findAllByIndex($criteria,$fields,$values)
        {
                $index = $this->getIndexKeyCondition($this->getTableInfo(),$fields,$values);
                if(strlen($where = $criteria->getCondition())>0)
                        $criteria->setCondition("({$index}) AND ({$where})");
                else
                        $criteria->setCondition($index);
                $command = $this->getFindCommand($criteria);
                $this->onCreateCommand($command, $criteria);
                return $this->onExecuteCommand($command,$command->query());
        }

        /**
         * @param array multiple primary key values or composite value arrays
         * @return integer number of rows affected.
         */
        public function deleteByPk($keys)
        {
                $where = $this->getCompositeKeyCondition((array)$keys);
                $command = $this->getBuilder()->createDeleteCommand($where);
                $this->onCreateCommand($command, new TSqlCriteria($where,$keys));
                $command->prepare();
                return $this->onExecuteCommand($command,$command->execute());
        }

        public function getIndexKeyCondition($table,$fields,$values)
        {
                if (!count($values))
                        return 'FALSE';
                $columns = array();
                $tableName = $table->getTableFullName();
                foreach($fields as $field)
                        $columns[] = $tableName.'.'.$table->getColumn($field)->getColumnName();
                return '('.implode(', ',$columns).') IN '.$this->quoteTuple($values);
        }

        /**
         * Construct a "pk IN ('key1', 'key2', ...)" criteria.
         * @param array values for IN predicate
         * @param string SQL string for primary keys IN a list.
         */
        protected function getCompositeKeyCondition($values)
        {
                $primary = $this->getTableInfo()->getPrimaryKeys();
                $count = count($primary);
                if($count===0)
                {
                        throw new TDbException('dbtablegateway_no_primary_key_found',
                                $this->getTableInfo()->getTableFullName());
                }
                if(!is_array($values) || count($values) === 0)
                {
                        throw new TDbException('dbtablegateway_missing_pk_values',
                                $this->getTableInfo()->getTableFullName());
                }
                if($count>1 && !is_array($values[0]))
                        $values = array($values);
                if($count > 1 && count($values[0]) !== $count)
                {
                        throw new TDbException('dbtablegateway_pk_value_count_mismatch',
                                $this->getTableInfo()->getTableFullName());
                }
                return $this->getIndexKeyCondition($this->getTableInfo(),$primary, $values);
        }

        /**
         * @param TDbConnection database connection.
         * @param array values
         * @return string quoted recursive tuple values, e.g. "('val1', 'val2')".
         */
        protected function quoteTuple($array)
        {
                $conn = $this->getDbConnection();
                $data = array();
                foreach($array as $k=>$v)
                        $data[] = is_array($v) ? $this->quoteTuple($v) : $conn->quoteString($v);
                return '('.implode(', ', $data).')';
        }

        /**
         * Create the condition and parameters for find by primary.
         * @param array primary key values
         * @return array tuple($where, $parameters)
         */
        protected function getPrimaryKeyCondition($values)
        {
                $primary = $this->getTableInfo()->getPrimaryKeys();
                if(count($primary)===0)
                {
                        throw new TDbException('dbtablegateway_no_primary_key_found',
                                $this->getTableInfo()->getTableFullName());
                }
                $criteria=array();
                $bindings=array();
                $i = 0;
                foreach($primary as $key)
                {
                        $column = $this->getTableInfo()->getColumn($key)->getColumnName();
                        $criteria[] = $column.' = :'.$key;
                        $bindings[$key] = $values[$i++];
                }
                return array(implode(' AND ', $criteria), $bindings);
        }

        /**
         * Find one matching records for arbituary SQL.
         * @param TSqlCriteria $criteria
         * @return TDbDataReader record reader.
         */
        public function findBySql($criteria)
        {
                $command = $this->getSqlCommand($criteria);
                return $this->onExecuteCommand($command, $command->queryRow());
        }

        /**
         * Find zero or more matching records for arbituary SQL.
         * @param TSqlCriteria $criteria
         * @return TDbDataReader record reader.
         */
        public function findAllBySql($criteria)
        {
                $command = $this->getSqlCommand($criteria);
                return $this->onExecuteCommand($command, $command->query());
        }

        /**
         * Build sql command from the criteria. Limit, Offset and Ordering are applied if applicable.
         * @param TSqlCriteria $criteria
         * @return TDbCommand command corresponding to the criteria.
         */
        protected function getSqlCommand($criteria)
        {
                $sql = $criteria->getCondition();
                $ordering = $criteria->getOrdersBy();
                $limit = $criteria->getLimit();
                $offset = $criteria->getOffset();
                if(count($ordering) > 0)
                        $sql = $this->getBuilder()->applyOrdering($sql, $ordering);
                if($limit>=0 || $offset>=0)
                        $sql = $this->getBuilder()->applyLimitOffset($sql, $limit, $offset);
                $command = $this->getBuilder()->createCommand($sql);
                $this->getBuilder()->bindArrayValues($command, $criteria->getParameters()->toArray());
                $this->onCreateCommand($command, $criteria);
                return $command;
        }

        /**
         * @param TSqlCriteria $criteria
         * @return integer number of records.
         */
        public function count($criteria)
        {
                if($criteria===null)
                        return (int)$this->getBuilder()->createCountCommand()->queryScalar();
                $where = $criteria->getCondition();
                $parameters = $criteria->getParameters()->toArray();
                $ordering = $criteria->getOrdersBy();
                $limit = $criteria->getLimit();
                $offset = $criteria->getOffset();
                $command = $this->getBuilder()->createCountCommand($where,$parameters,$ordering,$limit,$offset);
                $this->onCreateCommand($command, $criteria);
                return $this->onExecuteCommand($command, (int)$command->queryScalar());
        }

        /**
         * Inserts a new record into the table. Each array key must
         * correspond to a column name in the table unless a null value is permitted.
         * @param array new record data.
         * @return mixed last insert id if one column contains a serial or sequence,
         * otherwise true if command executes successfully and affected 1 or more rows.
         */
        public function insert($data)
        {
                $command=$this->getBuilder()->createInsertCommand($data);
                $this->onCreateCommand($command, new TSqlCriteria(null,$data));
                $command->prepare();
                if($this->onExecuteCommand($command, $command->execute()) > 0)
                {
                        $value = $this->getLastInsertId();
                        return $value !== null ? $value : true;
                }
                return false;
        }

        /**
         * Iterate through all the columns and returns the last insert id of the
         * first column that has a sequence or serial.
         * @return mixed last insert id, null if none is found.
         */
        public function getLastInsertID()
        {
                return $this->getBuilder()->getLastInsertID();
        }

        /**
         * @param string __call method name
         * @param string criteria conditions
         * @param array method arguments
         * @return TActiveRecordCriteria criteria created from the method name and its arguments.
         */
        public function createCriteriaFromString($method, $condition, $args)
        {
                $fields = $this->extractMatchingConditions($method, $condition);
                $args=count($args) === 1 && is_array($args[0]) ? $args[0] : $args;
                if(count($fields)>count($args))
                {
                        throw new TDbException('dbtablegateway_mismatch_args_exception',
                                $method,count($fields),count($args));
                }
                return new TSqlCriteria(implode(' ',$fields), $args);
        }

        /**
         * Calculates the AND/OR condition from dynamic method substrings using
         * table meta data, allows for any AND-OR combinations.
         * @param string dynamic method name
         * @param string dynamic method search criteria
         * @return array search condition substrings
         */
        protected function extractMatchingConditions($method, $condition)
        {
                $table = $this->getTableInfo();
                $columns = $table->getLowerCaseColumnNames();
                $regexp = '/('.implode('|', array_keys($columns)).')(and|_and_|or|_or_)?/i';
                $matches = array();
                if(!preg_match_all($regexp, strtolower($condition), $matches,PREG_SET_ORDER))
                {
                        throw new TDbException('dbtablegateway_mismatch_column_name',
                                $method, implode(', ', $columns), $table->getTableFullName());
                }

                $fields = array();
                foreach($matches as $match)
                {
                        $key = $columns[$match[1]];
                        $column = $table->getColumn($key)->getColumnName();
                        $sql = $column . ' = ? ';
                        if(count($match) > 2)
                                $sql .= strtoupper(str_replace('_', '', $match[2]));
                        $fields[] = $sql;
                }
                return $fields;
        }

        /**
         * Raised when a command is prepared and parameter binding is completed.
         * The parameter object is TDataGatewayEventParameter of which the
         * {@link TDataGatewayEventParameter::getCommand Command} property can be
         * inspected to obtain the sql query to be executed.
         * @param TDataGatewayCommand originator $sender
         * @param TDataGatewayEventParameter
         */
        public function onCreateCommand($command, $criteria)
        {
                $this->raiseEvent('OnCreateCommand', $this, new TDataGatewayEventParameter($command,$criteria));
        }

        /**
         * Raised when a command is executed and the result from the database was returned.
         * The parameter object is TDataGatewayResultEventParameter of which the
         * {@link TDataGatewayEventParameter::getResult Result} property contains
         * the data return from the database. The data returned can be changed
         * by setting the {@link TDataGatewayEventParameter::setResult Result} property.
         * @param TDataGatewayCommand originator $sender
         * @param TDataGatewayResultEventParameter
         */
        public function onExecuteCommand($command, $result)
        {
                $parameter = new TDataGatewayResultEventParameter($command, $result);
                $this->raiseEvent('OnExecuteCommand', $this, $parameter);
                return $parameter->getResult();
        }
}

/**
 * TDataGatewayEventParameter class contains the TDbCommand to be executed as
 * well as the criteria object.
 *
 * @author Wei Zhuo <weizho[at]gmail[dot]com>
 * @version $Id$
 * @package System.Data.DataGateway
 * @since 3.1
 */
class TDataGatewayEventParameter extends TEventParameter
{
        private $_command;
        private $_criteria;

        public function __construct($command,$criteria)
        {
                $this->_command=$command;
                $this->_criteria=$criteria;
        }

        /**
         * The database command to be executed. Do not rebind the parameters or change
         * the sql query string.
         * @return TDbCommand command to be executed.
         */
        public function getCommand()
        {
                return $this->_command;
        }

        /**
         * @return TSqlCriteria criteria used to bind the sql query parameters.
         */
        public function getCriteria()
        {
                return $this->_criteria;
        }
}

/**
 * TDataGatewayResultEventParameter contains the TDbCommand executed and the resulting
 * data returned from the database. The data can be changed by changing the
 * {@link setResult Result} property.
 *
 * @author Wei Zhuo <weizho[at]gmail[dot]com>
 * @version $Id$
 * @package System.Data.DataGateway
 * @since 3.1
 */
class TDataGatewayResultEventParameter extends TEventParameter
{
        private $_command;
        private $_result;

        public function __construct($command,$result)
        {
                $this->_command=$command;
                $this->_result=$result;
        }

        /**
         * @return TDbCommand database command executed.
         */
        public function getCommand()
        {
                return $this->_command;
        }

        /**
         * @return mixed result returned from executing the command.
         */
        public function getResult()
        {
                return $this->_result;
        }

        /**
         * @param mixed change the result returned by the gateway.
         */
        public function setResult($value)
        {
                $this->_result=$value;
        }
}

?>
Subversion-Projekte lars-tiefland.prado

(root)/framework/Data/DataGateway/TDataGatewayCommand.php – Revision 1
