DataSet Class Reference

Inheritance diagram for DataSet:

QueryDataSet TableDataSet

List of all members.

Public Member Functions

 getIterator ()
 Return iterator (for IteratorAggregate interface).
 resultSet ()
 Gets the ResultSet for this DataSet.
 allRecordsRetrieved ()
 Check if all the records have been retrieve.
 setAllRecordsRetrieved ($set)
 Set all records retrieved.
 removeRecord (Record $rec)
 Remove a record from the DataSet's internal storage.
 clearRecords ()
 Remove all records from the DataSet and nulls those records out and close() the DataSet.
 releaseRecords ()
 Removes the records from the DataSet, but does not null the records out.
 close ()
 Releases the records, closes the ResultSet and the Statement, and nulls the Schema and Connection references.
 reset ()
 Essentially the same as releaseRecords, but it won't work on a QueryDataSet that has been created with a ResultSet.
 connection ()
 Gets the current database connection.
 schema ()
 Gets the Schema for this DataSet.
 getRecord ($pos)
 Get Record at 0 based index position.
 findRecord ($pos)
 Find Record at 0 based index position.
 containsRecord ($pos)
 Check to see if the DataSet contains a Record at 0 based position.
 fetchRecords ($p1=0, $p2=null)
 Causes the DataSet to hit the database and fetch max records, starting at start.
 lastFetchSize ()
 The number of records that were fetched with the last fetchRecords.
 keydef ()
 gets the KeyDef object for this DataSet
 __toString ()
 This returns a represention of this DataSet.
 getSelectSql ()
 Classes extending this class must implement this method.
 getColumns ()
 Returns the columns attribute for the DataSet.
 size ()
 Gets the number of Records in this DataSet.

Public Attributes

const ALL_RECORDS = 0
 indicates that all records should be retrieved during a fetch

Protected Attributes

 $records
 this DataSet's collection of Record objects
 $conn
 this DataSet's connection object
 $allRecordsRetrieved = false
 have all records been retrieved with the fetchRecords?
 $recordRetrievedCount = 0
 number of records retrieved
 $lastFetchSize = 0
 number of records that were last fetched
 $totalFetchCount = 0
 number of records total that have been fetched
 $columns
 the columns in the SELECT statement for this DataSet
 $selectSql
 the select string that was used to build this DataSet
 $keyDef
 the KeyDef for this DataSet
 $resultSet
 the result set for this DataSet
 $stmt
 the Statement for this DataSet


Detailed Description

Definition at line 50 of file DataSet.php.


Member Function Documentation

DataSet::__toString (  ) 

This returns a represention of this DataSet.

Definition at line 379 of file DataSet.php.

References getRecord(), and size().

00380     {
00381         $sb = "";        
00382         for ($i = 0, $size = $this->size(); $i < $size; $i++) {
00383             $sb .= $this->getRecord($i);
00384         }
00385         return $sb;
00386     }       

DataSet::allRecordsRetrieved (  ) 

Check if all the records have been retrieve.

Returns:
boolean True if all records have been retrieved

Definition at line 123 of file DataSet.php.

Referenced by fetchRecords(), and setAllRecordsRetrieved().

00124     {
00125         return $this->allRecordsRetrieved;
00126     }

DataSet::clearRecords (  ) 

Remove all records from the DataSet and nulls those records out and close() the DataSet.

Returns:
an instance of myself

Definition at line 157 of file DataSet.php.

00158     {
00159         $this->records = null;
00160         return $this;
00161     }

DataSet::close (  ) 

Releases the records, closes the ResultSet and the Statement, and nulls the Schema and Connection references.

Returns:
void

Definition at line 183 of file DataSet.php.

References releaseRecords(), resultSet(), and schema().

00184     {
00185         $this->releaseRecords();
00186         $this->schema = null;
00187 
00188         if ($this->resultSet !== null && !$this instanceof QueryDataSet) {
00189             $this->resultSet->close();
00190         }
00191             
00192         $this->resultSet = null;
00193         
00194         if ( $this->stmt !== null ) {
00195             $this->stmt->close();
00196         }
00197 
00198         $this->conn = null;
00199     }

DataSet::connection (  ) 

Gets the current database connection.

Returns:
Connection A database connection.

Definition at line 222 of file DataSet.php.

00223     {
00224         return $this->conn;
00225     }

DataSet::containsRecord ( pos  ) 

Check to see if the DataSet contains a Record at 0 based position.

Parameters:
pos 
Returns:
true if record exists

Definition at line 279 of file DataSet.php.

Referenced by findRecord(), and getRecord().

00280     {
00281         return (isset($this->records[$pos]));            
00282     }   

DataSet::fetchRecords ( p1 = 0,
p2 = null 
)

