3 namespace Org\Mxchange\CoreFramework\Result\Database;
5 // Import framework stuff
6 use Org\Mxchange\CoreFramework\Criteria\Local\LocalSearchCriteria;
7 use Org\Mxchange\CoreFramework\Criteria\Local\LocalUpdateCriteria;
8 use Org\Mxchange\CoreFramework\Criteria\Storing\StoreableCriteria;
9 use Org\Mxchange\CoreFramework\Database\Frontend\DatabaseFrontend;
10 use Org\Mxchange\CoreFramework\Database\Backend\BaseDatabaseBackend;
11 use Org\Mxchange\CoreFramework\Result\Database\BaseDatabaseResult;
12 use Org\Mxchange\CoreFramework\Result\Search\SearchableResult;
13 use Org\Mxchange\CoreFramework\Result\Update\UpdateableResult;
16 use \InvalidArgumentException;
17 use \OutOfBoundsException;
18 use \SeekableIterator;
21 * A database result class
23 * @author Roland Haeder <webmaster@shipsimu.org>
25 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2020 Core Developer Team
26 * @license GNU GPL 3.0 or any newer version
27 * @link http://www.shipsimu.org
29 * This program is free software: you can redistribute it and/or modify
30 * it under the terms of the GNU General Public License as published by
31 * the Free Software Foundation, either version 3 of the License, or
32 * (at your option) any later version.
34 * This program is distributed in the hope that it will be useful,
35 * but WITHOUT ANY WARRANTY; without even the implied warranty of
36 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
37 * GNU General Public License for more details.
39 * You should have received a copy of the GNU General Public License
40 * along with this program. If not, see <http://www.gnu.org/licenses/>.
42 class CachedDatabaseResult extends BaseDatabaseResult implements SearchableResult, UpdateableResult, SeekableIterator {
43 // Exception constants
44 const EXCEPTION_INVALID_DATABASE_RESULT = 0x1c0;
45 const EXCEPTION_RESULT_UPDATE_FAILED = 0x1c1;
48 * Current position in array
50 private $currentPos = -1;
55 private $currentRow = NULL;
60 private $resultArray = [];
63 * Array of out-dated entries
65 private $outDated = [];
70 private $affectedRows = 0;
75 private $foundValue = '';
78 * Protected constructor
82 protected function __construct () {
83 // Call parent constructor
84 parent::__construct(__CLASS__);
88 * Creates an instance of this result by a provided result array
90 * @param $resultArray The array holding the result from query
91 * @return $resultInstance An instance of this class
92 * @throws InvalidArgumentException If a parameter is invalid
94 public static final function createCachedDatabaseResult (array $resultArray) {
96 if (count($resultArray) == 0) {
98 throw new InvalidArgumentException('Array "resultArray" cannot be empty.');
99 } elseif (!array_key_exists(BaseDatabaseResult::RESULT_NAME_ROWS, $resultArray)) {
100 // Yes, then abort here
101 throw new InvalidArgumentException(sprintf('resultArray(%d)=%s has no element "%s".', count($resultArray), print_r($resultArray, TRUE), BaseDatabaseResult::RESULT_NAME_ROWS));
104 // Get a new instance
105 $resultInstance = new CachedDatabaseResult();
107 // Set the result array and reset current position
108 $resultInstance->setResultArray($resultArray);
109 $resultInstance->resetCurrentPosition();
112 $resultInstance->setAffectedRows(count($resultArray[BaseDatabaseResult::RESULT_NAME_ROWS]));
114 // Return the instance
115 return $resultInstance;
119 * Setter for result array
121 * @param $resultArray The array holding the result from query
124 protected final function setResultArray (array $resultArray) {
125 $this->resultArray = $resultArray;
129 * Updates the current entry by given update criteria
131 * @param $updateInstance An instance of an Updateable criteria
134 private function updateCurrentEntryByCriteria (LocalUpdateCriteria $updateInstance) {
135 // Get the current entry key
136 $entryKey = $this->key();
138 // Now get the update criteria array and update all entries
139 foreach ($updateInstance->getUpdateCriteria() as $criteriaKey => $criteriaValue) {
141 $this->resultArray[BaseDatabaseResult::RESULT_NAME_ROWS][$entryKey][$criteriaKey] = $criteriaValue;
143 // Mark it as out-dated
144 $this->outDated[$criteriaKey] = 1;
149 * "Iterator" method next() to advance to the next valid entry. This method
150 * does also check if result is invalid
152 * @return $nextValid Whether the next entry is valid
154 public function next () {
155 // Default is not valid
161 // Is the result valid?
162 if ($this->valid()) {
163 // Next entry found, so cache it
164 $this->currentRow = $this->resultArray[BaseDatabaseResult::RESULT_NAME_ROWS][$this->currentPos];
173 * Seeks for to a specified position
175 * @param $seekPosition Position to seek to
177 * @throws OutOfBoundsException If the position is not seekable
179 public function seek (int $seekPosition) {
180 // Validate parameter
181 if ($seekPosition < 0) {
183 throw new OutOfBoundsException(sprintf('seekPositon=%d is not seekable', $seekPosition));
186 // Rewind to beginning
189 // Search for the entry
190 while (($this->currentPos < $seekPosition) && ($this->valid())) {
197 * Gives back the current position or null if not found
199 * @return $current Current element to give back
201 public function current () {
202 // Default is not found
205 // Does the current enty exist?
206 if (isset($this->resultArray[BaseDatabaseResult::RESULT_NAME_ROWS][$this->currentPos])) {
208 $current = $this->resultArray[BaseDatabaseResult::RESULT_NAME_ROWS][$this->currentPos];
216 * Checks if next() and rewind will give a valid result
218 * @return $isValid Whether the next/rewind entry is valid
220 public function valid () {
221 // Check if all is fine ...
222 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('CACHED-DATABASE-RESULT: this->currentPos=%d - CALLED!', $this->currentPos));
223 $isValid = ($this->ifStatusIsOkay() && isset($this->resultArray[BaseDatabaseResult::RESULT_NAME_ROWS][$this->currentPos]) && isset($this->resultArray[BaseDatabaseResult::RESULT_NAME_ROWS][0]));
226 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('CACHED-DATABASE-RESULT: isValid=%d - EXIT!', intval($isValid)));
231 * Returns count of entries
233 * @return $isValid Whether the next/rewind entry is valid
235 public function count () {
237 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('CACHED-DATABASE-RESULT: CALLED!');
238 $count = count($this->resultArray[BaseDatabaseResult::RESULT_NAME_ROWS]);
241 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('CACHED-DATABASE-RESULT: count=%d - EXIT!', $count));
246 * Determines whether the status of the query was fine (BaseDatabaseBackend::RESULT_OKAY)
248 * @return $ifStatusOkay Whether the status of the query was okay
250 public function ifStatusIsOkay () {
251 // Check all conditions
252 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('CACHED-DATABASE-RESULT: this->currentPos=%d - CALLED!', $this->currentPos));
253 $ifStatusOkay = (isset($this->resultArray[BaseDatabaseResult::RESULT_NAME_STATUS]) && $this->resultArray[BaseDatabaseResult::RESULT_NAME_STATUS] === BaseDatabaseBackend::RESULT_OKAY);
256 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('CACHED-DATABASE-RESULT: ifStatusOkay=%s - EXIT!', intval($ifStatusOkay)));
257 return $ifStatusOkay;
261 * Gets the current key of iteration
263 * @return $currentPos Key from iterator
265 public function key () {
266 // Return current array position
267 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('CACHED-DATABASE-RESULT: this->currentPos=%d - CALLED!', $this->currentPos));
268 return $this->currentPos;
272 * Rewind to the beginning and clear array $currentRow
276 public function rewind () {
277 // Reset both current array position and current row
278 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('CACHED-DATABASE-RESULT: this->currentPos=%d - CALLED!', $this->currentPos));
279 $this->resetCurrentPosition();
280 $this->currentRow = [];
283 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('CACHED-DATABASE-RESULT: EXIT!');
287 * Resets current array position to 0 if at least one record is there or -1
288 * if no record is there.
292 private function resetCurrentPosition () {
294 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('CACHED-DATABASE-RESULT: CALLED!');
295 $this->currentPos = ($this->count() > 0 ? 0 : -1);
298 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('CACHED-DATABASE-RESULT: EXIT!');
302 * Searches for an entry in data result and returns it
304 * @param $criteriaInstance The criteria to look inside the data set
305 * @return $result Found result entry
308 public function searchEntry (LocalSearchCriteria $criteriaInstance) {
310 $this->debugBackTrace(sprintf('[%s:%d]: criteriaInstance=%s', __METHOD__, __LINE__, print_r($criteriaInstance, TRUE)));
314 * Adds an update request to the database result for writing it to the
317 * @param $updateInstance An instance of a updateable criteria
319 * @throws ResultUpdateException If no result was updated
321 public function add2UpdateQueue (LocalUpdateCriteria $updateInstance) {
322 // Rewind the pointer
325 // Get search criteria
326 $searchInstance = $updateInstance->getSearchInstance();
328 // And start looking for the result
329 $foundEntries = $this->getAffectedRows();
330 while (($this->valid()) && ($foundEntries < $searchInstance->getLimit())) {
333 $currentEntry = $this->current();
335 // Is this entry found?
336 if ($searchInstance->ifEntryMatches($currentEntry)) {
338 $this->updateCurrentEntryByCriteria($updateInstance);
345 // If no entry is found/updated throw an exception
346 if ($foundEntries == 0) {
347 // Throw an exception here
348 throw new ResultUpdateException($this, self::EXCEPTION_RESULT_UPDATE_FAILED);
352 $this->setAffectedRows($foundEntries);
354 // Set update instance
355 $this->setUpdateInstance($updateInstance);
359 * Setter for affected rows
361 * @param $rows Number of affected rows
364 public final function setAffectedRows (int $rows) {
365 $this->affectedRows = $rows;
369 * Getter for affected rows
371 * @return $rows Number of affected rows
373 public final function getAffectedRows () {
374 return $this->affectedRows;
378 * Getter for found value of previous found() call
380 * @return $foundValue Found value of previous found() call
382 public final function getFoundValue () {
383 return $this->foundValue;
387 * Checks whether we have out-dated entries or not
389 * @return $needsUpdate Whether we have out-dated entries
391 public function ifDataNeedsFlush () {
392 $needsUpdate = (count($this->outDated) > 0);
397 * Adds registration elements to a given dataset instance
399 * @param $criteriaInstance An instance of a StoreableCriteria class
402 public function addElementsToDataSet (StoreableCriteria $criteriaInstance) {
403 // Walk only through out-dated columns
404 foreach ($this->outDated as $key => $dummy) {
405 // Does this key exist?
406 if ($this->find($key)) {
408 $criteriaInstance->addCriteria($key, $this->getFoundValue());
414 * Find a key inside the result array
416 * @param $key The key we shall find
417 * @return $found Whether the key was found or not
419 public function find (string $key) {
420 // By default nothing is found
423 // Rewind the pointer
426 // Walk through all entries
427 while ($this->valid()) {
428 // Advance to next entry
431 // Get the whole array
432 $currentEntry = $this->current();
434 // Is the element there?
435 if (isset($currentEntry[$key])) {
440 $this->foundValue = $currentEntry[$key];
442 // And stop searching
452 * Solver for result index value with call-back method
454 * @param $databaseColumn Database column where the index might be found
455 * @param $frontendInstance The frontend instance to ask for array element
456 * @para $callBack Call-back object for setting the index;
457 * 0=object instance,1=method name
459 * @todo Find a caching way without modifying the result array
461 public function solveResultIndex (string $databaseColumn, DatabaseFrontend $frontendInstance, array $callBack) {
462 // By default nothing is found
465 // Is the element in result itself found?
466 if ($this->find($databaseColumn)) {
468 $indexValue = $this->getFoundValue();
469 } elseif ($this->find($frontendInstance->getIndexKey())) {
471 $indexValue = $this->getFoundValue();
475 call_user_func_array($callBack, array($indexValue));