From 595a0acc2554da4c4c52f065dc76893c241f2624 Mon Sep 17 00:00:00 2001
From: wei <>
Date: Tue, 1 May 2007 00:27:01 +0000
Subject: Add comments to active record relationships, add semi-colon to js
 files.

---
 .../Relations/TActiveRecordHasManyAssociation.php  | 18 +++++--
 .../ActiveRecord/Relations/TActiveRecordHasOne.php | 55 +++++++++++++++++++++-
 .../Relations/TActiveRecordRelationContext.php     |  6 +--
 3 files changed, 71 insertions(+), 8 deletions(-)

(limited to 'framework/Data/ActiveRecord/Relations')

diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php b/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php
index a86fdffd..bb2cc583 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php
@@ -1,4 +1,4 @@
-<?php
+<?php
 
 /**
  * Loads base active record relations class.
@@ -75,18 +75,28 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation
 		$finder = $this->getContext()->getForeignRecordFinder();
 		$command = $this->createCommand($criteria, $foreignKeys,$indexValues,$sourceKeys);
 		$srcProps = array_keys($sourceKeys);
-		$type = get_class($finder);
 		$collections=array();
 		foreach($command->query() as $row)
 		{
 			$hash = $this->getObjectHash($row, $srcProps);
 			foreach($srcProps as $column)
 				unset($row[$column]);
-			$collections[$hash][] = $finder->populateObject($type,$row);
+			$collections[$hash][] = $this->populateObject($finder, $row);
 		}
 
 		$this->setResultCollection($results, $collections, array_values($sourceKeys));
 	}
+	
+	protected function populateObject($finder, $data)
+	{
+		$registry = $finder->getRecordManager()->getObjectStateRegistry();
+		if(!is_null($obj = $registry->getCachedInstance($data, false)))
+			return $obj;
+		$gateway = $finder->getRecordManager()->getRecordGateway();
+		$type = get_class($finder);
+		$obj = new $type($data);
+		return $registry->addCachedInstance($data,$obj);
+	}
 
 	/**
 	 * @param TSqlCriteria
@@ -145,5 +155,5 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation
 
 		return "INNER JOIN {$refTable} ON ({$joinCondition}) AND {$index}";
 	}
-}
+}
 ?>
\ No newline at end of file
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php b/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php
index e8c2ccee..4286254b 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php
@@ -18,10 +18,63 @@ 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. 
+ * related to the source object. The HAS_ONE relation is very similar to the
+ * HAS_MANY relationship (in fact, it is equivalent in the entities relationship point of view).
  *
+ * The difference of HAS_ONE from HAS_MANY is that the foreign object is singular. 
+ * That is, HAS_MANY will return a collection of records while HAS_ONE returns the
+ * corresponding record.
  *
+ * Consider the <b>entity</b> relationship between a Car and a Engine.
+ * <code>
+ * +-----+            +--------+
+ * | Car | 1 <----- 1 | Engine |
+ * +-----+            +--------+
+ * </code>
+ * Where each engine belongs to only one car, that is, the Engine entity has
+ * a foreign key to the Car's primary key. We may model 
+ * Engine-Car <b>object</b> relationship as active record as follows.
+ * <code>
+ * class CarRecord extends TActiveRecord
+ * {
+ *     const TABLE='car';
+ *     public $car_id; //primary key
+ *     public $colour;
+ *
+ *     public $engine; //engine foreign object
+ *
+ *     protected static $RELATIONS=array(
+ *         'engine' => array(self::HAS_ONE, 'EngineRecord'));
+ *
+ *	   public static function finder($className=__CLASS__)
+ *	   {
+ *		   return parent::finder($className);
+ *	   }
+ * }
+ * class EngineRecord extends TActiveRecord
+ * {
+ *     const TABLE='engine';
+ *     public $engine_id;
+ *     public $capacity;
+ *     public $car_id; //foreign key to cars
  * 
+ *	   public static function finder($className=__CLASS__)
+ *	   {
+ *		   return parent::finder($className);
+ *	   }
+ * }
+ * </code>
+ * The <tt>$RELATIONS</tt> static property of CarRecord defines that the
+ * property <tt>$engine</tt> that will reference an <tt>EngineRecord</tt> instance.
+ *
+ * The car record with engine property list may be fetched as follows.
+ * <code>
+ * $cars = CarRecord::finder()->with_engine()->findAll();
+ * </code>
+ * The method <tt>with_xxx()</tt> (where <tt>xxx</tt> is the relationship property
+ * name, in this case, <tt>engine</tt>) fetchs the corresponding EngineRecords 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_engine('capacity < ?', 3.8)</tt>.
  *
  * @author Wei Zhuo <weizho[at]gmail[dot]com>
  * @version $Id$
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php b/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php
index a33e105e..033d7638 100644
--- a/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php
+++ b/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php
@@ -1,4 +1,4 @@
-<?php
+<?php
 /**
  * TActiveRecordRelationContext class.
  *
@@ -156,9 +156,9 @@ class TActiveRecordRelationContext
 				Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordBelongsTo');
 				return new TActiveRecordBelongsTo($this);
 			default:
-				throw new TException('Not done yet');
+				throw new TActiveRecordException('ar_invalid_relationship');
 		}
 	}
 }
-
+
 ?>
\ No newline at end of file
-- 
cgit v1.2.3