- Memory optimization: no longer store all DBObjects in memory while browsng through a Set, but pull them one by one from the MySQL client buffer as needed.

- Also renamed Merge to Append since it's really what it does (seems to be used only in the tests)

git-svn-id: http://svn.code.sf.net/p/itop/code/trunk@3142 a333f486-631f-4898-b8df-5754b55c2be0

core/dbobjectset.class.php

@@ -1,5 +1,5 @@
 <?php
-// Copyright (C) 2010-2013 Combodo SARL
+// Copyright (C) 2010-2014 Combodo SARL
 //
 //   This file is part of iTop.
 //
@@ -26,20 +26,34 @@
 
 
 /**
- * A set of persistent objects, could be heterogeneous 
+ * A set of persistent objects, could be heterogeneous as long as the objects in the set have a common ancestor class 
  *
  * @package     iTopORM
  */
 class DBObjectSet
 {
-	private $m_oFilter;
-	private $m_aAddedIds; // Ids of objects added (discrete lists)
-	private $m_aOrderBy;
+	protected $m_aAddedIds; // Ids of objects added (discrete lists)
+	protected $m_aAddedObjects;
+	protected $m_aArgs;
+	protected $m_aAttToLoad;
+	protected $m_aOrderBy;
 	public $m_bLoaded;
-	private $m_aData;
-	private $m_aId2Row;
-	private $m_iCurrRow;
+	protected $m_iNumTotalDBRows;
+	protected $m_iNumLoadedDBRows;
+	protected $m_iCurrRow;
+	protected $m_oFilter;
+	protected $m_oSQLResult;
 
+	/**
+	 * Create a new set based on a Search definition.
+	 * 
+	 * @param DBObjectSearch $oFilter The search filter defining the objects which are part of the set (multiple columns/objects per row are supported)
+	 * @param hash $aOrderBy
+	 * @param hash $aArgs Values to substitute for the search/query parameters (if any). Format: param_name => value
+	 * @param hash $aExtendedDataSpec
+	 * @param int $iLimitCount Maximum number of rows to load (i.e. equivalent to MySQL's LIMIT start, count)
+	 * @param int $iLimitStart Index of the first row to load (i.e. equivalent to MySQL's LIMIT start, count)
+	 */
 	public function __construct(DBObjectSearch $oFilter, $aOrderBy = array(), $aArgs = array(), $aExtendedDataSpec = null, $iLimitCount = 0, $iLimitStart = 0)
 	{
 		$this->m_oFilter = $oFilter->DeepClone();
@@ -51,15 +65,20 @@ class DBObjectSet
 		$this->m_iLimitCount = $iLimitCount;
 		$this->m_iLimitStart = $iLimitStart;
 
-		$this->m_iCount = null; // null if unknown yet
+		$this->m_iNumTotalDBRows = null; // Total number of rows for the query without LIMIT. null if unknown yet
+		$this->m_iNumLoadedDBRows = 0; // Total number of rows LOADED in $this->m_oSQLResult via a SQL query. 0 by default
 		$this->m_bLoaded = false; // true when the filter has been used OR the set is built step by step (AddObject...)
-		$this->m_aData = array(); // array of (row => array of (classalias) => object/null)
-		$this->m_aId2Row = array(); // array of (pkey => index in m_aData)
+		$this->m_aAddedObjects = array(); // array of (row => array of (classalias) => object/null) storing the objects added "in memory"
 		$this->m_iCurrRow = 0;
+		$this->m_oSQLResult = null;
 	}
 
 	public function __destruct()
 	{
+		if (is_object($this->m_oSQLResult))
+		{
+			$this->m_oSQLResult->free();
+		}
 	}
 
 	public function __toString()
@@ -82,6 +101,13 @@ class DBObjectSet
 		return $sRet;
 	}
 
+	/**
+	 * Specify the subset of attributes to load (for each class of objects) before performing the SQL query for retrieving the rows from the DB
+	 * 
+	 * @param hash $aAttToLoad Format: alias => array of attribute_codes
+	 * 
+	 * @return void
+	 */
 	public function OptimizeColumnLoad($aAttToLoad)
 	{
 		if (is_null($aAttToLoad))
@@ -125,6 +151,13 @@ class DBObjectSet
 		}
 	}
 
