Unsupported array found, maybe later add a call-backable class here, for now
[core.git] / framework / main / classes / lists / class_BaseList.php
1 <?php
2 // Own namespace
3 namespace CoreFramework\Lists;
4
5 // Import framework stuff
6 use CoreFramework\Factory\ObjectFactory;
7 use CoreFramework\Generic\FrameworkInterface;
8 use CoreFramework\Object\BaseFrameworkSystem;
9 use CoreFramework\Visitor\Visitable;
10
11 // Import SPL stuff
12 use \IteratorAggregate;
13 use \Countable;
14
15 /**
16  * A general list class
17  *
18  * @author              Roland Haeder <webmaster@shipsimu.org>
19  * @version             0.0.0
20  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2017 Core Developer Team
21  * @license             GNU GPL 3.0 or any newer version
22  * @link                http://www.shipsimu.org
23  *
24  * This program is free software: you can redistribute it and/or modify
25  * it under the terms of the GNU General Public License as published by
26  * the Free Software Foundation, either version 3 of the License, or
27  * (at your option) any later version.
28  *
29  * This program is distributed in the hope that it will be useful,
30  * but WITHOUT ANY WARRANTY; without even the implied warranty of
31  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
32  * GNU General Public License for more details.
33  *
34  * You should have received a copy of the GNU General Public License
35  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
36  */
37 class BaseList extends BaseFrameworkSystem implements IteratorAggregate, Countable {
38         // Exception constants
39         const EXCEPTION_GROUP_ALREADY_ADDED = 0xf20;
40         const EXCEPTION_GROUP_NOT_FOUND     = 0xf21;
41         const EXCEPTION_INVALID_HASH        = 0xf22;
42
43         /**
44          * List groups array
45          */
46         private $listGroups = array();
47
48         /**
49          * List entries array
50          */
51         private $listEntries = array();
52
53         /**
54          * List index array
55          */
56         private $listIndex = array();
57
58         /**
59          * Protected constructor
60          *
61          * @param       $className      Name of the class
62          * @return      void
63          */
64         protected function __construct ($className) {
65                 // Call parent constructor
66                 parent::__construct($className);
67         }
68
69         /**
70          * Getter for iterator instance from this list
71          *
72          * @return      $iteratorInstance       An instance of a Iterator class
73          */
74         public function getIterator () {
75                 // Get iterator from here
76                 $iteratorInstance = $this->getIteratorInstance();
77
78                 // Is the instance set?
79                 if (is_null($iteratorInstance)) {
80                         // Prepare a default iterator
81                         $iteratorInstance = ObjectFactory::createObjectByConfiguredName('default_iterator_class', array($this));
82
83                         // Set it here
84                         $this->setIteratorInstance($iteratorInstance);
85                 } // END - if
86
87                 // And return it
88                 return $iteratorInstance;
89         }
90
91         /**
92          * Checks whether the given group is set
93          *
94          * @param       $groupName      Group to check if found in list
95          * @return      $isset          Whether the group is valid
96          */
97         public function isGroupSet ($groupName) {
98                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName);
99                 return isset($this->listGroups[$groupName]);
100         }
101
102         /**
103          * Adds the given group or if already added issues a ListGroupAlreadyAddedException
104          *
105          * @param       $groupName      Group to add
106          * @return      void
107          * @throws      ListGroupAlreadyAddedException  If the given group is already added
108          */
109         public function addGroup ($groupName) {
110                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName . ' - CALLED!');
111                 // Is the group already added?
112                 if ($this->isGroupSet($groupName)) {
113                         // Throw the exception here
114                         throw new ListGroupAlreadyAddedException(array($this, $groupName), self::EXCEPTION_GROUP_ALREADY_ADDED);
115                 } // END - if
116
117                 // Add the group which is a simple array
118                 $this->listGroups[$groupName] = ObjectFactory::createObjectByConfiguredName('list_group_class');
119                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName . ' - EXIT!');
120         }
121
122         /**
123          * Adds the given instance to list group and sub group
124          *
125          * @param       $groupName                      Group to add instance to
126          * @param       $subGroup                       Sub group to add instance to
127          * @param       $visitableInstance      An instance of Visitable
128          * @return      void
129          * @throws      NoListGroupException    If the given group is not found
130          */
131         public function addInstance ($groupName, $subGroup, Visitable $visitableInstance) {
132                 // Debug message
133                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName  . ',subGroup=' . $subGroup . ',visitableInstance=' . $visitableInstance->__toString() . ' - CALLED!');
134
135                 // Is the group there?
136                 if (!$this->isGroupSet($groupName)) {
137                         // Throw the exception here
138                         throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
139                 } // END - if
140
141                 // Is the sub group there?
142                 if (!$this->listGroups[$groupName]->isGroupSet($subGroup)) {
143                         // Automatically add it
144                         $this->listGroups[$groupName]->addGroup($subGroup);
145                 } // END - if
146
147                 // Generate the hash
148                 $hash = $this->generateHash($groupName, $subGroup, $visitableInstance);
149
150                 // Debug message
151                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName  . ',subGroup=' . $subGroup . ',hash=' . $hash . ' - Calling addEntry() ...');
152
153                 // Now add it to the group list and hash it
154                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',this->listGroups[' . $groupName . ']=' . $this->listGroups[$groupName]->__toString());
155                 //$this->listGroups[$groupName]->addEntry($subGroup, $hash);
156
157                 // Add the hash to the index
158                 array_push($this->listIndex, $hash);
159
160                 // Add the instance itself to the list
161                 $this->listEntries[$hash] = $visitableInstance;
162
163                 // Debug message
164                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName  . ',subGroup=' . $subGroup . ' - EXIT!');
165         }
166
167         /**
168          * Gets an array from given list
169          *
170          * @param       $list   The requested list
171          * @return      $array  The requested array
172          * @throws      NoListGroupException    If the given group is not found
173          */
174         public final function getArrayFromList ($list) {
175                 // Debug message
176                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',list[' . gettype($list) . ']=' . $list . ' - CALLED!');
177
178                 // Is the group there?
179                 if ((!is_null($list)) && (!$this->isGroupSet($list))) {
180                         // Throw the exception here
181                         throw new NoListGroupException(array($this, $list), self::EXCEPTION_GROUP_NOT_FOUND);
182                 } // END - if
183
184                 // Init array
185                 $array = array();
186
187                 // Is there another list?
188                 if (!is_null($list)) {
189                         // Then get it as well
190                         $array = $this->listGroups[$list]->getArrayFromList(NULL);
191                 } // END - if
192
193                 // Walk through all entries
194                 foreach ($this->listIndex as $hash) {
195                         // Debug message
196                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: hash=' . $hash);
197
198                         // Is the list entry set?
199                         if ($this->isHashValid($hash)) {
200                                 // Add it
201                                 array_push($array, $this->listEntries[$hash]);
202                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: hash=' . $hash . ',array(' . count($array) . ')=' . print_r($array, true) . ' - ADDED!');
203                         } // END - if
204                 } // END - foreach
205
206                 // Debug message
207                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',list[' . gettype($list) . ']=' . $list . ',array()=' . count($array) . ' - EXIT!');
208
209                 // Return it
210                 return $array;
211         }
212
213         /**
214          * Adds the given entry to list group
215          *
216          * @param       $groupName      Group to add instance to
217          * @param       $entry          An entry of any type
218          * @return      void
219          * @throws      NoListGroupException    If the given group is not found
220          */
221         public function addEntry ($groupName, $entry) {
222                 // Debug message
223                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName . ' - CALLED!');
224
225                 // Is the group already added?
226                 if (!$this->isGroupSet($groupName)) {
227                         // Throw the exception here
228                         throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
229                 } // END - if
230
231                 // Generate hash
232                 $hash = $this->generateHash($groupName, $groupName, $entry);
233
234                 // Debug message
235                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName . ',entry=' . print_r($entry, true) . ', hash=' . $hash);
236
237                 // Add the hash to the index
238                 array_push($this->listIndex, $hash);
239
240                 // Debug message
241                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName . ',listEntries()=' . count($this->listEntries));
242
243                 // Now add the entry to the list
244                 $this->listEntries[$hash] = $entry;
245
246                 // Debug message
247                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName . ',listEntries()=' . count($this->listEntries) . ' - EXIT!');
248         }
249
250         /**
251          * Removes given entry from the list group
252          *
253          * @param       $groupName      Group where we should remove the entry from
254          * @param       $entry          The entry we should remove
255          * @return      void
256          * @throws      NoListGroupException    If the given group is not found
257          */
258         public function removeEntry ($groupName, $entry) {
259                 // Debug message
260                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName . ' - CALLED!');
261
262                 // Is the group already added?
263                 if (!$this->isGroupSet($groupName)) {
264                         // Throw the exception here
265                         throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
266                 } // END - if
267
268                 // Generate hash
269                 $hash = $this->generateHash($groupName, $groupName, $entry);
270
271                 // Debug message
272                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName . ',entry=' . $entry . ', hash=' . $hash);
273
274                 // Remove it from the list ...
275                 unset($this->listEntries[$hash]);
276
277                 // ... and hash list as well
278                 unset($this->listIndex[array_search($hash, $this->listIndex)]);
279
280                 // Debug message
281                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']: this=' . $this->__toString() . ',groupName=' . $groupName . ' - EXIT!');
282         }
283
284         /**
285          * Generates a hash from given group, sub group and entry
286          *
287          * @param       $groupName      Group to add instance to
288          * @param       $subGroup       Sub group to add instance to
289          * @param       $entry          An entry of any type
290          * @return      $hash           The generated
291          */
292         private function generateHash ($groupName, $subGroup, $entry) {
293                 // Created entry, 'null' is default
294                 $entry2 = 'null';
295
296                 // Determine type of entry
297                 if (is_null($entry)) {
298                         // Ignore this
299                 } elseif ($entry instanceof FrameworkInterface) {
300                         // Own instance detected
301                         $entry2 = $entry->hashCode();
302                 } elseif ((is_int($entry)) || (is_float($entry)) || (is_resource($entry))) {
303                         // Integer/float/resource detected
304                         $entry2 = gettype($entry) . ':' . $entry;
305                 } elseif (is_string($entry)) {
306                         // String found
307                         $entry2 = crc32($entry) . ':' . strlen($entry);
308                 } elseif ((is_array($entry)) && (isset($entry['id']))) {
309                         // Supported array found
310                         $entry2 = crc32($entry['id']) . ':' . count($entry);
311                 } else {
312                         // Unsupported type detected
313                         self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST[' . __METHOD__ . ':' . __LINE__ . ']: Entry type ' . gettype($entry) . ' is unsupported.');
314
315                         // At least take all keys from array
316                         $entry2 = gettype($entry) . ':' . implode(':', array_keys($entry));
317                 }
318
319                 // Construct string which we shall hash
320                 $hashString = $groupName . ':' . $subGroup . ':' . $entry2;
321
322                 // Hash it with fastest hasher
323                 $hash = crc32($hashString);
324
325                 // And return it
326                 return $hash;
327         }
328
329         /**
330          * Clears an array of groups, all are being checked for existence
331          *
332          * @param       $groupNames             An array with existing list groups
333          * @return      void
334          */
335         protected function clearGroups (array $groupNames) {
336                 // Walk through all groups
337                 foreach ($groupNames as $groupName) {
338                         // Clear this group
339                         $this->clearGroup($groupName);
340                 } // END - foreach
341         }
342
343         /**
344          * Clears a single group by resetting it to its initial state (empty array)
345          *
346          * @param       $groupName      Name of an existing group to clear
347          * @return      void
348          */
349         protected function clearGroup ($groupName) {
350                 // Does this group exist?
351                 if (!$this->isGroupSet($groupName)) {
352                         // Throw the exception here
353                         throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
354                 } // END - if
355
356                 // Then clear this group list
357                 $this->listGroups[$groupName]->clearList();
358
359                 // Clear this list
360                 $this->listIndex = array();
361                 $this->listEntries = array();
362         }
363         
364         /**
365          * Counts all entries in this list
366          *
367          * @return      $count  All entries in this list
368          */
369         public final function count () {
370                 return count($this->listIndex);
371         }
372
373         /**
374          * Checks whether the given hash is valid
375          *
376          * @param       $hash           The hash we should validate
377          * @return      $isValid        Whether the given hash is valid
378          */
379         public final function isHashValid ($hash) {
380                 // Check it
381                 $isValid = ((in_array($hash, $this->listIndex)) && (isset($this->listEntries[$hash])));
382
383                 // Return the result
384                 return $isValid;
385         }
386
387         /**
388          * Getter for hash from given hash index
389          *
390          * @param       $hashIndex      Index holding the hash
391          * @return      $hash           The hash
392          */
393         public final function getHash ($hashIndex) {
394                 // Get it ...
395                 $hash = $this->listIndex[$hashIndex];
396
397                 // ... and return it
398                 return $hash;
399         }
400
401         /**
402          * Gets an entry from given hash index
403          *
404          * @param       $hashIndex      The hash index to resolve the mapped entry
405          * @return      $entry          Solved entry from list
406          * @throws      InvalidListHashException        If the solved hash index is invalid
407          */
408         public function getEntry ($hashIndex) {
409                 // Get the hash value
410                 $hash = $this->getHash($hashIndex);
411
412                 // Is the hash valid?
413                 if (!$this->isHashValid($hash)) {
414                         // Throw an exception here
415                         throw new InvalidListHashException(array($this, $hash, $hashIndex), self::EXCEPTION_INVALID_HASH);
416                 } // END - if
417
418                 // Now copy the entry
419                 $entry = $this->listEntries[$hash];
420
421                 // Return it
422                 return $entry;
423         }
424
425         /**
426          * Gets a full array from given group name
427          *
428          * @param       $groupName      The group name to get a list for
429          * @return      $entries        The array with all entries
430          * @throws      NoListGroupException    If the specified group is invalid
431          */
432         public function getArrayFromProtocolInstance ($groupName) {
433                 // Is the group valid?
434                 if (!$this->isGroupSet($groupName)) {
435                         // Throw the exception here
436                         throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
437                 } // END - if
438
439                 // Init the entries' array
440                 $entries = array();
441
442                 // Get an iterator
443                 $iteratorInstance = $this->listGroups[$groupName]->getIterator();
444
445                 // Rewind the iterator for this round
446                 $iteratorInstance->rewind();
447
448                 // Go through all entries
449                 while ($iteratorInstance->valid()) {
450                         // Get key
451                         $entryIndex = $iteratorInstance->key();
452
453                         // ... and the final entry which is the stored instance
454                         $entry = $this->getEntry($entryIndex);
455
456                         // Debug message
457                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('LIST: Adding entry ' . $entry . ' ...');
458
459                         // Add it to the list
460                         $entries[$iteratorInstance->current()] = $entry;
461
462                         // Skip to next one
463                         $iteratorInstance->next();
464                 } // END - while
465
466                 // Return the list
467                 return $entries;
468         }
469
470         /**
471          * Updates the given entry by hash with given array
472          *
473          * @param       $hash           Hash for this entry
474          * @param       $entryArray     Array with entry we should update
475          * @return      void
476          * @throws      InvalidListHashException        If the solved hash index is invalid
477          */
478         public function updateCurrentEntryByHash ($hash, array $entryArray) {
479                 // Is the hash valid?
480                 if (!$this->isHashValid($hash)) {
481                         // Throw an exception here, hashIndex is unknown at this point
482                         throw new InvalidListHashException(array($this, $hash, -999), self::EXCEPTION_INVALID_HASH);
483                 } // END - if
484
485                 // Set the entry
486                 $this->listEntries[$hash] = $entryArray;
487         }
488
489 }