3 * A database result class
5 * @author Roland Haeder <webmaster@ship-simu.org>
7 * @copyright Copyright (c) 2007 - 2009 Roland Haeder, this is free software
8 * @license GNU GPL 3.0 or any newer version
9 * @link http://www.ship-simu.org
11 * This program is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation, either version 3 of the License, or
14 * (at your option) any later version.
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
21 * You should have received a copy of the GNU General Public License
22 * along with this program. If not, see <http://www.gnu.org/licenses/>.
24 class DatabaseResult extends BaseFrameworkSystem implements SearchableResult, UpdateableResult, SeekableIterator {
25 // Exception constants
26 const EXCEPTION_INVALID_DATABASE_RESULT = 0x1c0;
27 const EXCEPTION_RESULT_UPDATE_FAILED = 0x1c1;
30 * Current position in array
32 private $currentPos = -1;
37 private $currentRow = null;
42 private $resultArray = array();
45 * Array of out-dated entries
47 private $outDated = array();
52 private $affectedRows = 0;
57 private $foundValue = "";
60 * Protected constructor
64 protected function __construct () {
65 // Call parent constructor
66 parent::__construct(__CLASS__);
69 $this->removeNumberFormaters();
70 $this->removeSystemArray();
74 * Creates an instance of this result by a provided result array
76 * @param $resultArray The array holding the result from query
77 * @return $resultInstance An instance of this class
79 public final static function createDatabaseResult (array $resultArray) {
81 $resultInstance = new DatabaseResult();
83 // Set the result array
84 $resultInstance->setResultArray($resultArray);
86 // Return the instance
87 return $resultInstance;
91 * Setter for result array
93 * @param $resultArray The array holding the result from query
96 protected final function setResultArray (array $resultArray) {
97 $this->resultArray = $resultArray;
101 * Updates the current entry by given update criteria
103 * @param $updateInstance An instance of an Updateable criteria
106 private function updateCurrentEntryByCriteria (LocalUpdateCriteria $updateInstance) {
107 // Get the current entry key
108 $entryKey = $this->key();
110 // Now get the update criteria array and update all entries
111 foreach ($updateInstance->getUpdateCriteria() as $criteriaKey => $criteriaValue) {
113 $this->resultArray['rows'][$entryKey][$criteriaKey] = $criteriaValue;
115 // Mark it as out-dated
116 $this->outDated[$criteriaKey] = 1;
121 * "Iterator" method next() to advance to the next valid entry. This method
122 * does also check if result is invalid
124 * @return $nextValid Wether the next entry is valid
126 public function next () {
127 // Default is not valid
130 // Is the result valid?
131 if ($this->valid()) {
132 // Next entry found, so count one up and cache it
134 $this->currentRow = $this->resultArray['rows'][$this->currentPos];
143 * Seeks for to a specified position
145 * @param $index Index to seek for
148 public function seek ($index) {
149 // Rewind to beginning
152 // Search for the entry
153 while ($this->currentPos < $index && ($this->valid())) {
160 * Gives back the current position or null if not found
162 * @return $current Current element to give back
164 public function current () {
165 // Default is not found
168 // Does the current enty exist?
169 if (isset($this->resultArray['rows'][$this->currentPos])) {
171 $current = $this->resultArray['rows'][$this->currentPos];
179 * Checks if next() and rewind will give a valid result
181 * @return $isValid Wether the next/rewind entry is valid
183 public function valid () {
184 // By default nothing is valid
188 if (($this->ifStatusIsOkay()) && (isset($this->resultArray['rows'][($this->currentPos + 1)])) && (isset($this->resultArray['rows'][0]))) {
198 * Determines wether the status of the query was fine ("ok")
200 * @return $ifStatusOkay Wether the status of the query was okay
202 public function ifStatusIsOkay () {
203 return ((isset($this->resultArray['status'])) && ($this->resultArray['status'] === "ok"));
207 * Gets the current key of iteration
209 * @return $currentPos Key from iterator
211 public function key () {
212 return $this->currentPos;
216 * Rewind to the beginning and clear array $currentRow
220 public function rewind () {
221 $this->currentPos = -1;
222 $this->currentRow = array();
226 * Searches for an entry in data result and returns it
228 * @param $criteriaInstance The criteria to look inside the data set
229 * @return $result Found result entry
232 public function searchEntry (LocalSearchCriteria $criteriaInstance) {
233 die(__METHOD__.": Unfinished!");
237 * Adds an update request to the database result for writing it to the
240 * @param $criteriaInstance An instance of a updateable criteria
242 * @throws ResultUpdateException If no result was updated
244 public function add2UpdateQueue (LocalUpdateCriteria $criteriaInstance) {
245 // Rewind the pointer
248 // Get search criteria
249 $searchInstance = $criteriaInstance->getSearchInstance();
251 // And start looking for the result
253 while (($this->valid()) && ($foundEntries < $searchInstance->getLimit())) {
256 $currentEntry = $this->current();
258 // Is this entry found?
259 if ($searchInstance->ifEntryMatches($currentEntry)) {
261 $this->updateCurrentEntryByCriteria($criteriaInstance);
268 // If no entry is found/updated throw an exception
269 if ($foundEntries == 0) {
270 // Throw an exception here
271 throw new ResultUpdateException($this, self::EXCEPTION_RESULT_UPDATE_FAILED);
275 $this->setAffectedRows($foundEntries);
277 // Set update instance
278 $this->setUpdateInstance($criteriaInstance);
282 * Setter for affected rows
284 * @param $rows Number of affected rows
287 public final function setAffectedRows ($rows) {
288 $this->affectedRows = $rows;
292 * Getter for affected rows
294 * @return $rows Number of affected rows
296 public final function getAffectedRows () {
297 return $this->affectedRows;
301 * Getter for found value of previous found() call
303 * @return $foundValue Found value of previous found() call
305 public final function getFoundValue () {
306 return $this->foundValue;
310 * Checks wether we have out-dated entries or not
312 * @return $needsUpdate Wether we have out-dated entries
314 public function ifDataNeedsFlush () {
315 $needsUpdate = (count($this->outDated) > 0);
320 * Adds registration elements to a given dataset instance
322 * @param $criteriaInstance An instance of a storeable criteria
325 public function addElementsToDataSet (StoreableCriteria $criteriaInstance) {
326 // Walk only through out-dated columns
327 foreach ($this->outDated as $key => $dummy) {
328 // Does this key exist?
329 //* DEBUG: */ echo "outDated: {$key}<br />\n";
330 if ($this->find($key)) {
332 $criteriaInstance->addCriteria($key, $this->getFoundValue());
338 * Find a key inside the result array
340 * @param $key The key we shall find
341 * @return $found Wether the key was found or not
343 public function find ($key) {
344 // By default nothing is found
347 // Rewind the pointer
350 // Walk through all entries
351 while ($this->valid()) {
352 // Advance to next entry
355 // Get the whole array
356 $currentEntry = $this->current();
358 // Is the element there?
359 if (isset($currentEntry[$key])) {
364 $this->foundValue = $currentEntry[$key];
366 // And stop searching
376 * Solver for result index value with call-back method
378 * @param $databaseColumn Database column where the index might be found
379 * @param $wrapperInstance The wrapper instance to ask for array element
380 * @para $callBack Call-back object for setting the index;
381 * 0=object instance,1=method name
383 4 * @todo Find a caching way without modifying the result array
385 public function solveResultIndex ($databaseColumn, BaseDatabaseWrapper $wrapperInstance, array $callBack) {
386 // By default nothing is found
389 // Is the element in result itself found?
390 if ($this->find($databaseColumn)) {
392 $indexValue = $this->getFoundValue();
393 } elseif ($this->find($wrapperInstance->getIndexKey())) {
395 $indexValue = $this->getFoundValue();
399 call_user_func_array($callBack, array($indexValue));