+	/**
+	 * Create a set (in-memory) containing just the given object
+	 * 
+	 * @param DBobject $oObject
+	 * 
+	 * @return DBObjectSet The singleton set
+	 */
 	static public function FromObject($oObject)
 	{
 		$oRetSet = self::FromScratch(get_class($oObject));
@@ -132,17 +165,31 @@ class DBObjectSet
 		return $oRetSet;
 	}
 
+	/**
+	 * Create an empty set (in-memory), for the given class (and its subclasses) of objects
+	 * 
+	 * @param string $sClass The class (or an ancestor) for the objects to be added in this set
+	 * 
+	 * @return DBObject The empty set
+	 */
 	static public function FromScratch($sClass)
 	{
 		$oFilter = new DBObjectSearch($sClass);
 		$oFilter->AddConditionExpression(new FalseExpression());
 		$oRetSet = new self($oFilter);
 		$oRetSet->m_bLoaded = true; // no DB load
+		$oRetSet->m_iNumTotalDBRows = 0; // Nothing from the DB
 		return $oRetSet;
 	} 
 
-	// create an object set ex nihilo
-	// input = array of objects
+	/**
+	 * Create a set (in-memory) with just one column (i.e. one object per row) and filled with the given array of objects
+	 * 
+	 * @param string $sClass The class of the objects (must be a common ancestor to all objects in the set)
+	 * @param array $aObjects The list of objects to add into the set
+	 * 
+	 * @return DBObjectSet
+	 */
 	static public function FromArray($sClass, $aObjects)
 	{
 		$oRetSet = self::FromScratch($sClass);
@@ -150,21 +197,30 @@ class DBObjectSet
 		return $oRetSet;
 	} 
 
-	// create an object set ex nihilo
-	// aClasses = array of (alias => class)
-	// input = array of (array of (classalias => object))
+	/**
+	 * Create a set in-memory with several classes of objects per row (with one alias per "column")
+	 * 
+	 * Limitation:
+	 * The filter/OQL query representing such a set can not be rebuilt (only the first column will be taken into account)
+	 * 
+	 * @param hash $aClasses Format: array of (alias => class)
+	 * @param hash $aObjects Format: array of (array of (classalias => object))
+	 * 
+	 * @return DBObjectSet
+	 */
 	static public function FromArrayAssoc($aClasses, $aObjects)
 	{
 		// In a perfect world, we should create a complete tree of DBObjectSearch,
 		// but as we lack most of the information related to the objects,
-		// let's create one search definition
+		// let's create one search definition corresponding only to the first column
 		$sClass = reset($aClasses);
 		$sAlias = key($aClasses);
 		$oFilter = new CMDBSearchFilter($sClass, $sAlias);
 
 		$oRetSet = new self($oFilter);
 		$oRetSet->m_bLoaded = true; // no DB load
-
+		$oRetSet->m_iNumTotalDBRows = 0; // Nothing from the DB
+		
 		foreach($aObjects as $rowIndex => $aObjectsByClassAlias)
 		{
 			$oRetSet->AddObjectExtended($aObjectsByClassAlias);
@@ -209,11 +265,13 @@ class DBObjectSet
 	public function ToArrayOfValues()
 	{
 		if (!$this->m_bLoaded) $this->Load();
+		$this->Rewind();
 
 		$aSelectedClasses = $this->m_oFilter->GetSelectedClasses();
 
 		$aRet = array();
-		foreach($this->m_aData as $iRow => $aObjects)
+		$iRow = 0;
+		while($aObjects = $this->FetchAssoc())
 		{
 			foreach($aObjects as $sClassAlias => $oObject)
 			{
@@ -249,6 +307,7 @@ class DBObjectSet
 					}
 				}
 			}
+			$iRow++;
 		}
 		return $aRet;
 	} 
@@ -271,6 +330,14 @@ class DBObjectSet
 		return $aRet;
 	}
 
