3 * A database result class
5 * @author Roland Haeder <webmaster@ship-simu.org>
7 * @copyright Copyright (c) 2007, 2008 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;
55 * Protected constructor
59 protected function __construct () {
60 // Call parent constructor
61 parent::__construct(__CLASS__);
64 $this->removeNumberFormaters();
65 $this->removeSystemArray();
69 * Creates an instance of this result by a provided result array
71 * @param $resultArray The array holding the result from query
72 * @return $resultInstance An instance of this class
74 public final static function createDatabaseResult (array $resultArray) {
76 $resultInstance = new DatabaseResult();
78 // Set the result array
79 $resultInstance->setResultArray($resultArray);
81 // Return the instance
82 return $resultInstance;
86 * Setter for result array
88 * @param $resultArray The array holding the result from query
91 protected final function setResultArray (array $resultArray) {
92 $this->resultArray = $resultArray;
96 * Updates the current entry by given update criteria
98 * @param $updateInstance An instance of an Updateable criteria
101 private function updateCurrentEntryByCriteria (LocalUpdateCriteria $updateInstance) {
102 // Get the current entry key
103 $entryKey = $this->key();
105 // Now get the update criteria array and update all entries
106 foreach ($updateInstance->getUpdateCriteria() as $criteriaKey => $criteriaValue) {
108 $this->resultArray['rows'][$entryKey][$criteriaKey] = $criteriaValue;
110 // Mark it as out-dated
111 $this->outDated[$criteriaKey] = 1;
116 * "Iterator" method next() to advance to the next valid entry. This method
117 * does also check if the result is invalid
119 * @return $nextValid Wether the next entry is valid
121 public function next () {
122 // Default is not valid
125 // Is the result valid?
126 if ($this->valid()) {
127 // Next entry found, so count one up and cache it
129 $this->currentRow = $this->resultArray['rows'][$this->currentPos];
138 * Seeks for to a specified position
140 * @param $index Index to seek for
143 public function seek ($index) {
144 // Rewind to beginning
147 // Search for the entry
148 while ($this->currentPos < $index && ($this->valid())) {
155 * Gives back the current position or null if not found
157 * @return $current Current element to give back
159 public function current () {
160 // Default is not found
163 // Does the current enty exist?
164 if (isset($this->resultArray['rows'][$this->currentPos])) {
166 $current = $this->resultArray['rows'][$this->currentPos];
174 * Checks if next() and rewind will give a valid result
176 * @return $isValid Wether the next/rewind entry is valid
178 public function valid () {
179 // By default nothing is valid
183 if (($this->ifStatusIsOkay()) && (isset($this->resultArray['rows'][($this->currentPos + 1)])) && (isset($this->resultArray['rows'][0]))) {
193 * Determines wether the status of the query was fine ("ok")
195 * @return $ifStatusOkay Wether the status of the query was okay
197 public function ifStatusIsOkay () {
198 return ((isset($this->resultArray['status'])) && ($this->resultArray['status'] === "ok"));
202 * Gets the current key of iteration
204 * @return $currentPos Key from iterator
206 public function key () {
207 return $this->currentPos;
211 * Rewind to the beginning
215 public function rewind () {
216 $this->currentPos = -1;
220 * Searches for an entry in the data result and returns it
222 * @param $criteriaInstance The criteria to look inside the data set
223 * @return $result Found result entry
226 public function searchEntry (LocalSearchCriteria $criteriaInstance) {
227 die(__METHOD__.": Unfinished!");
231 * Adds an update request to the database result for writing it to the
234 * @param $criteriaInstance An instance of a updateable criteria
236 * @throws ResultUpdateException If no result was updated
238 public function add2UpdateQueue (LocalUpdateCriteria $criteriaInstance) {
239 // Rewind the pointer
242 // Get search criteria
243 $searchInstance = $criteriaInstance->getSearchInstance();
245 // And start looking for the result
247 while (($this->valid()) && ($foundEntries < $searchInstance->getLimit())) {
250 $currentEntry = $this->current();
252 // Is this entry found?
253 if ($searchInstance->ifEntryMatches($currentEntry)) {
255 $this->updateCurrentEntryByCriteria($criteriaInstance);
263 $this->setAffectedRows($foundEntries);
265 // If no entry is found/updated throw an exception
266 if ($foundEntries == 0) {
267 // Throw an exception here
268 throw new ResultUpdateException($this, self::EXCEPTION_RESULT_UPDATE_FAILED);
271 // Set search instance
272 $this->setSearchInstance($searchInstance);
276 * Setter for affected rows
278 * @param $rows Number of affected rows
281 public final function setAffectedRows ($rows) {
282 $this->affectedRows = $rows;
286 * Getter for affected rows
288 * @return $rows Number of affected rows
290 public final function getAffectedRows () {
291 return $this->affectedRows;
295 * Checks wether we have out-dated entries or not
297 * @return $needsUpdate Wether we have out-dated entries
299 public function ifDataNeedsFlush () {
300 $needsUpdate = (count($this->outDated) > 0);
305 * Adds registration elements to a given dataset instance
307 * @param $criteriaInstance An instance of a storeable criteria
310 public function addElementsToDataSet (StoreableCriteria $criteriaInstance) {
311 // Rewind the pointer
314 // Walk through all entries
315 while ($this->valid()) {
318 $currentEntry = $this->current();
320 // Walk only through out-dated columns
321 foreach ($this->outDated as $key => $dummy) {
322 // Does this key exist?
323 //* DEBUG: */ echo "outDated: {$key}<br />\n";
324 if (isset($currentEntry[$key])) {
326 $criteriaInstance->addCriteria($key, $currentEntry[$key]);