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/ActiveRecord/TActiveRecord.php | 83 +++++--- .../Data/ActiveRecord/TActiveRecordCriteria.php | 22 --- .../Data/ActiveRecord/TActiveRecordGateway.php | 149 ++++++-------- .../Data/ActiveRecord/TActiveRecordManager.php | 66 +------ framework/Data/Common/Mssql/TMssqlMetaData.php | 24 +++ framework/Data/Common/Mssql/TMssqlTableColumn.php | 9 + framework/Data/Common/Mssql/TMssqlTableInfo.php | 4 + framework/Data/Common/Mysql/TMysqlMetaData.php | 2 + framework/Data/Common/Pgsql/TPgsqlMetaData.php | 2 + framework/Data/Common/Sqlite/TSqliteMetaData.php | 2 + .../Data/Common/Sqlite/TSqliteTableColumn.php | 3 + framework/Data/Common/TDbMetaData.php | 2 +- framework/Data/Common/TDbTableColumn.php | 2 +- framework/Data/DataGateway/TDataGatewayCommand.php | 213 ++++++++++++++++++--- framework/Data/DataGateway/TSqlCriteria.php | 4 +- framework/Data/DataGateway/TTableGateway.php | 146 +++++++++++++- 16 files changed, 505 insertions(+), 228 deletions(-) (limited to 'framework/Data') diff --git a/framework/Data/ActiveRecord/TActiveRecord.php b/framework/Data/ActiveRecord/TActiveRecord.php index 0400661d..1ea06a60 100644 --- a/framework/Data/ActiveRecord/TActiveRecord.php +++ b/framework/Data/ActiveRecord/TActiveRecord.php @@ -17,7 +17,10 @@ Prado::using('System.Data.ActiveRecord.TActiveRecordCriteria'); * Base class for active records. * * An active record creates an object that wraps a row in a database table - * or view, encapsulates the database access, and adds domain logic on that data. + * or view, encapsulates the database access, and adds domain logic on that data. + * + * Active record objects are stateful, this is main difference between the + * TActiveRecord implementation and the TTableGateway implementation. * * The essence of an Active Record is an object model of the * domain (e.g. products, items) that incorporates both behavior and @@ -140,7 +143,11 @@ abstract class TActiveRecord extends TComponent } /** - * Returns the instance of a active record finder for a particular class. + * Returns the instance of a active record finder for a particular class. + * The finder objects are static instances for each ActiveRecord class. + * This means that event handlers bound to these finder instances are class wide. + * Create a new instance of the ActiveRecord class if you wish to bound the + * event handlers to object instance. * @param string active record class name. * @return TActiveRecord active record finder instance. * @throws TActiveRecordException if class name equals 'TActiveRecord'. @@ -168,6 +175,14 @@ abstract class TActiveRecord extends TComponent public function getRecordManager() { return TActiveRecordManager::getInstance(); + } + + /** + * @return TActiveRecordGateway record table gateway. + */ + public function getRecordGateway() + { + return $this->getRecordManager()->getRecordGateway(); } /** @@ -266,15 +281,20 @@ abstract class TActiveRecord extends TComponent //try the cache (the cache object must be clean) if(!is_null($obj = $registry->getCachedInstance($data))) - return $obj; + return $obj; + + $gateway = $this->getRecordManager()->getRecordGateway(); //create and populate the object $obj = Prado::createComponent($type); - foreach($data as $name => $value) - $obj->{$name} = $value; + $tableInfo = $gateway->getRecordTableInfo($obj); + foreach($tableInfo->getColumns()->getKeys() as $name) + { + if(isset($data[$name])) + $obj->{$name} = $data[$name]; + } - $gateway = $this->getRecordManager()->getRecordGateway(); - $obj->_readOnly = $gateway->getRecordTableInfo($this)->getIsView(); + $obj->_readOnly = $tableInfo->getIsView(); //cache it return $registry->addCachedInstance($data,$obj); @@ -484,21 +504,38 @@ abstract class TActiveRecord extends TComponent else throw new TActiveRecordException('ar_invalid_criteria'); } + + /** + * 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. + * + * Note well that the finder objects obtained from ActiveRecord::finder() + * method are static objects. This means that the event handlers are + * bound to a static finder object and not to each distinct active record object. + * @param TDataGatewayEventParameter + */ + public function onCreateCommand($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. + * + * Note well that the finder objects obtained from ActiveRecord::finder() + * method are static objects. This means that the event handlers are + * bound to a static finder object and not to each distinct active record object. + * @param TDataGatewayResultEventParameter + */ + public function onExecuteCommand($param) + { + $this->raiseEvent('OnExecuteCommand', $this, $param); + } } - -/** - * TActiveRecordEventParameter class. - * - * @author Wei Zhuo - * @version $Id$ - * @package System.Data.ActiveRecord - * @since 3.1 - */ -class TActiveRecordEventParameter extends TEventParameter -{ - -} - - - ?> diff --git a/framework/Data/ActiveRecord/TActiveRecordCriteria.php b/framework/Data/ActiveRecord/TActiveRecordCriteria.php index cc4da7c8..8328b4a6 100644 --- a/framework/Data/ActiveRecord/TActiveRecordCriteria.php +++ b/framework/Data/ActiveRecord/TActiveRecordCriteria.php @@ -34,29 +34,7 @@ Prado::using('System.Data.DataGateway.TSqlCriteria'); */ class TActiveRecordCriteria extends TSqlCriteria { - /** - * This method is invoked before the object is deleted from the database. - * The method raises 'OnDelete' event. - * If you override this method, be sure to call the parent implementation - * so that the event handlers can be invoked. - * @param TActiveRecordEventParameter event parameter to be passed to the event handlers - */ - public function onDelete($param) - { - $this->raiseEvent('OnDelete', $this, $param); - } - /** - * This method is invoked before any select query is executed on the database. - * The method raises 'OnSelect' event. - * If you override this method, be sure to call the parent implementation - * so that the event handlers can be invoked. - * @param TActiveRecordEventParameter event parameter to be passed to the event handlers - */ - public function onSelect($param) - { - $this->raiseEvent('OnSelect', $this, $param); - } } ?> \ No newline at end of file diff --git a/framework/Data/ActiveRecord/TActiveRecordGateway.php b/framework/Data/ActiveRecord/TActiveRecordGateway.php index 9c480ad0..c3239c5c 100644 --- a/framework/Data/ActiveRecord/TActiveRecordGateway.php +++ b/framework/Data/ActiveRecord/TActiveRecordGateway.php @@ -1,6 +1,6 @@ * @link http://www.pradosoft.com/ @@ -25,6 +25,8 @@ class TActiveRecordGateway extends TComponent private $_tables=array(); //table cache private $_meta=array(); //meta data cache. private $_commandBuilders=array(); + private $_currentRecord; + /** * Constant name for specifying optional table name in TActiveRecord. */ @@ -99,7 +101,7 @@ class TActiveRecordGateway extends TComponent if(!isset($this->_meta[$connStr])) { Prado::using('System.Data.Common.TDbMetaData'); - $this->_meta[$connStr] = TDbMetaData::getMetaData($connection); + $this->_meta[$connStr] = TDbMetaData::getInstance($connection); } $tableInfo = $this->_meta[$connStr]->getTableInfo($tableName); } @@ -123,13 +125,52 @@ class TActiveRecordGateway extends TComponent { $builder = $tableInfo->createCommandBuilder($record->getDbConnection()); Prado::using('System.Data.DataGateway.TDataGatewayCommand'); - $this->_commandBuilders[$connStr] = new TDataGatewayCommand($builder); + $command = new TDataGatewayCommand($builder); + $command->OnCreateCommand[] = array($this, 'onCreateCommand'); + $command->OnExecuteCommand[] = array($this, 'onExecuteCommand'); + $this->_commandBuilders[$connStr] = $command; + } $this->_commandBuilders[$connStr]->getBuilder()->setTableInfo($tableInfo); - + $this->_currentRecord=$record; return $this->_commandBuilders[$connStr]; } + /** + * 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. + * This method also raises the OnCreateCommand event on the ActiveRecord + * object calling this gateway. + * @param TDataGatewayCommand originator $sender + * @param TDataGatewayEventParameter + */ + public function onCreateCommand($sender, $param) + { + $this->raiseEvent('OnCreateCommand', $this, $param); + if($this->_currentRecord!==null) + $this->_currentRecord->onCreateCommand($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. + * This method also raises the OnCreateCommand event on the ActiveRecord + * object calling this gateway. + * @param TDataGatewayCommand originator $sender + * @param TDataGatewayResultEventParameter + */ + public function onExecuteCommand($sender, $param) + { + $this->raiseEvent('OnExecuteCommand', $this, $param); + if($this->_currentRecord!==null) + $this->_currentRecord->onExecuteCommand($param); + } + /** * Returns record data matching the given primary key(s). If the table uses * composite key, specify the name value pairs as an array. @@ -139,7 +180,8 @@ class TActiveRecordGateway extends TComponent */ public function findRecordByPK(TActiveRecord $record,$keys) { - return $this->getCommand($record)->findByPk($keys); + $command = $this->getCommand($record); + return $command->findByPk($keys); } /** @@ -164,10 +206,8 @@ class TActiveRecordGateway extends TComponent */ public function findRecordsByCriteria(TActiveRecord $record, $criteria, $iterator=false) { - if($iterator) - return $this->getCommand($record)->findAll($criteria); - else - return $this->getCommand($record)->find($criteria); + $command = $this->getCommand($record); + return $iterator ? $command->findAll($criteria) : $command->find($criteria); } /** @@ -205,6 +245,10 @@ class TActiveRecordGateway extends TComponent return $result; } + /** + * Sets the last insert ID to the corresponding property of the record if available. + * @param TActiveRecord record for insertion + */ protected function updatePostInsert($record) { $command = $this->getCommand($record); @@ -324,91 +368,16 @@ class TActiveRecordGateway extends TComponent * @param string command type * @param TDbCommand sql command to be executed. * @param TActiveRecord active record - * @param mixed data for the command. + * @param TActiveRecordCriteria data for the command. */ - protected function raiseCommandEvent($type,$command,$record=null,$data=null) + protected function raiseCommandEvent($event,$command,$record,$criteria) { - $param = new TActiveRecordGatewayEventParameter($type,$command,$record,$data); + if(!($criteria instanceof TSqlCriteria)) + $criteria = new TActiveRecordCriteria(null,$criteria); + $param = new TActiveRecordEventParameter($command,$record,$criteria); $manager = $record->getRecordManager(); - $event = 'on'.$type; - if($data instanceof TActiveRecordCriteria) - $data->{$event}($param); $manager->{$event}($param); - } -} - -/** - * Command statement types. - * - * @author Wei Zhuo - * @version $Id$ - * @package System.Data.ActiveRecord - * @since 3.1 - */ -class TActiveRecordStatementType -{ - const Insert='Insert'; - const Update='Update'; - const Delete='Delete'; - const Select='Select'; -} - -/** - * Active Record command event parameter. - * - * @author Wei Zhuo - * @version $Id$ - * @package System.Data.ActiveRecord - * @since 3.1 - */ -class TActiveRecordGatewayEventParameter extends TActiveRecordEventParameter -{ - private $_type; - private $_command; - private $_record; - private $_data; - - /** - * New gateway command event parameter. - */ - public function __construct($type,$command,$record=null,$data=null) - { - $this->_type=$type; - $this->_command=$command; - $this->_data=$data; - $this->_record=$record; - } - - /** - * @return string TActiveRecordStateType - */ - public function getType() - { - return $this->_type; - } - - /** - * @return TDbCommand command to be executed. - */ - public function getCommand() - { - return $this->_command; - } - - /** - * @return TActiveRecord active record. - */ - public function getRecord() - { - return $this->_record; - } - - /** - * @return mixed command data. - */ - public function getData() - { - return $this->_data; + $record->{$event}($param); } } diff --git a/framework/Data/ActiveRecord/TActiveRecordManager.php b/framework/Data/ActiveRecord/TActiveRecordManager.php index 5e463d2d..ab6fe88d 100644 --- a/framework/Data/ActiveRecord/TActiveRecordManager.php +++ b/framework/Data/ActiveRecord/TActiveRecordManager.php @@ -20,20 +20,16 @@ Prado::using('System.Data.ActiveRecord.TActiveRecordStateRegistry'); * TActiveRecordManager provides the default DB connection, default object state * registry, default active record gateway, and table meta data inspector. * - * You can provide a different registry by overriding the {@link createObjectStateRegistry()} method. - * Similarly, override {@link createRecordGateway()} for default gateway and override - * {@link createMetaDataInspector() }for meta data inspector. - * * The default connection can be set as follows: * * TActiveRecordManager::getInstance()->setDbConnection($conn); * * All new active record created after setting the - * {@link DbConnection setDbConnection()} will use that connection. + * {@link DbConnection setDbConnection()} will use that connection unless + * the custom ActiveRecord class overrides the ActiveRecord::getDbConnection(). * - * The {@link onInsert()}, {@link onUpdate()}, - * {@link onDelete()} and {@link onSelect()} events are raised - * before their respective command are executed. + * Set the {@link setCache Cache} property to an ICache object to allow + * the active record gateway to cache the table meta data information. * * @author Wei Zhuo * @version $Id$ @@ -84,10 +80,12 @@ class TActiveRecordManager extends TComponent /** * @return TActiveRecordManager static instance of record manager. */ - public static function getInstance() + public static function getInstance($self=null) { static $instance; - if($instance===null) + if($self!==null) + $instance=$self; + else if($instance===null) $instance = new self; return $instance; } @@ -127,54 +125,6 @@ class TActiveRecordManager extends TComponent { return new TActiveRecordGateway($this); } - - /** - * This method is invoked before the object is inserted into the database. - * The method raises 'OnInsert' event. - * If you override this method, be sure to call the parent implementation - * so that the event handlers can be invoked. - * @param TActiveRecordEventParameter event parameter to be passed to the event handlers - */ - public function onInsert($param) - { - $this->raiseEvent('OnInsert', $this, $param); - } - - /** - * This method is invoked before the object is deleted from the database. - * The method raises 'OnDelete' event. - * If you override this method, be sure to call the parent implementation - * so that the event handlers can be invoked. - * @param TActiveRecordEventParameter event parameter to be passed to the event handlers - */ - public function onDelete($param) - { - $this->raiseEvent('OnDelete', $this, $param); - } - - /** - * This method is invoked before the object data is updated in the database. - * The method raises 'OnUpdate' event. - * If you override this method, be sure to call the parent implementation - * so that the event handlers can be invoked. - * @param TActiveRecordEventParameter event parameter to be passed to the event handlers - */ - public function onUpdate($param) - { - $this->raiseEvent('OnUpdate', $this, $param); - } - - /** - * This method is invoked before any select query is executed on the database. - * The method raises 'OnSelect' event. - * If you override this method, be sure to call the parent implementation - * so that the event handlers can be invoked. - * @param TActiveRecordEventParameter event parameter to be passed to the event handlers - */ - public function onSelect($param) - { - $this->raiseEvent('OnSelect', $this, $param); - } } diff --git a/framework/Data/Common/Mssql/TMssqlMetaData.php b/framework/Data/Common/Mssql/TMssqlMetaData.php index c70bc349..5d14aac1 100644 --- a/framework/Data/Common/Mssql/TMssqlMetaData.php +++ b/framework/Data/Common/Mssql/TMssqlMetaData.php @@ -1,4 +1,14 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005-2007 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Id: TPgsqlMetaData.php 1866 2007-04-14 05:02:29Z wei $ + * @package System.Data.Common.Pgsql + */ /** * Load the base TDbMetaData class. @@ -6,6 +16,14 @@ Prado::using('System.Data.Common.TDbMetaData'); Prado::using('System.Data.Common.Mssql.TMssqlTableInfo'); +/** + * TMssqlMetaData loads MSSQL database table and column information. + * + * @author Wei Zhuo + * @version $Id: TPgsqlMetaData.php 1866 2007-04-14 05:02:29Z wei $ + * @package System.Data.Commom.Pgsql + * @since 3.1 + */ class TMssqlMetaData extends TDbMetaData { /** @@ -45,9 +63,15 @@ EOD; $tableInfo = $this->createNewTableInfo($col); $this->processColumn($tableInfo,$col); } + if($tableInfo===null) + throw new TDbException('dbmetadata_invalid_table_view', $table); return $tableInfo; } + /** + * @param string table name + * @return array tuple($catalogName,$schemaName,$tableName) + */ protected function getCatalogSchemaTableName($table) { //remove possible delimiters diff --git a/framework/Data/Common/Mssql/TMssqlTableColumn.php b/framework/Data/Common/Mssql/TMssqlTableColumn.php index 77c115e5..f108248d 100644 --- a/framework/Data/Common/Mssql/TMssqlTableColumn.php +++ b/framework/Data/Common/Mssql/TMssqlTableColumn.php @@ -37,16 +37,25 @@ class TMssqlTableColumn extends TDbTableColumn return 'string'; } + /** + * @return boolean true if the column has identity (auto-increment) + */ public function getAutoIncrement() { return $this->getInfo('AutoIncrement',false); } + /** + * @return boolean true if auto increments. + */ public function hasSequence() { return $this->getAutoIncrement(); } + /** + * @return boolean true if db type is 'timestamp'. + */ public function getIsExcluded() { return strtolower($this->getDbType())==='timestamp'; diff --git a/framework/Data/Common/Mssql/TMssqlTableInfo.php b/framework/Data/Common/Mssql/TMssqlTableInfo.php index b407ad44..e408440b 100644 --- a/framework/Data/Common/Mssql/TMssqlTableInfo.php +++ b/framework/Data/Common/Mssql/TMssqlTableInfo.php @@ -34,6 +34,9 @@ class TMssqlTableInfo extends TDbTableInfo return $this->getInfo('SchemaName'); } + /** + * @return string catalog name (database name) + */ public function getCatalogName() { return $this->getInfo('CatalogName'); @@ -44,6 +47,7 @@ class TMssqlTableInfo extends TDbTableInfo */ public function getTableFullName() { + //MSSQL alway returns the catalog, schem and table names. return '['.$this->getCatalogName().'].['.$this->getSchemaName().'].['.$this->getTableName().']'; } diff --git a/framework/Data/Common/Mysql/TMysqlMetaData.php b/framework/Data/Common/Mysql/TMysqlMetaData.php index 9e947298..32d5114f 100644 --- a/framework/Data/Common/Mysql/TMysqlMetaData.php +++ b/framework/Data/Common/Mysql/TMysqlMetaData.php @@ -26,6 +26,8 @@ class TMysqlMetaData extends TDbMetaData $col['index'] = $index++; $this->processColumn($tableInfo,$col); } + if($index===0) + throw new TDbException('dbmetadata_invalid_table_view', $table); return $tableInfo; } diff --git a/framework/Data/Common/Pgsql/TPgsqlMetaData.php b/framework/Data/Common/Pgsql/TPgsqlMetaData.php index ac7e6b7a..bb03b6cd 100644 --- a/framework/Data/Common/Pgsql/TPgsqlMetaData.php +++ b/framework/Data/Common/Pgsql/TPgsqlMetaData.php @@ -109,6 +109,8 @@ EOD; $col['index'] = $index++; $this->processColumn($tableInfo, $col); } + if($index===0) + throw new TDbException('dbmetadata_invalid_table_view', $table); return $tableInfo; } diff --git a/framework/Data/Common/Sqlite/TSqliteMetaData.php b/framework/Data/Common/Sqlite/TSqliteMetaData.php index 2ce46fb7..6fcf7b7f 100644 --- a/framework/Data/Common/Sqlite/TSqliteMetaData.php +++ b/framework/Data/Common/Sqlite/TSqliteMetaData.php @@ -52,6 +52,8 @@ class TSqliteMetaData extends TDbMetaData $info['TableName'] = $table; if($this->getIsView($tableName)) $info['IsView'] = true; + if(count($columns)===0) + throw new TDbException('dbmetadata_invalid_table_view', $tableName); $tableInfo = new TSqliteTableInfo($info,$primary,$foreign); $tableInfo->getColumns()->copyFrom($columns); return $tableInfo; diff --git a/framework/Data/Common/Sqlite/TSqliteTableColumn.php b/framework/Data/Common/Sqlite/TSqliteTableColumn.php index b8287218..80dcd9d9 100644 --- a/framework/Data/Common/Sqlite/TSqliteTableColumn.php +++ b/framework/Data/Common/Sqlite/TSqliteTableColumn.php @@ -25,6 +25,9 @@ Prado::using('System.Data.Common.TDbTableColumn'); */ class TSqliteTableColumn extends TDbTableColumn { + /** + * @TODO add sqlite types. + */ private static $types = array(); /** diff --git a/framework/Data/Common/TDbMetaData.php b/framework/Data/Common/TDbMetaData.php index 6838d7dc..d0963f44 100644 --- a/framework/Data/Common/TDbMetaData.php +++ b/framework/Data/Common/TDbMetaData.php @@ -47,7 +47,7 @@ abstract class TDbMetaData extends TComponent * @param TDbConnection database connection. * @return TDbMetaData database specific TDbMetaData. */ - public static function getMetaData($conn) + public static function getInstance($conn) { $conn->setActive(true); //must be connected before retrieving driver name $driver = $conn->getDriverName(); diff --git a/framework/Data/Common/TDbTableColumn.php b/framework/Data/Common/TDbTableColumn.php index 6ff2ff46..84fb238c 100644 --- a/framework/Data/Common/TDbTableColumn.php +++ b/framework/Data/Common/TDbTableColumn.php @@ -100,7 +100,7 @@ class TDbTableColumn extends TComponent } /** - * @return integer one-based ordinal position of the column in the table. + * @return integer zero-based ordinal position of the column in the table. */ public function getColumnIndex() { 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