+	/**
+	 * Retrieve the DBObjectSearch corresponding to the objects present in this set
+	 * 
+	 * Limitation:
+	 * This method will NOT work for sets with several columns (i.e. several objects per row)
+	 * 
+	 * @return DBObjectSearch
+	 */
 	public function GetFilter()
 	{
 		// Make sure that we carry on the parameters of the set with the filter
@@ -293,37 +360,72 @@ class DBObjectSet
 		}
 	}
 
+	/**
+	 * The (common ancestor) class of the objects in the first column of this set
+	 * 
+	 * @return string The class of the objects in the first column
+	 */
 	public function GetClass()
 	{
 		return $this->m_oFilter->GetClass();
 	}
 
+	/**
+	 * The alias for the class of the objects in the first column of this set
+	 * 
+	 * @return string The alias of the class in the first column
+	 */
 	public function GetClassAlias()
 	{
 		return $this->m_oFilter->GetClassAlias();
 	}
 
+	/**
+	 * The list of all classes (one per column) which are part of this set
+	 * 
+	 * @return hash Format: alias => class
+	 */
 	public function GetSelectedClasses()
 	{
 		return $this->m_oFilter->GetSelectedClasses();
 	}
 
+	/**
+	 * The root class (i.e. highest ancestor in the MeaModel class hierarchy) for the first column on this set
+	 * 
+	 * @return string The root class for the objects in the first column of the set
+	 */
 	public function GetRootClass()
 	{
 		return MetaModel::GetRootClass($this->GetClass());
 	}
 
+	/**
+	 * The arguments used for building this set
+	 * 
+	 * @return hash Format: parameter_name => value
+	 */
 	public function GetArgs()
 	{
 		return $this->m_aArgs;
 	}
 
+	/**
+	 * Sets the limits for loading the rows from the DB. Equivalent to MySQL's LIMIT start,count clause.
+	 * @param int $iLimitCount The number of rows to load
+	 * @param int $iLimitStart The index of the first row to load
+	 */
 	public function SetLimit($iLimitCount, $iLimitStart = 0)
 	{
 		$this->m_iLimitCount = $iLimitCount;
 		$this->m_iLimitStart = $iLimitStart;
 	}
 
+	/**
+	 * Sets the sort order for loading the rows from the DB. Changing the order by causes a Reload.
+	 * 
+	 * @param hash $aOrderBy Format: field_code => boolean (true = ascending, false = descending)
+	 */
 	public function SetOrderBy($aOrderBy)
 	{
 		if ($this->m_aOrderBy != $aOrderBy)
@@ -337,16 +439,33 @@ class DBObjectSet
 		}
 	}
 
+	/**
+	 * Returns the 'count' limit for loading the rows from the DB
+	 * 
+	 * @return int
+	 */
 	public function GetLimitCount()
 	{
 		return $this->m_iLimitCount;
 	}
 
+	/**
+	 * Returns the 'start' limit for loading the rows from the DB
+	 * 
+	 * @return int
+	 */
 	public function GetLimitStart()
 	{
 		return $this->m_iLimitStart;
 	}
 
+	/**
+	 * Get the sort order used for loading this set from the database
+	 * 
+	 * Limitation: the sort order has no effect on objects added in-memory
+	 * 
+	 * @return hash Format: field_code => boolean (true = ascending, false = descending)
+	 */
 	public function GetRealSortOrder()
 	{
 		// Get the class default sort order if not specified with the API
@@ -361,6 +480,9 @@ class DBObjectSet
 		}
 	}
 
