]> git.mxchange.org Git - core.git/blob - inc/classes/main/result/class_DatabaseResult.php
Continued:
[core.git] / inc / classes / main / result / class_DatabaseResult.php
1 <?php
2 /**
3  * A database result class
4  *
5  * @author              Roland Haeder <webmaster@shipsimu.org>
6  * @version             0.0.0
7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2013 Core Developer Team
8  * @license             GNU GPL 3.0 or any newer version
9  * @link                http://www.shipsimu.org
10  *
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.
15  *
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.
20  *
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/>.
23  */
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;
28
29         /**
30          * Current position in array
31          */
32         private $currentPos = -1;
33
34         /**
35          * Current row
36          */
37         private $currentRow = NULL;
38
39         /**
40          * Result array
41          */
42         private $resultArray = array();
43
44         /**
45          * Array of out-dated entries
46          */
47         private $outDated = array();
48
49         /**
50          * Affected rows
51          */
52         private $affectedRows = 0;
53
54         /**
55          * Found value
56          */
57         private $foundValue = '';
58
59         /**
60          * Protected constructor
61          *
62          * @return      void
63          */
64         protected function __construct () {
65                 // Call parent constructor
66                 parent::__construct(__CLASS__);
67         }
68
69         /**
70          * Creates an instance of this result by a provided result array
71          *
72          * @param       $resultArray            The array holding the result from query
73          * @return      $resultInstance         An instance of this class
74          */
75         public static final function createDatabaseResult (array $resultArray) {
76                 // Get a new instance
77                 $resultInstance = new DatabaseResult();
78
79                 // Set the result array
80                 $resultInstance->setResultArray($resultArray);
81
82                 // Set affected rows
83                 $resultInstance->setAffectedRows(count($resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS]));
84
85                 // Return the instance
86                 return $resultInstance;
87         }
88
89         /**
90          * Setter for result array
91          *
92          * @param       $resultArray    The array holding the result from query
93          * @return      void
94          */
95         protected final function setResultArray (array $resultArray) {
96                 $this->resultArray = $resultArray;
97         }
98
99         /**
100          * Updates the current entry by given update criteria
101          *
102          * @param       $updateInstance         An instance of an Updateable criteria
103          * @return      void
104          */
105         private function updateCurrentEntryByCriteria (LocalUpdateCriteria $updateInstance) {
106                 // Get the current entry key
107                 $entryKey = $this->key();
108
109                 // Now get the update criteria array and update all entries
110                 foreach ($updateInstance->getUpdateCriteria() as $criteriaKey => $criteriaValue) {
111                         // Update data
112                         $this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][$entryKey][$criteriaKey] = $criteriaValue;
113
114                         // Mark it as out-dated
115                         $this->outDated[$criteriaKey] = 1;
116                 } // END - foreach
117         }
118
119         /**
120          * "Iterator" method next() to advance to the next valid entry. This method
121          * does also check if result is invalid
122          *
123          * @return      $nextValid      Whether the next entry is valid
124          */
125         public function next () {
126                 // Default is not valid
127                 $nextValid = FALSE;
128
129                 // Is the result valid?
130                 if ($this->valid()) {
131                         // Next entry found, so count one up and cache it
132                         $this->currentPos++;
133                         $this->currentRow = $this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][$this->currentPos];
134                         $nextValid = TRUE;
135                 } // END - if
136
137                 // Return the result
138                 return $nextValid;
139         }
140
141         /**
142          * Seeks for to a specified position
143          *
144          * @param       $index  Index to seek for
145          * @return      void
146          */
147         public function seek ($index) {
148                 // Rewind to beginning
149                 $this->rewind();
150
151                 // Search for the entry
152                 while (($this->currentPos < $index) && ($this->valid())) {
153                         // Continue on
154                         $this->next();
155                 } // END - while
156         }
157
158         /**
159          * Gives back the current position or null if not found
160          *
161          * @return      $current        Current element to give back
162          */
163         public function current () {
164                 // Default is not found
165                 $current = NULL;
166
167                 // Does the current enty exist?
168                 if (isset($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][$this->currentPos])) {
169                         // Then get it
170                         $current = $this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][$this->currentPos];
171                 } // END - if
172
173                 // Return the result
174                 return $current;
175         }
176
177         /**
178          * Checks if next() and rewind will give a valid result
179          *
180          * @return      $isValid Whether the next/rewind entry is valid
181          */
182         public function valid () {
183                 // By default nothing is valid
184                 $isValid = FALSE;
185
186                 // Check if 
187                 if (($this->ifStatusIsOkay()) && (isset($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][($this->currentPos + 1)])) && (isset($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][0]))) {
188                         // All fine!
189                         $isValid = TRUE;
190                 } // END - if
191
192                 // Return the result
193                 return $isValid;
194         }
195
196         /**
197          * Returns count of entries
198          *
199          * @return      $isValid Whether the next/rewind entry is valid
200          */
201         public function count () {
202                 // Return it
203                 return count($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS]);
204         }
205
206         /**
207          * Determines whether the status of the query was fine (BaseDatabaseBackend::RESULT_OKAY)
208          *
209          * @return      $ifStatusOkay   Whether the status of the query was okay
210          */
211         public function ifStatusIsOkay () {
212                 return ((isset($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_STATUS])) && ($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_STATUS] === BaseDatabaseBackend::RESULT_OKAY));
213         }
214
215         /**
216          * Gets the current key of iteration
217          *
218          * @return      $currentPos     Key from iterator
219          */
220         public function key () {
221                 return $this->currentPos;
222         }
223
224         /**
225          * Rewind to the beginning and clear array $currentRow
226          *
227          * @return      void
228          */
229         public function rewind () {
230                 $this->currentPos = -1;
231                 $this->currentRow = array();
232         }
233
234         /**
235          * Searches for an entry in data result and returns it
236          *
237          * @param       $criteriaInstance       The criteria to look inside the data set
238          * @return      $result                         Found result entry
239          * @todo        0% done
240          */
241         public function searchEntry (LocalSearchCriteria $criteriaInstance) {
242                 $this->debugBackTrace('[' . '[' . __METHOD__ . ':' . __LINE__ . ']:  Unfinished!');
243         }
244
245         /**
246          * Adds an update request to the database result for writing it to the
247          * database layer
248          *
249          * @param       $criteriaInstance       An instance of a updateable criteria
250          * @return      void
251          * @throws      ResultUpdateException   If no result was updated
252          */
253         public function add2UpdateQueue (LocalUpdateCriteria $criteriaInstance) {
254                 // Rewind the pointer
255                 $this->rewind();
256
257                 // Get search criteria
258                 $searchInstance = $criteriaInstance->getSearchInstance();
259
260                 // And start looking for the result
261                 $foundEntries = 0;
262                 while (($this->valid()) && ($foundEntries < $searchInstance->getLimit())) {
263                         // Get next entry
264                         $this->next();
265                         $currentEntry = $this->current();
266
267                         // Is this entry found?
268                         if ($searchInstance->ifEntryMatches($currentEntry)) {
269                                 // Update this entry
270                                 $this->updateCurrentEntryByCriteria($criteriaInstance);
271
272                                 // Count one up
273                                 $foundEntries++;
274                         } // END - if
275                 } // END - while
276
277                 // If no entry is found/updated throw an exception
278                 if ($foundEntries == 0) {
279                         // Throw an exception here
280                         throw new ResultUpdateException($this, self::EXCEPTION_RESULT_UPDATE_FAILED);
281                 } // END - if
282
283                 // Set affected rows
284                 $this->setAffectedRows($foundEntries);
285
286                 // Set update instance
287                 $this->setUpdateInstance($criteriaInstance);
288         }
289
290         /**
291          * Setter for affected rows
292          *
293          * @param       $rows   Number of affected rows
294          * @return      void
295          */
296         public final function setAffectedRows ($rows) {
297                 $this->affectedRows = $rows;
298         }
299
300         /**
301          * Getter for affected rows
302          *
303          * @return      $rows   Number of affected rows
304          */
305         public final function getAffectedRows () {
306                 return $this->affectedRows;
307         }
308
309         /**
310          * Getter for found value of previous found() call
311          *
312          * @return      $foundValue             Found value of previous found() call
313          */
314         public final function getFoundValue () {
315                 return $this->foundValue;
316         }
317
318         /**
319          * Checks whether we have out-dated entries or not
320          *
321          * @return      $needsUpdate    Whether we have out-dated entries
322          */
323         public function ifDataNeedsFlush () {
324                 $needsUpdate = (count($this->outDated) > 0);
325                 return $needsUpdate;
326         }
327
328         /**
329          * Adds registration elements to a given dataset instance
330          *
331          * @param       $criteriaInstance       An instance of a StoreableCriteria class
332          * @param       $requestInstance        An instance of a Requestable class
333          * @return      void
334          */
335         public function addElementsToDataSet (StoreableCriteria $criteriaInstance, Requestable $requestInstance = NULL) {
336                 // Walk only through out-dated columns
337                 foreach ($this->outDated as $key => $dummy) {
338                         // Does this key exist?
339                         //* DEBUG: */ echo "outDated: {$key}<br />\n";
340                         if ($this->find($key)) {
341                                 // Then update it
342                                 $criteriaInstance->addCriteria($key, $this->getFoundValue());
343                         } // END - if
344                 } // END - foreach
345         }
346
347         /**
348          * Find a key inside the result array
349          *
350          * @param       $key    The key we shall find
351          * @return      $found  Whether the key was found or not
352          */
353         public function find ($key) {
354                 // By default nothing is found
355                 $found = FALSE;
356
357                 // Rewind the pointer
358                 $this->rewind();
359
360                 // Walk through all entries
361                 while ($this->valid()) {
362                         // Advance to next entry
363                         $this->next();
364
365                         // Get the whole array
366                         $currentEntry = $this->current();
367
368                         // Is the element there?
369                         if (isset($currentEntry[$key])) {
370                                 // Okay, found!
371                                 $found = TRUE;
372
373                                 // So "cache" it
374                                 $this->foundValue = $currentEntry[$key];
375
376                                 // And stop searching
377                                 break;
378                         } // END - if
379                 } // END - while
380
381                 // Return the result
382                 return $found;
383         }
384
385         /**
386          * Solver for result index value with call-back method
387          *
388          * @param       $databaseColumn         Database column where the index might be found
389          * @param       $wrapperInstance        The wrapper instance to ask for array element
390          * @para        $callBack                       Call-back object for setting the index;
391          *                                                              0=object instance,1=method name
392          * @return      void
393          * @todo        Find a caching way without modifying the result array
394          */
395         public function solveResultIndex ($databaseColumn, DatabaseWrapper $wrapperInstance, array $callBack) {
396                 // By default nothing is found
397                 $indexValue = 0;
398
399                 // Is the element in result itself found?
400                 if ($this->find($databaseColumn)) {
401                         // Use this value
402                         $indexValue = $this->getFoundValue();
403                 } elseif ($this->find($wrapperInstance->getIndexKey())) {
404                         // Use this value
405                         $indexValue = $this->getFoundValue();
406                 }
407
408                 // Set the index
409                 call_user_func_array($callBack, array($indexValue));
410         }
411 }
412
413 // [EOF]
414 ?>