Updates to db stuff, removed js build from build.xml (no longer necessary)

16 files changed, 505 insertions, 228 deletions

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 <weizho[at]gmail[dot]com>
- * @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 @@
 <?php
 /**

- * TActiveRecordGateway, TActiveRecordStatementType, TActiveRecordGatewayEventParameter classes file.

+ * TActiveRecordGateway, TActiveRecordStatementType, TActiveRecordEventParameter classes file.

  *

  * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

  * @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,14 +125,53 @@ 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.

 	 * @param TActiveRecord active record instance.

@@ -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 <weizho[at]gmail[dot]com>

- * @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 <weizho[at]gmail[dot]com>

- * @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:

  * <code>

  * TActiveRecordManager::getInstance()->setDbConnection($conn);

  * </code>

  * 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

- * <b>before</b> 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 <weizho[at]gmail[dot]com>

  * @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 @@
 <?php

+/**

+ * TMssqlMetaData class file.

+ *

+ * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

+ * @link http://www.pradosoft.com/

+ * @copyright Copyright &copy; 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 <weizho[at]gmail[dot]com>

+ * @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 @@
 <?php
+/**

+ * TDataGatewayCommand, TDataGatewayEventParameter and TDataGatewayResultEventParameter class file.

+ *

+ * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

+ * @link http://www.pradosoft.com/

+ * @copyright Copyright &copy; 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 <weizho[at]gmail[dot]com>

+ * @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,27 +290,11 @@ 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 <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;

+	}

 }

 
 ?>
\ 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 &copy; 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 <weizho[at]gmail[dot]com>

  * @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 @@
-<?php
+<?php

+/**

+ * TTableGateway class file.

+ *

+ * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

+ * @link http://www.pradosoft.com/

+ * @copyright Copyright &copy; 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:

+ * <code>

+ * //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);

+ * </code>

+ *

+ * 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.

+ *

+ * <code>

+ * $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.

+ * }

+ * </code>

+ *

+ * @author Wei Zhuo <weizho[at]gmail[dot]com>

+ * @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;