Packages:
default
System
System.Caching
System.Collections
System.Data
System.Data.ActiveRecord
System.Data.ActiveRecord.Relations
System.Data.ActiveRecord.Scaffold
System.Data.ActiveReecord.Scaffold.InputBuilder
System.Data.Commom.Sqlite
System.Data.Common
System.Data.Common.Mssql
System.Data.Common.Mysql
System.Data.Common.Oracle
System.Data.Common.Pgsql
System.Data.Common.Sqlite
System.Data.DataGateway
System.Data.SqlMap
System.Data.SqlMap.Configuration
System.Data.SqlMap.Statements
System.Exceptions
System.I18N
System.IO
System.Security
System.Util
System.Web
System.Web.Services
System.Web.UI
System.Web.UI.ActiveControls
System.Web.UI.WebControls
System.Web.UI.WebControls.assets
System.Xml

Classes:

TActiveRecordBelongsTo
TActiveRecordHasMany
TActiveRecordHasManyAssociation
TActiveRecordHasOne
TActiveRecordRelation
TActiveRecordRelationContext

Class TActiveRecordHasManyAssociation

TActiveRecordRelation
   |
   --TActiveRecordHasManyAssociation

Implements the M-N (many to many) relationship via association table.

Consider the entity relationship between Articles and Categories via the association table <tt>Article_Category</tt>.

 +---------+            +------------------+            +----------+
 | Article | * -----> * | Article_Category | * <----- * | Category |
 +---------+            +------------------+            +----------+

Where one article may have 0 or more categories and each category may have 0 or more articles. We may model Article-Category object relationship as active record as follows.

 class ArticleRecord
 {
     const TABLE='Article';
     public $article_id;
 
     public $Categories=array(); //foreign object collection.
 
     
     public static $RELATIONS = array
     (
         'Categories' => array(self::MANY_TO_MANY, 'CategoryRecord', 'Article_Category')
     );
 
     public static function finder($className=__CLASS__)
     {
         return parent::finder($className);
     }
 }
 class CategoryRecord
 {
     const TABLE='Category';
     public $category_id;
 
     public $Articles=array();
 
     public static $RELATIONS = array
     (
         'Articles' => array(self::MANY_TO_MANY, 'ArticleRecord', 'Article_Category')
     );
 
     public static function finder($className=__CLASS__)
     {
         return parent::finder($className);
     }
 }

The static <tt>$RELATIONS</tt> property of ArticleRecord defines that the property <tt>$Categories</tt> has many <tt>CategoryRecord</tt>s. Similar, the static <tt>$RELATIONS</tt> property of CategoryRecord defines many ArticleRecords.

The articles with categories list may be fetched as follows.

 $articles = TeamRecord::finder()->withCategories()->findAll();

The method <tt>with_xxx()</tt> (where <tt>xxx</tt> is the relationship property name, in this case, <tt>Categories</tt>) fetchs the corresponding CategoryRecords using a second query (not by using a join). The <tt>with_xxx()</tt> accepts the same arguments as other finder methods of TActiveRecord.

Method Summary
protected void	collectForeignObjects ( array &$results) Get the foreign key index values from the results and make calls to the database to find the corresponding foreign objects using association table.
void	createCommand ( TSqlCriteria $criteria, TTableInfo $foreignKeys, array $indexValues, array $sourceKeys)
protected TActiveRecord	createFkObject ( string $type, array $row, array $foreignKeys)
protected void	fetchForeignObjects ( array &$results, array $foreignKeys, mixed $indexValues, mixed $sourceKeys) Fetches the foreign objects using TActiveRecord::findAllByIndex()
protected string	getAssociationJoin ( array $foreignKeys, array $indexValues, array $sourceKeys) SQL inner join for M-N relationship via association table.
protected TDbTableInfo	getAssociationTable ()
protected TDbCommandBuilder	getAssociationTableCommandBuilder ()
protected TDataGatewayCommand	getCommandBuilder ()
protected TDataGatewayCommand	getForeignCommandBuilder ()
protected TDbTableInfo	getForeignTable ()
array	getRelationForeignKeys ()
protected string	getSourceColumns ( array $sourceKeys)
protected TDbTableInfo	getSourceTable ()
boolean	updateAssociatedRecords () Updates the associated foreign objects.

Methods Inherited From TActiveRecordRelation

TActiveRecordRelation::fetchResultsInto(), TActiveRecordRelation::findForeignKeys(), TActiveRecordRelation::findForeignObjects(), TActiveRecordRelation::getContext(), TActiveRecordRelation::getCriteria(), TActiveRecordRelation::getIndexValues(), TActiveRecordRelation::getObjectHash(), TActiveRecordRelation::getSourceRecord(), TActiveRecordRelation::populateResult(), TActiveRecordRelation::setObjectProperty(), TActiveRecordRelation::setResultCollection(), TActiveRecordRelation::__call()

Method Details

collectForeignObjects

protected void collectForeignObjects

(array &$results )

Get the foreign key index values from the results and make calls to the database to find the corresponding foreign objects using association table.

Input
array	&$results	original results.
Output
Exception

createCommand

public void createCommand

(TSqlCriteria $criteria , TTableInfo $foreignKeys , array $indexValues , array $sourceKeys )

Input
TSqlCriteria	$criteria
TTableInfo	$foreignKeys	association table info
array	$indexValues	field names
array	$sourceKeys	field values
Output
Exception

createFkObject

protected TActiveRecord createFkObject

(string $type , array $row , array $foreignKeys )

Input
string	$type	active record class name.
array	$row	row data
array	$foreignKeys	foreign key column names
Output
Exception

fetchForeignObjects

protected void fetchForeignObjects

(array &$results , array $foreignKeys , mixed $indexValues , mixed $sourceKeys )

Fetches the foreign objects using TActiveRecord::findAllByIndex()

Input
array	&$results	field names
array	$foreignKeys	foreign key index values.
mixed	$indexValues
mixed	$sourceKeys
Output
Exception

getAssociationJoin

protected string getAssociationJoin

(array $foreignKeys , array $indexValues , array $sourceKeys )

SQL inner join for M-N relationship via association table.

Input
array	$foreignKeys	foreign table column key names.
array	$indexValues	source table index values.
array	$sourceKeys	source table column names.
Output
string	inner join condition for M-N relationship via association table.
Exception

getAssociationTable

protected TDbTableInfo getAssociationTable

()

Output
TDbTableInfo	association table information.
Exception

getAssociationTableCommandBuilder

protected TDbCommandBuilder getAssociationTableCommandBuilder

()

getCommandBuilder

protected TDataGatewayCommand getCommandBuilder

()

getForeignCommandBuilder

protected TDataGatewayCommand getForeignCommandBuilder

()

getForeignTable

protected TDbTableInfo getForeignTable

()

Output
TDbTableInfo	foreign table information.
Exception

getRelationForeignKeys

public array getRelationForeignKeys

()

Output
array	2 arrays of source keys and foreign keys from the association table.
Exception

getSourceColumns

protected string getSourceColumns

(array $sourceKeys )

Input
array	$sourceKeys	source table column names.
Output
string	comma separated source column names.
Exception

getSourceTable

protected TDbTableInfo getSourceTable

()

Output
TDbTableInfo	source table information.
Exception

updateAssociatedRecords

public boolean updateAssociatedRecords

()

Updates the associated foreign objects.

Output
boolean	true if all update are success (including if no update was required), false otherwise .
Exception