+	/**
+	 * Loads the set from the database. Actually performs the SQL query to retrieve the records from the DB. 
+	 */
 	public function Load()
 	{
 		if ($this->m_bLoaded) return;
@@ -375,87 +497,149 @@ class DBObjectSet
 		{
 			$sSQL = MetaModel::MakeSelectQuery($this->m_oFilter, $this->GetRealSortOrder(), $this->m_aArgs, $this->m_aAttToLoad, $this->m_aExtendedDataSpec);
 		}
-		$resQuery = CMDBSource::Query($sSQL);
-		if (!$resQuery) return;
-
-		$sClass = $this->m_oFilter->GetClass();
-		while ($aRow = CMDBSource::FetchArray($resQuery))
+		
+		if (is_object($this->m_oSQLResult))
 		{
-			$aObjects = array();
-			foreach ($this->m_oFilter->GetSelectedClasses() as $sClassAlias => $sClass)
-			{
-				if (is_null($aRow[$sClassAlias.'id']))
-				{
-					$oObject = null;
-				}
-				else
-				{
-					$oObject = MetaModel::GetObjectByRow($sClass, $aRow, $sClassAlias, $this->m_aAttToLoad, $this->m_aExtendedDataSpec);
-				}
-
-				$aObjects[$sClassAlias] = $oObject;
-			}
-			$this->AddObjectExtended($aObjects, true /* internal load */);
+			// Free previous resultset if any
+			$this->m_oSQLResult->free();
+		}
+		$this->m_iNumTotalDBRows = null;
+		
+		$this->m_oSQLResult = CMDBSource::Query($sSQL);
+		if ($this->m_oSQLResult === false) return;
+		
+		if (($this->m_iLimitCount == 0) && ($this->m_iLimitStart == 0))
+		{
+			$this->m_iNumTotalDBRows = $this->m_oSQLResult->num_rows;
 		}
-		CMDBSource::FreeResult($resQuery);
+		$this->m_iNumLoadedDBRows = $this->m_oSQLResult->num_rows;
 	}
 
+	/**
+	 * The total number of rows in this set. Independently of the SetLimit used for loading the set and taking into account the rows added in-memory.
+	 * 
+	 * May actually perform the SQL query SELECT COUNT... if the set was not previously loaded, or loaded with a SetLimit
+	 * 
+	 * @return int The total number of rows for this set.
+	 */
 	public function Count()
 	{
-		if ($this->m_bLoaded && ($this->m_iLimitCount == 0) && ($this->m_iLimitStart == 0))
-		{
-			return count($this->m_aData);
-		}
-		else
+		if (is_null($this->m_iNumTotalDBRows))
 		{
-			if (is_null($this->m_iCount))
-			{
-				$sSQL = MetaModel::MakeSelectQuery($this->m_oFilter, array(), $this->m_aArgs, null, null, 0, 0, true);
-				$resQuery = CMDBSource::Query($sSQL);
-				if (!$resQuery) return 0;
-		
-				$aRow = CMDBSource::FetchArray($resQuery);
-				CMDBSource::FreeResult($resQuery);
-				$this->m_iCount = $aRow['COUNT'];
-			}
-			return $this->m_iCount; // WARNING this value can be wrong, see Trac #887
+			$sSQL = MetaModel::MakeSelectQuery($this->m_oFilter, array(), $this->m_aArgs, null, null, 0, 0, true);
+			$resQuery = CMDBSource::Query($sSQL);
+			if (!$resQuery) return 0;
+	
+			$aRow = CMDBSource::FetchArray($resQuery);
+			CMDBSource::FreeResult($resQuery);
+			$this->m_iNumTotalDBRows = $aRow['COUNT'];
 		}
+		return $this->m_iNumTotalDBRows + count($this->m_aAddedObjects); // Does it fix Trac #887 ??
+	}
+	
+	/**
+	 * Number of rows available in memory (loaded from DB + added in memory)
+	 * 
+	 * @return number The number of rows available for Fetch'ing
+	 */
+	protected function CountLoaded()
+	{
+		return $this->m_iNumLoadedDBRows + count($this->m_aAddedObjects);
 	}
 
