Reverted TActiveRecord::populateObject to protected

7 files changed, 214 insertions, 48 deletions

diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php b/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php
index 3bb1a74b..c72ba160 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php
@@ -1,7 +1,71 @@
-<?php
+<?php

+/**

+ * TActiveRecordBelongsTo 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.ActiveRecord.Relations

+ */

 

+/**

+ * Loads base active record relationship class.

+ */

 Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');

 

+/**

+ * Implements the foreign key relationship (TActiveRecord::BELONGS_TO) between 

+ * the source objects and the related foreign object. Consider the 

+ * <b>entity</b> relationship between a Team and a Player.

+ * <code>

+ * +------+            +--------+

+ * | Team | 1 <----- * | Player |

+ * +------+            +--------+

+ * </code>

+ * Where one team may have 0 or more players and each player belongs to only

+ * one team. We may model Team-Player <b>object</b> relationship as active record as follows.

+ * <code>

+ * class TeamRecord extends TActiveRecord

+ * {

+ *     // see TActiveRecordHasMany for detailed definition.

+ * }

+ * class PlayerRecord extends TActiveRecord

+ * {

+ *     const TABLE='player';

+ *     public $player_id; //primary key

+ *     public $team_name; //foreign key player.team_name <-> team.name

+ * 	   public $age;

+ *     public $team; //foreign object TeamRecord

+ * 

+ *     protected static $RELATIONS = array(

+ *			'team' => array(self::BELONGS_TO, 'TeamRecord'));

+ * 

+ *	   public static function finder($className=__CLASS__)

+ *	   {

+ *		   return parent::finder($className);

+ *	   }

+ * }

+ * </code>

+ * The <tt>$RELATIONS</tt> static property of PlayerRecord defines that the

+ * property <tt>$team</tt> belongs to (or is a) <tt>TeamRecord</tt>s.

+ *

+ * The team object may be fetched as follows.

+ * <code>

+ * $players = PlayerRecord::finder()->with_team()->findAll();

+ * </code>

+ * The method <tt>with_xxx()</tt> (where <tt>xxx</tt> is the relationship property

+ * name, in this case, <tt>team</tt>) fetchs the corresponding TeamRecords using

+ * a second query (not by using a join). The <tt>with_xxx()</tt> accepts the same

+ * arguments as other finder methods of TActiveRecord, e.g. 

+ * <tt>with_team('location = ?', 'Madrid')</tt>.

+ *

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

+ * @version $Id$

+ * @package System.Data.ActiveRecord.Relations

+ * @since 3.1

+ */

 class TActiveRecordBelongsTo extends TActiveRecordRelation

 {

 	/**

@@ -39,5 +103,5 @@ class TActiveRecordBelongsTo extends TActiveRecordRelation
 		}

 	}

 }

-
+

 ?>
\ No newline at end of file
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php b/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php
index 27ffd194..795630ab 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php
@@ -17,14 +17,14 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
 

 /**

  * Implements TActiveRecord::HAS_MANY relationship between the source object having zero or

- * more foreign objects. Consider the relationship between a Team and a Player.

+ * more foreign objects. Consider the <b>entity</b> relationship between a Team and a Player.

  * <code>

  * +------+            +--------+

- * | Team | 1 -----> * | Player |

+ * | Team | 1 <----- * | Player |

  * +------+            +--------+

  * </code>

  * Where one team may have 0 or more players and each player belongs to only

- * one team. We may model Team-Player relationship as active record as follows.

+ * one team. We may model Team-Player <b>object</b> relationship as active record as follows.

  * <code>

  * class TeamRecord extends TActiveRecord

  * {

@@ -44,15 +44,7 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');
  * }

  * class PlayerRecord extends TActiveRecord

  * {

- *     const TABLE='player';

- *     public $player_id; //primary key

- *     public $team_name; //foreign key player.team_name <-> team.name

- * 	   public $age;

- *

- *	   public static function finder($className=__CLASS__)

- *	   {

- *		   return parent::finder($className);

- *	   }

+ *     // see TActiveRecordBelongsTo for detailed definition

  * }

  * </code>

  * The <tt>$RELATIONS</tt> static property of TeamRecord defines that the

diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php b/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php
index 048f776b..e8c2ccee 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php
@@ -1,6 +1,33 @@
-<?php
+<?php

+/**

+ * TActiveRecordHasOne 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.ActiveRecord.Relations

+ */

+

+/**

+ * Loads base active record relationship class.

+ */

 Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation');

 

+/**

+ * TActiveRecordHasOne models the object relationship that a record (the source object)

+ * property is an instance of foreign record object having a foreign key

+ * related to the source object. 

+ *

+ *

+ * 

+ *

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

+ * @version $Id$

+ * @package System.Data.ActiveRecord.Relations

+ * @since 3.1

+ */

 class TActiveRecordHasOne extends TActiveRecordRelation

 {

 	/**

@@ -38,5 +65,5 @@ class TActiveRecordHasOne extends TActiveRecordRelation
 		}

 	}

 }

-
+

 ?>
\ No newline at end of file
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php b/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php
index f1e8fa60..38455309 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php
@@ -1,6 +1,30 @@
 <?php

+/**

+ * TActiveRecordRelation 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.ActiveRecord.Relations

+ */

+

+/**

+ * Load active record relationship context.

+ */

 Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelationContext');

 

+/**

+ * Base class for active record relationships.

+ *

+ * description

+ *

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

+ * @version $Id$

+ * @package System.Data.ActiveRecord.Relations

+ * @since 3.1

+ */

 abstract class TActiveRecordRelation

 {

 	private $_context;

@@ -28,11 +52,10 @@ abstract class TActiveRecordRelation
 

 	/**

 	 * Dispatch the method calls to the source record finder object. When

-	 * the results are returned as array or is an instance of TActiveRecord we

-	 * will fetch the corresponding foreign objects with an sql query and populate

-	 * the results obtained earlier.

+	 * an instance of TActiveRecord or an array of TActiveRecord is returned

+	 * the corresponding foreign objects are also fetched and assigned.

 	 *

-	 * Allows chaining multiple relation handlers.

+	 * Multiple relationship calls can be chain together.

 	 *

 	 * @param string method name called

 	 * @param array method arguments

@@ -106,7 +129,7 @@ abstract class TActiveRecordRelation
 	/**

 	 * Obtain the foreign key index values from the results.

 	 * @param array property names

-	 * @param array|TActiveRecord TActiveRecord results

+	 * @param array TActiveRecord results

 	 * @return array foreign key index values.

 	 */

 	protected function getIndexValues($keys, $results)

@@ -134,14 +157,16 @@ abstract class TActiveRecordRelation
 	{

 		$collections=array();

 		foreach($fkObjects as $fkObject)

-		{

-			$hash = $this->getObjectHash($fkObject, $fields);

-			$collections[$hash][]=$fkObject;

-		}

-

+			$collections[$this->getObjectHash($fkObject, $fields)][]=$fkObject;

 		$this->setResultCollection($results, $collections, $properties);

 	}

 

+	/**

+	 * Populates the result array with foreign objects (matched using foreign key hashed property values).

+	 * @param array $results

+	 * @param array $collections

+	 * @param array property names

+	 */

 	protected function setResultCollection(&$results, &$collections, $properties)

 	{

 		if(is_array($results))

@@ -150,9 +175,7 @@ abstract class TActiveRecordRelation
 				$this->setObjectProperty($results[$i], $properties, $collections);

 		}

 		else

-		{

 			$this->setObjectProperty($results, $properties, $collections);

-		}

 	}

 

 	/**

diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php b/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php
index 03dc4cd5..a33e105e 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php
@@ -1,7 +1,33 @@
 <?php
+/**

+ * TActiveRecordRelationContext class.

+ *

+ * @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.ActiveRecord.Relations

+ */

 

+/**

+ * TActiveRecordRelationContext holds information regarding record relationships

+ * such as record relation property name, query criteria and foreign object record

+ * class names.

+ *

+ * This class is use internally by passing a context to the TActiveRecordRelation

+ * constructor.

+ *

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

+ * @version $Id$

+ * @package System.Data.ActiveRecord.Relations

+ * @since 3.1

+ */

 class TActiveRecordRelationContext

 {

+	/**

+	 * static property name in TActiveRecord that defines the record relationships.

+	 */

 	const RELATIONS_CONST = 'RELATIONS';

 

 	private $_property;

@@ -16,9 +42,13 @@ class TActiveRecordRelationContext
 		$this->_criteria=$criteria;

 		$this->_relation = $this->getSourceRecordRelation($property);

 	}

+

 	/**

+	 * Uses ReflectionClass to obtain the relation details array of a given

+	 * property from the $RELATIONS static property in TActiveRecord.

 	 * @param string relation property name

 	 * @return array relation definition.

+	 * @throws TActiveRecordException if property is not defined or missing.

 	 */

 	protected function getSourceRecordRelation($property)

 	{

@@ -34,46 +64,76 @@ class TActiveRecordRelationContext
 				$property, get_class($this->_sourceRecord), self::RELATIONS_CONST);

 	}

 

+	/**

+	 * @return string name of the record property that the relationship results will be assigned to.

+	 */

 	public function getProperty()

 	{

 		return $this->_property;

 	}

 

+	/**

+	 * @return TActiveRecordCriteria sql query criteria for fetching the related record.

+	 */

 	public function getCriteria()

 	{

 		return $this->_criteria;

 	}

 

+	/**

+	 * @return TActiveRecord the active record instance that queried for its related records.

+	 */

 	public function getSourceRecord()

 	{

 		return $this->_sourceRecord;

 	}

 

+	/**

+	 * @return string foreign record class name.

+	 */

 	public function getForeignRecordClass()

 	{

 		return $this->_relation[1];

 	}

 

+	/**

+	 * @return string HAS_MANY, HAS_ONE, or BELONGS_TO

+	 */

 	public function getRelationType()

 	{

 		return $this->_relation[0];

 	}

 

+	/**

+	 * @return string the M-N relationship association table name.

+	 */

 	public function getAssociationTable()

 	{

 		return $this->_relation[2];

 	}

 

+	/**

+	 * @return boolean true if the relationship is HAS_MANY and requires an association table.

+	 */

 	public function hasAssociationTable()

 	{

 		return isset($this->_relation[2]);

 	}

 

+	/**

+	 * @return TActiveRecord corresponding relationship foreign object finder instance.

+	 */

 	public function getForeignRecordFinder()

 	{

 		return TActiveRecord::finder($this->getForeignRecordClass());

 	}

 

+	/**

+	 * Creates and return the TActiveRecordRelation handler for specific relationships.

+	 * An instance of TActiveRecordHasOne, TActiveRecordBelongsTo, TActiveRecordHasMany,

+	 * or TActiveRecordHasManyAssocation will be returned.

+	 * @return TActiveRecordRelation record relationship handler instnace.

+	 */

 	public function getRelationHandler()

 	{

 		switch($this->getRelationType())

diff --git a/framework/Data/ActiveRecord/TActiveRecord.php b/framework/Data/ActiveRecord/TActiveRecord.php
index 67057554..2ff3f1d4 100644
--- a/framework/Data/ActiveRecord/TActiveRecord.php
+++ b/framework/Data/ActiveRecord/TActiveRecord.php
@@ -10,9 +10,9 @@
  * @package System.Data.ActiveRecord
  */
 
-/**

- * Load record manager, criteria and relations.

- */

+/**
+ * Load record manager, criteria and relations.
+ */
 Prado::using('System.Data.ActiveRecord.TActiveRecordManager');
 Prado::using('System.Data.ActiveRecord.TActiveRecordCriteria');
 Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelationContext');
@@ -282,7 +282,7 @@ abstract class TActiveRecord extends TComponent
 	 * @param array name value pair record data
 	 * @return TActiveRecord object record, null if data is empty.
 	 */
-	public function populateObject($type, $data)
+	protected function populateObject($type, $data)
 	{
 		if(empty($data)) return null;
 		$registry = $this->getRecordManager()->getObjectStateRegistry();
@@ -311,7 +311,7 @@ abstract class TActiveRecord extends TComponent
 	/**
 	 * @param TDbDataReader data reader
 	 */
-	public function collectObjects($reader)
+	protected function collectObjects($reader)
 	{
 		$result=array();
 		$class = get_class($this);
@@ -428,14 +428,14 @@ abstract class TActiveRecord extends TComponent
 	}
 
 	/**
-	 * Fetches records using the sql clause "(fields) IN (values)", where

-	 * fields is an array of column names and values is an array of values that

-	 * the columns must have.

-	 *

-	 * This method is to be used by the relationship handler.

-	 *

-	 * @param TActiveRecordCriteria additional criteria

-	 * @param array field names to match with "(fields) IN (values)" sql clause.

+	 * Fetches records using the sql clause "(fields) IN (values)", where
+	 * fields is an array of column names and values is an array of values that
+	 * the columns must have.
+	 *
+	 * This method is to be used by the relationship handler.
+	 *
+	 * @param TActiveRecordCriteria additional criteria
+	 * @param array field names to match with "(fields) IN (values)" sql clause.
 	 * @param array matching field values.
 	 * @return array matching active records.
 	 */
@@ -461,17 +461,17 @@ abstract class TActiveRecord extends TComponent
 		return $gateway->countRecords($this,$criteria);
 	}
 
-	/**

-	 * Returns the active record relationship handler for $RELATION with key

+	/**
+	 * Returns the active record relationship handler for $RELATION with key
 	 * value equal to the $property value.
-	 * @param string relationship property name.

+	 * @param string relationship property name.
 	 * @param array method call arguments.
 	 * @return TActiveRecordRelation
 	 */
 	protected function getRelationHandler($property,$args)
 	{
-		$criteria = $this->getCriteria(count($args)>0 ? $args[0] : null, array_slice($args,1));

-		$context = new TActiveRecordRelationContext($this, $property, $criteria);

+		$criteria = $this->getCriteria(count($args)>0 ? $args[0] : null, array_slice($args,1));
+		$context = new TActiveRecordRelationContext($this, $property, $criteria);
 		return $context->getRelationHandler();
 	}
 
diff --git a/framework/Data/ActiveRecord/TActiveRecordStateRegistry.php b/framework/Data/ActiveRecord/TActiveRecordStateRegistry.php
index ef415b5e..691090dc 100644
--- a/framework/Data/ActiveRecord/TActiveRecordStateRegistry.php
+++ b/framework/Data/ActiveRecord/TActiveRecordStateRegistry.php
@@ -54,13 +54,13 @@ class TActiveRecordStateRegistry
 	 * @param mixed row data fetched

 	 * @return TActiveRecord cached object if found, null otherwise.

 	 */

-	public function getCachedInstance($data)

+	public function getCachedInstance($data,$mustBeClean=true)

 	{

 		$key = $this->getObjectDataKey($data);

 		if(isset($this->_cachedObjects[$key]))

 		{

 			$obj = $this->_cachedObjects[$key];

-			if($this->getIsCleanObject($obj))

+			if(!($mustBeClean && !$this->getIsCleanObject($obj)))

 				return $obj;

 		}

 	}