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