framework/main/classes/class_BaseFrameworkSystem.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Object;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Bootstrap\FrameworkBootstrap;
   7 use Org\Mxchange\CoreFramework\EntryPoint\ApplicationEntryPoint;
   8 use Org\Mxchange\CoreFramework\Factory\Object\ObjectFactory;
   9 use Org\Mxchange\CoreFramework\Filesystem\FileIoException;
  10 use Org\Mxchange\CoreFramework\Filesystem\PathWriteProtectedException;
  11 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
  12 use Org\Mxchange\CoreFramework\Generic\NullPointerException;
  13 use Org\Mxchange\CoreFramework\Generic\UnsupportedOperationException;
  14 use Org\Mxchange\CoreFramework\Helper\Application\ApplicationHelper;
  15 use Org\Mxchange\CoreFramework\Loader\ClassLoader;
  16 use Org\Mxchange\CoreFramework\Manager\ManageableApplication;
  17 use Org\Mxchange\CoreFramework\Middleware\Debug\DebugMiddleware;
  18 use Org\Mxchange\CoreFramework\Registry\GenericRegistry;
  19 use Org\Mxchange\CoreFramework\Result\Database\CachedDatabaseResult;
  20 use Org\Mxchange\CoreFramework\State\Stateable;
  21 use Org\Mxchange\CoreFramework\Stream\Output\OutputStreamer;
  22 use Org\Mxchange\CoreFramework\Utils\Strings\StringUtils;
  23
  24 // Import SPL stuff
  25 use \BadMethodCallException;
  26 use \InvalidArgumentException;
  27 use \ReflectionClass;
  28 use \SplFileInfo;
  29 use \stdClass;
  30
  31 /**
  32  * The simulator system class is the super class of all other classes. This
  33  * class handles saving of games etc.
  34  *
  35  * @author              Roland Haeder <webmaster@shipsimu.org>
  36  * @version             0.0.0
  37  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
  38  * @license             GNU GPL 3.0 or any newer version
  39  * @link                http://www.shipsimu.org
  40  *
  41  * This program is free software: you can redistribute it and/or modify
  42  * it under the terms of the GNU General Public License as published by
  43  * the Free Software Foundation, either version 3 of the License, or
  44  * (at your option) any later version.
  45  *
  46  * This program is distributed in the hope that it will be useful,
  47  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  48  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  49  * GNU General Public License for more details.
  50  *
  51  * You should have received a copy of the GNU General Public License
  52  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  53  */
  54 abstract class BaseFrameworkSystem extends stdClass implements FrameworkInterface {
  55         /**
  56          * Self-referencing instance
  57          */
  58         private static $selfInstance = NULL;
  59
  60         /**
  61          * Debug instance
  62          */
  63         private static $debugInstance = NULL;
  64
  65         /**
  66          * Stub methods
  67          */
  68         private static $stubMethods = [
  69                 'partialStub' => true,
  70                 '__call' => true,
  71                 '__callStatic' => true,
  72         ];
  73
  74         /**
  75          * The real class name
  76          */
  77         private $realClass = __CLASS__;
  78
  79         /**
  80          * Call-back instance
  81          */
  82         private $callbackInstance = NULL;
  83
  84         /**
  85          * Generic array
  86          */
  87         private $genericArray = [];
  88
  89         /***********************
  90          * Exception codes.... *
  91          ***********************/
  92
  93         // @todo Try to clean these constants up
  94         const EXCEPTION_IS_NULL_POINTER              = 0x001;
  95         const EXCEPTION_IS_NO_OBJECT                 = 0x002;
  96         const EXCEPTION_IS_NO_ARRAY                  = 0x003;
  97         const EXCEPTION_MISSING_METHOD               = 0x004;
  98         const EXCEPTION_CLASSES_NOT_MATCHING         = 0x005;
  99         const EXCEPTION_INDEX_OUT_OF_BOUNDS          = 0x006;
 100         const EXCEPTION_DIMENSION_ARRAY_INVALID      = 0x007;
 101         const EXCEPTION_ITEM_NOT_TRADEABLE           = 0x008;
 102         const EXCEPTION_ITEM_NOT_IN_PRICE_LIST       = 0x009;
 103         const EXCEPTION_GENDER_IS_WRONG              = 0x00a;
 104         const EXCEPTION_BIRTH_DATE_IS_INVALID        = 0x00b;
 105         const EXCEPTION_EMPTY_STRUCTURES_ARRAY       = 0x00c;
 106         const EXCEPTION_HAS_ALREADY_PERSONELL_LIST   = 0x00d;
 107         const EXCEPTION_NOT_ENOUGTH_UNEMPLOYEES      = 0x00e;
 108         const EXCEPTION_TOTAL_PRICE_NOT_CALCULATED   = 0x00f;
 109         const EXCEPTION_HARBOR_HAS_NO_SHIPYARDS      = 0x010;
 110         const EXCEPTION_CONTRACT_PARTNER_INVALID     = 0x011;
 111         const EXCEPTION_CONTRACT_PARTNER_MISMATCH    = 0x012;
 112         const EXCEPTION_CONTRACT_ALREADY_SIGNED      = 0x013;
 113         const EXCEPTION_UNEXPECTED_EMPTY_STRING      = 0x014;
 114         const EXCEPTION_PATH_NOT_FOUND               = 0x015;
 115         const EXCEPTION_INVALID_PATH_NAME            = 0x016;
 116         const EXCEPTION_READ_PROTECED_PATH           = 0x017;
 117         const EXCEPTION_WRITE_PROTECED_PATH          = 0x018;
 118         const EXCEPTION_DIR_POINTER_INVALID          = 0x019;
 119         const EXCEPTION_FILE_POINTER_INVALID         = 0x01a;
 120         const EXCEPTION_INVALID_RESOURCE             = 0x01b;
 121         const EXCEPTION_LIMIT_ELEMENT_IS_UNSUPPORTED = 0x01d;
 122         const EXCEPTION_GETTER_IS_MISSING            = 0x01e;
 123         const EXCEPTION_ARRAY_EXPECTED               = 0x01f;
 124         const EXCEPTION_ARRAY_HAS_INVALID_COUNT      = 0x020;
 125         const EXCEPTION_ID_IS_INVALID_FORMAT         = 0x021;
 126         const EXCEPTION_MD5_CHECKSUMS_MISMATCH       = 0x022;
 127         const EXCEPTION_UNEXPECTED_STRING_SIZE       = 0x023;
 128         const EXCEPTION_SIMULATOR_ID_INVALID         = 0x024;
 129         const EXCEPTION_MISMATCHING_COMPRESSORS      = 0x025;
 130         const EXCEPTION_CONTAINER_ITEM_IS_NULL       = 0x026;
 131         const EXCEPTION_ITEM_IS_NO_ARRAY             = 0x027;
 132         const EXCEPTION_CONTAINER_MAYBE_DAMAGED      = 0x028;
 133         const EXCEPTION_INVALID_STRING               = 0x029;
 134         const EXCEPTION_VARIABLE_NOT_SET             = 0x02a;
 135         const EXCEPTION_ATTRIBUTES_ARE_MISSING       = 0x02b;
 136         const EXCEPTION_ARRAY_ELEMENTS_MISSING       = 0x02c;
 137         const EXCEPTION_TEMPLATE_ENGINE_UNSUPPORTED  = 0x02d;
 138         const EXCEPTION_FACTORY_REQUIRE_PARAMETER    = 0x02e;
 139         const EXCEPTION_MISSING_ELEMENT              = 0x02f;
 140         const EXCEPTION_HEADERS_ALREADY_SENT         = 0x030;
 141         const EXCEPTION_DEFAULT_CONTROLLER_GONE      = 0x031;
 142         const EXCEPTION_REQUIRED_INTERFACE_MISSING   = 0x033;
 143         const EXCEPTION_FATAL_ERROR                  = 0x034;
 144         const EXCEPTION_FILE_NOT_FOUND               = 0x035;
 145         const EXCEPTION_ASSERTION_FAILED             = 0x036;
 146         const EXCEPTION_FILE_NOT_REACHABLE           = 0x037;
 147         const EXCEPTION_FILE_CANNOT_BE_READ          = 0x038;
 148         const EXCEPTION_FILE_CANNOT_BE_WRITTEN       = 0x039;
 149         const EXCEPTION_PATH_CANNOT_BE_WRITTEN       = 0x03a;
 150         const EXCEPTION_DATABASE_UPDATED_NOT_ALLOWED = 0x03b;
 151         const EXCEPTION_FILTER_CHAIN_INTERCEPTED     = 0x03c;
 152         const EXCEPTION_INVALID_SOCKET               = 0x03d;
 153         const EXCEPTION_SELF_INSTANCE                = 0x03e;
 154
 155         /**
 156          * Startup time in miliseconds
 157          */
 158         private static $startupTime = 0;
 159
 160         /**
 161          * Protected super constructor
 162          *
 163          * @param       $className      Name of the class
 164          * @return      void
 165          */
 166         protected function __construct (string $className) {
 167                 // Set real class
 168                 $this->setRealClass($className);
 169
 170                 // Is the startup time set? (0 cannot be true anymore)
 171                 if (self::$startupTime == 0) {
 172                         // Then set it
 173                         self::$startupTime = microtime(true);
 174                 }
 175         }
 176
 177         /**
 178          * Destructor for all classes. You should not call this method on your own.
 179          *
 180          * @return      void
 181          */
 182         public function __destruct () {
 183                 // Is this object already destroyed?
 184                 if ($this->__toString() != 'DestructedObject') {
 185                         // Destroy all informations about this class but keep some text about it alive
 186                         $this->setRealClass('DestructedObject');
 187                 } elseif ((defined('DEBUG_DESTRUCTOR')) && (is_object($this->getDebugInstance()))) {
 188                         // Already destructed object
 189                         self::createDebugInstance(__CLASS__, __LINE__)->warningMessage(sprintf('The object <span class="object_name">%s</span> is already destroyed.',
 190                                 $this->__toString()
 191                         ));
 192                 } else {
 193                         // Do not call this twice
 194                         trigger_error(__METHOD__ . ': Called twice.');
 195                         exit(255);
 196                 }
 197         }
 198
 199         /**
 200          * The __call() method where all non-implemented methods end up
 201          *
 202          * @param       $methodName             Name of the missing method
 203          * @args        $args                   Arguments passed to the method
 204          * @return      void
 205          */
 206         public final function __call (string $methodName, array $args = NULL) {
 207                 // Set self-instance
 208                 self::$selfInstance = $this;
 209
 210                 // Call static method
 211                 self::__callStatic($methodName, $args);
 212
 213                 // Clear self-instance
 214                 self::$selfInstance = NULL;
 215         }
 216
 217         /**
 218          * The __callStatic() method where all non-implemented static methods end up
 219          *
 220          * @param       $methodName             Name of the missing method
 221          * @param       $args                   Arguments passed to the method
 222          * @return      void
 223          * @throws      InvalidArgumentException If self::$selfInstance is not a framework's own object
 224          */
 225         public static final function __callStatic (string $methodName, array $args = NULL) {
 226                 // Init argument string and class name
 227                 //* PRINT-DEBUG: */ printf('[%s:%d]: methodName=%s,args[]=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $methodName, gettype($args));
 228                 $argsString = '';
 229                 $className = 'unknown';
 230
 231                 // Is self-instance set?
 232                 if (self::$selfInstance instanceof FrameworkInterface) {
 233                         // Framework's own instance
 234                         $className = self::$selfInstance->__toString();
 235                 } elseif (!is_null(self::$selfInstance)) {
 236                         // Invalid argument!
 237                         throw new InvalidArgumentException(sprintf('self::instance[%s] is not expected.', gettype(self::$selfInstance)), self::EXCEPTION_SELF_INSTANCE);
 238                 }
 239
 240                 // Is it NULL, empty or an array?
 241                 if (is_null($args)) {
 242                         // No arguments
 243                         $argsString = 'NULL';
 244                 } elseif (is_array($args)) {
 245                         // Start braces
 246                         $argsString = '(';
 247
 248                         // Some arguments are there
 249                         foreach ($args as $arg) {
 250                                 // Add data about the argument
 251                                 $argsString .= gettype($arg) . ':';
 252
 253                                 if (is_null($arg)) {
 254                                         // Found a NULL argument
 255                                         $argsString .= 'NULL';
 256                                 } elseif (is_string($arg)) {
 257                                         // Add length for strings
 258                                         $argsString .= strlen($arg);
 259                                 } elseif ((is_int($arg)) || (is_float($arg))) {
 260                                         // ... integer/float
 261                                         $argsString .= $arg;
 262                                 } elseif (is_array($arg)) {
 263                                         // .. or size if array
 264                                         $argsString .= count($arg);
 265                                 } elseif (is_object($arg)) {
 266                                         // Get reflection
 267                                         $reflection = new ReflectionClass($arg);
 268
 269                                         // Is an other object, maybe no __toString() available
 270                                         $argsString .= $reflection->getName();
 271                                 } elseif ($arg === true) {
 272                                         // ... is boolean 'true'
 273                                         $argsString .= 'true';
 274                                 } elseif ($arg === false) {
 275                                         // ... is boolean 'false'
 276                                         $argsString .= 'false';
 277                                 }
 278
 279                                 // Comma for next one
 280                                 $argsString .= ', ';
 281                         }
 282
 283                         // Last comma found?
 284                         if (substr($argsString, -2, 1) == ',') {
 285                                 // Remove last comma
 286                                 $argsString = substr($argsString, 0, -2);
 287                         }
 288
 289                         // Close braces
 290                         $argsString .= ')';
 291                 }
 292
 293                 // Output stub message
 294                 // @TODO __CLASS__ does always return BaseFrameworkSystem but not the extending (=child) class
 295                 self::createDebugInstance(__CLASS__, __LINE__)->warningMessage(sprintf('[%s::%s]: Stub! Args: %s',
 296                         $className,
 297                         $methodName,
 298                         $argsString
 299                 ));
 300
 301                 // Return nothing
 302                 return NULL;
 303         }
 304
 305         /**
 306          * Getter for $realClass
 307          *
 308          * @return      $realClass The name of the real class (not BaseFrameworkSystem)
 309          */
 310         public function __toString () {
 311                 return $this->realClass;
 312         }
 313
 314         /**
 315          * Magic method to catch setting of missing but set class fields/attributes
 316          *
 317          * @param       $name   Name of the field/attribute
 318          * @param       $value  Value to store
 319          * @return      void
 320          */
 321         public final function __set (string $name, $value) {
 322                 $this->debugBackTrace(sprintf('Tried to set a missing field. name=%s, value[%s]=%s',
 323                         $name,
 324                         gettype($value),
 325                         print_r($value, true)
 326                 ));
 327         }
 328
 329         /**
 330          * Magic method to catch getting of missing fields/attributes
 331          *
 332          * @param       $name   Name of the field/attribute
 333          * @return      void
 334          */
 335         public final function __get (string $name) {
 336                 $this->debugBackTrace(sprintf('Tried to get a missing field. name=%s',
 337                         $name
 338                 ));
 339         }
 340
 341         /**
 342          * Magic method to catch unsetting of missing fields/attributes
 343          *
 344          * @param       $name   Name of the field/attribute
 345          * @return      void
 346          */
 347         public final function __unset (string $name) {
 348                 $this->debugBackTrace(sprintf('Tried to unset a missing field. name=%s',
 349                         $name
 350                 ));
 351         }
 352
 353         /**
 354          * Magic method to catch object serialization
 355          *
 356          * @return      $unsupported    Unsupported method
 357          * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
 358          */
 359         public final function __sleep () {
 360                 throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION);
 361         }
 362
 363         /**
 364          * Magic method to catch object deserialization
 365          *
 366          * @return      $unsupported    Unsupported method
 367          * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
 368          */
 369         public final function __wakeup () {
 370                 throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION);
 371         }
 372
 373         /**
 374          * Magic method to catch calls when an object instance is called
 375          *
 376          * @return      $unsupported    Unsupported method
 377          * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
 378          */
 379         public final function __invoke () {
 380                 throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION);
 381         }
 382
 383         /**
 384          * Setter for the real class name
 385          *
 386          * @param       $realClass      Class name (string)
 387          * @return      void
 388          */
 389         public final function setRealClass (string $realClass) {
 390                 // Set real class
 391                 $this->realClass = $realClass;
 392         }
 393
 394         /**
 395          * Setter for debug instance
 396          *
 397          * @param       $debugInstance  The instance for debug output class
 398          * @return      void
 399          */
 400         public final function setDebugInstance (DebugMiddleware $debugInstance) {
 401                 self::$debugInstance = $debugInstance;
 402         }
 403
 404         /**
 405          * Getter for debug instance
 406          *
 407          * @return      $debugInstance  Instance to class DebugConsoleOutput or DebugWebOutput
 408          */
 409         public final function getDebugInstance () {
 410                 return self::$debugInstance;
 411         }
 412
 413         /**
 414          * Setter for web output instance
 415          *
 416          * @param       $webInstance    The instance for web output class
 417          * @return      void
 418          */
 419         public final function setWebOutputInstance (OutputStreamer $webInstance) {
 420                 GenericRegistry::getRegistry()->addInstance('web_output', $webInstance);
 421         }
 422
 423         /**
 424          * Getter for web output instance
 425          *
 426          * @return      $webOutputInstance - Instance to class WebOutput
 427          */
 428         public final function getWebOutputInstance () {
 429                 return GenericRegistry::getRegistry()->getInstance('web_output');
 430         }
 431
 432         /**
 433          * Setter for call-back instance
 434          *
 435          * @param       $callbackInstance       An instance of a FrameworkInterface class
 436          * @return      void
 437          */
 438         public final function setCallbackInstance (FrameworkInterface $callbackInstance) {
 439                 $this->callbackInstance = $callbackInstance;
 440         }
 441
 442         /**
 443          * Getter for call-back instance
 444          *
 445          * @return      $callbackInstance       An instance of a FrameworkInterface class
 446          */
 447         protected final function getCallbackInstance () {
 448                 return $this->callbackInstance;
 449         }
 450
 451         /**
 452          * Checks whether an object equals this object. You should overwrite this
 453          * method to implement own equality checks
 454          *
 455          * @param       $objectInstance         An instance of a FrameworkInterface object
 456          * @return      $equals                         Whether both objects equals
 457          */
 458         public function equals (FrameworkInterface $objectInstance) {
 459                 // Now test it
 460                 $equals = ((
 461                         $this->__toString() == $objectInstance->__toString()
 462                 ) && (
 463                         $this->hashCode() == $objectInstance->hashCode()
 464                 ));
 465
 466                 // Return the result
 467                 return $equals;
 468         }
 469
 470         /**
 471          * Generates a generic hash code of this class. You should really overwrite
 472          * this method with your own hash code generator code. But keep KISS in mind.
 473          *
 474          * @return      $hashCode       A generic hash code respresenting this whole class
 475          */
 476         public function hashCode () {
 477                 // Simple hash code
 478                 return crc32($this->__toString());
 479         }
 480
 481         /**
 482          * Appends a trailing slash to a string
 483          *
 484          * @param       $str    A string (maybe) without trailing slash
 485          * @return      $str    A string with an auto-appended trailing slash
 486          * @throws      InvalidArgumentException        If a paramter has an invalid value
 487          */
 488         public final function addMissingTrailingSlash (string $str) {
 489                 // Check parameter
 490                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: str=%s - CALLED!', $str));
 491                 if (empty($str)) {
 492                         // Throw IAE
 493                         throw new InvalidArgumentException('Parameter "str" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 494                 }
 495
 496                 // Is there a trailing slash?
 497                 if (substr($str, -1, 1) != '/') {
 498                         $str .= '/';
 499                 }
 500
 501                 // Return string with trailing slash
 502                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: str=%s - EXIT!', $str));
 503                 return $str;
 504         }
 505
 506         /**
 507          * Debugs this instance by putting out it's full content
 508          *
 509          * @param       $message        Optional message to show in debug output
 510          * @return      void
 511          * @throws      InvalidArgumentException        If a paramter has an invalid value
 512          */
 513         public final function debugInstance (string $message = '') {
 514                 // Check parameter
 515                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: message=%s - CALLED!', $message));
 516                 if (empty($message)) {
 517                         // Throw IAE
 518                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 519                 }
 520
 521                 // Restore the error handler to avoid trouble with missing array elements or undeclared variables
 522                 restore_error_handler();
 523
 524                 // Init content
 525                 $content = '';
 526
 527                 // Is a message set?
 528                 if (!empty($message)) {
 529                         // Construct message
 530                         $content = sprintf('<div class="debug_message">
 531         Message: %s
 532 </div>' . PHP_EOL, $message);
 533                 }
 534
 535                 // Generate the output
 536                 $content .= sprintf('<pre>%s</pre>',
 537                         trim(
 538                                 htmlentities(
 539                                         print_r($this, true)
 540                                 )
 541                         )
 542                 );
 543
 544                 // Output it
 545                 ApplicationEntryPoint::exitApplication(sprintf('<div class="debug_header">
 546         %s debug output:
 547 </div>
 548 <div class="debug_content">
 549         %s
 550 </div>
 551 Loaded includes:
 552 <div class="debug_include_list">
 553         %s
 554 </div>',
 555                         $this->__toString(),
 556                         $content,
 557                         ClassLoader::getSelfInstance()->getPrintableIncludeList()
 558                 ));
 559         }
 560
 561         /**
 562          * Outputs a debug backtrace and stops further script execution
 563          *
 564          * @param       $message        An optional message to output
 565          * @param       $doExit         Whether exit the program (true is default)
 566          * @return      void
 567          * @throws      InvalidArgumentException        If a paramter has an invalid value
 568          */
 569         public function debugBackTrace (string $message = '', bool $doExit = true) {
 570                 // Check parameter
 571                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: message=%s,doExit=%d - CALLED!', $message, intval($doExit)));
 572                 if (empty($message)) {
 573                         // Throw IAE
 574                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 575                 }
 576
 577                 // Sorry, there is no other way getting this nice backtrace
 578                 if (!empty($message)) {
 579                         // Output message
 580                         printf('Message: %s<br />' . PHP_EOL, $message);
 581                 }
 582
 583                 print('<pre>');
 584                 debug_print_backtrace();
 585                 print('</pre>');
 586
 587                 // Exit program?
 588                 if ($doExit === true) {
 589                         // Yes, with error code
 590                         exit(255);
 591                 }
 592         }
 593
 594         /**
 595          * Creates an instance of a debugger instance
 596          *
 597          * @param       $className              Name of the class (currently unsupported)
 598          * @param       $lineNumber             Line number where the call was made
 599          * @return      $debugInstance  An instance of a debugger class
 600          * @throws      InvalidArgumentException        If a parameter has an invalid value
 601          * @deprecated  Not fully, as the new Logger facilities are not finished yet.
 602          */
 603         public final static function createDebugInstance (string $className, int $lineNumber = NULL) {
 604                 // Validate parameter
 605                 //* NOISY-DEBUG: */ printf('[%s:%d]: className=%s,lineNumber[%s]=%d - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $className, gettype($lineNumber), $lineNumber);
 606                 if (empty($className)) {
 607                         // Throw IAE
 608                         throw new InvalidArgumentException('Parameter "className" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 609                 }
 610
 611                 // Is the debug instance set?
 612                 //* NOISY-DEBUG: */ printf('[%s:%d]: self::debugInstance[]=%s' . PHP_EOL, __METHOD__, __LINE__, gettype(self::$debugInstance));
 613                 if (is_null(self::$debugInstance)) {
 614                         // Init debug instance
 615                         self::$debugInstance = NULL;
 616
 617                         // Try it
 618                         try {
 619                                 // Get a debugger instance
 620                                 //* NOISY-DEBUG: */ printf('[%s:%d]: className=%s' . PHP_EOL, __METHOD__, __LINE__, $className);
 621                                 self::$debugInstance = DebugMiddleware::createDebugMiddleware(FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('debug_' . FrameworkBootstrap::getRequestTypeFromSystem() . '_class'), $className);
 622                         } catch (NullPointerException $e) {
 623                                 // Didn't work, no instance there
 624                                 exit(sprintf('[%s:%d]: Cannot create debugInstance! Exception=%s,message=%s,className=%s,lineNumber=%d' . PHP_EOL, __METHOD__, __LINE__, $e->__toString(), $e->getMessage(), $className, $lineNumber));
 625                         }
 626                 }
 627
 628                 // Return it
 629                 //* NOISY-DEBUG: */ printf('[%s:%d]: self::debugInstance=%s - EXIT!' . PHP_EOL, __METHOD__, __LINE__, self::$debugInstance->__toString());
 630                 return self::$debugInstance;
 631         }
 632
 633         /**
 634          * Simple output of a message with line-break
 635          *
 636          * @param       $message        Message to output
 637          * @return      void
 638          * @throws      InvalidArgumentException        If a paramter has an invalid value
 639          */
 640         public function outputLine (string $message) {
 641                 // Check parameter
 642                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: message=%s - CALLED!', $message));
 643                 if (empty($message)) {
 644                         // Throw IAE
 645                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 646                 }
 647
 648                 // Simply output it
 649                 print($message . PHP_EOL);
 650         }
 651
 652         /**
 653          * Marks up the code by adding e.g. line numbers
 654          *
 655          * @param       $phpCode                Unmarked PHP code
 656          * @return      $markedCode             Marked PHP code
 657          * @throws      InvalidArgumentException        If a paramter has an invalid value
 658          */
 659         public function markupCode (string $phpCode) {
 660                 // Check parameter
 661                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: phpCode=%s - CALLED!', $phpCode));
 662                 if (empty($phpCode)) {
 663                         // Throw IAE
 664                         throw new InvalidArgumentException('Parameter "phpCode" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 665                 }
 666
 667                 // Init marked code
 668                 $markedCode = '';
 669
 670                 // Get last error
 671                 $errorArray = error_get_last();
 672
 673                 // Init the code with error message
 674                 if (is_array($errorArray)) {
 675                         // Get error infos
 676                         $markedCode = sprintf('<div id="error_header">File: <span id="error_data">%s</span>, Line: <span id="error_data">%s</span>, Message: <span id="error_data">%s</span>, Type: <span id="error_data">%s</span></div>',
 677                                 basename($errorArray['file']),
 678                                 $errorArray['line'],
 679                                 $errorArray['message'],
 680                                 $errorArray['type']
 681                         );
 682                 }
 683
 684                 // Add line number to the code
 685                 foreach (explode(chr(10), $phpCode) as $lineNo => $code) {
 686                         // Add line numbers
 687                         $markedCode .= sprintf('<span id="code_line">%s</span>: %s' . PHP_EOL,
 688                                 ($lineNo + 1),
 689                                 htmlentities($code, ENT_QUOTES)
 690                         );
 691                 }
 692
 693                 // Return the code
 694                 return $markedCode;
 695         }
 696
 697         /**
 698          * "Getter" for databse entry
 699          *
 700          * @return      $entry  An array with database entries
 701          * @throws      NullPointerException    If the database result is not found
 702          * @throws      InvalidDatabaseResultException  If the database result is invalid
 703          * @deprecated  Monolithic method, should be moved to proper classes
 704          */
 705         protected final function getDatabaseEntry () {
 706                 // This method is deprecated
 707                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: CALLED!');
 708                 $this->deprecationWarning('Monolithic method, should be moved to proper classes');
 709
 710                 // Is there an instance?
 711                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->resultInstance[]=%s', gettype($this->getResultInstance())));
 712                 if (!$this->getResultInstance() instanceof SearchableResult) {
 713                         // Throw an exception here
 714                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 715                 }
 716
 717                 // Rewind it
 718                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: Invoking this->resultInstance->rewind() ...');
 719                 $this->getResultInstance()->rewind();
 720
 721                 // Do we have an entry?
 722                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->resultInstance->isValid()=%d', intval($this->getResultInstance()->isValid())));
 723                 if ($this->getResultInstance()->valid() === false) {
 724                         // @TODO Move the constant to e.g. BaseDatabaseResult when there is a non-cached database result available
 725                         throw new InvalidDatabaseResultException(array($this, $this->getResultInstance()), CachedDatabaseResult::EXCEPTION_INVALID_DATABASE_RESULT);
 726                 }
 727
 728                 // Get next entry
 729                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: Invoking this->resultInstance->next() ...');
 730                 $this->getResultInstance()->next();
 731
 732                 // Fetch it
 733                 $entry = $this->getResultInstance()->current();
 734
 735                 // And return it
 736                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: entry[]=%s - EXIT!', gettype($entry)));
 737                 return $entry;
 738         }
 739
 740         /**
 741          * Getter for field name
 742          *
 743          * @param       $fieldName              Field name which we shall get
 744          * @return      $fieldValue             Field value from the user
 745          * @throws      NullPointerException    If the result instance is null
 746          * @throws      InvalidArgumentException        If a parameter is not valid
 747          * @deprecated  Monolithic method, should be moved to proper classes
 748          */
 749         public final function getField (string $fieldName) {
 750                 // Check parameter
 751                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldName=%s - CALLED!', $fieldName));
 752                 if (empty($fieldName)) {
 753                         // Throw IAE
 754                         throw new InvalidArgumentException('Parameter "fieldName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 755                 }
 756
 757                 // This method is deprecated
 758                 $this->deprecationWarning('Monolithic method, should be moved to proper classes');
 759
 760                 // Default field value
 761                 $fieldValue = NULL;
 762
 763                 // Get result instance
 764                 $resultInstance = $this->getResultInstance();
 765
 766                 // Is this instance null?
 767                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: resultInstance[]=%s', gettype($resultInstance)));
 768                 if (is_null($resultInstance)) {
 769                         // Then the user instance is no longer valid (expired cookies?)
 770                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 771                 }
 772
 773                 // Get current array
 774                 $fieldArray = $resultInstance->current();
 775
 776                 // Convert dashes to underscore
 777                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldArray()=%d', count($fieldArray)));
 778                 $fieldName2 = StringUtils::convertDashesToUnderscores($fieldName);
 779
 780                 // Does the field exist?
 781                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldName2=%s', $fieldName2));
 782                 if ($this->isFieldSet($fieldName)) {
 783                         // Get it
 784                         $fieldValue = $fieldArray[$fieldName2];
 785                 } elseif (FrameworkBootstrap::getConfigurationInstance()->isEnabled('developer_mode')) {
 786                         // Missing field entry, may require debugging
 787                         self::createDebugInstance(__CLASS__, __LINE__)->warningMessage('BASE-FRAMEWORK-SYSTEM: fieldArray<pre>=' . print_r($fieldArray, true) . '</pre>,fieldName=' . $fieldName . ' not found!');
 788                 } else {
 789                         // Missing field entry, may require debugging
 790                         self::createDebugInstance(__CLASS__, __LINE__)->warningMessage('BASE-FRAMEWORK-SYSTEM: fieldName=' . $fieldName . ' not found!');
 791                 }
 792
 793                 // Return it
 794                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldValue[]=%s - EXIT!', gettype($fieldValue)));
 795                 return $fieldValue;
 796         }
 797
 798         /**
 799          * Checks if given field is set
 800          *
 801          * @param       $fieldName      Field name to check
 802          * @return      $isSet          Whether the given field name is set
 803          * @throws      NullPointerException    If the result instance is null
 804          * @throws      InvalidArgumentException        If a parameter is not valid
 805          */
 806         public function isFieldSet (string $fieldName) {
 807                 // Check parameter
 808                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldName=%s - CALLED!', $fieldName));
 809                 if (empty($fieldName)) {
 810                         // Throw IAE
 811                         throw new InvalidArgumentException('Parameter "fieldName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 812                 }
 813
 814                 // Get result instance
 815                 $resultInstance = $this->getResultInstance();
 816
 817                 // Is this instance null?
 818                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: resultInstance[]=%s', gettype($resultInstance)));
 819                 if (is_null($resultInstance)) {
 820                         // Then the user instance is no longer valid (expired cookies?)
 821                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 822                 }
 823
 824                 // Get current array
 825                 $fieldArray = $resultInstance->current();
 826
 827                 // Convert dashes to underscore
 828                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldArray()=%d,fieldName=%s - BEFORE!', count($fieldArray), $fieldName));
 829                 $fieldName = StringUtils::convertDashesToUnderscores($fieldName);
 830
 831                 // Determine it
 832                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fieldName=%s - AFTER!', $fieldName));
 833                 $isset = isset($fieldArray[$fieldName]);
 834
 835                 // Return result
 836                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isset=%d - EXIT!', intval($isset)));
 837                 return $isset;
 838         }
 839
 840         /**
 841          * Outputs a deprecation warning to the developer.
 842          *
 843          * @param       $message        The message we shall output to the developer
 844          * @return      void
 845          * @throws      InvalidArgumentException        If a paramter has an invalid value
 846          * @todo        Write a logging mechanism for productive mode
 847          */
 848         public function deprecationWarning (string $message) {
 849                 // Check parameter
 850                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: message=%s - CALLED!', $message));
 851                 if (empty($message)) {
 852                         // Throw IAE
 853                         throw new InvalidArgumentException('Parameter "message" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 854                 }
 855
 856                 // Is developer mode active?
 857                 if (FrameworkBootstrap::getConfigurationInstance()->isEnabled('developer_mode')) {
 858                         // Debug instance is there?
 859                         if (!is_null($this->getDebugInstance())) {
 860                                 // Output stub message
 861                                 self::createDebugInstance(__CLASS__, __LINE__)->warningMessage($message);
 862                         } else {
 863                                 // Trigger an error
 864                                 trigger_error($message . "<br />\n");
 865                                 exit(255);
 866                         }
 867                 } else {
 868                         // @TODO Finish this part!
 869                         DebugMiddleware::getSelfInstance()->partialStub('Developer mode inactive. Message:' . $message);
 870                 }
 871
 872                 // Trace mesage
 873                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
 874         }
 875
 876         /**
 877          * Checks whether the given PHP extension is loaded
 878          *
 879          * @param       $phpExtension   The PHP extension we shall check
 880          * @return      $isLoaded       Whether the PHP extension is loaded
 881          * @throws      InvalidArgumentException        If a parameter is not valid
 882          */
 883         public final function isPhpExtensionLoaded (string $phpExtension) {
 884                 // Check parameter
 885                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: phpExtension=%s - CALLED!', $phpExtension));
 886                 if (empty($phpExtension)) {
 887                         // Throw IAE
 888                         throw new InvalidArgumentException('Parameter "phpExtension" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 889                 }
 890
 891                 // Is it loaded?
 892                 $isLoaded = in_array($phpExtension, get_loaded_extensions());
 893
 894                 // Return result
 895                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isLoaded=%d - EXIT!', intval($isLoaded)));
 896                 return $isLoaded;
 897         }
 898
 899         /**
 900          * "Getter" as a time() replacement but with milliseconds. You should use this
 901          * method instead of the encapsulated getimeofday() function.
 902          *
 903          * @return      $milliTime      Timestamp with milliseconds
 904          */
 905         public function getMilliTime () {
 906                 // Get the time of day as float
 907                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: CALLED!');
 908                 $milliTime = gettimeofday(true);
 909
 910                 // Return it
 911                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: milliTime=%s - EXIT!', $milliTime));
 912                 return $milliTime;
 913         }
 914
 915         /**
 916          * Idles (sleeps) for given milliseconds
 917          *
 918          * @return      $hasSlept       Whether it goes fine
 919          * @throws      InvalidArgumentException        If a parameter is not valid
 920          */
 921         public function idle (int $milliSeconds) {
 922                 // Check parameter
 923                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: milliSeconds=%s - CALLED!', $milliSeconds));
 924                 if ($milliSeconds < 1) {
 925                         // Throw IAE
 926                         throw new InvalidArgumentException(sprintf('milliSeconds=%d are not a reasonable value to idle', $milliSeconds));
 927                 }
 928
 929                 // Sleep is fine by default
 930                 $hasSlept = true;
 931
 932                 // Idle so long with found function
 933                 if (function_exists('time_sleep_until')) {
 934                         // Get current time and add idle time
 935                         $sleepUntil = $this->getMilliTime() + abs($milliSeconds) / 1000;
 936
 937                         // New PHP 5.1.0 function found, ignore errors
 938                         $hasSlept = @time_sleep_until($sleepUntil);
 939                 } else {
 940                         /*
 941                          * My Sun station doesn't have that function even with latest PHP
 942                          * package. :(
 943                          */
 944                         usleep($milliSeconds * 1000);
 945                 }
 946
 947                 // Return result
 948                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: hasSlept=%d - EXIT!', intval($hasSlept)));
 949                 return $hasSlept;
 950         }
 951
 952         /**
 953          * Checks whether the given encoded data was encoded with Base64
 954          *
 955          * @param       $encodedData    Encoded data we shall check
 956          * @return      $isBase64               Whether the encoded data is Base64
 957          * @throws      InvalidArgumentException        If a parameter is not valid
 958          */
 959         protected function isBase64Encoded (string $encodedData) {
 960                 // Check parameter
 961                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: encodedData=%s - CALLED!', $encodedData));
 962                 if (empty($encodedData)) {
 963                         // Throw IAE
 964                         throw new InvalidArgumentException('Parameter "encodedData" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 965                 }
 966
 967                 // Determine it
 968                 $isBase64 = (@base64_decode($encodedData, true) !== false);
 969
 970                 // Return it
 971                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isBase64=%d - EXIT!', intval($isBase64)));
 972                 return $isBase64;
 973         }
 974
 975         /**
 976          * Getter for startup time in miliseconds
 977          *
 978          * @return      $startupTime    Startup time in miliseconds
 979          */
 980         protected function getStartupTime () {
 981                 return self::$startupTime;
 982         }
 983
 984         /**
 985          * "Getter" for a printable currently execution time in nice braces
 986          *
 987          * @return      $executionTime  Current execution time in nice braces
 988          */
 989         protected function getPrintableExecutionTime () {
 990                 // Calculate execution time and pack it in nice braces
 991                 $executionTime = sprintf('[ %01.5f ] ', (microtime(true) - $this->getStartupTime()));
 992
 993                 // And return it
 994                 return $executionTime;
 995         }
 996
 997         /**
 998          * Determines if an element is set in the generic array
 999          *
1000          * @param       $keyGroup       Main group for the key
1001          * @param       $subGroup       Sub group for the key
1002          * @param       $key            Key to check
1003          * @param       $element        Element to check
1004          * @return      $isset          Whether the given key is set
1005          * @throws      InvalidArgumentException        If a parameter is not valid
1006          */
1007         protected final function isGenericArrayElementSet (string $keyGroup, string $subGroup, string $key, string $element) {
1008                 // Check parameter
1009                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s - CALLED!', $keyGroup, $subGroup, $key, $element));
1010                 if (empty($keyGroup)) {
1011                         // Throw IAE
1012                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1013                 } elseif (empty($subGroup)) {
1014                         // Throw IAE
1015                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1016                 } elseif (empty($key)) {
1017                         // Throw IAE
1018                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1019                 } elseif ($element === '') {
1020                         // Throw IAE
1021                         throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1022                 }
1023
1024                 // Is it there?
1025                 $isset = isset($this->genericArray[$keyGroup][$subGroup][$key][$element]);
1026
1027                 // Return it
1028                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isset=%d - EXIT!', intval($isset)));
1029                 return $isset;
1030         }
1031         /**
1032          * Determines if a key is set in the generic array
1033          *
1034          * @param       $keyGroup       Main group for the key
1035          * @param       $subGroup       Sub group for the key
1036          * @param       $key            Key to check
1037          * @return      $isset          Whether the given key is set
1038          * @throws      InvalidArgumentException        If a parameter is not valid
1039          */
1040         protected final function isGenericArrayKeySet (string $keyGroup, string $subGroup, string $key) {
1041                 // Check parameter
1042                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1043                 if (empty($keyGroup)) {
1044                         // Throw IAE
1045                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1046                 } elseif (empty($subGroup)) {
1047                         // Throw IAE
1048                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1049                 } elseif (empty($key)) {
1050                         // Throw IAE
1051                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1052                 }
1053
1054                 // Is it there?
1055                 $isset = isset($this->genericArray[$keyGroup][$subGroup][$key]);
1056
1057                 // Return it
1058                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isset=%d - EXIT!', intval($isset)));
1059                 return $isset;
1060         }
1061
1062         /**
1063          * Determines if a group is set in the generic array
1064          *
1065          * @param       $keyGroup       Main group
1066          * @param       $subGroup       Sub group
1067          * @return      $isset          Whether the given group is set
1068          * @throws      InvalidArgumentException        If a parameter is not valid
1069          */
1070         protected final function isGenericArrayGroupSet (string $keyGroup, string $subGroup) {
1071                 // Check parameter
1072                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s - CALLED!', $keyGroup, $subGroup));
1073                 if (empty($keyGroup)) {
1074                         // Throw IAE
1075                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1076                 } elseif (empty($subGroup)) {
1077                         // Throw IAE
1078                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1079                 }
1080
1081                 // Is it there?
1082                 $isset = isset($this->genericArray[$keyGroup][$subGroup]);
1083
1084                 // Return it
1085                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isset=%d - EXIT!', intval($isset)));
1086                 return $isset;
1087         }
1088
1089         /**
1090          * Getter for sub key group
1091          *
1092          * @param       $keyGroup       Main key group
1093          * @param       $subGroup       Sub key group
1094          * @return      $array          An array with all array elements
1095          * @throws      InvalidArgumentException        If a parameter is not valid
1096          * @throws      BadMethodCallException  If key/sub group isn't there but this method is invoked
1097          */
1098         protected final function getGenericSubArray (string $keyGroup, string $subGroup) {
1099                 // Check parameter
1100                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s - CALLED!', $keyGroup, $subGroup));
1101                 if (empty($keyGroup)) {
1102                         // Throw IAE
1103                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1104                 } elseif (empty($subGroup)) {
1105                         // Throw IAE
1106                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1107                 } elseif (!$this->isGenericArrayGroupSet($keyGroup, $subGroup)) {
1108                         // No, then abort here
1109                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s not found.', $keyGroup, $subGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1110                 }
1111
1112                 // Return it
1113                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->genericArray[%s][%s][]=%s - EXIT!', $keyGroup, $subGroup, gettype($this->genericArray[$keyGroup][$subGroup])));
1114                 return $this->genericArray[$keyGroup][$subGroup];
1115         }
1116
1117         /**
1118          * Unsets a given key in generic array
1119          *
1120          * @param       $keyGroup       Main group for the key
1121          * @param       $subGroup       Sub group for the key
1122          * @param       $key            Key to unset
1123          * @return      void
1124          * @throws      InvalidArgumentException        If a parameter is not valid
1125          */
1126         protected final function unsetGenericArrayKey (string $keyGroup, string $subGroup, string $key) {
1127                 // Check parameter
1128                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1129                 if (empty($keyGroup)) {
1130                         // Throw IAE
1131                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1132                 } elseif (empty($subGroup)) {
1133                         // Throw IAE
1134                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1135                 } elseif (empty($key)) {
1136                         // Throw IAE
1137                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1138                 }
1139
1140                 // Remove it
1141                 unset($this->genericArray[$keyGroup][$subGroup][$key]);
1142
1143                 // Trace mesage
1144                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1145         }
1146
1147         /**
1148          * Unsets a given element in generic array
1149          *
1150          * @param       $keyGroup       Main group for the key
1151          * @param       $subGroup       Sub group for the key
1152          * @param       $key            Key to unset
1153          * @param       $element        Element to unset
1154          * @return      void
1155          * @throws      InvalidArgumentException        If a parameter is not valid
1156          */
1157         protected final function unsetGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element) {
1158                 // Check parameter
1159                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s - CALLED!', $keyGroup, $subGroup, $key, $element));
1160                 if (empty($keyGroup)) {
1161                         // Throw IAE
1162                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1163                 } elseif (empty($subGroup)) {
1164                         // Throw IAE
1165                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1166                 } elseif (empty($key)) {
1167                         // Throw IAE
1168                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1169                 } elseif ($element === '') {
1170                         // Throw IAE
1171                         throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1172                 }
1173
1174                 // Remove it
1175                 unset($this->genericArray[$keyGroup][$subGroup][$key][$element]);
1176
1177                 // Trace mesage
1178                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1179         }
1180
1181         /**
1182          * Append a string to a given generic array key
1183          *
1184          * @param       $keyGroup       Main group for the key
1185          * @param       $subGroup       Sub group for the key
1186          * @param       $key            Key to unset
1187          * @param       $value          Value to add/append
1188          * @return      void
1189          * @throws      InvalidArgumentException        If a parameter is not valid
1190          */
1191         protected final function appendStringToGenericArrayKey (string $keyGroup, string $subGroup, string $key, string $value, string $appendGlue = '') {
1192                 // Check parameter
1193                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,value=%s,appendGlue=%s - CALLED!', $keyGroup, $subGroup, $key, $value, $appendGlue));
1194                 if (empty($keyGroup)) {
1195                         // Throw IAE
1196                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1197                 } elseif (empty($subGroup)) {
1198                         // Throw IAE
1199                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1200                 } elseif (empty($key)) {
1201                         // Throw IAE
1202                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1203                 }
1204
1205                 // Is it already there?
1206                 if ($this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1207                         // Append it
1208                         $this->genericArray[$keyGroup][$subGroup][$key] .= $appendGlue . $value;
1209                 } else {
1210                         // Add it
1211                         $this->genericArray[$keyGroup][$subGroup][$key] = $value;
1212                 }
1213
1214                 // Trace mesage
1215                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1216         }
1217
1218         /**
1219          * Append a string to a given generic array element
1220          *
1221          * @param       $keyGroup       Main group for the key
1222          * @param       $subGroup       Sub group for the key
1223          * @param       $key            Key to unset
1224          * @param       $element        Element to check
1225          * @param       $value          Value to add/append
1226          * @return      void
1227          * @throws      InvalidArgumentException        If a parameter is not valid
1228          */
1229         protected final function appendStringToGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element, string $value, string $appendGlue = '') {
1230                 // Check parameter
1231                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s,value=%s,appendGlue=%s - CALLED!', $keyGroup, $subGroup, $key, $element, $value, $appendGlue));
1232                 if (empty($keyGroup)) {
1233                         // Throw IAE
1234                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1235                 } elseif (empty($subGroup)) {
1236                         // Throw IAE
1237                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1238                 } elseif (empty($key)) {
1239                         // Throw IAE
1240                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1241                 } elseif ($element === '') {
1242                         // Throw IAE
1243                         throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1244                 }
1245
1246                 // Is it already there?
1247                 if ($this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
1248                         // Append it
1249                         $this->genericArray[$keyGroup][$subGroup][$key][$element] .= $appendGlue . $value;
1250                 } else {
1251                         // Add it
1252                         $this->setGenericArrayElement($keyGroup, $subGroup, $key, $element, $value);
1253                 }
1254
1255                 // Trace mesage
1256                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1257         }
1258
1259         /**
1260          * Initializes given generic array group
1261          *
1262          * @param       $keyGroup       Main group for the key
1263          * @param       $subGroup       Sub group for the key
1264          * @param       $key            Key to use
1265          * @param       $forceInit      Optionally force initialization
1266          * @return      void
1267          * @throws      InvalidArgumentException        If a parameter is not valid
1268          * @throws      BadMethodCallException  If key/sub group has already been initialized
1269          */
1270         protected final function initGenericArrayGroup (string $keyGroup, string $subGroup, bool $forceInit = false) {
1271                 // Check parameter
1272                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,forceInit=%d - CALLED!', $keyGroup, $subGroup, intval($forceInit)));
1273                 if (empty($keyGroup)) {
1274                         // Throw IAE
1275                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1276                 } elseif (empty($subGroup)) {
1277                         // Throw IAE
1278                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1279                 } elseif (($forceInit === false) && ($this->isGenericArrayGroupSet($keyGroup, $subGroup))) {
1280                         // Already initialized
1281                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s already initialized.', $keyGroup, $subGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1282                 }
1283
1284                 // Initialize it
1285                 $this->genericArray[$keyGroup][$subGroup] = [];
1286
1287                 // Trace mesage
1288                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1289         }
1290
1291         /**
1292          * Initializes given generic array key
1293          *
1294          * @param       $keyGroup       Main group for the key
1295          * @param       $subGroup       Sub group for the key
1296          * @param       $key            Key to use
1297          * @param       $forceInit      Optionally force initialization
1298          * @return      void
1299          * @throws      InvalidArgumentException        If a parameter is not valid
1300          * @throws      BadMethodCallException  If key/sub group has already been initialized
1301          */
1302         protected final function initGenericArrayKey (string $keyGroup, string $subGroup, string $key, bool $forceInit = false) {
1303                 // Check parameter
1304                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,forceInit=%d - CALLED!', $keyGroup, $subGroup, $key, intval($forceInit)));
1305                 if (empty($keyGroup)) {
1306                         // Throw IAE
1307                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1308                 } elseif (empty($subGroup)) {
1309                         // Throw IAE
1310                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1311                 } elseif (empty($key)) {
1312                         // Throw IAE
1313                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1314                 } elseif (($forceInit === false) && ($this->isGenericArrayKeySet($keyGroup, $subGroup, $key))) {
1315                         // Already initialized
1316                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s already initialized.', $keyGroup, $subGroup, gettype($key), $key), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1317                 }
1318
1319                 // Initialize it
1320                 $this->genericArray[$keyGroup][$subGroup][$key] = [];
1321
1322                 // Trace mesage
1323                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1324         }
1325
1326         /**
1327          * Initializes given generic array element
1328          *
1329          * @param       $keyGroup       Main group for the key
1330          * @param       $subGroup       Sub group for the key
1331          * @param       $key            Key to use
1332          * @param       $element        Element to use
1333          * @param       $forceInit      Optionally force initialization
1334          * @return      void
1335          * @throws      InvalidArgumentException        If a parameter is not valid
1336          * @throws      BadMethodCallException  If key/sub group isn't there but this method is invoked
1337          */
1338         protected final function initGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element, bool $forceInit = false) {
1339                 // Check parameter
1340                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s,forceInit=%d - CALLED!', $keyGroup, $subGroup, $key, $element, intval($forceInit)));
1341                 if (empty($keyGroup)) {
1342                         // Throw IAE
1343                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1344                 } elseif (empty($subGroup)) {
1345                         // Throw IAE
1346                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1347                 } elseif (empty($key)) {
1348                         // Throw IAE
1349                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1350                 } elseif ($element === '') {
1351                         // Throw IAE
1352                         throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1353                 } elseif (($forceInit === false) && ($this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element))) {
1354                         // Already initialized
1355                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s,element[%s]=%s already initialized.', $keyGroup, $subGroup, gettype($key), $key, gettype($element), $element), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1356                 }
1357
1358                 // Initialize it
1359                 $this->genericArray[$keyGroup][$subGroup][$key][$element] = [];
1360
1361                 // Trace mesage
1362                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1363         }
1364
1365         /**
1366          * Pushes an element to a generic key. If the key isn't found, it will be initialized.
1367          *
1368          * @param       $keyGroup       Main group for the key
1369          * @param       $subGroup       Sub group for the key
1370          * @param       $key            Key to use
1371          * @param       $value          Value to add/append
1372          * @return      $count          Number of array elements
1373          * @throws      InvalidArgumentException        If a parameter is not valid
1374          */
1375         protected final function pushValueToGenericArrayKey (string $keyGroup, string $subGroup, string $key, $value) {
1376                 // Check parameter
1377                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,value[]=%s - CALLED!', $keyGroup, $subGroup, $key, gettype($value)));
1378                 if (empty($keyGroup)) {
1379                         // Throw IAE
1380                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1381                 } elseif (empty($subGroup)) {
1382                         // Throw IAE
1383                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1384                 } elseif (empty($key)) {
1385                         // Throw IAE
1386                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1387                 } elseif (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1388                         // Initialize array
1389                         $this->initGenericArrayKey($keyGroup, $subGroup, $key);
1390                 }
1391
1392                 // Then push it
1393                 $count = array_push($this->genericArray[$keyGroup][$subGroup][$key], $value);
1394
1395                 // Return count
1396                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1397                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: count=%d - EXIT!', $count));
1398                 return $count;
1399         }
1400
1401         /**
1402          * Pushes an element to a generic array element. If the key isn't found, it will be initialized.
1403          *
1404          * @param       $keyGroup       Main group for the key
1405          * @param       $subGroup       Sub group for the key
1406          * @param       $key            Key to use
1407          * @param       $element        Element to check
1408          * @param       $value          Value to add/append
1409          * @return      $count          Number of array elements
1410          * @throws      InvalidArgumentException        If a parameter is not valid
1411          */
1412         protected final function pushValueToGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element, $value) {
1413                 // Check parameter
1414                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s,value[]=%s - CALLED!', $keyGroup, $subGroup, $key, $element, gettype($value)));
1415                 if (empty($keyGroup)) {
1416                         // Throw IAE
1417                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1418                 } elseif (empty($subGroup)) {
1419                         // Throw IAE
1420                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1421                 } elseif (empty($key)) {
1422                         // Throw IAE
1423                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1424                 } elseif ($element === '') {
1425                         // Throw IAE
1426                         throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1427                 } elseif (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
1428                         // Initialize array
1429                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: Invoking this->initGenericArrayElement(%s,%s,%s,%s) ...', $keyGroup, $subGroup, $key, $element));
1430                         $this->initGenericArrayElement($keyGroup, $subGroup, $key, $element);
1431                 }
1432
1433                 // Then push it
1434                 $count = array_push($this->genericArray[$keyGroup][$subGroup][$key][$element], $value);
1435
1436                 // Return count
1437                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1438                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: count=%d - EXIT!', $count));
1439                 return $count;
1440         }
1441
1442         /**
1443          * Pops an element from  a generic group
1444          *
1445          * @param       $keyGroup       Main group for the key
1446          * @param       $subGroup       Sub group for the key
1447          * @param       $key            Key to unset
1448          * @return      $value          Last "popped" value
1449          * @throws      InvalidArgumentException        If a parameter is not valid
1450          * @throws      BadMethodCallException  If key/sub group isn't there but this method is invoked
1451          */
1452         protected final function popGenericArrayElement (string $keyGroup, string $subGroup, string $key) {
1453                 // Check parameter
1454                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1455                 if (empty($keyGroup)) {
1456                         // Throw IAE
1457                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1458                 } elseif (empty($subGroup)) {
1459                         // Throw IAE
1460                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1461                 } elseif (empty($key)) {
1462                         // Throw IAE
1463                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1464                 } elseif (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1465                         // Not found
1466                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s not found.', $keyGroup, $subGroup, gettype($key), $key), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1467                 }
1468
1469                 // Then "pop" it
1470                 $value = array_pop($this->genericArray[$keyGroup][$subGroup][$key]);
1471
1472                 // Return value
1473                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1474                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: value[]=%s - EXIT!', gettype($value)));
1475                 return $value;
1476         }
1477
1478         /**
1479          * Shifts an element from  a generic group
1480          *
1481          * @param       $keyGroup       Main group for the key
1482          * @param       $subGroup       Sub group for the key
1483          * @param       $key            Key to unset
1484          * @return      $value          Last "shifted" value
1485          * @throws      InvalidArgumentException        If a parameter is not valid
1486          * @throws      BadMethodCallException  If key/sub group isn't there but this method is invoked
1487          */
1488         protected final function shiftGenericArrayElement (string $keyGroup, string $subGroup, string $key) {
1489                 // Check parameter
1490                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1491                 if (empty($keyGroup)) {
1492                         // Throw IAE
1493                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1494                 } elseif (empty($subGroup)) {
1495                         // Throw IAE
1496                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1497                 } elseif (empty($key)) {
1498                         // Throw IAE
1499                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1500                 } elseif (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1501                         // Not found
1502                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s not found.', $keyGroup, $subGroup, gettype($key), $key), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1503                 }
1504
1505                 // Then "shift" it
1506                 $value = array_shift($this->genericArray[$keyGroup][$subGroup][$key]);
1507
1508                 // Return value
1509                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
1510                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: value[]=%s - EXIT!', gettype($value)));
1511                 return $value;
1512         }
1513
1514         /**
1515          * Count generic array group
1516          *
1517          * @param       $keyGroup       Main group for the key
1518          * @return      $count          Count of given group
1519          * @throws      InvalidArgumentException        If a parameter is not valid
1520          * @throws      BadMethodCallException  If key group isn't there but this method is invoked
1521          */
1522         protected final function countGenericArray (string $keyGroup) {
1523                 // Check parameter
1524                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s - CALLED!', $keyGroup));
1525                 if (empty($keyGroup)) {
1526                         // Throw IAE
1527                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1528                 } elseif (!isset($this->genericArray[$keyGroup])) {
1529                         // Not found
1530                         throw new BadMethodCallException(sprintf('keyGroup=%s not found.', $keyGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1531                 }
1532
1533                 // Then count it
1534                 $count = count($this->genericArray[$keyGroup]);
1535
1536                 // Return it
1537                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: count=%d - EXIT!', $count));
1538                 return $count;
1539         }
1540
1541         /**
1542          * Count generic array sub group
1543          *
1544          * @param       $keyGroup       Main group for the key
1545          * @param       $subGroup       Sub group for the key
1546          * @return      $count          Count of given group
1547          * @throws      InvalidArgumentException        If a parameter is not valid
1548          * @throws      BadMethodCallException  If key/sub group isn't there but this method is invoked
1549          */
1550         protected final function countGenericArrayGroup (string $keyGroup, string $subGroup) {
1551                 // Check parameter
1552                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s - CALLED!', $keyGroup, $subGroup));
1553                 if (empty($keyGroup)) {
1554                         // Throw IAE
1555                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1556                 } elseif (empty($subGroup)) {
1557                         // Throw IAE
1558                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1559                 } elseif (!$this->isGenericArrayGroupSet($keyGroup, $subGroup)) {
1560                         // Abort here
1561                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s not found.', $keyGroup, $subGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1562                 }
1563
1564                 // Then count it
1565                 $count = count($this->genericArray[$keyGroup][$subGroup]);
1566
1567                 // Return it
1568                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: count=%d - EXIT!', $count));
1569                 return $count;
1570         }
1571
1572         /**
1573          * Count generic array elements
1574          *
1575          * @param       $keyGroup       Main group for the key
1576          * @param       $subGroup       Sub group for the key
1577          * @param       $key            Key to count
1578          * @return      $count          Count of given key
1579          * @throws      InvalidArgumentException        If a parameter is not valid
1580          * @throws      BadMethodCallException  If key/sub group isn't there but this method is invoked
1581          */
1582         protected final function countGenericArrayElements (string $keyGroup, string $subGroup, string $key) {
1583                 // Check parameter
1584                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1585                 if (empty($keyGroup)) {
1586                         // Throw IAE
1587                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1588                 } elseif (empty($subGroup)) {
1589                         // Throw IAE
1590                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1591                 } elseif (empty($key)) {
1592                         // Throw IAE
1593                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1594                 } elseif (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1595                         // Abort here
1596                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s not found.', $keyGroup, $subGroup, gettype($key), $key), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1597                 } elseif (!$this->isValidGenericArrayGroup($keyGroup, $subGroup)) {
1598                         // Not valid
1599                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s is not a valid key/sub group.', $keyGroup, $subGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1600                 }
1601
1602                 // Then count it
1603                 $count = count($this->genericArray[$keyGroup][$subGroup][$key]);
1604
1605                 // Return it
1606                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: count=%d - EXIT!', $count));
1607                 return $count;
1608         }
1609
1610         /**
1611          * Getter for whole generic group array
1612          *
1613          * @param       $keyGroup       Key group to get
1614          * @return      $array          Whole generic array group
1615          * @throws      InvalidArgumentException        If a parameter is not valid
1616          * @throws      BadMethodCallException  If key/sub group isn't there but this method is invoked
1617          */
1618         protected final function getGenericArray (string $keyGroup) {
1619                 // Check parameters
1620                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s - CALLED!', $keyGroup));
1621                 if (empty($keyGroup)) {
1622                         // Throw IAE
1623                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1624                 } elseif (!isset($this->genericArray[$keyGroup])) {
1625                         // Then abort here
1626                         throw new BadMethodCallException(sprintf('keyGroup=%s not found', $keyGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1627                 }
1628
1629                 // Return it
1630                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->genericArray[%s][]=%s - EXIT!', $keyGroup, gettype($this->genericArray[$keyGroup])));
1631                 return $this->genericArray[$keyGroup];
1632         }
1633
1634         /**
1635          * Setter for generic array key
1636          *
1637          * @param       $keyGroup       Key group to get
1638          * @param       $subGroup       Sub group for the key
1639          * @param       $key            Key to unset
1640          * @param       $value          Mixed value from generic array element
1641          * @return      void
1642          * @throws      InvalidArgumentException        If a parameter is not valid
1643          * @throws      BadMethodCallException  If key/sub group isn't there but this method is invoked
1644          */
1645         protected final function setGenericArrayKey (string $keyGroup, string $subGroup, string $key, $value) {
1646                 // Check parameters
1647                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,value[]=%s - CALLED!', $keyGroup, $subGroup, $key, gettype($value)));
1648                 if (empty($keyGroup)) {
1649                         // Throw IAE
1650                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1651                 } elseif (empty($subGroup)) {
1652                         // Throw IAE
1653                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1654                 } elseif (empty($key)) {
1655                         // Throw IAE
1656                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1657                 } elseif (!$this->isValidGenericArrayGroup($keyGroup, $subGroup)) {
1658                         // Then abort here
1659                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s not found', $keyGroup), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1660                 }
1661
1662                 // Set value here
1663                 $this->genericArray[$keyGroup][$subGroup][$key] = $value;
1664
1665                 // Trace mesage
1666                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1667         }
1668
1669         /**
1670          * Getter for generic array key
1671          *
1672          * @param       $keyGroup       Key group to get
1673          * @param       $subGroup       Sub group for the key
1674          * @param       $key            Key to unset
1675          * @return      $value          Mixed value from generic array element
1676          * @throws      InvalidArgumentException        If a parameter is not valid
1677          * @throws      BadMethodCallException  If key/sub group isn't there but this method is invoked
1678          */
1679         protected final function getGenericArrayKey (string $keyGroup, string $subGroup, string $key) {
1680                 // Check parameters
1681                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1682                 if (empty($keyGroup)) {
1683                         // Throw IAE
1684                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1685                 } elseif (empty($subGroup)) {
1686                         // Throw IAE
1687                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1688                 } elseif (empty($key)) {
1689                         // Throw IAE
1690                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1691                 } elseif (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
1692                         // Then abort here
1693                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s not found.', $keyGroup, $subGroup, gettype($key), $key), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1694                 }
1695
1696                 // Return it
1697                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->genericArray[%s][%s][%s][]=%s - EXIT!', $keyGroup, $subGroup, $key, gettype($this->genericArray[$keyGroup][$subGroup][$key])));
1698                 return $this->genericArray[$keyGroup][$subGroup][$key];
1699         }
1700
1701         /**
1702          * Sets a value in given generic array key/element
1703          *
1704          * @param       $keyGroup       Main group for the key
1705          * @param       $subGroup       Sub group for the key
1706          * @param       $key            Key to set
1707          * @param       $element        Element to set
1708          * @param       $value          Value to set
1709          * @return      void
1710          * @throws      InvalidArgumentException        If a parameter is not valid
1711          */
1712         protected final function setGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element, $value) {
1713                 // Check parameter
1714                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s,value[]=%s - CALLED!', $keyGroup, $subGroup, $key, $element, gettype($value)));
1715                 if (empty($keyGroup)) {
1716                         // Throw IAE
1717                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1718                 } elseif (empty($subGroup)) {
1719                         // Throw IAE
1720                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1721                 } elseif (empty($key)) {
1722                         // Throw IAE
1723                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1724                 } elseif ($element === '') {
1725                         // Throw IAE
1726                         throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1727                 } elseif (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
1728                         // Initialize array
1729                         $this->initGenericArrayElement($keyGroup, $subGroup, $key, $element);
1730                 }
1731
1732                 // Then set it
1733                 $this->genericArray[$keyGroup][$subGroup][$key][$element] = $value;
1734
1735                 // Trace mesage
1736                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1737         }
1738
1739         /**
1740          * Getter for generic array element
1741          *
1742          * @param       $keyGroup       Key group to get
1743          * @param       $subGroup       Sub group for the key
1744          * @param       $key            Key to look for
1745          * @param       $element        Element to look for
1746          * @return      $value          Mixed value from generic array element
1747          * @throws      InvalidArgumentException        If a parameter is not valid
1748          * @throws      BadMethodCallException  If key/sub group isn't there but this method is invoked
1749          */
1750         protected final function getGenericArrayElement (string $keyGroup, string $subGroup, string $key, string $element) {
1751                 // Check parameter
1752                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s,element=%s - CALLED!', $keyGroup, $subGroup, $key, $element));
1753                 if (empty($keyGroup)) {
1754                         // Throw IAE
1755                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1756                 } elseif (empty($subGroup)) {
1757                         // Throw IAE
1758                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1759                 } elseif (empty($key)) {
1760                         // Throw IAE
1761                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1762                 } elseif ($element === '') {
1763                         // Throw IAE
1764                         throw new InvalidArgumentException('Parameter "element" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1765                 } elseif (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
1766                         // Then abort here
1767                         throw new BadMethodCallException(sprintf('keyGroup=%s,subGroup=%s,key[%s]=%s,element[%s]=%s not found.', $keyGroup, $subGroup, gettype($key), $key, gettype($element), $element), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1768                 }
1769
1770                 // Return it
1771                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: this->genericArray[%s][%s][%s][%s][]=%s - EXIT!', $keyGroup, $subGroup, $key, gettype($this->genericArray[$keyGroup][$subGroup][$key][$element])));
1772                 return $this->genericArray[$keyGroup][$subGroup][$key][$element];
1773         }
1774
1775         /**
1776          * Checks if a given sub group is valid (array)
1777          *
1778          * @param       $keyGroup       Key group to get
1779          * @param       $subGroup       Sub group for the key
1780          * @return      $isValid        Whether given sub group is valid
1781          * @throws      InvalidArgumentException        If a parameter is not valid
1782          */
1783         protected final function isValidGenericArrayGroup (string $keyGroup, string $subGroup) {
1784                 // Check parameter
1785                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s - CALLED!', $keyGroup, $subGroup));
1786                 if (empty($keyGroup)) {
1787                         // Throw IAE
1788                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1789                 } elseif (empty($subGroup)) {
1790                         // Throw IAE
1791                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1792                 }
1793
1794                 // Determine it
1795                 $isValid = (($this->isGenericArrayGroupSet($keyGroup, $subGroup)) && (is_array($this->getGenericSubArray($keyGroup, $subGroup))));
1796
1797                 // Return it
1798                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isValid=%d - EXIT!', intval($isValid)));
1799                 return $isValid;
1800         }
1801
1802         /**
1803          * Checks if a given key is valid (array)
1804          *
1805          * @param       $keyGroup       Key group to get
1806          * @param       $subGroup       Sub group for the key
1807          * @param       $key            Key to check
1808          * @return      $isValid        Whether given sub group is valid
1809          */
1810         protected final function isValidGenericArrayKey (string $keyGroup, string $subGroup, string $key) {
1811                 // Check parameters
1812                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: keyGroup=%s,subGroup=%s,key=%s - CALLED!', $keyGroup, $subGroup, $key));
1813                 if (empty($keyGroup)) {
1814                         // Throw IAE
1815                         throw new InvalidArgumentException('Parameter "keyGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1816                 } elseif (empty($subGroup)) {
1817                         // Throw IAE
1818                         throw new InvalidArgumentException('Parameter "subGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1819                 } elseif (empty($key)) {
1820                         // Throw IAE
1821                         throw new InvalidArgumentException('Parameter "key" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
1822                 }
1823
1824                 // Determine it
1825                 $isValid = (($this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) && (is_array($this->getGenericArrayKey($keyGroup, $subGroup, $key))));
1826
1827                 // Return it
1828                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: isValid=%d - EXIT!', intval($isValid)));
1829                 return $isValid;
1830         }
1831
1832         /**
1833          * Initializes the web output instance
1834          *
1835          * @return      void
1836          */
1837         protected function initWebOutputInstance () {
1838                 // Init web output instance
1839                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: CALLED!');
1840                 $outputInstance = ObjectFactory::createObjectByConfiguredName('output_class');
1841
1842                 // Set it locally
1843                 $this->setWebOutputInstance($outputInstance);
1844
1845                 // Trace mesage
1846                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: EXIT!');
1847         }
1848
1849         /**
1850          * Translates boolean true to 'Y' and false to 'N'
1851          *
1852          * @param       $boolean                Boolean value
1853          * @return      $translated             Translated boolean value
1854          */
1855         public static final function translateBooleanToYesNo (bool $boolean) {
1856                 // "Translate" it
1857                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: boolean=%d - CALLED!', intval($boolean)));
1858                 $translated = ($boolean === true) ? 'Y' : 'N';
1859
1860                 // ... and return it
1861                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: translated=%s - EXIT!', $translated));
1862                 return $translated;
1863         }
1864
1865         /**
1866          * Creates a full-qualified file name (FQFN) for given file name by adding
1867          * a configured temporary file path to it.
1868          *
1869          * @param       $infoInstance   An instance of a SplFileInfo class
1870          * @return      $fileInfoInstance       An instance of a SplFileInfo class (temporary file)
1871          * @throw       PathWriteProtectedException If the path in 'temp_file_path' is write-protected
1872          * @throws      FileIoException If the file cannot be written
1873          */
1874          protected static function createTempPathForFile (SplFileInfo $infoInstance) {
1875                 // Get config entry
1876                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: infoInstance=%s - CALLED!', $infoInstance->__toString()));
1877                 $basePath = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('temp_file_path');
1878
1879                 // Is the path writeable?
1880                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: basePath=%s', $basePath));
1881                 if (!is_writable($basePath)) {
1882                         // Path is write-protected
1883                         throw new PathWriteProtectedException($infoInstance, self::EXCEPTION_PATH_CANNOT_BE_WRITTEN);
1884                 }
1885
1886                 // Add it
1887                 $fileInfoInstance = new SplFileInfo($basePath . DIRECTORY_SEPARATOR . $infoInstance->getBasename());
1888
1889                 // Is it reachable?
1890                 if (!FrameworkBootstrap::isReachableFilePath($fileInfoInstance)) {
1891                         // Not reachable
1892                         throw new FileIoException($fileInfoInstance, self::EXCEPTION_FILE_NOT_REACHABLE);
1893                 }
1894
1895                 // Return it
1896                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: fileInfoInstance=%s - EXIT!', $fileInfoInstance->__toString()));
1897                 return $fileInfoInstance;
1898          }
1899
1900         /**
1901          * "Getter" for a printable state name
1902          *
1903          * @return      $stateName      Name of the node's state in a printable format
1904          * @throws      BadMethodCallException  If this instance doesn't have a callable getter for stateInstance
1905          * @todo        Move this class away from this monolithic place (not whole class is monolithic)
1906          */
1907         public final function getPrintableState () {
1908                 // Check if getter is there
1909                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-FRAMEWORK-SYSTEM: CALLED!');
1910                 if (!is_callable($this, 'getStateInstance')) {
1911                         // Throw BMCE
1912                         throw new BadMethodCallException(sprintf('this=%s has no callable getter for stateInstance', $this->__toString()), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
1913                 }
1914
1915                 // Default is 'null'
1916                 $stateName = 'null';
1917
1918                 // Get the state instance
1919                 $stateInstance = $this->getStateInstance();
1920
1921                 // Is it an instance of Stateable?
1922                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: stateInstance[]=%s', gettype($stateInstance)));
1923                 if ($stateInstance instanceof Stateable) {
1924                         // Then use that state name
1925                         $stateName = $stateInstance->getStateName();
1926                 }
1927
1928                 // Return result
1929                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-FRAMEWORK-SYSTEM: stateName=%s - EXIT!', $stateName));
1930                 return $stateName;
1931         }
1932
1933 }