-	public function Fetch($sClassAlias = '')
+	/**
+	 * Fetch the object (with the given class alias) at the current position in the set and move the cursor to the next position.
+	 * 
+	 * @param string $sRequestedClassAlias The class alias to fetch (if there are several objects/classes per row)
+	 * @return DBObject The fetched object or null when at the end
+	 */
+	public function Fetch($sRequestedClassAlias = '')
 	{
 		if (!$this->m_bLoaded) $this->Load();
 
-		if ($this->m_iCurrRow >= count($this->m_aData))
+		if ($this->m_iCurrRow >= $this->CountLoaded())
 		{
 			return null;
 		}
 	
-		if (strlen($sClassAlias) == 0)
+		if (strlen($sRequestedClassAlias) == 0)
 		{
-			$sClassAlias = $this->m_oFilter->GetClassAlias();
+			$sRequestedClassAlias = $this->m_oFilter->GetClassAlias();
+		}
+
+		if ($this->m_iCurrRow < $this->m_iNumLoadedDBRows)
+		{
+			// Pick the row from the database
+			$aRow = CMDBSource::FetchArray($this->m_oSQLResult);
+			foreach ($this->m_oFilter->GetSelectedClasses() as $sClassAlias => $sClass)
+			{
+				if ($sRequestedClassAlias == $sClassAlias)
+				{
+					if (is_null($aRow[$sClassAlias.'id']))
+					{
+						$oRetObj = null;
+					}
+					else
+					{
+						$oRetObj = MetaModel::GetObjectByRow($sClass, $aRow, $sClassAlias, $this->m_aAttToLoad, $this->m_aExtendedDataSpec);
+					}
+					break;
+				}
+			}
+		}
+		else
+		{
+			// Pick the row from the objects added *in memory*
+			$oRetObj = $this->m_aAddedObjects[$this->m_iCurrRow - $this->m_iNumLoadedDBRows][$sRequestedClassAlias];
 		}
-		$oRetObj = $this->m_aData[$this->m_iCurrRow][$sClassAlias];
 		$this->m_iCurrRow++;
 		return $oRetObj;
 	}
 
-	// Return the whole line if several classes have been specified in the query
-	//
+	/**
+	 * Fetch the whole row of objects (if several classes have been specified in the query) and move the cursor to the next position
+	 * 
+	 * @return hash A hash with the format 'classAlias' => $oObj representing the current row of the set. Returns null when at the end.
+	 */
 	public function FetchAssoc()
 	{
 		if (!$this->m_bLoaded) $this->Load();
 
-		if ($this->m_iCurrRow >= count($this->m_aData))
+		if ($this->m_iCurrRow >= $this->CountLoaded())
 		{
 			return null;
 		}
 	
-		$aRetObjects = $this->m_aData[$this->m_iCurrRow];
+		if ($this->m_iCurrRow < $this->m_iNumLoadedDBRows)
+		{
+			// Pick the row from the database
+			$aRow = CMDBSource::FetchArray($this->m_oSQLResult);
+			$aRetObjects = array();
+			foreach ($this->m_oFilter->GetSelectedClasses() as $sClassAlias => $sClass)
+			{
+				if (is_null($aRow[$sClassAlias.'id']))
+				{
+					$oObj = null;
+				}
+				else
+				{
+					$oObj = MetaModel::GetObjectByRow($sClass, $aRow, $sClassAlias, $this->m_aAttToLoad, $this->m_aExtendedDataSpec);
+				}
+				$aRetObjects[$sClassAlias] = $oObj;
+			}
+		}
+		else
+		{
+			// Pick the row from the objects added *in memory*
+			$oRetObj = $this->m_aAddedObjects[$this->m_iCurrRow - $this->m_iNumLoadedDBRows][$sRequestedClassAlias];
+		}
 		$this->m_iCurrRow++;
 		return $aRetObjects;
 	}
 
+	/**
+	 * Position the cursor (for iterating in the set) to the first position (equivalent to Seek(0))
+	 */
 	public function Rewind()
 	{
 		if ($this->m_bLoaded)
@@ -464,14 +648,32 @@ class DBObjectSet
 		}
 	}
 
+	/**
+	 * Position the cursor (for iterating in the set) to the given position
+	 * 
+	 * @param int $iRow
+	 */
 	public function Seek($iRow)
 	{
 		if (!$this->m_bLoaded) $this->Load();
 
-		$this->m_iCurrRow = min($iRow, count($this->m_aData));
+		$this->m_iCurrRow = min($iRow, $this->Count());
+		if ($this->m_iCurrRow < $this->m_iNumLoadedDBRows)
+		{
+			$this->m_oSQLResult->data_seek($this->m_iCurrRow);
+		}
 		return $this->m_iCurrRow;
 	}
 
