Changeset 2309

Timestamp:

10/07/2007 10:24:07 PM (15 months ago)

Author:

wei

Message:

Allow active records to have multiple foreign key references to the same table. Add TXCache.

Location:

trunk

Files:

• UPGRADE (modified) (1 diff)
• demos/northwind-db/protected/database/Employee.php (modified) (1 diff)
• demos/quickstart/protected/pages/Database/ActiveRecord.page (modified) (6 diffs)
• demos/quickstart/protected/pages/Database/ar_objects.png (modified) (previous)
• demos/quickstart/protected/pages/Database/ar_objects.vsd (modified) (previous)
• demos/quickstart/protected/pages/Database/id/ActiveRecord.page (modified) (4 diffs)
• framework/Caching/TXCache.php (added)
• framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php (modified) (2 diffs)
• framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php (modified) (2 diffs)
• framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php (modified) (5 diffs)
• framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php (modified) (2 diffs)
• framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php (modified) (6 diffs)
• framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php (modified) (9 diffs)
• framework/Data/ActiveRecord/TActiveRecord.php (modified) (3 diffs)
• tests/simple_unit/ActiveRecord/ForeignKeyTestCase.php (modified) (4 diffs)
• tests/simple_unit/ActiveRecord/ForeignObjectUpdateTest.php (modified) (3 diffs)
• tests/simple_unit/ActiveRecord/MultipleForeignKeyTestCase.php (added)
• tests/simple_unit/ActiveRecord/records/ItemRecord.php (modified) (1 diff)
• tests/simple_unit/ActiveRecord/test1.sqlite (added)
• tests/test_tools/simpletest/test_case.php (modified) (1 diff)

trunk/UPGRADE

@@ -12 +12 @@
 Upgrading from v3.1.1
 ---------------------
+- The RELATIONS type declaration in Active Record classes for Many-to-Many using
+  an association table was change from "self::HAS_MANY" to "self::MANY_TO_MANY".
+  E.g. change 
+     'albums' => array(self::HAS_MANY, 'Artist', 'album_artists')
+  to
+     'albums' => array(self::MANY_TO_MANY, 'Artist', 'album_artists')
+
 
 Upgrading from v3.1.0

trunk/demos/northwind-db/protected/database/Employee.php

