Continued:

[core.git] / framework / main / classes / lists / class_BaseList.php

diff --git a/framework/main/classes/lists/class_BaseList.php b/framework/main/classes/lists/class_BaseList.php
index 5cf4c15c19c005a2c9c05e59a7a60f7ca3b0c473..edca181d6fa99913340a9ec8abb481fb5abd05f9 100644 (file)
--- a/framework/main/classes/lists/class_BaseList.php
+++ b/framework/main/classes/lists/class_BaseList.php
@@ -10,6 +10,8 @@ use Org\Mxchange\CoreFramework\Traits\Iterator\IteratorTrait;
 use Org\Mxchange\CoreFramework\Visitor\Visitable;
 
 // Import SPL stuff
+use \BadMethodCallException;
+use \InvalidArgumentException;
 use \IteratorAggregate;
 use \Countable;
 
@@ -18,7 +20,7 @@ use \Countable;
  *
  * @author             Roland Haeder <webmaster@shipsimu.org>
  * @version            0.0.0
- * @copyright  Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2020 Core Developer Team
+ * @copyright  Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2021 Core Developer Team
  * @license            GNU GPL 3.0 or any newer version
  * @link               http://www.shipsimu.org
  *
@@ -59,6 +61,14 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         */
        private $listIndex = [];
 