Causes the DataSet to hit the database and fetch max records, starting at start.

Record count begins at 0.

This method supports two signatures:

  • fetchRecords(10); // LIMIT = 10
  • fetchRecords(5, 10); // OFFSET = 5, LIMIT = 10

Parameters:
int $p1 max - or start if $p2 is set
int $p2 start
Returns:
DataSet This class.
Exceptions:
SQLException 
DataSetException 

Reimplemented in TableDataSet.

Definition at line 298 of file DataSet.php.

References allRecordsRetrieved(), lastFetchSize(), resultSet(), and setAllRecordsRetrieved().

00299     {
00300         if ($p2 !== null) {
00301             $start = $p1;
00302             $max = $p2;
00303         } else {
00304             $start = 0;
00305             $max = $p1;
00306         }
00307         
00308         if ($this->lastFetchSize() > 0 && $this->records !== null) {
00309             throw new DataSetException("You must call DataSet::clearRecords() before executing DataSet::fetchRecords() again!");
00310         }
00311 
00312         try {
00313         
00314             if ($this->stmt === null && $this->resultSet === null) {
00315                 $this->stmt = $this->conn->createStatement();
00316                 $this->stmt->setOffset($start);
00317                 $this->stmt->setLimit($max);
00318                 // reset, since native limit applied
00319                 $start = 0;
00320                 $max = 0;
00321                 $this->resultSet = $this->stmt->executeQuery($this->selectSql);
00322             }
00323 
00324             if ($this->resultSet !== null) {
00325 
00326                 $this->records = array();
00327 
00328                 $startCounter = 0;
00329                 $fetchCount = 0;
00330                 while (! $this->allRecordsRetrieved() ) {
00331                     if ($this->resultSet->next()) {
00332                         if ($startCounter >= $start) {
00333                             $this->records[] = new Record($this);
00334                             $fetchCount++;
00335                             if ($fetchCount === $max) { // check after because we must fetch at least 1
00336                                 break;
00337                             }
00338                         } else {
00339                             $startCounter++;
00340                         }
00341                     } else {
00342                         $this->setAllRecordsRetrieved(true);
00343                         break;
00344                     }
00345                 }                
00346                 $this->lastFetchSize = $fetchCount;
00347             }
00348         } catch (SQLException $e) {
00349             if ($this->stmt) $this->stmt->close();
00350             throw $e;
00351         }
00352 
00353         return $this;
00354     }

DataSet::findRecord ( pos  ) 

Find Record at 0 based index position.

This is an internal alternative to getRecord which tries to be smart about the type of record it is.

Parameters:
int $pos
Returns:
Record an instance of the found Record
Exceptions:
DataSetException 

Definition at line 265 of file DataSet.php.

References containsRecord().

00266     {
00267         if ($this->containsRecord($pos)) {
00268             return $this->records[$pos];
00269         }
00270         throw new DataSetException ("Record not found at index: " . $pos);
00271     }

DataSet::getColumns (  ) 

Returns the columns attribute for the DataSet.

Returns:
the columns attribute for the DataSet

Definition at line 401 of file DataSet.php.

00402     {
00403         return $this->columns;
00404     }

DataSet::getIterator (  ) 

Return iterator (for IteratorAggregate interface).

This allows this class to be used in a foreach() loop. foreach($dataset as $record) { print "col1 = " . $record->getValue("col1") . "\n"; }

Returns:
DataSetIterator

Definition at line 98 of file DataSet.php.

00099     {
00100         $it = new DataSetIterator($this);
00101         return $it;
00102     }

DataSet::getRecord ( pos  ) 

Get Record at 0 based index position.

Parameters:
int $pos
Returns:
Record An instance of the found Record
Exceptions:
DataSetException 

Definition at line 244 of file DataSet.php.

References containsRecord().

Referenced by __toString().

00245     {
00246         if ($this->containsRecord($pos)) {
00247             $rec = $this->records[$pos];
00248             if ($this instanceof TableDataSet) {
00249                 $rec->markForUpdate();
00250             }
00251             $this->recordRetrievedCount++;
00252             return $rec;
00253         }
00254         throw new DataSetException ("Record not found at index: " . $pos);
00255     }

DataSet::getSelectSql (  )  [abstract]

Classes extending this class must implement this method.

Returns:
string The SELECT SQL.
Exceptions:
DataSetException; 

Reimplemented in QueryDataSet, and TableDataSet.

DataSet::keydef (  ) 

gets the KeyDef object for this DataSet

Returns:
KeyDef The keydef for this DataSet, this value can be null

Definition at line 371 of file DataSet.php.

00372     {
00373         return $this->keyDef;
00374     }

DataSet::lastFetchSize (  ) 

