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