From 4a2ebb333d239b58c19d09ee88646fa0e32e71ed Mon Sep 17 00:00:00 2001 From: wei <> Date: Mon, 16 Apr 2007 02:02:27 +0000 Subject: Updates to db stuff, removed js build from build.xml (no longer necessary) --- framework/Data/DataGateway/TDataGatewayCommand.php | 213 ++++++++++++++++++--- framework/Data/DataGateway/TSqlCriteria.php | 4 +- framework/Data/DataGateway/TTableGateway.php | 146 +++++++++++++- 3 files changed, 330 insertions(+), 33 deletions(-) (limited to 'framework/Data/DataGateway') diff --git a/framework/Data/DataGateway/TDataGatewayCommand.php b/framework/Data/DataGateway/TDataGatewayCommand.php index 8a340ee7..dbabd2b7 100644 --- a/framework/Data/DataGateway/TDataGatewayCommand.php +++ b/framework/Data/DataGateway/TDataGatewayCommand.php @@ -1,5 +1,39 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005-2007 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 + * @version $Id$ + * @package System.Data.DataGateway + * @since 3.1 + */ class TDataGatewayCommand extends TComponent { private $_builder; @@ -46,6 +80,7 @@ class TDataGatewayCommand extends TComponent $where = $criteria->getCondition(); $parameters = $criteria->getParameters()->toArray(); $command = $this->getBuilder()->createDeleteCommand($where, $parameters); + $this->onCreateCommand($command,$criteria); $command->prepare(); return $command->execute(); } @@ -61,8 +96,9 @@ class TDataGatewayCommand extends TComponent $where = $criteria->getCondition(); $parameters = $criteria->getParameters()->toArray(); $command = $this->getBuilder()->createUpdateCommand($data,$where, $parameters); + $this->onCreateCommand($command,$criteria); $command->prepare(); - return $command->execute(); + return $this->onExecuteCommand($command, $command->execute()); } /** @@ -83,7 +119,8 @@ class TDataGatewayCommand extends TComponent */ public function find($criteria) { - return $this->getFindCommand($criteria)->queryRow(); + $command = $this->getFindCommand($criteria); + return $this->onExecuteCommand($command, $command->queryRow()); } /** @@ -93,7 +130,27 @@ class TDataGatewayCommand extends TComponent */ public function findAll($criteria) { - return $this->getFindCommand($criteria)->query(); + $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; } /** @@ -104,7 +161,8 @@ class TDataGatewayCommand extends TComponent { list($where, $parameters) = $this->getPrimaryKeyCondition((array)$keys); $command = $this->getBuilder()->createFindCommand($where, $parameters); - return $command->queryRow(); + $this->onCreateCommand($command, new TSqlCriteria($where,$parameters)); + return $this->onExecuteCommand($command, $command->queryRow()); } /** @@ -115,7 +173,8 @@ class TDataGatewayCommand extends TComponent { $where = $this->getCompositeKeyCondition((array)$keys); $command = $this->getBuilder()->createFindCommand($where); - return $command->query(); + $this->onCreateCommand($command, new TSqlCriteria($where,$keys)); + return $this->onExecuteCommand($command,$command->query()); } /** @@ -126,8 +185,9 @@ class TDataGatewayCommand extends TComponent { $where = $this->getCompositeKeyCondition((array)$keys); $command = $this->getBuilder()->createDeleteCommand($where); + $this->onCreateCommand($command, new TSqlCriteria($where,$keys)); $command->prepare(); - return $command->execute(); + return $this->onExecuteCommand($command,$command->execute()); } /** @@ -209,7 +269,8 @@ class TDataGatewayCommand extends TComponent */ public function findBySql($criteria) { - return $this->getSqlCommand($criteria)->query(); + $command = $this->getSqlCommand($criteria); + return $this->onExecuteCommand($command, $command->query()); } /** @@ -229,26 +290,10 @@ class TDataGatewayCommand extends TComponent $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; } - /** - * 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(); - return $this->getBuilder()->createFindCommand($where,$parameters,$ordering,$limit,$offset); - } - /** * @param TSqlCriteria $criteria * @return integer number of records. @@ -263,7 +308,8 @@ class TDataGatewayCommand extends TComponent $limit = $criteria->getLimit(); $offset = $criteria->getOffset(); $command = $this->getBuilder()->createCountCommand($where,$parameters,$ordering,$limit,$offset); - return intval($command->queryScalar()); + $this->onCreateCommand($command, $criteria); + return $this->onExecuteCommand($command, intval($command->queryScalar())); } /** @@ -276,8 +322,9 @@ class TDataGatewayCommand extends TComponent public function insert($data) { $command=$this->getBuilder()->createInsertCommand($data); + $this->onCreateCommand($command, new TSqlCriteria(null,$data)); $command->prepare(); - if($command->execute() > 0) + if($this->onExecuteCommand($command, $command->execute()) > 0) { $value = $this->getLastInsertId(); return $value !== null ? $value : true; @@ -344,6 +391,120 @@ class TDataGatewayCommand extends TComponent } 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 + * @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 + * @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; + } } ?> \ No newline at end of file diff --git a/framework/Data/DataGateway/TSqlCriteria.php b/framework/Data/DataGateway/TSqlCriteria.php index ac5f00f2..d073cd10 100644 --- a/framework/Data/DataGateway/TSqlCriteria.php +++ b/framework/Data/DataGateway/TSqlCriteria.php @@ -7,7 +7,7 @@ * @copyright Copyright © 2005-2007 PradoSoft * @license http://www.pradosoft.com/license/ * @version $Id: TDbSqlCriteria.php 1835 2007-04-03 01:38:15Z wei $ - * @package System.Data.Common + * @package System.Data.DataGateway */ /** @@ -26,7 +26,7 @@ * * @author Wei Zhuo * @version $Id: TDbSqlCriteria.php 1835 2007-04-03 01:38:15Z wei $ - * @package System.Data.Common + * @package System.Data.DataGateway * @since 3.1 */ class TSqlCriteria extends TComponent diff --git a/framework/Data/DataGateway/TTableGateway.php b/framework/Data/DataGateway/TTableGateway.php index 6a77c064..f278eed5 100644 --- a/framework/Data/DataGateway/TTableGateway.php +++ b/framework/Data/DataGateway/TTableGateway.php @@ -1,27 +1,163 @@ - + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005-2007 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @package System.Data.DataGateway + */ +/** + * Loads the data gateway command builder and sql criteria. + */ Prado::using('System.Data.DataGateway.TSqlCriteria'); Prado::using('System.Data.DataGateway.TDataGatewayCommand'); +/** + * TTableGateway class provides several find methods to get data from the database + * and update, insert, and delete methods. + * + * Each method maps the input parameters into a SQL call and executes the SQL + * against a database connection. The TTableGateway is stateless + * (with respect to the data and data objects), as its role is to push data back and forth. + * + * Example usage: + * + * //create a connection + * $dsn = 'pgsql:host=localhost;dbname=test'; + * $conn = new TDbConnection($dsn, 'dbuser','dbpass'); + * + * //create a table gateway for table/view named 'address' + * $table = new TTableGateway('address', $conn); + * + * //insert a new row, returns last insert id (if applicable) + * $id = $table->insert(array('name'=>'wei', 'phone'=>'111111')); + * + * $record1 = $table->findByPk($id); //find inserted record + * + * //finds all records, returns an iterator + * $records = $table->findAll(); + * print_r($records->readAll()); + * + * //update the row + * $table->updateByPk($record1, $id); + * + * + * All methods that may return more than one row of data will return an + * TDbDataReader iterator. + * + * The OnCreateCommand event is raised when a command is prepared and parameter + * binding is completed. The parameter object is a TDataGatewayEventParameter of which the + * {@link TDataGatewayEventParameter::getCommand Command} property can be + * inspected to obtain the sql query to be executed. + * + * The OnExecuteCommand event is raised when a command is executed and the result + * from the database was returned. The parameter object is a + * 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. + * + * + * $table->OnCreateCommand[] = 'log_it'; //any valid PHP callback statement + * $table->OnExecuteCommand[] = array($obj, 'method_name'); // calls 'method_name' on $obj + * + * function log_it($sender, $param) + * { + * var_dump($param); //TDataGatewayEventParameter object. + * } + * + * + * @author Wei Zhuo + * @version $Id$ + * @package System.Data.DataGateway + * @since 3.1 + */ class TTableGateway extends TComponent { private $_command; private $_connection; - public function __construct($tableName,$connection) + /** + * Creates a new generic table gateway for a given table or view name + * and a database connection. + * @param string|TDbTableInfo table or view name or table information. + * @param TDbConnection database connection. + */ + public function __construct($table,$connection) { $this->_connection=$connection; - $this->setTableName($tableName); + if(is_string($table)) + $this->setTableName($table); + else if($table instanceof TDbTableInfo) + $this->setTableInfo($table); + else + throw new TDbException('dbtablegateway_invalid_table_info'); + } + + /** + * @param TDbTableInfo table or view information. + */ + protected function setTableInfo($tableInfo) + { + $builder = $tableInfo->createCommandBuilder($this->getDbConnection()); + $this->initCommandBuilder($builder); } + /** + * Sets up the command builder for the given table. + * @param string table or view name. + */ protected function setTableName($tableName) { Prado::using('System.Data.Common.TDbMetaData'); - $meta = TDbMetaData::getMetaData($this->getDbConnection()); - $builder = $meta->createCommandBuilder($tableName); + $meta = TDbMetaData::getInstance($this->getDbConnection()); + $this->initCommandBuilder($meta->createCommandBuilder($tableName)); + } + + /** + * @param TDbCommandBuilder database specific command builder. + */ + protected function initCommandBuilder($builder) + { $this->_command = new TDataGatewayCommand($builder); + $this->_command->OnCreateCommand[] = array($this, 'onCreateCommand'); + $this->_command->OnExecuteCommand[] = array($this, 'onExecuteCommand'); } + /** + * 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($sender, $param) + { + $this->raiseEvent('OnCreateCommand', $this, $param); + } + + /** + * 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($sender, $param) + { + $this->raiseEvent('OnExecuteCommand', $this, $param); + } + + /** + * @return TDataGatewayCommand command builder and executor. + */ protected function getCommand() { return $this->_command; -- cgit v1.2.3