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\Search\SearchableResult;
12 use Org\Mxchange\CoreFramework\Result\Update\UpdateableResult;
15 use \InvalidArgumentException;
16 use \SeekableIterator;
19 * A database result class
21 * @author Roland Haeder <webmaster@shipsimu.org>
23 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2020 Core Developer Team
24 * @license GNU GPL 3.0 or any newer version
25 * @link http://www.shipsimu.org
27 * This program is free software: you can redistribute it and/or modify
28 * it under the terms of the GNU General Public License as published by
29 * the Free Software Foundation, either version 3 of the License, or
30 * (at your option) any later version.
32 * This program is distributed in the hope that it will be useful,
33 * but WITHOUT ANY WARRANTY; without even the implied warranty of
34 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
35 * GNU General Public License for more details.
37 * You should have received a copy of the GNU General Public License
38 * along with this program. If not, see <http://www.gnu.org/licenses/>.
40 class CachedDatabaseResult extends BaseDatabaseResult implements SearchableResult, UpdateableResult, SeekableIterator {
41 // Exception constants
42 const EXCEPTION_INVALID_DATABASE_RESULT = 0x1c0;
43 const EXCEPTION_RESULT_UPDATE_FAILED = 0x1c1;
46 * Current position in array
48 private $currentPos = -1;
53 private $currentRow = NULL;
58 private $resultArray = [];
61 * Array of out-dated entries
63 private $outDated = [];
68 private $affectedRows = 0;
73 private $foundValue = '';
76 * Protected constructor
80 protected function __construct () {
81 // Call parent constructor
82 parent::__construct(__CLASS__);
86 * Creates an instance of this result by a provided result array
88 * @param $resultArray The array holding the result from query
89 * @return $resultInstance An instance of this class
90 * @throws InvalidArgumentException If a parameter is invalid
92 public static final function createCachedDatabaseResult (array $resultArray) {
94 if (count($resultArray) == 0) {
96 throw new InvalidArgumentException('Array "resultArray" cannot be empty.');
97 } elseif (!array_key_exists(BaseDatabaseBackend::RESULT_INDEX_ROWS, $resultArray)) {
98 // Yes, then abort here
99 throw new InvalidArgumentException(sprintf('resultArray(%d)=%s has no element "%s".', count($resultArray), print_r($resultArray, TRUE), BaseDatabaseBackend::RESULT_INDEX_ROWS));
102 // Get a new instance
103 $resultInstance = new CachedDatabaseResult();
105 // Set the result array
106 $resultInstance->setResultArray($resultArray);
109 $resultInstance->setAffectedRows(count($resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS]));
111 // Return the instance
112 return $resultInstance;
116 * Setter for result array
118 * @param $resultArray The array holding the result from query
121 protected final function setResultArray (array $resultArray) {
122 $this->resultArray = $resultArray;
126 * Updates the current entry by given update criteria
128 * @param $updateInstance An instance of an Updateable criteria
131 private function updateCurrentEntryByCriteria (LocalUpdateCriteria $updateInstance) {
132 // Get the current entry key
133 $entryKey = $this->key();
135 // Now get the update criteria array and update all entries
136 foreach ($updateInstance->getUpdateCriteria() as $criteriaKey => $criteriaValue) {
138 $this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][$entryKey][$criteriaKey] = $criteriaValue;
140 // Mark it as out-dated
141 $this->outDated[$criteriaKey] = 1;
146 * "Iterator" method next() to advance to the next valid entry. This method
147 * does also check if result is invalid
149 * @return $nextValid Whether the next entry is valid
151 public function next () {
152 // Default is not valid
155 // Is the result valid?
156 if ($this->valid()) {
157 // Next entry found, so count one up and cache it
159 $this->currentRow = $this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][$this->currentPos];
168 * Seeks for to a specified position
170 * @param $index Index to seek for
173 public function seek ($index) {
174 // Rewind to beginning
177 // Search for the entry
178 while (($this->currentPos < $index) && ($this->valid())) {
185 * Gives back the current position or null if not found
187 * @return $current Current element to give back
189 public function current () {
190 // Default is not found
193 // Does the current enty exist?
194 if (isset($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][$this->currentPos])) {
196 $current = $this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][$this->currentPos];
204 * Checks if next() and rewind will give a valid result
206 * @return $isValid Whether the next/rewind entry is valid
208 public function valid () {
209 // By default nothing is valid
213 //*NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . '] this->currentPos=' . $this->currentPos);
215 // Check if all is fine ...
216 if (($this->ifStatusIsOkay()) && (isset($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][($this->currentPos + 1)])) && (isset($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS][0]))) {
226 * Returns count of entries
228 * @return $isValid Whether the next/rewind entry is valid
230 public function count () {
232 return count($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_ROWS]);
236 * Determines whether the status of the query was fine (BaseDatabaseBackend::RESULT_OKAY)
238 * @return $ifStatusOkay Whether the status of the query was okay
240 public function ifStatusIsOkay () {
241 $ifStatusOkay = ((isset($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_STATUS])) && ($this->resultArray[BaseDatabaseBackend::RESULT_INDEX_STATUS] === BaseDatabaseBackend::RESULT_OKAY));
242 //*NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . '] ifStatusOkay=' . intval($ifStatusOkay));
243 return $ifStatusOkay;
247 * Gets the current key of iteration
249 * @return $currentPos Key from iterator
251 public function key () {
252 return $this->currentPos;
256 * Rewind to the beginning and clear array $currentRow
260 public function rewind () {
261 $this->currentPos = -1;
262 $this->currentRow = [];
266 * Searches for an entry in data result and returns it
268 * @param $criteriaInstance The criteria to look inside the data set
269 * @return $result Found result entry
272 public function searchEntry (LocalSearchCriteria $criteriaInstance) {
273 $this->debugBackTrace('[' . '[' . __METHOD__ . ':' . __LINE__ . ']: Unfinished!');
277 * Adds an update request to the database result for writing it to the
280 * @param $updateInstance An instance of a updateable criteria
282 * @throws ResultUpdateException If no result was updated
284 public function add2UpdateQueue (LocalUpdateCriteria $updateInstance) {
285 // Rewind the pointer
288 // Get search criteria
289 $searchInstance = $updateInstance->getSearchInstance();
291 // And start looking for the result
292 $foundEntries = $this->getAffectedRows();
293 while (($this->valid()) && ($foundEntries < $searchInstance->getLimit())) {
296 $currentEntry = $this->current();
298 // Is this entry found?
299 if ($searchInstance->ifEntryMatches($currentEntry)) {
301 $this->updateCurrentEntryByCriteria($updateInstance);
308 // If no entry is found/updated throw an exception
309 if ($foundEntries == 0) {
310 // Throw an exception here
311 throw new ResultUpdateException($this, self::EXCEPTION_RESULT_UPDATE_FAILED);
315 $this->setAffectedRows($foundEntries);
317 // Set update instance
318 $this->setUpdateInstance($updateInstance);
322 * Setter for affected rows
324 * @param $rows Number of affected rows
327 public final function setAffectedRows (int $rows) {
328 $this->affectedRows = $rows;
332 * Getter for affected rows
334 * @return $rows Number of affected rows
336 public final function getAffectedRows () {
337 return $this->affectedRows;
341 * Getter for found value of previous found() call
343 * @return $foundValue Found value of previous found() call
345 public final function getFoundValue () {
346 return $this->foundValue;
350 * Checks whether we have out-dated entries or not
352 * @return $needsUpdate Whether we have out-dated entries
354 public function ifDataNeedsFlush () {
355 $needsUpdate = (count($this->outDated) > 0);
360 * Adds registration elements to a given dataset instance
362 * @param $criteriaInstance An instance of a StoreableCriteria class
365 public function addElementsToDataSet (StoreableCriteria $criteriaInstance) {
366 // Walk only through out-dated columns
367 foreach ($this->outDated as $key => $dummy) {
368 // Does this key exist?
369 //* DEBUG: */ echo "outDated: {$key}<br />\n";
370 if ($this->find($key)) {
372 $criteriaInstance->addCriteria($key, $this->getFoundValue());
378 * Find a key inside the result array
380 * @param $key The key we shall find
381 * @return $found Whether the key was found or not
383 public function find ($key) {
384 // By default nothing is found
387 // Rewind the pointer
390 // Walk through all entries
391 while ($this->valid()) {
392 // Advance to next entry
395 // Get the whole array
396 $currentEntry = $this->current();
398 // Is the element there?
399 if (isset($currentEntry[$key])) {
404 $this->foundValue = $currentEntry[$key];
406 // And stop searching
416 * Solver for result index value with call-back method
418 * @param $databaseColumn Database column where the index might be found
419 * @param $frontendInstance The frontend instance to ask for array element
420 * @para $callBack Call-back object for setting the index;
421 * 0=object instance,1=method name
423 * @todo Find a caching way without modifying the result array
425 public function solveResultIndex ($databaseColumn, DatabaseFrontend $frontendInstance, array $callBack) {
426 // By default nothing is found
429 // Is the element in result itself found?
430 if ($this->find($databaseColumn)) {
432 $indexValue = $this->getFoundValue();
433 } elseif ($this->find($frontendInstance->getIndexKey())) {
435 $indexValue = $this->getFoundValue();
439 call_user_func_array($callBack, array($indexValue));