+	/**
+	 * Add an object to the current set (in-memory only, nothing is written to the database)
+	 * 
+	 * Limitation:
+	 * Sets with several objects per row are NOT supported
+	 * 
+	 * @param DBObject $oObject The object to add
+	 * @param string $sClassAlias The alias for the class of the object
+	 */
 	public function AddObject($oObject, $sClassAlias = '')
 	{
 		if (!$this->m_bLoaded) $this->Load();
@@ -481,35 +683,52 @@ class DBObjectSet
 			$sClassAlias = $this->m_oFilter->GetClassAlias();
 		}
 
-		$iNextPos = count($this->m_aData);
-		$this->m_aData[$iNextPos][$sClassAlias] = $oObject;
+		$iNextPos = count($this->m_aAddedObjects);
+		$this->m_aAddedObjects[$iNextPos][$sClassAlias] = $oObject;
 		if (!is_null($oObject))
 		{
-			$this->m_aId2Row[$sClassAlias][$oObject->GetKey()] = $iNextPos;
 			$this->m_aAddedIds[$oObject->GetKey()] = true;
 		}
 	}
 
-	protected function AddObjectExtended($aObjectArray, $bInternalLoad = false)
+	/**
+	 * Add a hash containig objects into the current set.
+	 * 
+	 * The expected format for the hash is: $aObjectArray[$idx][$sClassAlias] => $oObject
+	 * Limitation:
+	 * The aliases MUST match the ones used in the current set
+	 * Only the ID of the objects associated to the first alias (column) is remembered.. in case we have to rebuild a filter
+	 * 
+	 * @param hash $aObjectArray
+	 */
+	protected function AddObjectExtended($aObjectArray)
 	{
 		if (!$this->m_bLoaded) $this->Load();
 
-		$iNextPos = count($this->m_aData);
+		$iNextPos = count($this->m_aAddedObjects);
+		
+		$sFirstAlias = $this->m_oFilter->GetClassAlias();
 
 		foreach ($aObjectArray as $sClassAlias => $oObject)
 		{
-			$this->m_aData[$iNextPos][$sClassAlias] = $oObject;
-			if (!is_null($oObject))
+			$this->m_aAddedObjects[$iNextPos][$sClassAlias] = $oObject;
+			
+			if (!is_null($oObject) && ($sFirstAlias == $sClassAlias))
 			{
-				$this->m_aId2Row[$sClassAlias][$oObject->GetKey()] = $iNextPos;
-				if (!$bInternalLoad)
-				{
-					$this->m_aAddedIds[$oObject->GetKey()] = true;
-				}
+				$this->m_aAddedIds[$oObject->GetKey()] = true;
 			}
 		}
 	}
 
+	/**
+	 * Add an array of objects into the current set
+	 * 
+	 * Limitation:
+	 * Sets with several classes per row are not supported (use AddObjectExtended instead)
+	 * 
+	 * @param array $aObjects The array of objects to add
+	 * @param string $sClassAlias The Alias of the class for the added objects
+	 */
 	public function AddObjectArray($aObjects, $sClassAlias = '')
 	{
 		if (!$this->m_bLoaded) $this->Load();
@@ -521,7 +740,16 @@ class DBObjectSet
 		}
 	}
 
-	public function Merge($oObjectSet)
+	/**
+	 * Append a given set to the current object. (This method used to be named Merge)
+	 * 
+	 * Limitation:
+	 * The added objects are not checked for duplicates (i.e. one cann add several times the same object, or add an object already present in the set).
+	 * 
+	 * @param DBObjectSet $oObjectSet The set to append
+	 * @throws CoreException
+	 */
+	public function Append(DBObjectSet $oObjectSet)
 	{
 		if ($this->GetRootClass() != $oObjectSet->GetRootClass())
 		{
@@ -536,7 +764,18 @@ class DBObjectSet
 		}
 	}
 
