framework/main/classes/registry/class_BaseRegistry.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Registry;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Factory\Object\ObjectFactory;
   7 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
   8 use Org\Mxchange\CoreFramework\Generic\NullPointerException;
   9 use Org\Mxchange\CoreFramework\Object\BaseFrameworkSystem;
  10 use Org\Mxchange\CoreFramework\Traits\Iterator\IteratorTrait;
  11
  12 // Import SPL stuff
  13 use \InvalidArgumentExeption;
  14 use \IteratorAggregate;
  15 use \UnexpectedValueException;
  16
  17 /**
  18  * A general Registry
  19  *
  20  * @author              Roland Haeder <webmaster@shipsimu.org>
  21  * @version             0.0.0
  22  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
  23  * @license             GNU GPL 3.0 or any newer version
  24  * @link                http://www.shipsimu.org
  25  *
  26  * This program is free software: you can redistribute it and/or modify
  27  * it under the terms of the GNU General Public License as published by
  28  * the Free Software Foundation, either version 3 of the License, or
  29  * (at your option) any later version.
  30  *
  31  * This program is distributed in the hope that it will be useful,
  32  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  33  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  34  * GNU General Public License for more details.
  35  *
  36  * You should have received a copy of the GNU General Public License
  37  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  38  */
  39 abstract class BaseRegistry extends BaseFrameworkSystem implements Register, Registerable, IteratorAggregate {
  40         // Load traits
  41         use IteratorTrait;
  42
  43         /**
  44          * Glue for generating a registry key
  45          */
  46         const REGISTRY_KEY_GLUE = '_';
  47
  48         /**
  49          * Protected constructor
  50          *
  51          * @param       $className      Name of the class
  52          * @return      void
  53          */
  54         protected function __construct (string $className) {
  55                 // Call parent constructor
  56                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: className=%s - CONSTRUCTED!', $className));
  57                 parent::__construct($className);
  58
  59                 // Init generic arrays
  60                 $this->initGenericArrayGroup('registry', 'generic');
  61                 $this->initGenericArrayGroup('registry', 'instance');
  62
  63                 // Trace message
  64                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-REGISTRY: EXIT!');
  65         }
  66
  67         /**
  68          * Returns an iterator for this whole registry.
  69          *
  70          * @param       $onlyRegistries         Only iterate on these sub-registry keys, default is all
  71          * @return      $iteratorInstance       An instance of a Iterator class
  72          */
  73         public function getIterator (array $onlyRegistries = []) {
  74                 // Get iterator
  75                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: onlyRegistries()=%d - CALLED!', count($onlyRegistries)));
  76                 $iteratorInstance = $this->getIteratorInstance();
  77
  78                 // Is it set?
  79                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-REGISTRY: iteratorInstance[]=%s', gettype($iteratorInstance)));
  80                 if (is_null($iteratorInstance)) {
  81                         // Then instance it
  82                         $iteratorInstance = ObjectFactory::createObjectByConfiguredName('registry_iterator_class', [$this]);
  83
  84                         // ... and set it here
  85                         $this->setIteratorInstance($iteratorInstance);
  86                 }
  87
  88                 // Init iterator instance
  89                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: Invoking iteratorInstance->initIterator(onlyRegistries()=%d) ...', count($onlyRegistries)));
  90                 $iteratorInstance->initIterator($onlyRegistries);
  91
  92                 // Return it
  93                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: iteratorInstance=%s - EXIT!', $iteratorInstance->__toString()));
  94                 return $iteratorInstance;
  95         }
  96
  97         /**
  98          * Checks whether an instance key was found
  99          *
 100          * @param       $instanceKey    The key holding an instance in registry
 101          * @return      $exists                 Whether the key exists in registry
 102          * @throws      InvalidArgumentException        If a paramter has an invalid value
 103          */
 104         public function instanceExists (string $instanceKey) {
 105                 // Check parameter
 106                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: instanceKey=%s - CALLED!', $instanceKey));
 107                 if (empty($instanceKey)) {
 108                         // Throw IAE
 109                         throw new InvalidArgumentException('Parameter "instanceKey" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 110                 }
 111
 112                 // Does this key exists?
 113                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: Invoking this->isGenericArrayKeySet(registry, instance, %s) ...', $instanceKey));
 114                 $exists = $this->isGenericArrayKeySet('registry', 'instance', $instanceKey);
 115
 116                 // Return the result
 117                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: exists=%d - EXIT!', intval($exists)));
 118                 return $exists;
 119         }
 120
 121         /**
 122          * Adds/overwrites a new instance to the registry at the given key
 123          *
 124          * @param       $instanceKey            The key to identify the instance
 125          * @param       $objectInstance         An instance we shall store
 126          * @return      void
 127          * @throws      InvalidArgumentException        If a paramter has an invalid value
 128          */
 129         public function addInstance (string $instanceKey, Registerable $objectInstance) {
 130                 // Check parameter
 131                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: instanceKey=%s,objectInstance=%s - CALLED!', $instanceKey, $objectInstance->__toString()));
 132                 if (empty($instanceKey)) {
 133                         // Throw IAE
 134                         throw new InvalidArgumentExeption('Parameter "instanceKey" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 135                 }
 136
 137                 // Set entry in generic array
 138                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: Invoking this->setGenericArrayKey(registry,instance,%s,%s) ...', $instanceKey, $objectInstance->__toString()));
 139                 $this->setGenericArrayKey('registry', 'instance', $instanceKey, $objectInstance);
 140
 141                 // Trace message
 142                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-REGISTRY: EXIT!');
 143         }
 144
 145         /**
 146          * Getter for whole generic registry
 147          *
 148          * @return      $instanceRegistry       The whole generic registry array
 149          */
 150         public final function getGenericRegistry () {
 151                 return $this->getGenericSubArray('registry', 'generic');
 152         }
 153
 154         /**
 155          * Getter for whole instance registry
 156          *
 157          * @return      $instanceRegistry       The whole instance registry array
 158          */
 159         public final function getInstanceRegistry () {
 160                 return $this->getGenericSubArray('registry', 'instance');
 161         }
 162
 163         /**
 164          * Adds a new entry to the given list name. If you want to add objects
 165          * please use addInstance() and getInstance() instead.
 166          *
 167          * @param       $key    The key to identify the whole list
 168          * @param       $value  The value to be stored
 169          * @return      void
 170          * @throws      InvalidArgumentException        If a paramter has an invalid value
 171          */
 172         public final function addEntry (string $key, $value) {
 173                 // Check parameter
 174                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: key=%s,value[]=%s - CALLED!', $key, gettype($value)));
 175                 if (empty($key)) {
 176                         // Throw IAE
 177                         throw new InvalidArgumentExeption('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 178                 }
 179
 180                 // Push it
 181                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: Invoking this->pushValueToGenericArrayKey(registry,generic,%s,value[]=%s) ...', $key, gettype($value)));
 182                 $this->pushValueToGenericArrayKey('registry', 'generic', $key, $value);
 183
 184                 // Trace message
 185                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-REGISTRY: EXIT!');
 186         }
 187
 188         /**
 189          * Getter for entries or "sub entries"
 190          *
 191          * @param       $key    Key
 192          * @return      $entries        An array with entries from this registry
 193          * @throws      InvalidArgumentException        If a paramter has an invalid value
 194          */
 195         public final function getEntries (string $key = NULL) {
 196                 // Check parameter
 197                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: key=%s,value[]=%s - CALLED!', $key, gettype($value)));
 198                 if (!is_null($key) && empty($key)) {
 199                         // Throw IAE
 200                         throw new InvalidArgumentExeption('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 201                 }
 202
 203                 // Default is whole array
 204                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-REGISTRY: Invoking this->getGenericArray(registry) ...');
 205                 $entries = $this->getGenericArray('registry');
 206
 207                 // Is $key set?
 208                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-REGISTRY: key[]=%s,entries()=%d', $key, count($entries)));
 209                 if (!is_null($key)) {
 210                         // Then use this entry
 211                         /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: Invoking this->getGenericArrayKey(registry,generic,%s) ...', $key));
 212                         $entries = $this->getGenericArrayKey('registry', 'generic', $key);
 213                 }
 214
 215                 // Return the array
 216                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: entries()=%d - EXIT!', count($entries)));
 217                 return $entries;
 218         }
 219
 220         /**
 221          * "Getter" for an array of all entries for given key
 222          *
 223          * @param       $arrayKey       The array (key) to look in
 224          * @param       $lookFor        The key to look for
 225          * @return      $entry          An array with all keys
 226          * @throws      InvalidArgumentException        If a paramter has an invalid value
 227          * @throws      UnexpectedValueException        If $value3 is not an array
 228          */
 229         public function getArrayFromKey (string $arrayKey, string $lookFor) {
 230                 // Check parameter
 231                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: arrayKey=%s,lookFor=%s - CALLED!', $arrayKey, $lookFor));
 232                 if (empty($arrayKey)) {
 233                         // Throw IAE
 234                         throw new InvalidArgumentExeption('Parameter "arrayKey" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 235                 } elseif (empty($lookFor)) {
 236                         // Throw IAE
 237                         throw new InvalidArgumentExeption('Parameter "lookFor" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 238                 }
 239
 240                 // Init array
 241                 $entry = [];
 242
 243                 // "Walk" over all entries
 244                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-REGISTRY: Checking arrayKey=%s,lookFor=%s', $arrayKey, $lookFor));
 245                 foreach ($this->getEntries($arrayKey) as $key => $value) {
 246                         // If $value matches the $lookFor, we need to look for more entries for this!
 247                         /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-REGISTRY: Checking key=%s,value=%s,lookFor=%s', $key, $value, $lookFor));
 248                         if ($lookFor == $value) {
 249                                 // Look for more entries
 250                                 foreach ($this->getEntries() as $key2 => $value2) {
 251                                         // Now "walk" through all entries, if an array is returned
 252                                         /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-REGISTRY: key2=%s,value2[]=%s', $key2, gettype($value2)));
 253                                         if (is_array($value2)) {
 254                                                 // "Walk" through all of them
 255                                                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-REGISTRY: Checking key2=%s,value2()=%s,lookFor=%s', $key2, count($value2), $lookFor));
 256                                                 foreach ($value2 as $key3 => $value3) {
 257                                                         // $value3 needs to be an array
 258                                                         if (!is_array($value3)) {
 259                                                                 // Throw exception
 260                                                                 throw new UnexpectedValueException(sprintf('arrayKey=%s,key=%s,value=%s,key2=%s,key3=%s has unexpected value3[]=%s', $arrayKey, $key, $value, $key2, $key3, gettype($value3)), FrameworkInterface::EXCEPTION_UNEXPECTED_VALUE);
 261                                                         }
 262
 263                                                         // Both keys must match!
 264                                                         /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-REGISTRY: Checking key=%s,key3=%s,isset()=%s ...', $key, $key3, intval(isset($value3[$key]))));
 265                                                         if (($key == $key3) || (isset($value3[$key]))) {
 266                                                                 // Then add it
 267                                                                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-REGISTRY: Adding value3[%s]=%s ...', $key, $value3[$key]));
 268                                                                 $entry[$key3] = $value3[$key];
 269                                                         }
 270                                                 }
 271                                         }
 272                                 }
 273
 274                                 // Skip further lookups
 275                                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage('BASE-REGISTRY: BREAK!');
 276                                 break;
 277                         }
 278                 }
 279
 280                 // Return it
 281                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: entry()=%d - EXIT!', count($entry)));
 282                 return $entry;
 283         }
 284
 285         /**
 286          * Gets a registered instance or null if not found
 287          *
 288          * @param       $instanceKey            The key to identify the instance
 289          * @return      $objectInstance         An instance we shall store
 290          * @throws      InvalidArgumentException        If a paramter has an invalid value
 291          * @throws      NullPointerException    If the requested key is not found
 292          */
 293         public function getInstance (string $instanceKey) {
 294                 // Check parameter
 295                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: instanceKey=%s - CALLED!', $instanceKey));
 296                 if (empty($instanceKey)) {
 297                         // Throw IAE
 298                         throw new InvalidArgumentException('Parameter "instanceKey" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 299                 }
 300
 301                 // Is the instance there?
 302                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: Invoking this->instanceExists(%s) ...', $instanceKey));
 303                 if (!$this->instanceExists($instanceKey)) {
 304                         // This might happen if a non-registered key was requested
 305                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 306                 }
 307
 308                 // Get the instance
 309                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: Invoking this->getGenericArrayKey(registry,instance,%s) ...', $instanceKey));
 310                 $objectInstance = $this->getGenericArrayKey('registry', 'instance', $instanceKey);
 311
 312                 // Return the result
 313                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: objectInstance=%s - EXIT!', $objectInstance->__toString()));
 314                 return $objectInstance;
 315         }
 316
 317         /**
 318          * "Getter" for a registry key for given prefix and array. This method
 319          * calls implode() to get a suitable key. This method does not care about
 320          * the indexes.
 321          *
 322          * @param       $prefix                 Prefix for the key
 323          * @param       $data                   An array with data
 324          * @return      $registryKey    A registry key
 325          */
 326         public static function getRegistryKeyFromArray (string $prefix, array $data) {
 327                 // Check parameter
 328                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: prefix=%s,data()=%d - CALLED!', $prefix, count($data)));
 329                 if (empty($prefix)) {
 330                         // Throw IAE
 331                         throw new InvalidArgumentException('Parameter "prefix" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 332                 } elseif (count($data) == 0) {
 333                         // Throw IAE
 334                         throw new InvalidArgumentException('Parameter "data" is an empty array', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 335                 }
 336
 337                 // "Generate" the key
 338                 $registryKey = $prefix . self::REGISTRY_KEY_GLUE . implode(self::REGISTRY_KEY_GLUE, $data);
 339
 340                 // Return it
 341                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-REGISTRY: registryKey=%s - EXIT!', $registryKey));
 342                 return $registryKey;
 343         }
 344
 345 }