From ea0601cdd4a732fc15b83104a47788989bb004b3 Mon Sep 17 00:00:00 2001
From: wei <>
Date: Mon, 30 Apr 2007 03:44:49 +0000
Subject: Reverted TActiveRecord::populateObject to protected

---
 .../Relations/TActiveRecordRelationContext.php     | 60 ++++++++++++++++++++++
 1 file changed, 60 insertions(+)

(limited to 'framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php')

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())
-- 
cgit v1.2.3