-	public function CreateIntersect($oObjectSet)
+	/**
+	 * Create a set containing the objects present in both the current set and another specified set
+	 * 
+	 * Limitations:
+	 * Will NOT work if only a subset of the sets was loaded with SetLimit.
+	 * Works only with sets made of objects loaded from the database since the comparison is based on the objects identifiers
+	 * 
+	 * @param DBObjectSet $oObjectSet The set to intersect with. The current position inside the set will be lost (= at the end)
+	 * @throws CoreException
+	 * @return DBObjectSet A new set of objects, containing the objects present in both sets (based on their identifier)
+	 */
+	public function CreateIntersect(DBObjectSet $oObjectSet)
 	{
 		if ($this->GetRootClass() != $oObjectSet->GetRootClass())
 		{
@@ -544,58 +783,132 @@ class DBObjectSet
 		}
 		if (!$this->m_bLoaded) $this->Load();
 
+		$aId2Row = array();
+		$iCurrPos = $this->m_iCurrRow; // Save the cursor
+		$idx = 0;
+		while($oObj = $this->Fetch())
+		{
+			$aId2Row[$oObj->GetKey()] = $idx;
+			$idx++;
+		}
+		
 		$oNewSet = DBObjectSet::FromScratch($this->GetClass());
 
-		$sClassAlias = $this->m_oFilter->GetClassAlias();
 		$oObjectSet->Seek(0);
 		while ($oObject = $oObjectSet->Fetch())
 		{
-			if (array_key_exists($oObject->GetKey(), $this->m_aId2Row[$sClassAlias]))
+			if (array_key_exists($oObject->GetKey(), $aId2Row))
 			{
 				$oNewSet->AddObject($oObject);
 			}
 		}
+		$this->Seek($iCurrPos); // Restore the cursor
 		return $oNewSet;
 	}
 
-	// Note: This verb works only with objects existing in the database
-	//
-	public function HasSameContents($oObjectSet)
+	/**
+	 * Compare two sets of objects to determine if their content is identical or not.
+	 * 
+	 * Limitation:
+	 * Works only on objects written to the DB, since we rely on their identifiers
+	 * 
+	 * @param DBObjectSet $oObjectSet
+	 * @return boolean True if the sets are identical, false otherwise
+	 */
+	public function HasSameContents(DBObjectSet $oObjectSet)
 	{
 		if ($this->GetRootClass() != $oObjectSet->GetRootClass())
 		{
 			return false;
 		}
-		if (!$this->m_bLoaded) $this->Load();
-
 		if ($this->Count() != $oObjectSet->Count())
 		{
 			return false;
 		}
-		$sClassAlias = $this->m_oFilter->GetClassAlias();
+		
+		$aId2Row = array();
+		$bRet = true;
+		$iCurrPos = $this->m_iCurrRow; // Save the cursor
+		$idx = 0;
+		
+		// Optimization: we retain the first $iMaxObjects objects in memory
+		// to speed up the comparison of small sets (see below: $oObject->Equals($oSibling))
+		$iMaxObjects = 20;
+		$aCachedObjects = array();
+		while($oObj = $this->Fetch())
+		{
+			$aId2Row[$oObj->GetKey()] = $idx;
+			if ($idx <= $iMaxObjects)
+			{
+				$aCachedObjects[$idx] = $oObj;
+			}
+			$idx++;
+		}
+		
 		$oObjectSet->Rewind();
 		while ($oObject = $oObjectSet->Fetch())
 		{
 			$iObjectKey = $oObject->GetKey();
 			if ($iObjectKey < 0)
 			{
-				return false;
+				$bRet = false;
+				break;
 			}
-			if (!array_key_exists($iObjectKey, $this->m_aId2Row[$sClassAlias]))
+			if (!array_key_exists($iObjectKey, $aId2Row))
 			{
-				return false;
+				$bRet = false;
+				break;
+			}
+			$iRow = $aId2Row[$iObjectKey];
+			if (array_key_exists($iRow, $aCachedObjects))
+			{ 
+				// Cache hit
+				$oSibling = $aCachedObjects[$iRow];
+			}
+			else
+			{
+				// Go fetch it from the DB, unless it's an object added in-memory
+				$oSibling = $this->GetObjectAt($iRow);
 			}
-			$iRow = $this->m_aId2Row[$sClassAlias][$iObjectKey];
-			$oSibling = $this->m_aData[$iRow][$sClassAlias];
 			if (!$oObject->Equals($oSibling))
 			{
-				return false;
+				$bRet = false;
+				break;
 			}
 		}
-		return true;
+		$this->Seek($iCurrPos); // Restore the cursor
+		return $bRet;
 	}
 
