]> git.mxchange.org Git - core.git/blob - framework/main/classes/iterator/registry/class_RegistryIterator.php
Continued:
[core.git] / framework / main / classes / iterator / registry / class_RegistryIterator.php
1 <?php
2 // Own namespace
3 namespace Org\Mxchange\CoreFramework\Iterator\Registry;
4
5 // Import framework stuff
6 use Org\Mxchange\CoreFramework\EntryPoint\ApplicationEntryPoint;
7 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
8 use Org\Mxchange\CoreFramework\Generic\NullPointerException;
9 use Org\Mxchange\CoreFramework\Iterator\BaseIterator;
10 use Org\Mxchange\CoreFramework\Registry\Register;
11 use Org\Mxchange\CoreFramework\Registry\Registerable;
12 use Org\Mxchange\CoreFramework\Registry\Sub\SubRegistry;
13 use Org\Mxchange\CoreFramework\Traits\Registry\RegisterTrait;
14
15 // Import SPL stuff
16 use \BadMethodCallException;
17 use \LogicException;
18
19 /**
20  * A registry iterator
21  *
22  * @author              Roland Haeder <webmaster@ship-simu.org>
23  * @version             0.0.0
24  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
25  * @license             GNU GPL 3.0 or any newer version
26  * @link                http://www.ship-simu.org
27  *
28  * This program is free software: you can redistribute it and/or modify
29  * it under the terms of the GNU General Public License as published by
30  * the Free Software Foundation, either version 3 of the License, or
31  * (at your option) any later version.
32  *
33  * This program is distributed in the hope that it will be useful,
34  * but WITHOUT ANY WARRANTY; without even the implied warranty of
35  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
36  * GNU General Public License for more details.
37  *
38  * You should have received a copy of the GNU General Public License
39  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
40  */
41 class RegistryIterator extends BaseIterator implements IteratableRegistry {
42         // Load traits
43         use RegisterTrait;
44
45         /**
46          * All found registry keys
47          */
48         private $registryKeys = [];
49
50         /**
51          * An array containing keys ob sub-registries which keys should only be
52          * included in the iterator.
53          */
54         private $onlyRegistries = [];
55
56         /**
57          * Current array key
58          */
59         private $key = NULL;
60
61         /**
62          * Protected constructor
63          *
64          * @return      void
65          */
66         private function __construct () {
67                 // Call parent constructor
68                 parent::__construct(__CLASS__);
69
70                 // Init registry keys array
71                 $this->registryKeys = [
72                         // Generic registry
73                         'generic' => [],
74                         // Instance registry
75                         'instance' => [],
76                 ];
77         }
78
79         /**
80          * Creates an instance of this class
81          *
82          * @param       $registryInstance       An instance of a Register class
83          * @return      $iteratorInstance       An instance of a Iterator class
84          */
85         public final static function createRegistryIterator (Register $registryInstance) {
86                 // Get new instance
87                 $iteratorInstance = new RegistryIterator();
88
89                 // Set registry here
90                 $iteratorInstance->setRegistryInstance($registryInstance);
91
92                 // Return the prepared instance
93                 return $iteratorInstance;
94         }
95
96         /**
97          * Setter for only-registries array
98          *
99          * @param       $onlyRegistries         Array with keys only being iterated over
100          * @return      void
101          */
102         private function setOnlyRegistries (array $onlyRegistries) {
103                 $this->onlyRegistries = $onlyRegistries;
104         }
105
106         /**
107          * Initializes this iterator by scanning over the registry for all keys.
108          *
109          * @param       $onlyRegistries         Only iterate on these sub-registry keys, default is all
110          * @return      void
111          * @throws      LogicException  If a registry entry does not implement Registerable
112          * @throws      NullPointerException    If criteriaKey or criteriaMethod is not set but a call-back instance is set
113          */
114         public function initIterator (array $onlyRegistries = []) {
115                 // Set it in this registry
116                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR: onlyRegistries()=%d - CALLED!', count($onlyRegistries)));
117                 $this->setOnlyRegistries($onlyRegistries);
118
119                 // Get generic registry entries from it
120                 $entries = $this->getRegistryInstance()->getGenericRegistry();
121
122                 // Anything in there?
123                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[generic]: entries()=%d', count($entries)));
124                 if (count($entries) > 0) {
125                         // Debugging:
126                         /* DEBUG-DIE: */ ApplicationEntryPoint::exitApplication(sprintf('[%s:%d]: UNFINISHED: entries=%s', __METHOD__, __LINE__, print_r($entries, TRUE)));
127                 }
128
129                 // Get instance registry entries from it
130                 $entries = $this->getRegistryInstance()->getInstanceRegistry();
131
132                 // Anything in there?
133                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[instance]: entries()=%d', count($entries)));
134                 if (count($entries) > 0) {
135                         // Then run over all
136                         foreach ($entries as $key => $entry) {
137                                 // Is an unwanted registry found?
138                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[instance]: key=%s,entry[]=%s', $key, gettype($entry)));
139                                 if (substr($key, -8, 8) == 'registry') {
140                                         // Skip this!
141                                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[instance]: key=%s is a registry key, skipping ...', $key));
142                                         continue;
143                                 }
144
145                                 // Is it an instance of a sub-registry?
146                                 if (count($onlyRegistries) > 0 && !in_array($key, $onlyRegistries, TRUE)) {
147                                         // Not in requested registries
148                                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[instance]: key=%s is not wanted, skipping ...', $key));
149                                         continue;
150                                 } elseif ($entry instanceof SubRegistry) {
151                                         // Get iterator from this instance
152                                         $subRegistryInstances = $entry->getInstanceRegistry();
153
154                                         // Add all sub-registry keys to this registry keys array
155                                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[instance]: subRegistryInstances()=%d', count($subRegistryInstances)));
156                                         //* DEBUG-DIE: */ ApplicationEntryPoint::exitApplication(sprintf('[%s:%d]: key=%s,subRegistryInstances=%s', __METHOD__, __LINE__, $key, print_r($subRegistryInstances, TRUE)));
157                                         foreach (array_keys($subRegistryInstances) as $subKey) {
158                                                 // Add it
159                                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[instance]: Adding key=%s,subKey=%s ...', $key, $subKey));
160                                                 array_push($this->registryKeys['instance'], $subKey);
161
162                                                 // Is the current key set?
163                                                 if (is_null($this->key)) {
164                                                         // Init key
165                                                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[instance]: Setting subKey=%s as first key ...', $subKey));
166                                                         $this->key = $subKey;
167                                                 }
168                                         }
169
170                                         // Skip below code
171                                         continue;
172                                 } elseif (!($entry instanceof Registerable)) {
173                                         // Not registerable?!
174                                         throw new LogicException(sprintf('entry[]=%s does not implement Registerable.', gettype($entry)), FrameworkInterface::EXCEPTION_LOGIC_EXCEPTION);
175                                 }
176
177                                 // Is the current key set?
178                                 if (is_null($this->key)) {
179                                         // Init key
180                                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[instance]: Setting key=%s as first key ...', $key));
181                                         $this->key = $key;
182                                 }
183
184                                 // Add key to array
185                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[instance]: key=%s - Adding ...', $key));
186                                 //* DEBUG-DIE: */ ApplicationEntryPoint::exitApplication(sprintf('[%s:%d]: key=%s,entry=%s', __METHOD__, __LINE__, $key, print_r($entry, TRUE)));
187                                 array_push($this->registryKeys['instance'], $key);
188                         }
189                 }
190
191                 // Trace message
192                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('REGISTRY-ITERATOR: EXIT!');
193         }
194
195         /**
196          * Getter for all registry keys (array)
197          *
198          * @return      $registryKeys   Registry keys
199          */
200         public final function getRegistryKeys () {
201                 // Return it
202                 return $this->registryKeys;
203         }
204
205         /**
206          * Getter for current value from group or generic
207          *
208          * @return      $current        Current value in iteration
209          * @throws      NullPointerException    If current key points to a non-existing entry in searched registries
210          */
211         public function current () {
212                 // Default is null
213                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: CALLED!', $this->key()));
214                 //* DEBUG-DIE: */ ApplicationEntryPoint::exitApplication(sprintf('[%s:%d]: this->key(%d)[%s]=%s,this->valid=%d,this->registryKeys=%s', __METHOD__, __LINE__, strlen($this->key()), gettype($this->key()), $this->key(), intval($this->valid()), print_r($this->registryKeys, TRUE)));
215                 $current = NULL;
216                 $entries = [];
217
218                 // Get all registries
219                 $allRegistries = $this->getRegistryInstance()->getInstanceRegistry();
220
221                 // Loop through all sub-sets
222                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: allRegistries()=%d', $this->key(), count($allRegistries)));
223                 foreach ($allRegistries as $registryKey => $registryInstance) {
224                         // Is this key wanted?
225                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: registryKey=%s', $this->key(), $registryKey));
226                         if (count($this->onlyRegistries) == 0 || in_array($registryKey, $this->onlyRegistries)) {
227                                 // Yes, then loop through them only
228                                 $instances = $registryInstance->getInstanceRegistry();
229
230                                 // The key should be there
231                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: Handling registryKey=%s ...', $this->key(), $registryKey));
232                                 //* DEBUG-DIE: */ ApplicationEntryPoint::exitApplication(sprintf('[%s:%d]: instances=%s', __METHOD__, __LINE__, print_r($instances, TRUE)));
233                                 if (!isset($instances[$this->key()])) {
234                                         // Skip below code
235                                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: registryKey=%s has no this->key=%s, skipping ...', $this->key(), $registryKey));
236                                         continue;
237                                 }
238
239                                 // Set as current element and leave loop
240                                 $current = $instances[$this->key()];
241                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: registryKey=%s,current=%s found. - BREAK!', $this->key(), $registryKey, $current->__toString()));
242                                 break;
243                         }
244                 }
245
246                 // Is current still NULL?
247                 if (is_null($current)) {
248                         // This cannot happen and indicates a logic error
249                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
250                 }
251
252                 // Return it
253                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: current[%s]=%s - EXIT!', $this->key(), gettype($current), $current));
254                 return $current;
255         }
256
257         /**
258          * Getter for key from group or generic
259          *
260          * @return      $key    Current key in iteration
261          */
262         public function key () {
263                 // Return it
264                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: EXIT!', $this->key));
265                 return $this->key;
266         }
267
268         /**
269          * Advances to the next entry
270          *
271          * @return      void
272          * @throws      BadMethodCallException  If $this->valid() returns FALSE
273          * @throws      UnexpectedValueException        If $registryType is not changed
274          */
275         public function next () {
276                 // Is valid() still TRUE?
277                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: CALLED!', $this->key()));
278                 //* DEBUG-DIE: */ ApplicationEntryPoint::exitApplication(sprintf('[%s:%d]: this->key(%d)[%s]=%s,this->valid=%d,this->registryKeys=%s', __METHOD__, __LINE__, strlen($this->key()), gettype($this->key()), $this->key(), intval($this->valid()), print_r($this->registryKeys, TRUE)));
279                 if (!$this->valid()) {
280                         // Bad method call!
281                         throw new BadMethodCallException(sprintf('this->key[%s]=%s is no longer valid, but method was called.', gettype($this->key()), $this->key()), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
282                 } elseif ((count($this->registryKeys['generic']) == 0) && (count($this->registryKeys['instance']) == 0)) {
283                         // Both arrays are empty
284                         throw new BadMethodCallException('No array elements in "generic" and "instance" found but method called.', FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
285                 }
286
287                 // Default is not valid
288                 $nextIndex = -1;
289                 $isNextValid = FALSE;
290                 $registryType = 'invalid';
291
292                 // Get first array element ...
293                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: this->registryKeys[generic]()=%d,this->registryKeys[instance]()=%d', $this->key(), count($this->registryKeys['generic']), count($this->registryKeys['instance'])));
294                 if (count($this->registryKeys['generic']) > 0) {
295                         // First generic array
296                         /* UNFINISHED */ ApplicationEntryPoint::exitApplication(sprintf('[%s:%d]: this->key(%d)[%s]=%s,this->valid=%d,this->registryKeys=%s', __METHOD__, __LINE__, strlen($this->key()), gettype($this->key()), $this->key(), intval($this->valid()), print_r($this->registryKeys, TRUE)));
297                 } elseif (count($this->registryKeys['instance']) > 0) {
298                         // Second instance, current key's index + 1
299                         $nextIndex = array_search($this->key(), $this->registryKeys['instance']) + 1;
300                         $isNextValid = isset($this->registryKeys['instance'][$nextIndex]);
301                         $registryType = 'instance';
302                 }
303
304                 // Is it still valid?
305                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: isNextValid=%d', $this->key(), intval($isNextValid)));
306                 if (!$isNextValid) {
307                         // Throw exception
308                         throw new BadMethodCallException(sprintf('this->key=%s is last key in this iteration. Forgot to invoke valid() before?', $this->key()), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
309                 } elseif ($registryType == 'invalid') {
310                         // Not changed!
311                         throw new UnexpectedValueException('registryType has not been changed.');
312                 }
313
314                 // Yes, then advance to that entry
315                 $this->key = $this->registryKeys[$registryType][$nextIndex];
316
317                 // Trace message
318                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: EXIT!', $this->key()));
319         }
320
321         /**
322          * Rewinds to the beginning of the iteration
323          *
324          * @return      void
325          * @throws      BadMethodCallException  If $this->key is already the first element
326          */
327         public function rewind () {
328                 // Is current key first key?
329                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: CALLED!', $this->key()));
330                 //* DEBUG-DIE: */ ApplicationEntryPoint::exitApplication(sprintf('[%s:%d]: this->key(%d)[%s]=%s,this->valid=%d,this->registryKeys=%s', __METHOD__, __LINE__, strlen($this->key()), gettype($this->key()), $this->key(), intval($this->valid()), print_r($this->registryKeys, TRUE)));
331                 if (array_search($this->key(), $this->getRegistryKeys()) === 0) {
332                         // rewind() cannot rewind first entry!
333                         throw new BadMethodCallException(sprintf('this->key=%s is already first element, but method was called.', $this->key()), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
334                 } elseif ((count($this->registryKeys['generic']) == 0) && (count($this->registryKeys['instance']) == 0)) {
335                         // Both arrays are empty
336                         throw new BadMethodCallException('No array elements in "generic" and "instance" found but method called.', FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
337                 }
338
339                 // Get first array element ...
340                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: this->registryKeys[generic]()=%d,this->registryKeys[instance]()=%d', $this->key(), count($this->registryKeys['generic']), count($this->registryKeys['instance'])));
341                 if (count($this->registryKeys['generic']) > 0) {
342                         // First generic array
343                         /* UNFINISHED */ ApplicationEntryPoint::exitApplication(sprintf('[%s:%d]: this->key(%d)[%s]=%s,this->valid=%d,this->registryKeys=%s', __METHOD__, __LINE__, strlen($this->key()), gettype($this->key()), $this->key(), intval($this->valid()), print_r($this->registryKeys, TRUE)));
344                 } elseif (count($this->registryKeys['instance']) > 0) {
345                         // Second instance
346                         $this->key = $this->registryKeys['instance'][0];
347                 }
348
349                 // Trace message
350                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: EXIT!', $this->key()));
351         }
352
353         /**
354          * Checks wether the current entry is valid (not at the end of the list)
355          *
356          * @return      $valid  Whether the current key is still valid
357          */
358         public function valid () {
359                 // Is the element there?
360                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: CALLED!', $this->key()));
361                 //* DEBUG-DIE: */ ApplicationEntryPoint::exitApplication(sprintf('[%s:%d]: this->key(%d)[%s]=%s,this->registryKeys=%s', __METHOD__, __LINE__, strlen($this->key()), gettype($this->key()), $this->key(), print_r($this->registryKeys, TRUE)));
362                 $valid = (in_array($this->key(), $this->registryKeys['instance']) || in_array($this->key(), $this->registryKeys['generic']));
363
364                 // Return flag
365                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('REGISTRY-ITERATOR[%s]: valid=%d - EXIT!', $this->key(), intval($valid)));
366                 return $valid;
367         }
368
369 }