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