+       /**
+        * Cached values from "expensive" method calls
+        */
+       private $cache = [
+               // Cached isValidHash() calls
+               'is_valid' => [],
+       ];
+
        /**
         * Protected constructor
         *
@@ -99,28 +109,38 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         * @return      $isset          Whether the group is valid
         */
        public function isGroupSet (string $groupName) {
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName);
+               // Validate parameter
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-LIST: groupName=%s - CALLED!', $groupName));
+               if (empty($groupName)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "groupName" is empty');
+               }
+
+               // Check on existence ...
                return isset($this->listGroups[$groupName]);
        }
 
        /**
-        * Adds the given group or if already added issues a ListGroupAlreadyAddedException
+        * Adds the given group or if already added issues a BadMethodCallException
         *
         * @param       $groupName      Group to add
         * @return      void
-        * @throws      ListGroupAlreadyAddedException  If the given group is already added
+        * @throws      BadMethodCallException  If the given group is already added
         */
        public function addGroup (string $groupName) {
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName . ' - CALLED!');
-               // Is the group already added?
-               if ($this->isGroupSet($groupName)) {
+               // Validate parameter
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-LIST: groupName=%s - CALLED!', $groupName));
+               if (empty($groupName)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "groupName" is empty');
+               } elseif ($this->isGroupSet($groupName)) {
                        // Throw the exception here
-                       throw new ListGroupAlreadyAddedException(array($this, $groupName), self::EXCEPTION_GROUP_ALREADY_ADDED);
+                       throw new BadMethodCallException(sprintf('groupName=%s is already set', $groupName), self::EXCEPTION_GROUP_ALREADY_ADDED);
                }
 
                // Add the group which is a simple array
                $this->listGroups[$groupName] = ObjectFactory::createObjectByConfiguredName('list_group_class');
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName . ' - EXIT!');
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName=' . $groupName . ' - EXIT!');
        }
 
        /**
@@ -130,16 +150,20 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         * @param       $subGroup                       Sub group to add instance to
         * @param       $visitableInstance      An instance of Visitable
         * @return      void
-        * @throws      NoListGroupException    If the given group is not found
+        * @throws      BadMethodCallException  If the given group is not found
         */
        public function addInstance (string $groupName, string $subGroup, Visitable $visitableInstance) {
-               // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName  . ',subGroup=' . $subGroup . ',visitableInstance=' . $visitableInstance->__toString() . ' - CALLED!');
-
-               // Is the group there?
-               if (!$this->isGroupSet($groupName)) {
+               // Validate parameter
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName=' . $groupName  . ',subGroup=' . $subGroup . ',visitableInstance=' . $visitableInstance->__toString() . ' - CALLED!');
+               if (empty($groupName)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "groupName" is empty');
+               } elseif (empty($subGroup)) {
+                       // Throw it again
+                       throw new InvalidArgumentException('Parameter "subGroup" is empty');
+               } elseif (!$this->isGroupSet($groupName)) {
                        // Throw the exception here
-                       throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
+                       throw new BadMethodCallException(sprintf('groupName=%s is not a valid group', $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
                }
 
                // Is the sub group there?
@@ -151,51 +175,49 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
                // Generate the hash
                $hash = $this->generateHash($groupName, $subGroup, $visitableInstance);
 
-               // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',this->listGroups[' . $groupName . ']=' . $this->listGroups[$groupName]->__toString());
-
                // Add the hash to the index
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this->listGroups[' . $groupName . ']=' . $this->listGroups[$groupName]->__toString());
                array_push($this->listIndex, $hash);
 
                // Add the instance itself to the list
                $this->listEntries[$hash] = $visitableInstance;
 
                // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName  . ',subGroup=' . $subGroup . ' - EXIT!');
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName=' . $groupName  . ',subGroup=' . $subGroup . ' - EXIT!');
        }
 
        /**
         * Gets an array from given list
         *
-        * @param       $list   The requested list
+        * @param       $groupName      The requested list
         * @return      $array  The requested array
-        * @throws      NoListGroupException    If the given group is not found
+        * @throws      BadMethodCallException  If the given group is not found
         */
-       public final function getArrayFromList ($list) {
-               // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',list[' . gettype($list) . ']=' . $list . ' - CALLED!');
-
+       public final function getArrayFromList (string $groupName) {
                // Is the group there?
-               if ((!is_null($list)) && (!$this->isGroupSet($list))) {
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName[' . gettype($groupName) . ']=' . $groupName . ' - CALLED!');
+               if (empty($groupName)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "groupName" is empty');
+               } elseif (!$this->isGroupSet($groupName)) {
                        // Throw the exception here
-                       throw new NoListGroupException(array($this, $list), self::EXCEPTION_GROUP_NOT_FOUND);
+                       throw new BadMethodCallException(sprintf('groupName=%s is not a valid group', $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
                }
 
                // Init array
                $array = [];
 
                // Is there another list?
-               if (!is_null($list)) {
+               if ($this->listGroups[$groupName]->isGroupSet($groupName)) {
                        // Then get it as well
-                       $array = $this->listGroups[$list]->getArrayFromList(NULL);
+                       //* DEBUG-DIE: */ die(sprintf('[%s:%d]: groupName=%s,this=%s', __METHOD__, __LINE__, $groupName, print_r($this, TRUE)));
+                       $array = $this->listGroups[$groupName]->getArrayFromList($groupName);
                }
 
                // Walk through all entries
                foreach ($this->listIndex as $hash) {
-                       // Debug message
-                       //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: hash=' . $hash);
-
                        // Is the list entry set?
+                       //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: hash=' . $hash);
                        if ($this->isHashValid($hash)) {
                                // Add it
                                array_push($array, $this->listEntries[$hash]);
@@ -203,10 +225,8 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
                        }
                }
 
-               // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',list[' . gettype($list) . ']=' . $list . ',[]=' . count($array) . ' - EXIT!');
-
                // Return it
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName[' . gettype($groupName) . ']=' . $groupName . ',[]=' . count($array) . ' - EXIT!');
                return $array;
        }
 
@@ -216,35 +236,36 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         * @param       $groupName      Group to add instance to
         * @param       $entry          An entry of any type
         * @return      void
-        * @throws      NoListGroupException    If the given group is not found
+        * @throws      BadMethodCallException  If the given group is not found
         */
        public function addEntry (string $groupName, $entry) {
-               // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName . ' - CALLED!');
-
                // Is the group already added?
-               if (!$this->isGroupSet($groupName)) {
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName=' . $groupName . ' - CALLED!');
+               if (empty($groupName)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "groupName" is empty');
+               } elseif (!$this->isGroupSet($groupName)) {
                        // Throw the exception here
-                       throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
+                       throw new BadMethodCallException(sprintf('groupName=%s is not a valid group', $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
                }
 
                // Generate hash
                $hash = $this->generateHash($groupName, $groupName, $entry);
 
                // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName . ',entry=' . print_r($entry, true) . ', hash=' . $hash);
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName=' . $groupName . ',entry=' . print_r($entry, true) . ', hash=' . $hash);
 
                // Add the hash to the index
                array_push($this->listIndex, $hash);
 
                // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName . ',listEntries()=' . count($this->listEntries));
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName=' . $groupName . ',listEntries()=' . count($this->listEntries));
 
                // Now add the entry to the list
                $this->listEntries[$hash] = $entry;
 
                // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName . ',listEntries()=' . count($this->listEntries) . ' - EXIT!');
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName=' . $groupName . ',listEntries()=' . count($this->listEntries) . ' - EXIT!');
        }
 
        /**
@@ -253,23 +274,24 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         * @param       $groupName      Group where we should remove the entry from
         * @param       $entry          The entry we should remove
         * @return      void
-        * @throws      NoListGroupException    If the given group is not found
+        * @throws      BadMethodCallException  If the given group is not found
         */
        public function removeEntry (string $groupName, $entry) {
-               // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName . ' - CALLED!');
-
                // Is the group already added?
-               if (!$this->isGroupSet($groupName)) {
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName=' . $groupName . ' - CALLED!');
+               if (empty($groupName)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "groupName" is empty');
+               } elseif (!$this->isGroupSet($groupName)) {
                        // Throw the exception here
-                       throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
+                       throw new BadMethodCallException(sprintf('groupName=%s is not a valid group', $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
                }
 
                // Generate hash
                $hash = $this->generateHash($groupName, $groupName, $entry);
 
                // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName . ',entry=' . $entry . ', hash=' . $hash);
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName=' . $groupName . ',entry=' . $entry . ', hash=' . $hash);
 
                // Remove it from the list ...
                unset($this->listEntries[$hash]);
@@ -278,7 +300,7 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
                unset($this->listIndex[array_search($hash, $this->listIndex)]);
 
                // Debug message
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: this=' . $this->__toString() . ',groupName=' . $groupName . ' - EXIT!');
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName=' . $groupName . ' - EXIT!');
        }
 
        /**
@@ -291,6 +313,7 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         */
        private function generateHash (string $groupName, string $subGroup, $entry) {
                // Created entry, 'null' is default
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: groupName=' . $groupName  . ',subGroup=' . $subGroup . ',entry[]=' . gettype($entry) . ' - CALLED!');
                $entry2 = 'null';
 
                // Determine type of entry
@@ -320,12 +343,13 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
                }
 
                // Construct string which we shall hash
-               $hashString = $groupName . ':' . $subGroup . ':' . $entry2;
+               $hashString = sprintf('%s:%s:%s', $groupName, $subGroup, $entry2);
 
                // Hash it with fastest hasher
                $hash = crc32($hashString);
 
                // And return it
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-LIST: hash=%s - EXIT!', $hash));
                return $hash;
        }
 
@@ -351,9 +375,12 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         */
        protected function clearGroup (string $groupName) {
                // Does this group exist?
-               if (!$this->isGroupSet($groupName)) {
+               if (empty($groupName)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "groupName" is empty');
+               } elseif (!$this->isGroupSet($groupName)) {
                        // Throw the exception here
-                       throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
+                       throw new BadMethodCallException(sprintf('groupName=%s is not a valid group', $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
                }
 
                // Then clear this group list
@@ -379,12 +406,18 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         * @param       $hash           The hash we should validate
         * @return      $isValid        Whether the given hash is valid
         */
-       public final function isHashValid ($hash) {
-               // Check it
-               $isValid = ((in_array($hash, $this->listIndex)) && (isset($this->listEntries[$hash])));
+       public final function isHashValid (string $hash) {
+               // Validate parameter
+               if (empty($hash)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "hash" is empty');
+               } elseif (!isset($this->cache['is_valid'][$hash])) {
+                       // Check it
+                       $this->cache['is_valid'][$hash] = ((in_array($hash, $this->listIndex)) && (isset($this->listEntries[$hash])));
+               }
 
                // Return the result
-               return $isValid;
+               return $this->cache['is_valid'][$hash];
        }
 
        /**
@@ -393,7 +426,7 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         * @param       $hashIndex      Index holding the hash
         * @return      $hash           The hash
         */
-       public final function getHash ($hashIndex) {
+       public final function getHashByIndex (int $hashIndex) {
                // Get it ...
                $hash = $this->listIndex[$hashIndex];
 
@@ -408,9 +441,9 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         * @return      $entry          Solved entry from list
         * @throws      InvalidListHashException        If the solved hash index is invalid
         */
-       public function getEntry ($hashIndex) {
+       public function getEntryByIndex (int $hashIndex) {
                // Get the hash value
-               $hash = $this->getHash($hashIndex);
+               $hash = $this->getHashByIndex($hashIndex);
 
                // Is the hash valid?
                if (!$this->isHashValid($hash)) {
@@ -430,13 +463,17 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         *
         * @param       $groupName      The group name to get a list for
         * @return      $entries        The array with all entries
-        * @throws      NoListGroupException    If the specified group is invalid
+        * @throws      BadMethodCallException  If the specified group is invalid
         */
        public function getArrayFromProtocolInstance (string $groupName) {
                // Is the group valid?
-               if (!$this->isGroupSet($groupName)) {
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-LIST: groupName=%s - CALLED!', $groupName));
+               if (empty($groupName)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "groupName" is empty');
+               } elseif (!$this->isGroupSet($groupName)) {
                        // Throw the exception here
-                       throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
+                       throw new BadMethodCallException(sprintf('groupName=%s is not a valid group', $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
                }
 
                // Init the entries' array
@@ -454,12 +491,10 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
                        $entryIndex = $iteratorInstance->key();
 
                        // ... and the final entry which is the stored instance
-                       $entry = $this->getEntry($entryIndex);
-
-                       // Debug message
-                       //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('LIST: Adding entry ' . $entry . ' ...');
+                       $entry = $this->getEntryByIndex($entryIndex);
 
                        // Add it to the list
+                       //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-LIST: Adding entry ' . $entry . ' ...');
                        $entries[$iteratorInstance->current()] = $entry;
 
                        // Skip to next one
@@ -478,9 +513,12 @@ abstract class BaseList extends BaseFrameworkSystem implements IteratorAggregate
         * @return      void
         * @throws      InvalidListHashException        If the solved hash index is invalid
         */
-       public function updateCurrentEntryByHash ($hash, array $entryArray) {
+       public function updateCurrentEntryByHash (string $hash, array $entryArray) {
                // Is the hash valid?
-               if (!$this->isHashValid($hash)) {
+               if (empty($hash)) {
+                       // Throw IAE
+                       throw new InvalidArgumentException('Parameter "hash" is empty');
+               } elseif (!$this->isHashValid($hash)) {
                        // Throw an exception here, hashIndex is unknown at this point
                        throw new InvalidListHashException(array($this, $hash, -999), self::EXCEPTION_INVALID_HASH);
                }