-	public function CreateDelta($oObjectSet)
+	protected function GetObjectAt($iIndex)
+	{
+		if (!$this->m_bLoaded) $this->Load();
+		
+		// Save the current position for iteration
+		$iCurrPos = $this->m_iCurrRow;
+		
+		$this->Seek($iIndex);
+		$oObject = $this->Fetch();
+		
+		// Restore the current position for iteration
+		$this->Seek($this->m_iCurrRow);
+		
+		return $oObject;
+	}
+	
+	/**
+	 * Build a new set (in memory) made of objects of the given set which are NOT present in the current set
+	 * 
+	 * Limitations:
+	 * The objects inside the set must be written in the database since the comparison is based on their identifiers
+	 * Sets with several objects per row are NOT supported
+	 * 
+	 * @param DBObjectSet $oObjectSet
+	 * @throws CoreException
+	 * 
+	 * @return DBObjectSet The "delta" set.
+	 */
+	public function CreateDelta(DBObjectSet $oObjectSet)
 	{
 		if ($this->GetRootClass() != $oObjectSet->GetRootClass())
 		{
@@ -603,20 +916,37 @@ class DBObjectSet
 		}
 		if (!$this->m_bLoaded) $this->Load();
 
+		$aId2Row = array();
+		$iCurrPos = $this->m_iCurrRow; // Save the cursor
+		$idx = 0;
+		while($oObj = $this->Fetch())
+		{
+			$aId2Row[$oObj->GetKey()] = $idx;
+			$idx++;
+		}
+
 		$oNewSet = DBObjectSet::FromScratch($this->GetClass());
 
-		$sClassAlias = $this->m_oFilter->GetClassAlias();
 		$oObjectSet->Seek(0);
 		while ($oObject = $oObjectSet->Fetch())
 		{
-			if (!array_key_exists($oObject->GetKey(), $this->m_aId2Row[$sClassAlias]))
+			if (!array_key_exists($oObject->GetKey(), $aId2Row))
 			{
 				$oNewSet->AddObject($oObject);
 			}
 		}
+		$this->Seek($iCurrPos); // Restore the cursor
 		return $oNewSet;
 	}
 
+	/**
+	 * Compute the "RelatedObjects" (for the given relation, as defined by MetaModel::GetRelatedObjects) for a whole set of DBObjects
+	 * 
+	 * @param string $sRelCode The code of the relation to use for the computation
+	 * @param int $iMaxDepth Teh maximum recursion depth
+	 * 
+	 * @return Array An array containg all the "related" objects
+	 */
 	public function GetRelatedObjects($sRelCode, $iMaxDepth = 99)
 	{
 		$aRelatedObjs = array();
@@ -645,7 +975,7 @@ class DBObjectSet
 	 * in the set. If for a given attribute, objects in the set have various values
 	 * then the resulting object will contain null for this value.
 	 * @param $aValues Hash Output: the distribution of the values, in the set, for each attribute
-	 * @return Object
+	 * @return DBObject The object with the common values
 	 */
 	public function ComputeCommonObject(&$aValues)
 	{

test/testlist.inc.php

@@ -740,14 +740,14 @@ class TestMyBizModel extends TestBizModel
 		$oDelta = $oSet1->CreateDelta($oSet2);
 	
 		$oMerge = clone $oSet1;
-		$oMerge->Merge($oSet2);
-		$oMerge->Merge($oSet2);
+		$oAppend->Append($oSet2);
+		$oAppend->Append($oSet2);
 	
 		echo "Set1 - Found ".$oSet1->Count()." items.</br>\n";
 		echo "Set2 - Found ".$oSet2->Count()." items.</br>\n";
 		echo "Intersect - Found ".$oIntersect->Count()." items.</br>\n";
 		echo "Delta - Found ".$oDelta->Count()." items.</br>\n";
-		echo "Merge - Found ".$oMerge->Count()." items.</br>\n";
+		echo "Append - Found ".$oAppend->Count()." items.</br>\n";
 		//$this->show_list($oObjSet);
 	}