The number of records that were fetched with the last fetchRecords.

Returns:
int

Definition at line 361 of file DataSet.php.

Referenced by fetchRecords(), and releaseRecords().

00362     {
00363         return $this->lastFetchSize;
00364     }

DataSet::releaseRecords (  ) 

Removes the records from the DataSet, but does not null the records out.

Returns:
an instance of myself

Definition at line 168 of file DataSet.php.

References lastFetchSize(), and setAllRecordsRetrieved().

Referenced by close(), and reset().

00169     {
00170         $this->records = null;
00171         $this->recordRetrievedCount = 0;
00172         $this->lastFetchSize = 0;
00173         $this->setAllRecordsRetrieved(false);
00174         return $this;
00175     }

DataSet::removeRecord ( Record rec  ) 

Remove a record from the DataSet's internal storage.

Parameters:
Record $rec
Returns:
Record The record removed

Definition at line 144 of file DataSet.php.

00145     {
00146         $loc = array_search($rec, $this->records, true);
00147         $removeRec = array_splice($this->records, $loc, 1);                 
00148         return $removeRec;
00149     }

DataSet::reset (  ) 

Essentially the same as releaseRecords, but it won't work on a QueryDataSet that has been created with a ResultSet.

Returns:
DataSet This object.
Exceptions:
DataSetException 

Definition at line 208 of file DataSet.php.

References releaseRecords(), and resultSet().

00209     {
00210         if (! ($this->resultSet !== null && ($this instanceof QueryDataSet))) {
00211             return $this->releaseRecords();
00212         } else {
00213             throw new DataSetException("You cannot call reset() on a QueryDataSet.");
00214         }
00215     }

DataSet::resultSet (  ) 

Gets the ResultSet for this DataSet.

Returns:
ResultSet The result set for this DataSet
Exceptions:
DataSetException - if resultset is null

Definition at line 110 of file DataSet.php.

Referenced by QueryDataSet::__construct(), close(), fetchRecords(), and reset().

00111     {
00112         if ($this->resultSet === null) {
00113             throw new DataSetException ("ResultSet is null.");
00114         }            
00115         return $this->resultSet;
00116     }

DataSet::schema (  ) 

Gets the Schema for this DataSet.

Returns:
Schema The Schema for this DataSet

Definition at line 232 of file DataSet.php.

Referenced by close().

00233     {
00234         return $this->schema;
00235     }

DataSet::setAllRecordsRetrieved ( set  ) 

Set all records retrieved.

Parameters:
boolean $set
Returns:
void

Definition at line 133 of file DataSet.php.

References allRecordsRetrieved().

Referenced by fetchRecords(), and releaseRecords().

00134     {
00135         $this->allRecordsRetrieved = $set;
00136     }

DataSet::size (  ) 

Gets the number of Records in this DataSet.

It is 0 based.

Returns:
int Number of Records in this DataSet

Definition at line 411 of file DataSet.php.

Referenced by DataSetIterator::__construct(), and __toString().

00412     {
00413         if ( $this->records === null )
00414             return 0;
00415         return count($this->records);
00416     }


Member Data Documentation

DataSet::$allRecordsRetrieved = false [protected]

have all records been retrieved with the fetchRecords?

Definition at line 62 of file DataSet.php.

DataSet::$columns [protected]

the columns in the SELECT statement for this DataSet

Definition at line 74 of file DataSet.php.

DataSet::$conn [protected]

this DataSet's connection object

Definition at line 59 of file DataSet.php.

DataSet::$keyDef [protected]

the KeyDef for this DataSet

Definition at line 80 of file DataSet.php.

DataSet::$lastFetchSize = 0 [protected]

number of records that were last fetched

Definition at line 68 of file DataSet.php.

DataSet::$recordRetrievedCount = 0 [protected]

number of records retrieved

Definition at line 65 of file DataSet.php.

DataSet::$records [protected]

this DataSet's collection of Record objects

Definition at line 56 of file DataSet.php.

DataSet::$resultSet [protected]

the result set for this DataSet

Definition at line 83 of file DataSet.php.

DataSet::$selectSql [protected]

the select string that was used to build this DataSet

Definition at line 77 of file DataSet.php.

Referenced by QueryDataSet::__construct().

DataSet::$stmt [protected]

the Statement for this DataSet

Definition at line 86 of file DataSet.php.

DataSet::$totalFetchCount = 0 [protected]

number of records total that have been fetched

Definition at line 71 of file DataSet.php.

indicates that all records should be retrieved during a fetch

Definition at line 53 of file DataSet.php.


The documentation for this class was generated from the following file:

Generated on Wed May 6 23:10:49 2009 for fareofficelib by  doxygen 1.5.8