@@ -33 +33 @@
         public static $RELATIONS = array
         (
-                'Territories' => array(self::HAS_MANY, 'Territory', 'EmployeeTerritories'),
+                'Territories' => array(self::MANY_TO_MANY, 'Territory', 'EmployeeTerritories'),
                 'Orders' => array(self::HAS_MANY, 'Order'),
 

trunk/demos/quickstart/protected/pages/Database/ActiveRecord.page

@@ -658 +658 @@
 
 <div class="info"><b class="note">Info:</b>
-Active Record supports multiple table foreign key relationships with the restriction
-that each relationship corresponds to a unique table. For example, the <tt>Players</tt>
-table may only have one set of foreign key relationship with table <tt>Teams</tt>, it may
-have other relationships that corresponds to other tables (including the <tt>Players</tt> table itself).
+Since version <b>3.1.2</b>, Active Record supports multiple foreign key 
+references of the same table. Ambiguity between multiple foreign key references to the same table is
+resolved by providing the foreign key column name as the 3rd parameter in the relationship array. 
+For example, both the following foreign keys <tt>owner_id</tt> and <tt>reporter_id</tt>
+references the same table defined in <tt>UserRecord</tt>.
+<com:TTextHighlighter Language="php" CssClass="source block-content">
+class TicketRecord extends TActiveRecord
+{
+     public $owner_id;
+         public $reporter_id;
+
+     public $owner;
+         public $reporter;
+
+         public static $RELATION=array
+         (
+             'owner' => array(self::BELONGS_TO, 'UserRecord', 'owner_id'),
+                 'reporter' => array(self::BELONGS_TO, 'UserRecord', 'reporter_id'),
+         );
+}
+</com:TTextHighlighter>
+This is applicable to relationships including <tt>BELONGS_TO</tt>, <tt>HAS_ONE</tt> and
+<tt>HAS_MANY</tt>. See section <a href="#142021">Self Referenced Association Tables</a> for solving ambiguity of <tt>MANY_TO_MANY</tt> 
+relationships.
 </div>
 
@@ -714 +734 @@
     (
         'team' => array(self::BELONGS_TO, 'TeamRecord'),
-        'skills' => array(self::HAS_MANY, 'SkillRecord', 'Player_Skills'),
+        'skills' => array(self::MANY_TO_MANY, 'SkillRecord', 'Player_Skills'),
         'profile' => array(self::HAS_ONE, 'ProfileRecord'),
     );
@@ -851 +871 @@
 
 <p id="710035" class="block-content">The Prado Active Record design implements the two stage approach. For the
-<tt>Players</tt>-<tt>Skills</tt> M-N (many-to-many) entity relationship, we need
-to define a <b>has many</b> relationship in the <tt>PlayerRecord</tt> class and
-in addition define a <b>has many</b> relationship in the <tt>SkillRecord</tt> class as well.
+<tt>Players</tt>-<tt>Skills</tt> M-N (many-to-many) entity relationship, we 
+define a <b>many-to-many</b> relationship in the <tt>PlayerRecord</tt> class and
+in addition we may define a <b>many-to-many</b> relationship in the <tt>SkillRecord</tt> class as well.
 The following sample code defines the complete <tt>SkillRecord</tt> class with a
 many-to-many relationship with the <tt>PlayerRecord</tt> class. (See the <tt>PlayerRecord</tt>
@@ -870 +890 @@
     public static $RELATIONS=array
     (
-        'players' => array(self::HAS_MANY, 'PlayerRecord', 'Player_Skills'),
+        'players' => array(self::MANY_TO_MANY, 'PlayerRecord', 'Player_Skills'),
     );
 
@@ -883 +903 @@
 The static <tt>$RELATIONS</tt> property of SkillRecord defines that the
 property <tt>$players</tt> has many <tt>PlayerRecord</tt>s via an association table '<tt>Player_Skills</tt>'.
-In <tt>array(self::HAS_MANY, 'PlayerRecord', 'Player_Skills')</tt>, the first element defines the
-relationship type, in this case <strong><tt>self::HAS_MANY</tt></strong>,
+In <tt>array(self::MANY_TO_MANY, 'PlayerRecord', 'Player_Skills')</tt>, the first element defines the
+relationship type, in this case <strong><tt>self::MANY_TO_MANY</tt></strong>,
 the second element is a string <tt>'PlayerRecord'</tt> that corresponds to the
 class name of the <tt>PlayerRecord</tt> class, and the third element is the name
 of the association table name.
 </p>
+
+<div class="note"><b class="note">Note:</b>
+Prior to version <b>3.1.2</b> (versions up to 3.1.1), the many-to-many relationship was 
+defined using <tt>self::HAS_MANY</tt>. For version <b>3.1.2</b> onwards, this must be changed
+to <tt>self::MANY_TO_MANY</tt>. This can be done by searching for the <tt>HAS_MANY</tt> in your
+source code and carfully changing the appropriate definitions. 
+</div>
+
 <p id="710037" class="block-content">
 A list of player objects with the corresponding collection of skill objects may be fetched as follows.
@@ -952 +980 @@
     public static $RELATIONS=array
     (
-        'related_items' => array(self::HAS_MANY,
+        'related_items' => array(self::MANY_TO_MANY,
             'Item', 'related_items.related_item_id'),
     );

trunk/demos/quickstart/protected/pages/Database/id/ActiveRecord.page

@@ -616 +616 @@
     (
         'team' => array(self::BELONGS_TO, 'TeamRecord'),
-        'skills' => array(self::HAS_MANY, 'SkillRecord', 'Player_Skills'),
+        'skills' => array(self::MANY_TO_MANY, 'SkillRecord', 'Player_Skills'),
         'profile' => array(self::HAS_ONE, 'ProfileRecord'),
     );
@@ -738 +738 @@
     public static $RELATIONS=array
     (
-        'players' => array(self::HAS_MANY, 'PlayerRecord', 'Player_Skills'),
+        'players' => array(self::MANY_TO_MANY, 'PlayerRecord', 'Player_Skills'),
     );
 
@@ -750 +750 @@
 <p id="710036" class="block-content">
 Properti statis <tt>$RELATIONS</tt> dari SkillRecord mendefinisikan bahwa properti <tt>$players</tt> memiliki banyak <tt>PlayerRecord</tt>s melalui tabel asosiasi '<tt>Player_Skills</tt>'.
-Dalam <tt>array(self::HAS_MANY, 'PlayerRecord', 'Player_Skills')</tt>, elemen pertama mendefinisikan tipe hubungan, dalam hal ini <strong><tt>self::HAS_MANY</tt></strong>,
+Dalam <tt>array(self::MANY_TO_MANY, 'PlayerRecord', 'Player_Skills')</tt>, elemen pertama mendefinisikan tipe hubungan, dalam hal ini <strong><tt>self::HAS_MANY</tt></strong>,
 elemen kedua adalah string <tt>'PlayerRecord'</tt> yang terkait ke nama kelas dari kelas <tt>PlayerRecord</tt>, dan elemen ketiga adalah nama dari nama tabel asosiasi. 
 </p>
@@ -806 +806 @@
     public static $RELATIONS=array
     (
-        'related_items' => array(self::HAS_MANY, 
+        'related_items' => array(self::MANY_TO_MANY, 
             'Item', 'related_items.related_item_id'),
     );

trunk/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php

@@ -78 +78 @@
         protected function collectForeignObjects(&$results)
         {
-                $fkObject = $this->getContext()->getForeignRecordFinder();
-                $fkeys = $this->findForeignKeys($this->getSourceRecord(),$fkObject);
+                $fkeys = $this->getRelationForeignKeys();
 
                 $properties = array_keys($fkeys);
@@ -87 +86 @@
                 $fkObjects = $this->findForeignObjects($fields, $indexValues);
                 $this->populateResult($results,$properties,$fkObjects,$fields);
+        }
+        
+        /**
+         * @return array foreign key field names as key and object properties as value.
+         * @since 3.1.2
+         */
+        public function getRelationForeignKeys()
+        {
+                $fkObject = $this->getContext()->getForeignRecordFinder();
+                return $this->findForeignKeys($this->getSourceRecord(),$fkObject);              
         }
 

trunk/framework/Data/ActiveRecord/Relations/TActiveRecordHasMany.php

@@ -76 +76 @@
         protected function collectForeignObjects(&$results)
         {
-                $fkObject = $this->getContext()->getForeignRecordFinder();
-                $fkeys = $this->findForeignKeys($fkObject, $this->getSourceRecord());
+                $fkeys = $this->getRelationForeignKeys();
 
                 $properties = array_values($fkeys);
@@ -85 +84 @@
                 $fkObjects = $this->findForeignObjects($fields,$indexValues);
                 $this->populateResult($results,$properties,$fkObjects,$fields);
+        }
+
+        /**
+         * @return array foreign key field names as key and object properties as value.
+         * @since 3.1.2
+         */     
+        public function getRelationForeignKeys()
+        {
+                $fkObject = $this->getContext()->getForeignRecordFinder();
+                return $this->findForeignKeys($fkObject, $this->getSourceRecord());
         }
 

trunk/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php

@@ -38 +38 @@
  *     public static $RELATIONS = array
  *     (
- *         'Categories' => array(self::HAS_MANY, 'CategoryRecord', 'Article_Category')
+ *         'Categories' => array(self::MANY_TO_MANY, 'CategoryRecord', 'Article_Category')
  *     );
  *
@@ -55 +55 @@
  *     public static $RELATIONS = array
  *     (
- *         'Articles' => array(self::HAS_MANY, 'ArticleRecord', 'Article_Category')
+ *         'Articles' => array(self::MANY_TO_MANY, 'ArticleRecord', 'Article_Category')
  *     );
  *
@@ -97 +97 @@
         protected function collectForeignObjects(&$results)
         {
+                list($sourceKeys, $foreignKeys) = $this->getRelationForeignKeys();
+                $properties = array_values($sourceKeys);
+                $indexValues = $this->getIndexValues($properties, $results);
+                $this->fetchForeignObjects($results, $foreignKeys,$indexValues,$sourceKeys);
+        }
+
+        /**
+         * @return array 2 arrays of source keys and foreign keys from the association table.
+         */
+        public function getRelationForeignKeys()
+        {
                 $association = $this->getAssociationTable();
-                $sourceKeys = $this->findForeignKeys($association, $this->getSourceRecord());
-
-                $properties = array_values($sourceKeys);
-
-                $indexValues = $this->getIndexValues($properties, $results);
-
+                $sourceKeys = $this->findForeignKeys($association, $this->getSourceRecord(), true);
                 $fkObject = $this->getContext()->getForeignRecordFinder();
                 $foreignKeys = $this->findForeignKeys($association, $fkObject);
-
-                $this->fetchForeignObjects($results, $foreignKeys,$indexValues,$sourceKeys);
+                return array($sourceKeys, $foreignKeys);
         }
 
@@ -183 +188 @@
         protected function fetchForeignObjects(&$results,$foreignKeys,$indexValues,$sourceKeys)
         {
-                $criteria = $this->getContext()->getCriteria();
+                $criteria = $this->getCriteria();
                 $finder = $this->getContext()->getForeignRecordFinder();
                 $registry = $finder->getRecordManager()->getObjectStateRegistry();
@@ -199 +204 @@
                         $registry->registerClean($obj);
                 }
-
                 $this->setResultCollection($results, $collections, array_values($sourceKeys));
         }

trunk/framework/Data/ActiveRecord/Relations/TActiveRecordHasOne.php

@@ -93 +93 @@
         protected function collectForeignObjects(&$results)
         {
-                $fkObject = $this->getContext()->getForeignRecordFinder();
-                $fkeys = $this->findForeignKeys($fkObject, $this->getSourceRecord());
-
+                $fkeys = $this->getRelationForeignKeys();
                 $properties = array_values($fkeys);
                 $fields = array_keys($fkeys);
@@ -102 +100 @@
                 $fkObjects = $this->findForeignObjects($fields,$indexValues);
                 $this->populateResult($results,$properties,$fkObjects,$fields);
+        }
+        
+        /**
+         * @return array foreign key field names as key and object properties as value.
+         * @since 3.1.2
+         */
+        public function getRelationForeignKeys()
+        {
+                $fkObject = $this->getContext()->getForeignRecordFinder();
+                return $this->findForeignKeys($fkObject, $this->getSourceRecord());
         }
 

trunk/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php

@@ -27 +27 @@
 {
         private $_context;
-
-        public function __construct(TActiveRecordRelationContext $context)
+        private $_criteria;
+
+        public function __construct(TActiveRecordRelationContext $context, $criteria)
         {
                 $this->_context = $context;
+                $this->_criteria = $criteria;
         }
 
@@ -39 +41 @@
         {
                 return $this->_context;
+        }
+        
+        /**
+         * @return TActiveRecordCriteria
+         */
+        protected function getCriteria()
+        {
+                return $this->_criteria;
         }
 
@@ -76 +86 @@
                 return $results;
         }
+        
+        /**
+         * Fetch results for current relationship.
+         * @return boolean always true.
+         */
+        public function fetchResultsInto($obj)
+        {
+                $this->collectForeignObjects($obj);
+                return true;
+        }
 
         /**
@@ -85 +105 @@
          * @return array foreign keys with source column names as key and foreign column names as value.
          */
-        protected function findForeignKeys($from, $matchesRecord)
+        protected function findForeignKeys($from, $matchesRecord, $loose=false)
         {
                 $gateway = $matchesRecord->getRecordGateway();
@@ -94 +114 @@
                 foreach($tableInfo->getForeignKeys() as $fkeys)
                 {
-                        if($fkeys['table']===$matchingTableName)
-                                return $fkeys['keys'];
+                        if(strtolower($fkeys['table'])===strtolower($matchingTableName))
+                        {
+                                if(!$loose && $this->getContext()->hasFkField())
+                                        return $this->getFkFields($fkeys['keys']);
+                                else
+                                        return $fkeys['keys'];
+                        }
                 }
                 $matching = $gateway->getRecordTableInfo($matchesRecord)->getTableFullName();
                 throw new TActiveRecordException('ar_relations_missing_fk',
                         $tableInfo->getTableFullName(), $matching);
+        }
+        
+        /**
+         * @return array foreign key field names as key and object properties as value.
+         * @since 3.1.2  
+         */
+        abstract public function getRelationForeignKeys();
+        
+        /**
+         * Find matching foreign key fields from the 3rd element of an entry in TActiveRecord::$RELATION.
+         * Assume field names consist of [\w-] character sets. Prefix to the field names ending with a dot
+         * are ignored.
+         */
+        private function getFkFields($fkeys)
+        {
+                $matching = array();
+                preg_match_all('/\s*(\S+\.)?([\w-]+)\s*/', $this->getContext()->getFkField(), $matching);
+                $fields = array();
+                foreach($fkeys as $fkName => $field)
+                {
+                        if(in_array($fkName, $matching[2]))
+                                $fields[$fkName] = $field;
+                }
+                return $fields;
         }
 
@@ -123 +172 @@
         protected function findForeignObjects($fields, $indexValues)
         {
-                $criteria = $this->getContext()->getCriteria();
                 $finder = $this->getContext()->getForeignRecordFinder();
-                return $finder->findAllByIndex($criteria, $fields, $indexValues);
+                return $finder->findAllByIndex($this->_criteria, $fields, $indexValues);
         }
 

trunk/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php

@@ -33 +33 @@
         private $_property;
         private $_sourceRecord;
-        private $_criteria;
-        private $_relation;
-
-        public function __construct($source, $property=null, $criteria=null)
+        private $_relation; //data from an entry of TActiveRecord::$RELATION
+        private $_fkeys;
+
+        public function __construct($source, $property=null)
         {
                 $this->_sourceRecord=$source;
-                $this->_criteria=$criteria;
                 if($property!==null)
                         list($this->_property, $this->_relation) = $this->getSourceRecordRelation($property);
@@ -49 +48 @@
          * @param string relation property name
          * @return array array($propertyName, $relation) relation definition.
-         * @throws TActiveRecordException if property is not defined or missing.
          */
         protected function getSourceRecordRelation($property)
@@ -59 +57 @@
                                 return array($name, $relation);
                 }
-                throw new TActiveRecordException('ar_undefined_relation_prop',
-                        $property, get_class($this->_sourceRecord), self::RELATIONS_CONST);
         }
 
@@ -72 +68 @@
         }
 
+        /**
+         * @return boolean true if the relation is defined in TActiveRecord::$RELATIONS
+         * @since 3.1.2
+         */
+        public function hasRecordRelation()
+        {
+                return $this->_relation!==null;
+        }
+
         public function getPropertyValue()
         {
@@ -87 +92 @@
 
         /**
-         * @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.
          */
@@ -111 +108 @@
 
         /**
+         * @return array foreign key of this relations, the keys is dependent on the
+         * relationship type.
+         * @since 3.1.2
+         */
+        public function getRelationForeignKeys()
+        {
+                if($this->_fkeys===null)
+                        $this->_fkeys=$this->getRelationHandler()->getRelationForeignKeys();
+                return $this->_fkeys;
+        }
+
+        /**
          * @return string HAS_MANY, HAS_ONE, or BELONGS_TO
          */
@@ -119 +128 @@
 
         /**
+         * @return string foreign key field names, comma delimited.
+         * @since 3.1.2
+         */
+        public function getFkField()
+        {
+                return $this->_relation[2];
+        }
+
+        /**
+         * @return boolean true if the 3rd element of an TActiveRecord::$RELATION entry is set.
+         * @since 3.1.2
+         */
+        public function hasFkField()
+        {
+                $notManyToMany = $this->getRelationType() !== TActiveRecord::MANY_TO_MANY;
+                return $notManyToMany && isset($this->_relation[2]) && !empty($this->_relation[2]);
+        }
+
+        /**
          * @return string the M-N relationship association table name.
          */
@@ -131 +159 @@
         public function hasAssociationTable()
         {
-                return isset($this->_relation[2]);
+                $isManyToMany = $this->getRelationType() === TActiveRecord::MANY_TO_MANY;
+                return $isManyToMany && isset($this->_relation[2]) && !empty($this->_relation[2]);
         }
 
@@ -146 +175 @@
          * An instance of TActiveRecordHasOne, TActiveRecordBelongsTo, TActiveRecordHasMany,
          * or TActiveRecordHasManyAssocation will be returned.
+         * @param TActiveRecordCriteria search criteria
          * @return TActiveRecordRelation record relationship handler instnace.
-         */
-        public function getRelationHandler()
-        {
+         * @throws TActiveRecordException if property is not defined or missing.
+         */
+        public function getRelationHandler($criteria=null)
+        {
+                if(!$this->hasRecordRelation())
+                {
+                        throw new TActiveRecordException('ar_undefined_relation_prop',
+                                $property, get_class($this->_sourceRecord), self::RELATIONS_CONST);
+                }
+                if($criteria===null)
+                        $criteria = new TActiveRecordCriteria;
                 switch($this->getRelationType())
                 {
                         case TActiveRecord::HAS_MANY:
-                                if(!$this->hasAssociationTable())
-                                {
-                                        Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordHasMany');
-                                        return new TActiveRecordHasMany($this);
-                &nb