framework/main/classes/class_BaseFrameworkSystem.php

   1 <?php
   2 // Own namespace
   3 namespace CoreFramework\Object;
   4
   5 // Import framework stuff
   6 use CoreFramework\Compressor\Compressor;
   7 use CoreFramework\Configuration\FrameworkConfiguration;
   8 use CoreFramework\Connection\Database\DatabaseConnection;
   9 use CoreFramework\Controller\Controller;
  10 use CoreFramework\Criteria\Criteria;
  11 use CoreFramework\Criteria\Local\LocalSearchCriteria;
  12 use CoreFramework\Criteria\Local\LocalUpdateCriteria;
  13 use CoreFramework\Factory\Database\Wrapper\DatabaseWrapperFactory;
  14 use CoreFramework\Factory\ObjectFactory;
  15 use CoreFramework\Filesystem\FrameworkDirectory;
  16 use CoreFramework\Generic\FrameworkInterface;
  17 use CoreFramework\Generic\NullPointerException;
  18 use CoreFramework\Handler\Stream\IoHandler;
  19 use CoreFramework\Loader\ClassLoader;
  20 use CoreFramework\Manager\ManageableApplication;
  21 use CoreFramework\Middleware\Compressor\CompressorChannel;
  22 use CoreFramework\Middleware\Debug\DebugMiddleware;
  23 use CoreFramework\Registry\Register;
  24 use CoreFramework\Registry\Registry;
  25 use CoreFramework\Request\Requestable;
  26 use CoreFramework\Resolver\Resolver;
  27 use CoreFramework\Result\Database\CachedDatabaseResult;
  28 use CoreFramework\Result\Search\SearchableResult;
  29 use CoreFramework\Response\Responseable;
  30 use CoreFramework\Stream\Output\OutputStreamer;
  31 use CoreFramework\Template\CompileableTemplate;
  32 use CoreFramework\Wrapper\Database\DatabaseWrapper;
  33
  34 // Import SPL stuff
  35 use \stdClass;
  36 use \ReflectionClass;
  37
  38 /**
  39  * The simulator system class is the super class of all other classes. This
  40  * class handles saving of games etc.
  41  *
  42  * @author              Roland Haeder <webmaster@shipsimu.org>
  43  * @version             0.0.0
  44  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2017 Core Developer Team
  45  * @license             GNU GPL 3.0 or any newer version
  46  * @link                http://www.shipsimu.org
  47  *
  48  * This program is free software: you can redistribute it and/or modify
  49  * it under the terms of the GNU General Public License as published by
  50  * the Free Software Foundation, either version 3 of the License, or
  51  * (at your option) any later version.
  52  *
  53  * This program is distributed in the hope that it will be useful,
  54  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  55  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  56  * GNU General Public License for more details.
  57  *
  58  * You should have received a copy of the GNU General Public License
  59  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  60  */
  61 class BaseFrameworkSystem extends stdClass implements FrameworkInterface {
  62         /**
  63          * Length of output from hash()
  64          */
  65         private static $hashLength = NULL;
  66
  67         /**
  68          * The real class name
  69          */
  70         private $realClass = 'BaseFrameworkSystem';
  71
  72         /**
  73          * Instance of a Requestable class
  74          */
  75         private $requestInstance = NULL;
  76
  77         /**
  78          * Instance of a Responseable class
  79          */
  80         private $responseInstance = NULL;
  81
  82         /**
  83          * Search criteria instance
  84          */
  85         private $searchInstance = NULL;
  86
  87         /**
  88          * Update criteria instance
  89          */
  90         private $updateInstance = NULL;
  91
  92         /**
  93          * The file I/O instance for the template loader
  94          */
  95         private $fileIoInstance = NULL;
  96
  97         /**
  98          * Resolver instance
  99          */
 100         private $resolverInstance = NULL;
 101
 102         /**
 103          * Template engine instance
 104          */
 105         private $templateInstance = NULL;
 106
 107         /**
 108          * Database result instance
 109          */
 110         private $resultInstance = NULL;
 111
 112         /**
 113          * Instance for user class
 114          */
 115         private $userInstance = NULL;
 116
 117         /**
 118          * A controller instance
 119          */
 120         private $controllerInstance = NULL;
 121
 122         /**
 123          * Instance of a RNG
 124          */
 125         private $rngInstance = NULL;
 126
 127         /**
 128          * Instance of a crypto helper
 129          */
 130         private $cryptoInstance = NULL;
 131
 132         /**
 133          * Instance of an Iterator class
 134          */
 135         private $iteratorInstance = NULL;
 136
 137         /**
 138          * Instance of the list
 139          */
 140         private $listInstance = NULL;
 141
 142         /**
 143          * Instance of a menu
 144          */
 145         private $menuInstance = NULL;
 146
 147         /**
 148          * Instance of the image
 149          */
 150         private $imageInstance = NULL;
 151
 152         /**
 153          * Instance of the stacker
 154          */
 155         private $stackInstance = NULL;
 156
 157         /**
 158          * A Compressor instance
 159          */
 160         private $compressorInstance = NULL;
 161
 162         /**
 163          * A Parseable instance
 164          */
 165         private $parserInstance = NULL;
 166
 167         /**
 168          * A HandleableProtocol instance
 169          */
 170         private $protocolInstance = NULL;
 171
 172         /**
 173          * A database wrapper instance
 174          */
 175         private $databaseInstance = NULL;
 176
 177         /**
 178          * A helper instance for the form
 179          */
 180         private $helperInstance = NULL;
 181
 182         /**
 183          * An instance of a Source class
 184          */
 185         private $sourceInstance = NULL;
 186
 187         /**
 188          * An instance of a UrlSource class
 189          */
 190         private $urlSourceInstance = NULL;
 191
 192         /**
 193          * An instance of a InputStream class
 194          */
 195         private $inputStreamInstance = NULL;
 196
 197         /**
 198          * An instance of a OutputStream class
 199          */
 200         private $outputStreamInstance = NULL;
 201
 202         /**
 203          * Networkable handler instance
 204          */
 205         private $handlerInstance = NULL;
 206
 207         /**
 208          * Visitor handler instance
 209          */
 210         private $visitorInstance = NULL;
 211
 212         /**
 213          * DHT instance
 214          */
 215         private $dhtInstance = NULL;
 216
 217         /**
 218          * An instance of a database wrapper class
 219          */
 220         private $wrapperInstance = NULL;
 221
 222         /**
 223          * An instance of a file I/O pointer class (not handler)
 224          */
 225         private $pointerInstance = NULL;
 226
 227         /**
 228          * An instance of an Indexable class
 229          */
 230         private $indexInstance = NULL;
 231
 232         /**
 233          * An instance of a Block class
 234          */
 235         private $blockInstance = NULL;
 236
 237         /**
 238          * A Minable instance
 239          */
 240         private $minableInstance = NULL;
 241
 242         /**
 243          * A FrameworkDirectory instance
 244          */
 245         private $directoryInstance = NULL;
 246
 247         /**
 248          * Listener instance
 249          */
 250         private $listenerInstance = NULL;
 251
 252         /**
 253          * An instance of a communicator
 254          */
 255         private $communicatorInstance = NULL;
 256
 257         /**
 258          * The concrete output instance
 259          */
 260         private $outputInstance = NULL;
 261
 262         /**
 263          * State instance
 264          */
 265         private $stateInstance = NULL;
 266
 267         /**
 268          * Thousands separator
 269          */
 270         private $thousands = '.'; // German
 271
 272         /**
 273          * Decimal separator
 274          */
 275         private $decimals  = ','; // German
 276
 277         /**
 278          * Socket resource
 279          */
 280         private $socketResource = FALSE;
 281
 282         /**
 283          * Regular expression to use for validation
 284          */
 285         private $regularExpression = '';
 286
 287         /**
 288          * Package data
 289          */
 290         private $packageData = array();
 291
 292         /**
 293          * Generic array
 294          */
 295         private $genericArray = array();
 296
 297         /**
 298          * Command name
 299          */
 300         private $commandName = '';
 301
 302         /**
 303          * Controller name
 304          */
 305         private $controllerName = '';
 306
 307         /**
 308          * Name of used protocol
 309          */
 310         private $protocolName = 'invalid';
 311
 312         /**
 313          * Array with bitmasks and such for pack/unpack methods to support both
 314          * 32-bit and 64-bit systems
 315          */
 316         private $packingData = array(
 317                 32 => array(
 318                         'step'   => 3,
 319                         'left'   => 0xffff0000,
 320                         'right'  => 0x0000ffff,
 321                         'factor' => 16,
 322                         'format' => 'II',
 323                 ),
 324                 64 => array(
 325                         'step'   => 7,
 326                         'left'   => 0xffffffff00000000,
 327                         'right'  => 0x00000000ffffffff,
 328                         'factor' => 32,
 329                         'format' => 'NN'
 330                 )
 331         );
 332
 333         /**
 334          * Simple 64-bit check, thanks to "Salman A" from stackoverflow.com:
 335          *
 336          * The integer size is 4 bytes on 32-bit and 8 bytes on a 64-bit system.
 337          */
 338         private $archArrayElement = FALSE;
 339
 340         /***********************
 341          * Exception codes.... *
 342          ***********************/
 343
 344         // @todo Try to clean these constants up
 345         const EXCEPTION_IS_NULL_POINTER              = 0x001;
 346         const EXCEPTION_IS_NO_OBJECT                 = 0x002;
 347         const EXCEPTION_IS_NO_ARRAY                  = 0x003;
 348         const EXCEPTION_MISSING_METHOD               = 0x004;
 349         const EXCEPTION_CLASSES_NOT_MATCHING         = 0x005;
 350         const EXCEPTION_INDEX_OUT_OF_BOUNDS          = 0x006;
 351         const EXCEPTION_DIMENSION_ARRAY_INVALID      = 0x007;
 352         const EXCEPTION_ITEM_NOT_TRADEABLE           = 0x008;
 353         const EXCEPTION_ITEM_NOT_IN_PRICE_LIST       = 0x009;
 354         const EXCEPTION_GENDER_IS_WRONG              = 0x00a;
 355         const EXCEPTION_BIRTH_DATE_IS_INVALID        = 0x00b;
 356         const EXCEPTION_EMPTY_STRUCTURES_ARRAY       = 0x00c;
 357         const EXCEPTION_HAS_ALREADY_PERSONELL_LIST   = 0x00d;
 358         const EXCEPTION_NOT_ENOUGTH_UNEMPLOYEES      = 0x00e;
 359         const EXCEPTION_TOTAL_PRICE_NOT_CALCULATED   = 0x00f;
 360         const EXCEPTION_HARBOR_HAS_NO_SHIPYARDS      = 0x010;
 361         const EXCEPTION_CONTRACT_PARTNER_INVALID     = 0x011;
 362         const EXCEPTION_CONTRACT_PARTNER_MISMATCH    = 0x012;
 363         const EXCEPTION_CONTRACT_ALREADY_SIGNED      = 0x013;
 364         const EXCEPTION_UNEXPECTED_EMPTY_STRING      = 0x014;
 365         const EXCEPTION_PATH_NOT_FOUND               = 0x015;
 366         const EXCEPTION_INVALID_PATH_NAME            = 0x016;
 367         const EXCEPTION_READ_PROTECED_PATH           = 0x017;
 368         const EXCEPTION_WRITE_PROTECED_PATH          = 0x018;
 369         const EXCEPTION_DIR_POINTER_INVALID          = 0x019;
 370         const EXCEPTION_FILE_POINTER_INVALID         = 0x01a;
 371         const EXCEPTION_INVALID_RESOURCE             = 0x01b;
 372         const EXCEPTION_UNEXPECTED_OBJECT            = 0x01c;
 373         const EXCEPTION_LIMIT_ELEMENT_IS_UNSUPPORTED = 0x01d;
 374         const EXCEPTION_GETTER_IS_MISSING            = 0x01e;
 375         const EXCEPTION_ARRAY_EXPECTED               = 0x01f;
 376         const EXCEPTION_ARRAY_HAS_INVALID_COUNT      = 0x020;
 377         const EXCEPTION_ID_IS_INVALID_FORMAT         = 0x021;
 378         const EXCEPTION_MD5_CHECKSUMS_MISMATCH       = 0x022;
 379         const EXCEPTION_UNEXPECTED_STRING_SIZE       = 0x023;
 380         const EXCEPTION_SIMULATOR_ID_INVALID         = 0x024;
 381         const EXCEPTION_MISMATCHING_COMPRESSORS      = 0x025;
 382         const EXCEPTION_CONTAINER_ITEM_IS_NULL       = 0x026;
 383         const EXCEPTION_ITEM_IS_NO_ARRAY             = 0x027;
 384         const EXCEPTION_CONTAINER_MAYBE_DAMAGED      = 0x028;
 385         const EXCEPTION_INVALID_STRING               = 0x029;
 386         const EXCEPTION_VARIABLE_NOT_SET             = 0x02a;
 387         const EXCEPTION_ATTRIBUTES_ARE_MISSING       = 0x02b;
 388         const EXCEPTION_ARRAY_ELEMENTS_MISSING       = 0x02c;
 389         const EXCEPTION_TEMPLATE_ENGINE_UNSUPPORTED  = 0x02d;
 390         const EXCEPTION_UNSPPORTED_OPERATION         = 0x02e;
 391         const EXCEPTION_FACTORY_REQUIRE_PARAMETER    = 0x02f;
 392         const EXCEPTION_MISSING_ELEMENT              = 0x030;
 393         const EXCEPTION_HEADERS_ALREADY_SENT         = 0x031;
 394         const EXCEPTION_DEFAULT_CONTROLLER_GONE      = 0x032;
 395         const EXCEPTION_CLASS_NOT_FOUND              = 0x033;
 396         const EXCEPTION_REQUIRED_INTERFACE_MISSING   = 0x034;
 397         const EXCEPTION_FATAL_ERROR                  = 0x035;
 398         const EXCEPTION_FILE_NOT_FOUND               = 0x036;
 399         const EXCEPTION_ASSERTION_FAILED             = 0x037;
 400         const EXCEPTION_FILE_NOT_REACHABLE           = 0x038;
 401         const EXCEPTION_FILE_CANNOT_BE_READ          = 0x039;
 402         const EXCEPTION_FILE_CANNOT_BE_WRITTEN       = 0x03a;
 403         const EXCEPTION_PATH_CANNOT_BE_WRITTEN       = 0x03b;
 404         const EXCEPTION_DATABASE_UPDATED_NOT_ALLOWED = 0x03c;
 405         const EXCEPTION_FILTER_CHAIN_INTERCEPTED     = 0x03d;
 406
 407         /**
 408          * Hexadecimal->Decimal translation array
 409          */
 410         private static $hexdec = array(
 411                 '0' => 0,
 412                 '1' => 1,
 413                 '2' => 2,
 414                 '3' => 3,
 415                 '4' => 4,
 416                 '5' => 5,
 417                 '6' => 6,
 418                 '7' => 7,
 419                 '8' => 8,
 420                 '9' => 9,
 421                 'a' => 10,
 422                 'b' => 11,
 423                 'c' => 12,
 424                 'd' => 13,
 425                 'e' => 14,
 426                 'f' => 15
 427         );
 428
 429         /**
 430          * Decimal->hexadecimal translation array
 431          */
 432         private static $dechex = array(
 433                  0 => '0',
 434                  1 => '1',
 435                  2 => '2',
 436                  3 => '3',
 437                  4 => '4',
 438                  5 => '5',
 439                  6 => '6',
 440                  7 => '7',
 441                  8 => '8',
 442                  9 => '9',
 443                 10 => 'a',
 444                 11 => 'b',
 445                 12 => 'c',
 446                 13 => 'd',
 447                 14 => 'e',
 448                 15 => 'f'
 449         );
 450
 451         /**
 452          * Startup time in miliseconds
 453          */
 454         private static $startupTime = 0;
 455
 456         /**
 457          * Protected super constructor
 458          *
 459          * @param       $className      Name of the class
 460          * @return      void
 461          */
 462         protected function __construct ($className) {
 463                 // Set real class
 464                 $this->setRealClass($className);
 465
 466                 // Set configuration instance if no registry ...
 467                 if (!$this instanceof Register) {
 468                         // ... because registries doesn't need to be configured
 469                         $this->setConfigInstance(FrameworkConfiguration::getSelfInstance());
 470                 } // END - if
 471
 472                 // Is the startup time set? (0 cannot be TRUE anymore)
 473                 if (self::$startupTime == 0) {
 474                         // Then set it
 475                         self::$startupTime = microtime(TRUE);
 476                 } // END - if
 477
 478                 // Set array element
 479                 $this->archArrayElement = (PHP_INT_SIZE === 8 ? 64 : 32);
 480         }
 481
 482         /**
 483          * Destructor for all classes. You should not call this method on your own.
 484          *
 485          * @return      void
 486          */
 487         public function __destruct () {
 488                 // Flush any updated entries to the database
 489                 $this->flushPendingUpdates();
 490
 491                 // Is this object already destroyed?
 492                 if ($this->__toString() != 'DestructedObject') {
 493                         // Destroy all informations about this class but keep some text about it alive
 494                         $this->setRealClass('DestructedObject');
 495                 } elseif ((defined('DEBUG_DESTRUCTOR')) && (is_object($this->getDebugInstance()))) {
 496                         // Already destructed object
 497                         self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:] The object <span class="object_name">%s</span> is already destroyed.',
 498                                 __CLASS__,
 499                                 $this->__toString()
 500                         ));
 501                 } else {
 502                         // Do not call this twice
 503                         trigger_error(__METHOD__ . ': Called twice.');
 504                         exit;
 505                 }
 506         }
 507
 508         /**
 509          * The __call() method where all non-implemented methods end up
 510          *
 511          * @param       $methodName             Name of the missing method
 512          * @args        $args                   Arguments passed to the method
 513          * @return      void
 514          */
 515         public final function __call ($methodName, $args) {
 516                 return self::__callStatic($methodName, $args);
 517         }
 518
 519         /**
 520          * The __callStatic() method where all non-implemented static methods end up
 521          *
 522          * @param       $methodName             Name of the missing method
 523          * @args        $args                   Arguments passed to the method
 524          * @return      void
 525          */
 526         public static final function __callStatic ($methodName, $args) {
 527                 // Trace message
 528                 //* PRINT-DEBUG: */ printf('[%s:%d]: methodName=%s,args[]=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $methodName, gettype($args));
 529
 530                 // Init argument string
 531                 $argsString = '';
 532
 533                 // Is it NULL, empty or an array?
 534                 if (is_null($args)) {
 535                         // No arguments
 536                         $argsString = 'NULL';
 537                 } elseif (is_array($args)) {
 538                         // Start braces
 539                         $argsString = '(';
 540
 541                         // Some arguments are there
 542                         foreach ($args as $arg) {
 543                                 // Add data about the argument
 544                                 $argsString .= gettype($arg) . ':';
 545
 546                                 if (is_null($arg)) {
 547                                         // Found a NULL argument
 548                                         $argsString .= 'NULL';
 549                                 } elseif (is_string($arg)) {
 550                                         // Add length for strings
 551                                         $argsString .= strlen($arg);
 552                                 } elseif ((is_int($arg)) || (is_float($arg))) {
 553                                         // ... integer/float
 554                                         $argsString .= $arg;
 555                                 } elseif (is_array($arg)) {
 556                                         // .. or size if array
 557                                         $argsString .= count($arg);
 558                                 } elseif (is_object($arg)) {
 559                                         // Get reflection
 560                                         $reflection = new ReflectionClass($arg);
 561
 562                                         // Is an other object, maybe no __toString() available
 563                                         $argsString .= $reflection->getName();
 564                                 } elseif ($arg === TRUE) {
 565                                         // ... is boolean 'TRUE'
 566                                         $argsString .= 'TRUE';
 567                                 } elseif ($arg === FALSE) {
 568                                         // ... is boolean 'FALSE'
 569                                         $argsString .= 'FALSE';
 570                                 }
 571
 572                                 // Comma for next one
 573                                 $argsString .= ', ';
 574                         } // END - foreach
 575
 576                         // Remove last comma
 577                         if (substr($argsString, -2, 1) == ',') {
 578                                 $argsString = substr($argsString, 0, -2);
 579                         } // END - if
 580
 581                         // Close braces
 582                         $argsString .= ')';
 583                 } else {
 584                         // Invalid arguments!
 585                         $argsString = '!INVALID:' . gettype($args) . '!';
 586                 }
 587
 588                 // Output stub message
 589                 // @TODO __CLASS__ does always return BaseFrameworkSystem but not the extending (=child) class
 590                 self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[unknown::%s:] Stub! Args: %s',
 591                         $methodName,
 592                         $argsString
 593                 ));
 594
 595                 // Return nothing
 596                 return NULL;
 597         }
 598
 599         /**
 600          * Getter for $realClass
 601          *
 602          * @return      $realClass The name of the real class (not BaseFrameworkSystem)
 603          */
 604         public function __toString () {
 605                 return $this->realClass;
 606         }
 607
 608         /**
 609          * Magic method to catch setting of missing but set class fields/attributes
 610          *
 611          * @param       $name   Name of the field/attribute
 612          * @param       $value  Value to store
 613          * @return      void
 614          */
 615         public final function __set ($name, $value) {
 616                 $this->debugBackTrace(sprintf('Tried to set a missing field. name=%s, value[%s]=%s',
 617                         $name,
 618                         gettype($value),
 619                         print_r($value, TRUE)
 620                 ));
 621         }
 622
 623         /**
 624          * Magic method to catch getting of missing fields/attributes
 625          *
 626          * @param       $name   Name of the field/attribute
 627          * @return      void
 628          */
 629         public final function __get ($name) {
 630                 $this->debugBackTrace(sprintf('Tried to get a missing field. name=%s',
 631                         $name
 632                 ));
 633         }
 634
 635         /**
 636          * Magic method to catch unsetting of missing fields/attributes
 637          *
 638          * @param       $name   Name of the field/attribute
 639          * @return      void
 640          */
 641         public final function __unset ($name) {
 642                 $this->debugBackTrace(sprintf('Tried to unset a missing field. name=%s',
 643                         $name
 644                 ));
 645         }
 646
 647         /**
 648          * Magic method to catch object serialization
 649          *
 650          * @return      $unsupported    Unsupported method
 651          * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
 652          */
 653         public final function __sleep () {
 654                 throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
 655         }
 656
 657         /**
 658          * Magic method to catch object deserialization
 659          *
 660          * @return      $unsupported    Unsupported method
 661          * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
 662          */
 663         public final function __wakeup () {
 664                 throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
 665         }
 666
 667         /**
 668          * Magic method to catch calls when an object instance is called
 669          *
 670          * @return      $unsupported    Unsupported method
 671          * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
 672          */
 673         public final function __invoke () {
 674                 throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
 675         }
 676
 677         /**
 678          * Setter for the real class name
 679          *
 680          * @param       $realClass      Class name (string)
 681          * @return      void
 682          */
 683         public final function setRealClass ($realClass) {
 684                 // Set real class
 685                 $this->realClass = (string) $realClass;
 686         }
 687
 688         /**
 689          * Setter for database result instance
 690          *
 691          * @param       $resultInstance         An instance of a database result class
 692          * @return      void
 693          * @todo        SearchableResult and UpdateableResult shall have a super interface to use here
 694          */
 695         protected final function setResultInstance (SearchableResult $resultInstance) {
 696                 $this->resultInstance =  $resultInstance;
 697         }
 698
 699         /**
 700          * Getter for database result instance
 701          *
 702          * @return      $resultInstance         An instance of a database result class
 703          */
 704         public final function getResultInstance () {
 705                 return $this->resultInstance;
 706         }
 707
 708         /**
 709          * Setter for template engine instances
 710          *
 711          * @param       $templateInstance       An instance of a template engine class
 712          * @return      void
 713          */
 714         protected final function setTemplateInstance (CompileableTemplate $templateInstance) {
 715                 $this->templateInstance = $templateInstance;
 716         }
 717
 718         /**
 719          * Getter for template engine instances
 720          *
 721          * @return      $templateInstance       An instance of a template engine class
 722          */
 723         protected final function getTemplateInstance () {
 724                 return $this->templateInstance;
 725         }
 726
 727         /**
 728          * Setter for search instance
 729          *
 730          * @param       $searchInstance         Searchable criteria instance
 731          * @return      void
 732          */
 733         public final function setSearchInstance (LocalSearchCriteria $searchInstance) {
 734                 $this->searchInstance = $searchInstance;
 735         }
 736
 737         /**
 738          * Getter for search instance
 739          *
 740          * @return      $searchInstance         Searchable criteria instance
 741          */
 742         public final function getSearchInstance () {
 743                 return $this->searchInstance;
 744         }
 745
 746         /**
 747          * Setter for update instance
 748          *
 749          * @param       $updateInstance         An instance of a LocalUpdateCriteria clase
 750          * @return      void
 751          */
 752         public final function setUpdateInstance (LocalUpdateCriteria $updateInstance) {
 753                 $this->updateInstance = $updateInstance;
 754         }
 755
 756         /**
 757          * Getter for update instance
 758          *
 759          * @return      $updateInstance         Updateable criteria instance
 760          */
 761         public final function getUpdateInstance () {
 762                 return $this->updateInstance;
 763         }
 764
 765         /**
 766          * Setter for resolver instance
 767          *
 768          * @param       $resolverInstance       Instance of a command resolver class
 769          * @return      void
 770          */
 771         public final function setResolverInstance (Resolver $resolverInstance) {
 772                 $this->resolverInstance = $resolverInstance;
 773         }
 774
 775         /**
 776          * Getter for resolver instance
 777          *
 778          * @return      $resolverInstance       Instance of a command resolver class
 779          */
 780         public final function getResolverInstance () {
 781                 return $this->resolverInstance;
 782         }
 783
 784         /**
 785          * Setter for language instance
 786          *
 787          * @param       $configInstance         The configuration instance which shall
 788          *                                                              be FrameworkConfiguration
 789          * @return      void
 790          */
 791         public final function setConfigInstance (FrameworkConfiguration $configInstance) {
 792                 Registry::getRegistry()->addInstance('config', $configInstance);
 793         }
 794
 795         /**
 796          * Getter for configuration instance
 797          *
 798          * @return      $configInstance         Configuration instance
 799          */
 800         public final function getConfigInstance () {
 801                 $configInstance = Registry::getRegistry()->getInstance('config');
 802                 return $configInstance;
 803         }
 804
 805         /**
 806          * Setter for debug instance
 807          *
 808          * @param       $debugInstance  The instance for debug output class
 809          * @return      void
 810          */
 811         public final function setDebugInstance (DebugMiddleware $debugInstance) {
 812                 Registry::getRegistry()->addInstance('debug', $debugInstance);
 813         }
 814
 815         /**
 816          * Getter for debug instance
 817          *
 818          * @return      $debugInstance  Instance to class DebugConsoleOutput or DebugWebOutput
 819          */
 820         public final function getDebugInstance () {
 821                 // Get debug instance
 822                 $debugInstance = Registry::getRegistry()->getInstance('debug');
 823
 824                 // Return it
 825                 return $debugInstance;
 826         }
 827
 828         /**
 829          * Setter for web output instance
 830          *
 831          * @param       $webInstance    The instance for web output class
 832          * @return      void
 833          */
 834         public final function setWebOutputInstance (OutputStreamer $webInstance) {
 835                 Registry::getRegistry()->addInstance('web_output', $webInstance);
 836         }
 837
 838         /**
 839          * Getter for web output instance
 840          *
 841          * @return      $webOutputInstance - Instance to class WebOutput
 842          */
 843         public final function getWebOutputInstance () {
 844                 $webOutputInstance = Registry::getRegistry()->getInstance('web_output');
 845                 return $webOutputInstance;
 846         }
 847
 848         /**
 849          * Setter for database instance
 850          *
 851          * @param       $databaseInstance       The instance for the database connection (forced DatabaseConnection)
 852          * @return      void
 853          */
 854         public final function setDatabaseInstance (DatabaseConnection $databaseInstance) {
 855                 Registry::getRegistry()->addInstance('db_instance', $databaseInstance);
 856         }
 857
 858         /**
 859          * Getter for database layer
 860          *
 861          * @return      $databaseInstance       The database layer instance
 862          */
 863         public final function getDatabaseInstance () {
 864                 // Get instance
 865                 $databaseInstance = Registry::getRegistry()->getInstance('db_instance');
 866
 867                 // Return instance
 868                 return $databaseInstance;
 869         }
 870
 871         /**
 872          * Setter for compressor channel
 873          *
 874          * @param       $compressorInstance             An instance of CompressorChannel
 875          * @return      void
 876          */
 877         public final function setCompressorChannel (CompressorChannel $compressorInstance) {
 878                 Registry::getRegistry()->addInstance('compressor', $compressorInstance);
 879         }
 880
 881         /**
 882          * Getter for compressor channel
 883          *
 884          * @return      $compressorInstance             The compressor channel
 885          */
 886         public final function getCompressorChannel () {
 887                 $compressorInstance = Registry::getRegistry()->getInstance('compressor');
 888                 return $compressorInstance;
 889         }
 890
 891         /**
 892          * Protected getter for a manageable application helper class
 893          *
 894          * @return      $applicationInstance    An instance of a manageable application helper class
 895          */
 896         protected final function getApplicationInstance () {
 897                 $applicationInstance = Registry::getRegistry()->getInstance('application');
 898                 return $applicationInstance;
 899         }
 900
 901         /**
 902          * Setter for a manageable application helper class
 903          *
 904          * @param       $applicationInstance    An instance of a manageable application helper class
 905          * @return      void
 906          */
 907         public final function setApplicationInstance (ManageableApplication $applicationInstance) {
 908                 Registry::getRegistry()->addInstance('application', $applicationInstance);
 909         }
 910
 911         /**
 912          * Setter for request instance
 913          *
 914          * @param       $requestInstance        An instance of a Requestable class
 915          * @return      void
 916          */
 917         public final function setRequestInstance (Requestable $requestInstance) {
 918                 $this->requestInstance = $requestInstance;
 919         }
 920
 921         /**
 922          * Getter for request instance
 923          *
 924          * @return      $requestInstance        An instance of a Requestable class
 925          */
 926         public final function getRequestInstance () {
 927                 return $this->requestInstance;
 928         }
 929
 930         /**
 931          * Setter for response instance
 932          *
 933          * @param       $responseInstance       An instance of a Responseable class
 934          * @return      void
 935          */
 936         public final function setResponseInstance (Responseable $responseInstance) {
 937                 $this->responseInstance = $responseInstance;
 938         }
 939
 940         /**
 941          * Getter for response instance
 942          *
 943          * @return      $responseInstance       An instance of a Responseable class
 944          */
 945         public final function getResponseInstance () {
 946                 return $this->responseInstance;
 947         }
 948
 949         /**
 950          * Private getter for language instance
 951          *
 952          * @return      $langInstance   An instance to the language sub-system
 953          */
 954         protected final function getLanguageInstance () {
 955                 $langInstance = Registry::getRegistry()->getInstance('language');
 956                 return $langInstance;
 957         }
 958
 959         /**
 960          * Setter for language instance
 961          *
 962          * @param       $langInstance   An instance to the language sub-system
 963          * @return      void
 964          * @see         LanguageSystem
 965          */
 966         public final function setLanguageInstance (ManageableLanguage $langInstance) {
 967                 Registry::getRegistry()->addInstance('language', $langInstance);
 968         }
 969
 970         /**
 971          * Private getter for file IO instance
 972          *
 973          * @return      $fileIoInstance         An instance to the file I/O sub-system
 974          */
 975         protected final function getFileIoInstance () {
 976                 return $this->fileIoInstance;
 977         }
 978
 979         /**
 980          * Setter for file I/O instance
 981          *
 982          * @param       $fileIoInstance         An instance to the file I/O sub-system
 983          * @return      void
 984          */
 985         public final function setFileIoInstance (IoHandler $fileIoInstance) {
 986                 $this->fileIoInstance = $fileIoInstance;
 987         }
 988
 989         /**
 990          * Protected setter for user instance
 991          *
 992          * @param       $userInstance   An instance of a user class
 993          * @return      void
 994          */
 995         protected final function setUserInstance (ManageableAccount $userInstance) {
 996                 $this->userInstance = $userInstance;
 997         }
 998
 999         /**
1000          * Getter for user instance
1001          *
1002          * @return      $userInstance   An instance of a user class
1003          */
1004         public final function getUserInstance () {
1005                 return $this->userInstance;
1006         }
1007
1008         /**
1009          * Setter for controller instance (this surely breaks a bit the MVC patterm)
1010          *
1011          * @param       $controllerInstance             An instance of the controller
1012          * @return      void
1013          */
1014         public final function setControllerInstance (Controller $controllerInstance) {
1015                 $this->controllerInstance = $controllerInstance;
1016         }
1017
1018         /**
1019          * Getter for controller instance (this surely breaks a bit the MVC patterm)
1020          *
1021          * @return      $controllerInstance             An instance of the controller
1022          */
1023         public final function getControllerInstance () {
1024                 return $this->controllerInstance;
1025         }
1026
1027         /**
1028          * Setter for RNG instance
1029          *
1030          * @param       $rngInstance    An instance of a random number generator (RNG)
1031          * @return      void
1032          */
1033         protected final function setRngInstance (RandomNumberGenerator $rngInstance) {
1034                 $this->rngInstance = $rngInstance;
1035         }
1036
1037         /**
1038          * Getter for RNG instance
1039          *
1040          * @return      $rngInstance    An instance of a random number generator (RNG)
1041          */
1042         public final function getRngInstance () {
1043                 return $this->rngInstance;
1044         }
1045
1046         /**
1047          * Setter for Cryptable instance
1048          *
1049          * @param       $cryptoInstance An instance of a Cryptable class
1050          * @return      void
1051          */
1052         protected final function setCryptoInstance (Cryptable $cryptoInstance) {
1053                 $this->cryptoInstance = $cryptoInstance;
1054         }
1055
1056         /**
1057          * Getter for Cryptable instance
1058          *
1059          * @return      $cryptoInstance An instance of a Cryptable class
1060          */
1061         public final function getCryptoInstance () {
1062                 return $this->cryptoInstance;
1063         }
1064
1065         /**
1066          * Setter for the list instance
1067          *
1068          * @param       $listInstance   A list of Listable
1069          * @return      void
1070          */
1071         protected final function setListInstance (Listable $listInstance) {
1072                 $this->listInstance = $listInstance;
1073         }
1074
1075         /**
1076          * Getter for the list instance
1077          *
1078          * @return      $listInstance   A list of Listable
1079          */
1080         protected final function getListInstance () {
1081                 return $this->listInstance;
1082         }
1083
1084         /**
1085          * Setter for the menu instance
1086          *
1087          * @param       $menuInstance   A RenderableMenu instance
1088          * @return      void
1089          */
1090         protected final function setMenuInstance (RenderableMenu $menuInstance) {
1091                 $this->menuInstance = $menuInstance;
1092         }
1093
1094         /**
1095          * Getter for the menu instance
1096          *
1097          * @return      $menuInstance   A RenderableMenu instance
1098          */
1099         protected final function getMenuInstance () {
1100                 return $this->menuInstance;
1101         }
1102
1103         /**
1104          * Setter for image instance
1105          *
1106          * @param       $imageInstance  An instance of an image
1107          * @return      void
1108          */
1109         public final function setImageInstance (BaseImage $imageInstance) {
1110                 $this->imageInstance = $imageInstance;
1111         }
1112
1113         /**
1114          * Getter for image instance
1115          *
1116          * @return      $imageInstance  An instance of an image
1117          */
1118         public final function getImageInstance () {
1119                 return $this->imageInstance;
1120         }
1121
1122         /**
1123          * Setter for stacker instance
1124          *
1125          * @param       $stackInstance  An instance of an stacker
1126          * @return      void
1127          */
1128         public final function setStackInstance (Stackable $stackInstance) {
1129                 $this->stackInstance = $stackInstance;
1130         }
1131
1132         /**
1133          * Getter for stacker instance
1134          *
1135          * @return      $stackInstance  An instance of an stacker
1136          */
1137         public final function getStackInstance () {
1138                 return $this->stackInstance;
1139         }
1140
1141         /**
1142          * Setter for compressor instance
1143          *
1144          * @param       $compressorInstance     An instance of an compressor
1145          * @return      void
1146          */
1147         public final function setCompressorInstance (Compressor $compressorInstance) {
1148                 $this->compressorInstance = $compressorInstance;
1149         }
1150
1151         /**
1152          * Getter for compressor instance
1153          *
1154          * @return      $compressorInstance     An instance of an compressor
1155          */
1156         public final function getCompressorInstance () {
1157                 return $this->compressorInstance;
1158         }
1159
1160         /**
1161          * Setter for Parseable instance
1162          *
1163          * @param       $parserInstance An instance of an Parseable
1164          * @return      void
1165          */
1166         public final function setParserInstance (Parseable $parserInstance) {
1167                 $this->parserInstance = $parserInstance;
1168         }
1169
1170         /**
1171          * Getter for Parseable instance
1172          *
1173          * @return      $parserInstance An instance of an Parseable
1174          */
1175         public final function getParserInstance () {
1176                 return $this->parserInstance;
1177         }
1178
1179         /**
1180          * Setter for HandleableProtocol instance
1181          *
1182          * @param       $protocolInstance       An instance of an HandleableProtocol
1183          * @return      void
1184          */
1185         public final function setProtocolInstance (HandleableProtocol $protocolInstance) {
1186                 $this->protocolInstance = $protocolInstance;
1187         }
1188
1189         /**
1190          * Getter for HandleableProtocol instance
1191          *
1192          * @return      $protocolInstance       An instance of an HandleableProtocol
1193          */
1194         public final function getProtocolInstance () {
1195                 return $this->protocolInstance;
1196         }
1197
1198         /**
1199          * Setter for DatabaseWrapper instance
1200          *
1201          * @param       $wrapperInstance        An instance of an DatabaseWrapper
1202          * @return      void
1203          */
1204         public final function setWrapperInstance (DatabaseWrapper $wrapperInstance) {
1205                 $this->wrapperInstance = $wrapperInstance;
1206         }
1207
1208         /**
1209          * Getter for DatabaseWrapper instance
1210          *
1211          * @return      $wrapperInstance        An instance of an DatabaseWrapper
1212          */
1213         public final function getWrapperInstance () {
1214                 return $this->wrapperInstance;
1215         }
1216
1217         /**
1218          * Setter for socket resource
1219          *
1220          * @param       $socketResource         A valid socket resource
1221          * @return      void
1222          */
1223         public final function setSocketResource ($socketResource) {
1224                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($this->__toString() . '::' . __FUNCTION__ . ': socketResource=' . $socketResource . ',previous[' . gettype($this->socketResource) . ']=' . $this->socketResource);
1225                 $this->socketResource = $socketResource;
1226         }
1227
1228         /**
1229          * Getter for socket resource
1230          *
1231          * @return      $socketResource         A valid socket resource
1232          */
1233         public final function getSocketResource () {
1234                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($this->__toString() . '::' . __FUNCTION__ . ': socketResource[' . gettype($this->socketResource) . ']=' . $this->socketResource);
1235                 return $this->socketResource;
1236         }
1237
1238         /**
1239          * Setter for regular expression
1240          *
1241          * @param       $regularExpression      A valid regular expression
1242          * @return      void
1243          */
1244         public final function setRegularExpression ($regularExpression) {
1245                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($this->__toString() . '::' . __FUNCTION__ . ': regularExpression=' . $regularExpression . ',previous[' . gettype($this->regularExpression) . ']=' . $this->regularExpression);
1246                 $this->regularExpression = $regularExpression;
1247         }
1248
1249         /**
1250          * Getter for regular expression
1251          *
1252          * @return      $regularExpression      A valid regular expression
1253          */
1254         public final function getRegularExpression () {
1255                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($this->__toString() . '::' . __FUNCTION__ . ': regularExpression[' . gettype($this->regularExpression) . ']=' . $this->regularExpression);
1256                 return $this->regularExpression;
1257         }
1258
1259         /**
1260          * Setter for helper instance
1261          *
1262          * @param       $helperInstance         An instance of a helper class
1263          * @return      void
1264          */
1265         protected final function setHelperInstance (Helper $helperInstance) {
1266                 $this->helperInstance = $helperInstance;
1267         }
1268
1269         /**
1270          * Getter for helper instance
1271          *
1272          * @return      $helperInstance         An instance of a helper class
1273          */
1274         public final function getHelperInstance () {
1275                 return $this->helperInstance;
1276         }
1277
1278         /**
1279          * Setter for a Source instance
1280          *
1281          * @param       $sourceInstance         An instance of a Source class
1282          * @return      void
1283          */
1284         protected final function setSourceInstance (Source $sourceInstance) {
1285                 $this->sourceInstance = $sourceInstance;
1286         }
1287
1288         /**
1289          * Getter for a Source instance
1290          *
1291          * @return      $sourceInstance         An instance of a Source class
1292          */
1293         protected final function getSourceInstance () {
1294                 return $this->sourceInstance;
1295         }
1296
1297         /**
1298          * Setter for a UrlSource instance
1299          *
1300          * @param       $sourceInstance         An instance of a UrlSource class
1301          * @return      void
1302          */
1303         protected final function setUrlSourceInstance (UrlSource $urlSourceInstance) {
1304                 $this->urlSourceInstance = $urlSourceInstance;
1305         }
1306
1307         /**
1308          * Getter for a UrlSource instance
1309          *
1310          * @return      $urlSourceInstance              An instance of a UrlSource class
1311          */
1312         protected final function getUrlSourceInstance () {
1313                 return $this->urlSourceInstance;
1314         }
1315
1316         /**
1317          * Getter for a InputStream instance
1318          *
1319          * @param       $inputStreamInstance    The InputStream instance
1320          */
1321         protected final function getInputStreamInstance () {
1322                 return $this->inputStreamInstance;
1323         }
1324
1325         /**
1326          * Setter for a InputStream instance
1327          *
1328          * @param       $inputStreamInstance    The InputStream instance
1329          * @return      void
1330          */
1331         protected final function setInputStreamInstance (InputStream $inputStreamInstance) {
1332                 $this->inputStreamInstance = $inputStreamInstance;
1333         }
1334
1335         /**
1336          * Getter for a OutputStream instance
1337          *
1338          * @param       $outputStreamInstance   The OutputStream instance
1339          */
1340         protected final function getOutputStreamInstance () {
1341                 return $this->outputStreamInstance;
1342         }
1343
1344         /**
1345          * Setter for a OutputStream instance
1346          *
1347          * @param       $outputStreamInstance   The OutputStream instance
1348          * @return      void
1349          */
1350         protected final function setOutputStreamInstance (OutputStream $outputStreamInstance) {
1351                 $this->outputStreamInstance = $outputStreamInstance;
1352         }
1353
1354         /**
1355          * Setter for handler instance
1356          *
1357          * @param       $handlerInstance        An instance of a Handleable class
1358          * @return      void
1359          */
1360         protected final function setHandlerInstance (Handleable $handlerInstance) {
1361                 $this->handlerInstance = $handlerInstance;
1362         }
1363
1364         /**
1365          * Getter for handler instance
1366          *
1367          * @return      $handlerInstance        A Networkable instance
1368          */
1369         protected final function getHandlerInstance () {
1370                 return $this->handlerInstance;
1371         }
1372
1373         /**
1374          * Setter for visitor instance
1375          *
1376          * @param       $visitorInstance        A Visitor instance
1377          * @return      void
1378          */
1379         protected final function setVisitorInstance (Visitor $visitorInstance) {
1380                 $this->visitorInstance = $visitorInstance;
1381         }
1382
1383         /**
1384          * Getter for visitor instance
1385          *
1386          * @return      $visitorInstance        A Visitor instance
1387          */
1388         protected final function getVisitorInstance () {
1389                 return $this->visitorInstance;
1390         }
1391
1392         /**
1393          * Setter for DHT instance
1394          *
1395          * @param       $dhtInstance    A Distributable instance
1396          * @return      void
1397          */
1398         protected final function setDhtInstance (Distributable $dhtInstance) {
1399                 $this->dhtInstance = $dhtInstance;
1400         }
1401
1402         /**
1403          * Getter for DHT instance
1404          *
1405          * @return      $dhtInstance    A Distributable instance
1406          */
1407         protected final function getDhtInstance () {
1408                 return $this->dhtInstance;
1409         }
1410
1411         /**
1412          * Setter for raw package Data
1413          *
1414          * @param       $packageData    Raw package Data
1415          * @return      void
1416          */
1417         public final function setPackageData (array $packageData) {
1418                 $this->packageData = $packageData;
1419         }
1420
1421         /**
1422          * Getter for raw package Data
1423          *
1424          * @return      $packageData    Raw package Data
1425          */
1426         public function getPackageData () {
1427                 return $this->packageData;
1428         }
1429
1430
1431         /**
1432          * Setter for Iterator instance
1433          *
1434          * @param       $iteratorInstance       An instance of an Iterator
1435          * @return      void
1436          */
1437         protected final function setIteratorInstance (Iterator $iteratorInstance) {
1438                 $this->iteratorInstance = $iteratorInstance;
1439         }
1440
1441         /**
1442          * Getter for Iterator instance
1443          *
1444          * @return      $iteratorInstance       An instance of an Iterator
1445          */
1446         public final function getIteratorInstance () {
1447                 return $this->iteratorInstance;
1448         }
1449
1450         /**
1451          * Setter for FilePointer instance
1452          *
1453          * @param       $pointerInstance        An instance of an FilePointer class
1454          * @return      void
1455          */
1456         protected final function setPointerInstance (FilePointer $pointerInstance) {
1457                 $this->pointerInstance = $pointerInstance;
1458         }
1459
1460         /**
1461          * Getter for FilePointer instance
1462          *
1463          * @return      $pointerInstance        An instance of an FilePointer class
1464          */
1465         public final function getPointerInstance () {
1466                 return $this->pointerInstance;
1467         }
1468
1469         /**
1470          * Unsets pointer instance which triggers a call of __destruct() if the
1471          * instance is still there. This is surely not fatal on already "closed"
1472          * file pointer instances.
1473          *
1474          * I don't want to mess around with above setter by giving it a default
1475          * value NULL as setter should always explicitly only set (existing) object
1476          * instances and NULL is NULL.
1477          *
1478          * @return      void
1479          */
1480         protected final function unsetPointerInstance () {
1481                 // Simply it to NULL
1482                 $this->pointerInstance = NULL;
1483         }
1484
1485         /**
1486          * Setter for Indexable instance
1487          *
1488          * @param       $indexInstance  An instance of an Indexable class
1489          * @return      void
1490          */
1491         protected final function setIndexInstance (Indexable $indexInstance) {
1492                 $this->indexInstance = $indexInstance;
1493         }
1494
1495         /**
1496          * Getter for Indexable instance
1497          *
1498          * @return      $indexInstance  An instance of an Indexable class
1499          */
1500         public final function getIndexInstance () {
1501                 return $this->indexInstance;
1502         }
1503
1504         /**
1505          * Setter for Block instance
1506          *
1507          * @param       $blockInstance  An instance of an Block class
1508          * @return      void
1509          */
1510         protected final function setBlockInstance (Block $blockInstance) {
1511                 $this->blockInstance = $blockInstance;
1512         }
1513
1514         /**
1515          * Getter for Block instance
1516          *
1517          * @return      $blockInstance  An instance of an Block class
1518          */
1519         public final function getBlockInstance () {
1520                 return $this->blockInstance;
1521         }
1522
1523         /**
1524          * Setter for Minable instance
1525          *
1526          * @param       $minableInstance        A Minable instance
1527          * @return      void
1528          */
1529         protected final function setMinableInstance (Minable $minableInstance) {
1530                 $this->minableInstance = $minableInstance;
1531         }
1532
1533         /**
1534          * Getter for minable instance
1535          *
1536          * @return      $minableInstance        A Minable instance
1537          */
1538         protected final function getMinableInstance () {
1539                 return $this->minableInstance;
1540         }
1541
1542         /**
1543          * Setter for FrameworkDirectory instance
1544          *
1545          * @param       $directoryInstance      A FrameworkDirectory instance
1546          * @return      void
1547          */
1548         protected final function setDirectoryInstance (FrameworkDirectory $directoryInstance) {
1549                 $this->directoryInstance = $directoryInstance;
1550         }
1551
1552         /**
1553          * Getter for FrameworkDirectory instance
1554          *
1555          * @return      $directoryInstance      A FrameworkDirectory instance
1556          */
1557         protected final function getDirectoryInstance () {
1558                 return $this->directoryInstance;
1559         }
1560
1561         /**
1562          * Setter for listener instance
1563          *
1564          * @param       $listenerInstance       A Listenable instance
1565          * @return      void
1566          */
1567         protected final function setListenerInstance (Listenable $listenerInstance) {
1568                 $this->listenerInstance = $listenerInstance;
1569         }
1570
1571         /**
1572          * Getter for listener instance
1573          *
1574          * @return      $listenerInstance       A Listenable instance
1575          */
1576         protected final function getListenerInstance () {
1577                 return $this->listenerInstance;
1578         }
1579
1580         /**
1581          * Getter for communicator instance
1582          *
1583          * @return      $communicatorInstance   An instance of a Communicator class
1584          */
1585         public final function getCommunicatorInstance () {
1586                 return $this->communicatorInstance;
1587         }
1588
1589         /**
1590          * Setter for communicator instance
1591          *
1592          * @param       $communicatorInstance   An instance of a Communicator class
1593          * @return      void
1594          */
1595         protected final function setCommunicatorInstance (Communicator $communicatorInstance) {
1596                 $this->communicatorInstance = $communicatorInstance;
1597         }
1598
1599         /**
1600          * Setter for state instance
1601          *
1602          * @param       $stateInstance  A Stateable instance
1603          * @return      void
1604          */
1605         public final function setStateInstance (Stateable $stateInstance) {
1606                 $this->stateInstance = $stateInstance;
1607         }
1608
1609         /**
1610          * Getter for state instance
1611          *
1612          * @return      $stateInstance  A Stateable instance
1613          */
1614         public final function getStateInstance () {
1615                 return $this->stateInstance;
1616         }
1617
1618         /**
1619          * Setter for output instance
1620          *
1621          * @param       $outputInstance The debug output instance
1622          * @return      void
1623          */
1624         public final function setOutputInstance (OutputStreamer $outputInstance) {
1625                 $this->outputInstance = $outputInstance;
1626         }
1627
1628         /**
1629          * Getter for output instance
1630          *
1631          * @return      $outputInstance The debug output instance
1632          */
1633         public final function getOutputInstance () {
1634                 return $this->outputInstance;
1635         }
1636
1637         /**
1638          * Setter for command name
1639          *
1640          * @param       $commandName    Last validated command name
1641          * @return      void
1642          */
1643         protected final function setCommandName ($commandName) {
1644                 $this->commandName = $commandName;
1645         }
1646
1647         /**
1648          * Getter for command name
1649          *
1650          * @return      $commandName    Last validated command name
1651          */
1652         protected final function getCommandName () {
1653                 return $this->commandName;
1654         }
1655
1656         /**
1657          * Setter for controller name
1658          *
1659          * @param       $controllerName Last validated controller name
1660          * @return      void
1661          */
1662         protected final function setControllerName ($controllerName) {
1663                 $this->controllerName = $controllerName;
1664         }
1665
1666         /**
1667          * Getter for controller name
1668          *
1669          * @return      $controllerName Last validated controller name
1670          */
1671         protected final function getControllerName () {
1672                 return $this->controllerName;
1673         }
1674
1675         /**
1676          * Getter for protocol name
1677          *
1678          * @return      $protocolName   Name of used protocol
1679          */
1680         public final function getProtocolName () {
1681                 return $this->protocolName;
1682         }
1683
1684         /**
1685          * Setter for protocol name
1686          *
1687          * @param       $protocolName   Name of used protocol
1688          * @return      void
1689          */
1690         protected final function setProtocolName ($protocolName) {
1691                 $this->protocolName = $protocolName;
1692         }
1693
1694         /**
1695          * Checks whether an object equals this object. You should overwrite this
1696          * method to implement own equality checks
1697          *
1698          * @param       $objectInstance         An instance of a FrameworkInterface object
1699          * @return      $equals                         Whether both objects equals
1700          */
1701         public function equals (FrameworkInterface $objectInstance) {
1702                 // Now test it
1703                 $equals = ((
1704                         $this->__toString() == $objectInstance->__toString()
1705                 ) && (
1706                         $this->hashCode() == $objectInstance->hashCode()
1707                 ));
1708
1709                 // Return the result
1710                 return $equals;
1711         }
1712
1713         /**
1714          * Generates a generic hash code of this class. You should really overwrite
1715          * this method with your own hash code generator code. But keep KISS in mind.
1716          *
1717          * @return      $hashCode       A generic hash code respresenting this whole class
1718          */
1719         public function hashCode () {
1720                 // Simple hash code
1721                 return crc32($this->__toString());
1722         }
1723
1724         /**
1725          * Formats computer generated price values into human-understandable formats
1726          * with thousand and decimal separators.
1727          *
1728          * @param       $value          The in computer format value for a price
1729          * @param       $currency       The currency symbol (use HTML-valid characters!)
1730          * @param       $decNum         Number of decimals after commata
1731          * @return      $price          The for the current language formated price string
1732          * @throws      MissingDecimalsThousandsSeparatorException      If decimals or
1733          *                                                                                              thousands separator
1734          *                                                                                              is missing
1735          */
1736         public function formatCurrency ($value, $currency = '&euro;', $decNum = 2) {
1737                 // Are all required attriutes set?
1738                 if ((!isset($this->decimals)) || (!isset($this->thousands))) {
1739                         // Throw an exception
1740                         throw new MissingDecimalsThousandsSeparatorException($this, self::EXCEPTION_ATTRIBUTES_ARE_MISSING);
1741                 } // END - if
1742
1743                 // Cast the number
1744                 $value = (float) $value;
1745
1746                 // Reformat the US number
1747                 $price = number_format($value, $decNum, $this->decimals, $this->thousands) . $currency;
1748
1749                 // Return as string...
1750                 return $price;
1751         }
1752
1753         /**
1754          * Appends a trailing slash to a string
1755          *
1756          * @param       $str    A string (maybe) without trailing slash
1757          * @return      $str    A string with an auto-appended trailing slash
1758          */
1759         public final function addMissingTrailingSlash ($str) {
1760                 // Is there a trailing slash?
1761                 if (substr($str, -1, 1) != '/') {
1762                         $str .= '/';
1763                 } // END - if
1764
1765                 // Return string with trailing slash
1766                 return $str;
1767         }
1768
1769         /**
1770          * Prepare the template engine (HtmlTemplateEngine by default) for a given
1771          * application helper instance (ApplicationHelper by default).
1772          *
1773          * @param               $applicationInstance    An application helper instance or
1774          *                                                                              null if we shall use the default
1775          * @return              $templateInstance               The template engine instance
1776          * @throws              NullPointerException    If the discovered application
1777          *                                                                              instance is still null
1778          */
1779         protected function prepareTemplateInstance (ManageableApplication $applicationInstance = NULL) {
1780                 // Is the application instance set?
1781                 if (is_null($applicationInstance)) {
1782                         // Get the current instance
1783                         $applicationInstance = $this->getApplicationInstance();
1784
1785                         // Still null?
1786                         if (is_null($applicationInstance)) {
1787                                 // Thrown an exception
1788                                 throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
1789                         } // END - if
1790                 } // END - if
1791
1792                 // Initialize the template engine
1793                 $templateInstance = ObjectFactory::createObjectByConfiguredName('html_template_class');
1794
1795                 // Return the prepared instance
1796                 return $templateInstance;
1797         }
1798
1799         /**
1800          * Debugs this instance by putting out it's full content
1801          *
1802          * @param       $message        Optional message to show in debug output
1803          * @return      void
1804          */
1805         public final function debugInstance ($message = '') {
1806                 // Restore the error handler to avoid trouble with missing array elements or undeclared variables
1807                 restore_error_handler();
1808
1809                 // Init content
1810                 $content = '';
1811
1812                 // Is a message set?
1813                 if (!empty($message)) {
1814                         // Construct message
1815                         $content = sprintf('<div class="debug_message">Message: %s</div>' . PHP_EOL, $message);
1816                 } // END - if
1817
1818                 // Generate the output
1819                 $content .= sprintf('<pre>%s</pre>',
1820                         trim(
1821                                 htmlentities(
1822                                         print_r($this, TRUE)
1823                                 )
1824                         )
1825                 );
1826
1827                 // Output it
1828                 ApplicationEntryPoint::app_exit(sprintf('<div class="debug_header">%s debug output:</div><div class="debug_content">%s</div>Loaded includes: <div class="debug_include_list">%s</div>',
1829                         $this->__toString(),
1830                         $content,
1831                         ClassLoader::getSelfInstance()->getPrintableIncludeList()
1832                 ));
1833         }
1834
1835         /**
1836          * Replaces control characters with printable output
1837          *
1838          * @param       $str    String with control characters
1839          * @return      $str    Replaced string
1840          */
1841         protected function replaceControlCharacters ($str) {
1842                 // Replace them
1843                 $str = str_replace(
1844                         chr(13), '[r]', str_replace(
1845                         chr(10), '[n]', str_replace(
1846                         chr(9) , '[t]',
1847                         $str
1848                 )));
1849
1850                 // Return it
1851                 return $str;
1852         }
1853
1854         /**
1855          * Output a partial stub message for the caller method
1856          *
1857          * @param       $message        An optional message to display
1858          * @return      void
1859          */
1860         protected function partialStub ($message = '') {
1861                 // Get the backtrace
1862                 $backtrace = debug_backtrace();
1863
1864                 // Generate the class::method string
1865                 $methodName = 'UnknownClass-&gt;unknownMethod';
1866                 if ((isset($backtrace[1]['class'])) && (isset($backtrace[1]['function']))) {
1867                         $methodName = $backtrace[1]['class'] . '-&gt;' . $backtrace[1]['function'];
1868                 } // END - if
1869
1870                 // Construct the full message
1871                 $stubMessage = sprintf('[%s:] Partial stub!',
1872                         $methodName
1873                 );
1874
1875                 // Is the extra message given?
1876                 if (!empty($message)) {
1877                         // Then add it as well
1878                         $stubMessage .= ' Message: ' . $message;
1879                 } // END - if
1880
1881                 // Debug instance is there?
1882                 if (!is_null($this->getDebugInstance())) {
1883                         // Output stub message
1884                         self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($stubMessage);
1885                 } else {
1886                         // Trigger an error
1887                         trigger_error($stubMessage);
1888                         exit;
1889                 }
1890         }
1891
1892         /**
1893          * Outputs a debug backtrace and stops further script execution
1894          *
1895          * @param       $message        An optional message to output
1896          * @param       $doExit         Whether exit the program (TRUE is default)
1897          * @return      void
1898          */
1899         public function debugBackTrace ($message = '', $doExit = TRUE) {
1900                 // Sorry, there is no other way getting this nice backtrace
1901                 if (!empty($message)) {
1902                         // Output message
1903                         printf('Message: %s<br />' . PHP_EOL, $message);
1904                 } // END - if
1905
1906                 print('<pre>');
1907                 debug_print_backtrace();
1908                 print('</pre>');
1909
1910                 // Exit program?
1911                 if ($doExit === TRUE) {
1912                         exit();
1913                 } // END - if
1914         }
1915
1916         /**
1917          * Creates an instance of a debugger instance
1918          *
1919          * @param       $className              Name of the class (currently unsupported)
1920          * @param       $lineNumber             Line number where the call was made
1921          * @return      $debugInstance  An instance of a debugger class
1922          * @deprecated  Not fully, as the new Logger facilities are not finished yet.
1923          */
1924         public final static function createDebugInstance ($className, $lineNumber = NULL) {
1925                 // Is the instance set?
1926                 if (!Registry::getRegistry()->instanceExists('debug')) {
1927                         // Init debug instance
1928                         $debugInstance = NULL;
1929
1930                         // Try it
1931                         try {
1932                                 // Get a debugger instance
1933                                 $debugInstance = DebugMiddleware::createDebugMiddleware(FrameworkConfiguration::getSelfInstance()->getConfigEntry('debug_' . self::getResponseTypeFromSystem() . '_class'), $className);
1934                         } catch (NullPointerException $e) {
1935                                 // Didn't work, no instance there
1936                                 exit(sprintf('Cannot create debugInstance! Exception=%s,message=%s,className=%s,lineNumber=%d' . PHP_EOL, $e->__toString(), $e->getMessage(), $className, $lineNumber));
1937                         }
1938
1939                         // Empty string should be ignored and used for testing the middleware
1940                         DebugMiddleware::getSelfInstance()->output('');
1941
1942                         // Set it in its own class. This will set it in the registry
1943                         $debugInstance->setDebugInstance($debugInstance);
1944                 } else {
1945                         // Get instance from registry
1946                         $debugInstance = Registry::getRegistry()->getDebugInstance();
1947                 }
1948
1949                 // Return it
1950                 return $debugInstance;
1951         }
1952
1953         /**
1954          * Simple output of a message with line-break
1955          *
1956          * @param       $message        Message to output
1957          * @return      void
1958          */
1959         public function outputLine ($message) {
1960                 // Simply output it
1961                 print($message . PHP_EOL);
1962         }
1963
1964         /**
1965          * Outputs a debug message whether to debug instance (should be set!) or
1966          * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
1967          * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
1968          *
1969          * @param       $message        Message we shall send out...
1970          * @param       $doPrint        Whether print or die here (default: print)
1971          * @paran       $stripTags      Whether to strip tags (default: FALSE)
1972          * @return      void
1973          */
1974         public function debugOutput ($message, $doPrint = TRUE, $stripTags = FALSE) {
1975                 // Set debug instance to NULL
1976                 $debugInstance = NULL;
1977
1978                 // Try it:
1979                 try {
1980                         // Get debug instance
1981                         $debugInstance = $this->getDebugInstance();
1982                 } catch (NullPointerException $e) {
1983                         // The debug instance is not set (yet)
1984                 }
1985
1986                 // Is the debug instance there?
1987                 if (is_object($debugInstance)) {
1988                         // Use debug output handler
1989                         $debugInstance->output($message, $stripTags);
1990
1991                         if ($doPrint === FALSE) {
1992                                 // Die here if not printed
1993                                 exit();
1994                         } // END - if
1995                 } else {
1996                         // Are debug times enabled?
1997                         if ($this->getConfigInstance()->getConfigEntry('debug_' . self::getResponseTypeFromSystem() . '_output_timings') == 'Y') {
1998                                 // Prepent it
1999                                 $message = $this->getPrintableExecutionTime() . $message;
2000                         } // END - if
2001
2002                         // Put directly out
2003                         if ($doPrint === TRUE) {
2004                                 // Print message
2005                                 $this->outputLine($message);
2006                         } else {
2007                                 // Die here
2008                                 exit($message);
2009                         }
2010                 }
2011         }
2012
2013         /**
2014          * Converts e.g. a command from URL to a valid class by keeping out bad characters
2015          *
2016          * @param       $str            The string, what ever it is needs to be converted
2017          * @return      $className      Generated class name
2018          */
2019         public static final function convertToClassName ($str) {
2020                 // Init class name
2021                 $className = '';
2022
2023                 // Convert all dashes in underscores
2024                 $str = self::convertDashesToUnderscores($str);
2025
2026                 // Now use that underscores to get classname parts for hungarian style
2027                 foreach (explode('_', $str) as $strPart) {
2028                         // Make the class name part lower case and first upper case
2029                         $className .= ucfirst(strtolower($strPart));
2030                 } // END - foreach
2031
2032                 // Return class name
2033                 return $className;
2034         }
2035
2036         /**
2037          * Converts dashes to underscores, e.g. useable for configuration entries
2038          *
2039          * @param       $str    The string with maybe dashes inside
2040          * @return      $str    The converted string with no dashed, but underscores
2041          */
2042         public static final function convertDashesToUnderscores ($str) {
2043                 // Convert them all
2044                 $str = str_replace('-', '_', $str);
2045
2046                 // Return converted string
2047                 return $str;
2048         }
2049
2050         /**
2051          * Marks up the code by adding e.g. line numbers
2052          *
2053          * @param       $phpCode                Unmarked PHP code
2054          * @return      $markedCode             Marked PHP code
2055          */
2056         public function markupCode ($phpCode) {
2057                 // Init marked code
2058                 $markedCode = '';
2059
2060                 // Get last error
2061                 $errorArray = error_get_last();
2062
2063                 // Init the code with error message
2064                 if (is_array($errorArray)) {
2065                         // Get error infos
2066                         $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>',
2067                                 basename($errorArray['file']),
2068                                 $errorArray['line'],
2069                                 $errorArray['message'],
2070                                 $errorArray['type']
2071                         );
2072                 } // END - if
2073
2074                 // Add line number to the code
2075                 foreach (explode(chr(10), $phpCode) as $lineNo => $code) {
2076                         // Add line numbers
2077                         $markedCode .= sprintf('<span id="code_line">%s</span>: %s' . PHP_EOL,
2078                                 ($lineNo + 1),
2079                                 htmlentities($code, ENT_QUOTES)
2080                         );
2081                 } // END - foreach
2082
2083                 // Return the code
2084                 return $markedCode;
2085         }
2086
2087         /**
2088          * Filter a given GMT timestamp (non Uni* stamp!) to make it look more
2089          * beatiful for web-based front-ends. If null is given a message id
2090          * null_timestamp will be resolved and returned.
2091          *
2092          * @param       $timestamp      Timestamp to prepare (filter) for display
2093          * @return      $readable       A readable timestamp
2094          */
2095         public function doFilterFormatTimestamp ($timestamp) {
2096                 // Default value to return
2097                 $readable = '???';
2098
2099                 // Is the timestamp null?
2100                 if (is_null($timestamp)) {
2101                         // Get a message string
2102                         $readable = $this->getLanguageInstance()->getMessage('null_timestamp');
2103                 } else {
2104                         switch ($this->getLanguageInstance()->getLanguageCode()) {
2105                                 case 'de': // German format is a bit different to default
2106                                         // Split the GMT stamp up
2107                                         $dateTime  = explode(' ', $timestamp  );
2108                                         $dateArray = explode('-', $dateTime[0]);
2109                                         $timeArray = explode(':', $dateTime[1]);
2110
2111                                         // Construct the timestamp
2112                                         $readable = sprintf($this->getConfigInstance()->getConfigEntry('german_date_time'),
2113                                                 $dateArray[0],
2114                                                 $dateArray[1],
2115                                                 $dateArray[2],
2116                                                 $timeArray[0],
2117                                                 $timeArray[1],
2118                                                 $timeArray[2]
2119                                         );
2120                                         break;
2121
2122                                 default: // Default is pass-through
2123                                         $readable = $timestamp;
2124                                         break;
2125                         } // END - switch
2126                 }
2127
2128                 // Return the stamp
2129                 return $readable;
2130         }
2131
2132         /**
2133          * Filter a given number into a localized number
2134          *
2135          * @param       $value          The raw value from e.g. database
2136          * @return      $localized      Localized value
2137          */
2138         public function doFilterFormatNumber ($value) {
2139                 // Generate it from config and localize dependencies
2140                 switch ($this->getLanguageInstance()->getLanguageCode()) {
2141                         case 'de': // German format is a bit different to default
2142                                 $localized = number_format($value, $this->getConfigInstance()->getConfigEntry('decimals'), ',', '.');
2143                                 break;
2144
2145                         default: // US, etc.
2146                                 $localized = number_format($value, $this->getConfigInstance()->getConfigEntry('decimals'), '.', ',');
2147                                 break;
2148                 } // END - switch
2149
2150                 // Return it
2151                 return $localized;
2152         }
2153
2154         /**
2155          * "Getter" for databse entry
2156          *
2157          * @return      $entry  An array with database entries
2158          * @throws      NullPointerException    If the database result is not found
2159          * @throws      InvalidDatabaseResultException  If the database result is invalid
2160          */
2161         protected final function getDatabaseEntry () {
2162                 // Is there an instance?
2163                 if (!$this->getResultInstance() instanceof SearchableResult) {
2164                         // Throw an exception here
2165                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
2166                 } // END - if
2167
2168                 // Rewind it
2169                 $this->getResultInstance()->rewind();
2170
2171                 // Do we have an entry?
2172                 if ($this->getResultInstance()->valid() === FALSE) {
2173                         // @TODO Move the constant to e.g. BaseDatabaseResult when there is a non-cached database result available
2174                         throw new InvalidDatabaseResultException(array($this, $this->getResultInstance()), CachedDatabaseResult::EXCEPTION_INVALID_DATABASE_RESULT);
2175                 } // END - if
2176
2177                 // Get next entry
2178                 $this->getResultInstance()->next();
2179
2180                 // Fetch it
2181                 $entry = $this->getResultInstance()->current();
2182
2183                 // And return it
2184                 return $entry;
2185         }
2186
2187         /**
2188          * Getter for field name
2189          *
2190          * @param       $fieldName              Field name which we shall get
2191          * @return      $fieldValue             Field value from the user
2192          * @throws      NullPointerException    If the result instance is null
2193          */
2194         public final function getField ($fieldName) {
2195                 // Default field value
2196                 $fieldValue = NULL;
2197
2198                 // Get result instance
2199                 $resultInstance = $this->getResultInstance();
2200
2201                 // Is this instance null?
2202                 if (is_null($resultInstance)) {
2203                         // Then the user instance is no longer valid (expired cookies?)
2204                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
2205                 } // END - if
2206
2207                 // Get current array
2208                 $fieldArray = $resultInstance->current();
2209                 //* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($fieldName.':<pre>'.print_r($fieldArray, TRUE).'</pre>');
2210
2211                 // Convert dashes to underscore
2212                 $fieldName2 = self::convertDashesToUnderscores($fieldName);
2213
2214                 // Does the field exist?
2215                 if ($this->isFieldSet($fieldName)) {
2216                         // Get it
2217                         $fieldValue = $fieldArray[$fieldName2];
2218                 } elseif (defined('DEVELOPER')) {
2219                         // Missing field entry, may require debugging
2220                         self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']:fieldArray<pre>=' . print_r($fieldArray, TRUE) . '</pre>,fieldName=' . $fieldName . ' not found!');
2221                 } else {
2222                         // Missing field entry, may require debugging
2223                         self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']:fieldName=' . $fieldName . ' not found!');
2224                 }
2225
2226                 // Return it
2227                 return $fieldValue;
2228         }
2229
2230         /**
2231          * Checks if given field is set
2232          *
2233          * @param       $fieldName      Field name to check
2234          * @return      $isSet          Whether the given field name is set
2235          * @throws      NullPointerException    If the result instance is null
2236          */
2237         public function isFieldSet ($fieldName) {
2238                 // Get result instance
2239                 $resultInstance = $this->getResultInstance();
2240
2241                 // Is this instance null?
2242                 if (is_null($resultInstance)) {
2243                         // Then the user instance is no longer valid (expired cookies?)
2244                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
2245                 } // END - if
2246
2247                 // Get current array
2248                 $fieldArray = $resultInstance->current();
2249                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . $this->__toString() . ':' . __LINE__ . '] fieldName=' . $fieldName . ',fieldArray=<pre>'.print_r($fieldArray, TRUE).'</pre>');
2250
2251                 // Convert dashes to underscore
2252                 $fieldName = self::convertDashesToUnderscores($fieldName);
2253
2254                 // Determine it
2255                 $isSet = isset($fieldArray[$fieldName]);
2256
2257                 // Return result
2258                 return $isSet;
2259         }
2260
2261         /**
2262          * Flushs all pending updates to the database layer
2263          *
2264          * @return      void
2265          */
2266         public function flushPendingUpdates () {
2267                 // Get result instance
2268                 $resultInstance = $this->getResultInstance();
2269
2270                 // Do we have data to update?
2271                 if ((is_object($resultInstance)) && ($resultInstance->ifDataNeedsFlush())) {
2272                         // Get wrapper class name config entry
2273                         $configEntry = $resultInstance->getUpdateInstance()->getWrapperConfigEntry();
2274
2275                         // Create object instance
2276                         $wrapperInstance = DatabaseWrapperFactory::createWrapperByConfiguredName($configEntry);
2277
2278                         // Yes, then send the whole result to the database layer
2279                         $wrapperInstance->doUpdateByResult($this->getResultInstance());
2280                 } // END - if
2281         }
2282
2283         /**
2284          * Outputs a deprecation warning to the developer.
2285          *
2286          * @param       $message        The message we shall output to the developer
2287          * @return      void
2288          * @todo        Write a logging mechanism for productive mode
2289          */
2290         public function deprecationWarning ($message) {
2291                 // Is developer mode active?
2292                 if (defined('DEVELOPER')) {
2293                         // Debug instance is there?
2294                         if (!is_null($this->getDebugInstance())) {
2295                                 // Output stub message
2296                                 self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($message);
2297                         } else {
2298                                 // Trigger an error
2299                                 trigger_error($message . "<br />\n");
2300                                 exit;
2301                         }
2302                 } else {
2303                         // @TODO Finish this part!
2304                         $this->partialStub('Developer mode inactive. Message:' . $message);
2305                 }
2306         }
2307
2308         /**
2309          * Checks whether the given PHP extension is loaded
2310          *
2311          * @param       $phpExtension   The PHP extension we shall check
2312          * @return      $isLoaded       Whether the PHP extension is loaded
2313          */
2314         public final function isPhpExtensionLoaded ($phpExtension) {
2315                 // Is it loaded?
2316                 $isLoaded = in_array($phpExtension, get_loaded_extensions());
2317
2318                 // Return result
2319                 return $isLoaded;
2320         }
2321
2322         /**
2323          * "Getter" as a time() replacement but with milliseconds. You should use this
2324          * method instead of the encapsulated getimeofday() function.
2325          *
2326          * @return      $milliTime      Timestamp with milliseconds
2327          */
2328         public function getMilliTime () {
2329                 // Get the time of day as float
2330                 $milliTime = gettimeofday(TRUE);
2331
2332                 // Return it
2333                 return $milliTime;
2334         }
2335
2336         /**
2337          * Idles (sleeps) for given milliseconds
2338          *
2339          * @return      $hasSlept       Whether it goes fine
2340          */
2341         public function idle ($milliSeconds) {
2342                 // Sleep is fine by default
2343                 $hasSlept = TRUE;
2344
2345                 // Idle so long with found function
2346                 if (function_exists('time_sleep_until')) {
2347                         // Get current time and add idle time
2348                         $sleepUntil = $this->getMilliTime() + abs($milliSeconds) / 1000;
2349
2350                         // New PHP 5.1.0 function found, ignore errors
2351                         $hasSlept = @time_sleep_until($sleepUntil);
2352                 } else {
2353                         /*
2354                          * My Sun station doesn't have that function even with latest PHP
2355                          * package. :(
2356                          */
2357                         usleep($milliSeconds * 1000);
2358                 }
2359
2360                 // Return result
2361                 return $hasSlept;
2362         }
2363         /**
2364          * Converts a hexadecimal string, even with negative sign as first string to
2365          * a decimal number using BC functions.
2366          *
2367          * This work is based on comment #86673 on php.net documentation page at:
2368          * <http://de.php.net/manual/en/function.dechex.php#86673>
2369          *
2370          * @param       $hex    Hexadecimal string
2371          * @return      $dec    Decimal number
2372          */
2373         protected function hex2dec ($hex) {
2374                 // Convert to all lower-case
2375                 $hex = strtolower($hex);
2376
2377                 // Detect sign (negative/positive numbers)
2378                 $sign = '';
2379                 if (substr($hex, 0, 1) == '-') {
2380                         $sign = '-';
2381                         $hex = substr($hex, 1);
2382                 } // END - if
2383
2384                 // Decode the hexadecimal string into a decimal number
2385                 $dec = 0;
2386                 for ($i = strlen($hex) - 1, $e = 1; $i >= 0; $i--, $e = bcmul($e, 16)) {
2387                         $factor = self::$hexdec[substr($hex, $i, 1)];
2388                         $dec = bcadd($dec, bcmul($factor, $e));
2389                 } // END - for
2390
2391                 // Return the decimal number
2392                 return $sign . $dec;
2393         }
2394
2395         /**
2396          * Converts even very large decimal numbers, also signed, to a hexadecimal
2397          * string.
2398          *
2399          * This work is based on comment #97756 on php.net documentation page at:
2400          * <http://de.php.net/manual/en/function.hexdec.php#97756>
2401          *
2402          * @param       $dec            Decimal number, even with negative sign
2403          * @param       $maxLength      Optional maximum length of the string
2404          * @return      $hex    Hexadecimal string
2405          */
2406         protected function dec2hex ($dec, $maxLength = 0) {
2407                 // maxLength can be zero or devideable by 2
2408                 assert(($maxLength == 0) || (($maxLength % 2) == 0));
2409
2410                 // Detect sign (negative/positive numbers)
2411                 $sign = '';
2412                 if ($dec < 0) {
2413                         $sign = '-';
2414                         $dec = abs($dec);
2415                 } // END - if
2416
2417                 // Encode the decimal number into a hexadecimal string
2418                 $hex = '';
2419                 do {
2420                         $hex = self::$dechex[($dec % (2 ^ 4))] . $hex;
2421                         $dec /= (2 ^ 4);
2422                 } while ($dec >= 1);
2423
2424                 /*
2425                  * Leading zeros are required for hex-decimal "numbers". In some
2426                  * situations more leading zeros are wanted, so check for both
2427                  * conditions.
2428                  */
2429                 if ($maxLength > 0) {
2430                         // Prepend more zeros
2431                         $hex = str_pad($hex, $maxLength, '0', STR_PAD_LEFT);
2432                 } elseif ((strlen($hex) % 2) != 0) {
2433                         // Only make string's length dividable by 2
2434                         $hex = '0' . $hex;
2435                 }
2436
2437                 // Return the hexadecimal string
2438                 return $sign . $hex;
2439         }
2440
2441         /**
2442          * Converts a ASCII string (0 to 255) into a decimal number.
2443          *
2444          * @param       $asc    The ASCII string to be converted
2445          * @return      $dec    Decimal number
2446          */
2447         protected function asc2dec ($asc) {
2448                 // Convert it into a hexadecimal number
2449                 $hex = bin2hex($asc);
2450
2451                 // And back into a decimal number
2452                 $dec = $this->hex2dec($hex);
2453
2454                 // Return it
2455                 return $dec;
2456         }
2457
2458         /**
2459          * Converts a decimal number into an ASCII string.
2460          *
2461          * @param       $dec            Decimal number
2462          * @return      $asc    An ASCII string
2463          */
2464         protected function dec2asc ($dec) {
2465                 // First convert the number into a hexadecimal string
2466                 $hex = $this->dec2hex($dec);
2467
2468                 // Then convert it into the ASCII string
2469                 $asc = $this->hex2asc($hex);
2470
2471                 // Return it
2472                 return $asc;
2473         }
2474
2475         /**
2476          * Converts a hexadecimal number into an ASCII string. Negative numbers
2477          * are not allowed.
2478          *
2479          * @param       $hex    Hexadecimal string
2480          * @return      $asc    An ASCII string
2481          */
2482         protected function hex2asc ($hex) {
2483                 // Check for length, it must be devideable by 2
2484                 //* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('hex='.$hex);
2485                 assert((strlen($hex) % 2) == 0);
2486
2487                 // Walk the string
2488                 $asc = '';
2489                 for ($idx = 0; $idx < strlen($hex); $idx+=2) {
2490                         // Get the decimal number of the chunk
2491                         $part = hexdec(substr($hex, $idx, 2));
2492
2493                         // Add it to the final string
2494                         $asc .= chr($part);
2495                 } // END - for
2496
2497                 // Return the final string
2498                 return $asc;
2499         }
2500
2501         /**
2502          * Checks whether the given encoded data was encoded with Base64
2503          *
2504          * @param       $encodedData    Encoded data we shall check
2505          * @return      $isBase64               Whether the encoded data is Base64
2506          */
2507         protected function isBase64Encoded ($encodedData) {
2508                 // Determine it
2509                 $isBase64 = (@base64_decode($encodedData, TRUE) !== FALSE);
2510
2511                 // Return it
2512                 return $isBase64;
2513         }
2514
2515         /**
2516          * "Getter" to get response/request type from analysis of the system.
2517          *
2518          * @return      $responseType   Analyzed response type
2519          */
2520         protected static function getResponseTypeFromSystem () {
2521                 // Default is console
2522                 $responseType = 'console';
2523
2524                 // Is 'HTTP_HOST' set?
2525                 if (isset($_SERVER['HTTP_HOST'])) {
2526                         /*
2527                          * Then it is a HTML response/request as RSS and so on may be
2528                          * transfered over HTTP as well.
2529                          */
2530                         $responseType = 'html';
2531                 } // END - if
2532
2533                 // Return it
2534                 return $responseType;
2535         }
2536
2537         /**
2538          * Gets a cache key from Criteria instance
2539          *
2540          * @param       $criteriaInstance       An instance of a Criteria class
2541          * @param       $onlyKeys                       Only use these keys for a cache key
2542          * @return      $cacheKey                       A cache key suitable for lookup/storage purposes
2543          */
2544         protected function getCacheKeyByCriteria (Criteria $criteriaInstance, array $onlyKeys = array()) {
2545                 // Generate it
2546                 $cacheKey = sprintf('%s@%s',
2547                         $this->__toString(),
2548                         $criteriaInstance->getCacheKey($onlyKeys)
2549                 );
2550
2551                 // And return it
2552                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($this->__toString() . ': cacheKey=' . $cacheKey);
2553                 return $cacheKey;
2554         }
2555
2556         /**
2557          * Getter for startup time in miliseconds
2558          *
2559          * @return      $startupTime    Startup time in miliseconds
2560          */
2561         protected function getStartupTime () {
2562                 return self::$startupTime;
2563         }
2564
2565         /**
2566          * "Getter" for a printable currently execution time in nice braces
2567          *
2568          * @return      $executionTime  Current execution time in nice braces
2569          */
2570         protected function getPrintableExecutionTime () {
2571                 // Caculate the execution time
2572                 $executionTime = microtime(TRUE) - $this->getStartupTime();
2573
2574                 // Pack it in nice braces
2575                 $executionTime = sprintf('[ %01.5f ] ', $executionTime);
2576
2577                 // And return it
2578                 return $executionTime;
2579         }
2580
2581         /**
2582          * Hashes a given string with a simple but stronger hash function (no salt)
2583          * and hex-encode it.
2584          *
2585          * @param       $str    The string to be hashed
2586          * @return      $hash   The hash from string $str
2587          */
2588         public static final function hash ($str) {
2589                 // Hash given string with (better secure) hasher
2590                 $hash = bin2hex(mhash(MHASH_SHA256, $str));
2591
2592                 // Return it
2593                 return $hash;
2594         }
2595
2596         /**
2597          * "Getter" for length of hash() output. This will be "cached" to speed up
2598          * things.
2599          *
2600          * @return      $length         Length of hash() output
2601          */
2602         public static final function getHashLength () {
2603                 // Is it cashed?
2604                 if (is_null(self::$hashLength)) {
2605                         // No, then hash a string and save its length.
2606                         self::$hashLength = strlen(self::hash('abc123'));
2607                 } // END - if
2608
2609                 // Return it
2610                 return self::$hashLength;
2611         }
2612
2613         /**
2614          * Checks whether the given number is really a number (only chars 0-9).
2615          *
2616          * @param       $num            A string consisting only chars between 0 and 9
2617          * @param       $castValue      Whether to cast the value to double. Do only use this to secure numbers from Requestable classes.
2618          * @param       $assertMismatch         Whether to assert mismatches
2619          * @return      $ret            The (hopefully) secured numbered value
2620          */
2621         public function bigintval ($num, $castValue = TRUE, $assertMismatch = FALSE) {
2622                 // Filter all numbers out
2623                 $ret = preg_replace('/[^0123456789]/', '', $num);
2624
2625                 // Shall we cast?
2626                 if ($castValue === TRUE) {
2627                         // Cast to biggest numeric type
2628                         $ret = (double) $ret;
2629                 } // END - if
2630
2631                 // Assert only if requested
2632                 if ($assertMismatch === TRUE) {
2633                         // Has the whole value changed?
2634                         assert(('' . $ret . '' != '' . $num . '') && (!is_null($num)));
2635                 } // END - if
2636
2637                 // Return result
2638                 return $ret;
2639         }
2640
2641         /**
2642          * Checks whether the given hexadecimal number is really a hex-number (only chars 0-9,a-f).
2643          *
2644          * @param       $num    A string consisting only chars between 0 and 9
2645          * @param       $assertMismatch         Whether to assert mismatches
2646          * @return      $ret    The (hopefully) secured hext-numbered value
2647          */
2648         public function hexval ($num, $assertMismatch = FALSE) {
2649                 // Filter all numbers out
2650                 $ret = preg_replace('/[^0123456789abcdefABCDEF]/', '', $num);
2651
2652                 // Assert only if requested
2653                 if ($assertMismatch === TRUE) {
2654                         // Has the whole value changed?
2655                         assert(('' . $ret . '' != '' . $num . '') && (!is_null($num)));
2656                 } // END - if
2657
2658                 // Return result
2659                 return $ret;
2660         }
2661
2662         /**
2663          * Checks whether start/end marker are set
2664          *
2665          * @param       $data   Data to be checked
2666          * @return      $isset  Whether start/end marker are set
2667          */
2668         public final function ifStartEndMarkersSet ($data) {
2669                 // Determine it
2670                 $isset = ((substr($data, 0, strlen(BaseRawDataHandler::STREAM_START_MARKER)) == BaseRawDataHandler::STREAM_START_MARKER) && (substr($data, -1 * strlen(BaseRawDataHandler::STREAM_END_MARKER), strlen(BaseRawDataHandler::STREAM_END_MARKER)) == BaseRawDataHandler::STREAM_END_MARKER));
2671
2672                 // ... and return it
2673                 return $isset;
2674         }
2675
2676         /**
2677          * Determines if an element is set in the generic array
2678          *
2679          * @param       $keyGroup       Main group for the key
2680          * @param       $subGroup       Sub group for the key
2681          * @param       $key            Key to check
2682          * @param       $element        Element to check
2683          * @return      $isset          Whether the given key is set
2684          */
2685         protected final function isGenericArrayElementSet ($keyGroup, $subGroup, $key, $element) {
2686                 // Debug message
2687                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element);
2688
2689                 // Is it there?
2690                 $isset = isset($this->genericArray[$keyGroup][$subGroup][$key][$element]);
2691
2692                 // Return it
2693                 return $isset;
2694         }
2695         /**
2696          * Determines if a key is set in the generic array
2697          *
2698          * @param       $keyGroup       Main group for the key
2699          * @param       $subGroup       Sub group for the key
2700          * @param       $key            Key to check
2701          * @return      $isset          Whether the given key is set
2702          */
2703         protected final function isGenericArrayKeySet ($keyGroup, $subGroup, $key) {
2704                 // Debug message
2705                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
2706
2707                 // Is it there?
2708                 $isset = isset($this->genericArray[$keyGroup][$subGroup][$key]);
2709
2710                 // Return it
2711                 return $isset;
2712         }
2713
2714
2715         /**
2716          * Determines if a group is set in the generic array
2717          *
2718          * @param       $keyGroup       Main group
2719          * @param       $subGroup       Sub group
2720          * @return      $isset          Whether the given group is set
2721          */
2722         protected final function isGenericArrayGroupSet ($keyGroup, $subGroup) {
2723                 // Debug message
2724                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup);
2725
2726                 // Is it there?
2727                 $isset = isset($this->genericArray[$keyGroup][$subGroup]);
2728
2729                 // Return it
2730                 return $isset;
2731         }
2732
2733         /**
2734          * Getter for sub key group
2735          *
2736          * @param       $keyGroup       Main key group
2737          * @param       $subGroup       Sub key group
2738          * @return      $array          An array with all array elements
2739          */
2740         protected final function getGenericSubArray ($keyGroup, $subGroup) {
2741                 // Is it there?
2742                 if (!$this->isGenericArrayGroupSet($keyGroup, $subGroup)) {
2743                         // No, then abort here
2744                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' not found.');
2745                         exit;
2746                 } // END - if
2747
2748                 // Debug message
2749                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',value=' . print_r($this->genericArray[$keyGroup][$subGroup], TRUE));
2750
2751                 // Return it
2752                 return $this->genericArray[$keyGroup][$subGroup];
2753         }
2754
2755         /**
2756          * Unsets a given key in generic array
2757          *
2758          * @param       $keyGroup       Main group for the key
2759          * @param       $subGroup       Sub group for the key
2760          * @param       $key            Key to unset
2761          * @return      void
2762          */
2763         protected final function unsetGenericArrayKey ($keyGroup, $subGroup, $key) {
2764                 // Debug message
2765                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
2766
2767                 // Remove it
2768                 unset($this->genericArray[$keyGroup][$subGroup][$key]);
2769         }
2770
2771         /**
2772          * Unsets a given element in generic array
2773          *
2774          * @param       $keyGroup       Main group for the key
2775          * @param       $subGroup       Sub group for the key
2776          * @param       $key            Key to unset
2777          * @param       $element        Element to unset
2778          * @return      void
2779          */
2780         protected final function unsetGenericArrayElement ($keyGroup, $subGroup, $key, $element) {
2781                 // Debug message
2782                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element);
2783
2784                 // Remove it
2785                 unset($this->genericArray[$keyGroup][$subGroup][$key][$element]);
2786         }
2787
2788         /**
2789          * Append a string to a given generic array key
2790          *
2791          * @param       $keyGroup       Main group for the key
2792          * @param       $subGroup       Sub group for the key
2793          * @param       $key            Key to unset
2794          * @param       $value          Value to add/append
2795          * @return      void
2796          */
2797         protected final function appendStringToGenericArrayKey ($keyGroup, $subGroup, $key, $value, $appendGlue = '') {
2798                 // Debug message
2799                 //* 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);
2800
2801                 // Is it already there?
2802                 if ($this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
2803                         // Append it
2804                         $this->genericArray[$keyGroup][$subGroup][$key] .= $appendGlue . (string) $value;
2805                 } else {
2806                         // Add it
2807                         $this->genericArray[$keyGroup][$subGroup][$key] = (string) $value;
2808                 }
2809         }
2810
2811         /**
2812          * Append a string to a given generic array element
2813          *
2814          * @param       $keyGroup       Main group for the key
2815          * @param       $subGroup       Sub group for the key
2816          * @param       $key            Key to unset
2817          * @param       $element        Element to check
2818          * @param       $value          Value to add/append
2819          * @return      void
2820          */
2821         protected final function appendStringToGenericArrayElement ($keyGroup, $subGroup, $key, $element, $value, $appendGlue = '') {
2822                 // Debug message
2823                 //* 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);
2824
2825                 // Is it already there?
2826                 if ($this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
2827                         // Append it
2828                         $this->genericArray[$keyGroup][$subGroup][$key][$element] .= $appendGlue . (string) $value;
2829                 } else {
2830                         // Add it
2831                         $this->setStringGenericArrayElement($keyGroup, $subGroup, $key, $element, $value);
2832                 }
2833         }
2834
2835         /**
2836          * Sets a string in a given generic array element
2837          *
2838          * @param       $keyGroup       Main group for the key
2839          * @param       $subGroup       Sub group for the key
2840          * @param       $key            Key to unset
2841          * @param       $element        Element to check
2842          * @param       $value          Value to add/append
2843          * @return      void
2844          */
2845         protected final function setStringGenericArrayElement ($keyGroup, $subGroup, $key, $element, $value, $appendGlue = '') {
2846                 // Debug message
2847                 //* 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);
2848
2849                 // Set it
2850                 $this->genericArray[$keyGroup][$subGroup][$key][$element] = (string) $value;
2851         }
2852
2853         /**
2854          * Initializes given generic array group
2855          *
2856          * @param       $keyGroup       Main group for the key
2857          * @param       $subGroup       Sub group for the key
2858          * @param       $key            Key to use
2859          * @param       $forceInit      Optionally force initialization
2860          * @return      void
2861          */
2862         protected final function initGenericArrayGroup ($keyGroup, $subGroup, $forceInit = FALSE) {
2863                 // Debug message
2864                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',forceInit=' . intval($forceInit));
2865
2866                 // Is it already set?
2867                 if (($forceInit === FALSE) && ($this->isGenericArrayGroupSet($keyGroup, $subGroup))) {
2868                         // Already initialized
2869                         trigger_error(__METHOD__ . ':keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' already initialized.');
2870                         exit;
2871                 } // END - if
2872
2873                 // Initialize it
2874                 $this->genericArray[$keyGroup][$subGroup] = array();
2875         }
2876
2877         /**
2878          * Initializes given generic array key
2879          *
2880          * @param       $keyGroup       Main group for the key
2881          * @param       $subGroup       Sub group for the key
2882          * @param       $key            Key to use
2883          * @param       $forceInit      Optionally force initialization
2884          * @return      void
2885          */
2886         protected final function initGenericArrayKey ($keyGroup, $subGroup, $key, $forceInit = FALSE) {
2887                 // Debug message
2888                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',forceInit=' . intval($forceInit));
2889
2890                 // Is it already set?
2891                 if (($forceInit === FALSE) && ($this->isGenericArrayKeySet($keyGroup, $subGroup, $key))) {
2892                         // Already initialized
2893                         trigger_error(__METHOD__ . ':keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' already initialized.');
2894                         exit;
2895                 } // END - if
2896
2897                 // Initialize it
2898                 $this->genericArray[$keyGroup][$subGroup][$key] = array();
2899         }
2900
2901         /**
2902          * Initializes given generic array element
2903          *
2904          * @param       $keyGroup       Main group for the key
2905          * @param       $subGroup       Sub group for the key
2906          * @param       $key            Key to use
2907          * @param       $element        Element to use
2908          * @param       $forceInit      Optionally force initialization
2909          * @return      void
2910          */
2911         protected final function initGenericArrayElement ($keyGroup, $subGroup, $key, $element, $forceInit = FALSE) {
2912                 // Debug message
2913                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ',forceInit=' . intval($forceInit));
2914
2915                 // Is it already set?
2916                 if (($forceInit === FALSE) && ($this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element))) {
2917                         // Already initialized
2918                         trigger_error(__METHOD__ . ':keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ' already initialized.');
2919                         exit;
2920                 } // END - if
2921
2922                 // Initialize it
2923                 $this->genericArray[$keyGroup][$subGroup][$key][$element] = array();
2924         }
2925
2926         /**
2927          * Pushes an element to a generic key
2928          *
2929          * @param       $keyGroup       Main group for the key
2930          * @param       $subGroup       Sub group for the key
2931          * @param       $key            Key to use
2932          * @param       $value          Value to add/append
2933          * @return      $count          Number of array elements
2934          */
2935         protected final function pushValueToGenericArrayKey ($keyGroup, $subGroup, $key, $value) {
2936                 // Debug message
2937                 //* NOISY-DEBUG: */ if (!is_object($value)) $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',value[' . gettype($value) . ']=' . print_r($value, TRUE));
2938
2939                 // Is it set?
2940                 if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
2941                         // Initialize array
2942                         $this->initGenericArrayKey($keyGroup, $subGroup, $key);
2943                 } // END - if
2944
2945                 // Then push it
2946                 $count = array_push($this->genericArray[$keyGroup][$subGroup][$key], $value);
2947
2948                 // Return count
2949                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], TRUE));
2950                 //* DEBUG: */ print(__METHOD__ . ': count=' . $count . PHP_EOL);
2951                 return $count;
2952         }
2953
2954         /**
2955          * Pushes an element to a generic array element
2956          *
2957          * @param       $keyGroup       Main group for the key
2958          * @param       $subGroup       Sub group for the key
2959          * @param       $key            Key to use
2960          * @param       $element        Element to check
2961          * @param       $value          Value to add/append
2962          * @return      $count          Number of array elements
2963          */
2964         protected final function pushValueToGenericArrayElement ($keyGroup, $subGroup, $key, $element, $value) {
2965                 // Debug message
2966                 //* 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));
2967
2968                 // Is it set?
2969                 if (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
2970                         // Initialize array
2971                         $this->initGenericArrayElement($keyGroup, $subGroup, $key, $element);
2972                 } // END - if
2973
2974                 // Then push it
2975                 $count = array_push($this->genericArray[$keyGroup][$subGroup][$key][$element], $value);
2976
2977                 // Return count
2978                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], TRUE));
2979                 //* DEBUG: */ print(__METHOD__ . ': count=' . $count . PHP_EOL);
2980                 return $count;
2981         }
2982
2983         /**
2984          * Pops an element from  a generic group
2985          *
2986          * @param       $keyGroup       Main group for the key
2987          * @param       $subGroup       Sub group for the key
2988          * @param       $key            Key to unset
2989          * @return      $value          Last "popped" value
2990          */
2991         protected final function popGenericArrayElement ($keyGroup, $subGroup, $key) {
2992                 // Debug message
2993                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
2994
2995                 // Is it set?
2996                 if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
2997                         // Not found
2998                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' not found.');
2999                         exit;
3000                 } // END - if
3001
3002                 // Then "pop" it
3003                 $value = array_pop($this->genericArray[$keyGroup][$subGroup][$key]);
3004
3005                 // Return value
3006                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], TRUE));
3007                 //* DEBUG: */ print(__METHOD__ . ': value[' . gettype($value) . ']=' . print_r($value, TRUE) . PHP_EOL);
3008                 return $value;
3009         }
3010
3011         /**
3012          * Shifts an element from  a generic group
3013          *
3014          * @param       $keyGroup       Main group for the key
3015          * @param       $subGroup       Sub group for the key
3016          * @param       $key            Key to unset
3017          * @return      $value          Last "popped" value
3018          */
3019         protected final function shiftGenericArrayElement ($keyGroup, $subGroup, $key) {
3020                 // Debug message
3021                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
3022
3023                 // Is it set?
3024                 if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
3025                         // Not found
3026                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' not found.');
3027                         exit;
3028                 } // END - if
3029
3030                 // Then "shift" it
3031                 $value = array_shift($this->genericArray[$keyGroup][$subGroup][$key]);
3032
3033                 // Return value
3034                 //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], TRUE));
3035                 //* DEBUG: */ print(__METHOD__ . ': value[' . gettype($value) . ']=' . print_r($value, TRUE) . PHP_EOL);
3036                 return $value;
3037         }
3038
3039         /**
3040          * Count generic array group
3041          *
3042          * @param       $keyGroup       Main group for the key
3043          * @return      $count          Count of given group
3044          */
3045         protected final function countGenericArray ($keyGroup) {
3046                 // Debug message
3047                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup);
3048
3049                 // Is it there?
3050                 if (!isset($this->genericArray[$keyGroup])) {
3051                         // Abort here
3052                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ' not found.');
3053                         exit;
3054                 } // END - if
3055
3056                 // Then count it
3057                 $count = count($this->genericArray[$keyGroup]);
3058
3059                 // Debug message
3060                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',count=' . $count);
3061
3062                 // Return it
3063                 return $count;
3064         }
3065
3066         /**
3067          * Count generic array sub group
3068          *
3069          * @param       $keyGroup       Main group for the key
3070          * @param       $subGroup       Sub group for the key
3071          * @return      $count          Count of given group
3072          */
3073         protected final function countGenericArrayGroup ($keyGroup, $subGroup) {
3074                 // Debug message
3075                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup);
3076
3077                 // Is it there?
3078                 if (!$this->isGenericArrayGroupSet($keyGroup, $subGroup)) {
3079                         // Abort here
3080                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' not found.');
3081                         exit;
3082                 } // END - if
3083
3084                 // Then count it
3085                 $count = count($this->genericArray[$keyGroup][$subGroup]);
3086
3087                 // Debug message
3088                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',count=' . $count);
3089
3090                 // Return it
3091                 return $count;
3092         }
3093
3094         /**
3095          * Count generic array elements
3096          *
3097          * @param       $keyGroup       Main group for the key
3098          * @param       $subGroup       Sub group for the key
3099          * @para        $key            Key to count
3100          * @return      $count          Count of given key
3101          */
3102         protected final function countGenericArrayElements ($keyGroup, $subGroup, $key) {
3103                 // Debug message
3104                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
3105
3106                 // Is it there?
3107                 if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
3108                         // Abort here
3109                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' not found.');
3110                         exit;
3111                 } elseif (!$this->isValidGenericArrayGroup($keyGroup, $subGroup)) {
3112                         // Not valid
3113                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' is not an array.');
3114                         exit;
3115                 }
3116
3117                 // Then count it
3118                 $count = count($this->genericArray[$keyGroup][$subGroup][$key]);
3119
3120                 // Debug message
3121                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',count=' . $count);
3122
3123                 // Return it
3124                 return $count;
3125         }
3126
3127         /**
3128          * Getter for whole generic group array
3129          *
3130          * @param       $keyGroup       Key group to get
3131          * @return      $array          Whole generic array group
3132          */
3133         protected final function getGenericArray ($keyGroup) {
3134                 // Debug message
3135                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup);
3136
3137                 // Is it there?
3138                 if (!isset($this->genericArray[$keyGroup])) {
3139                         // Then abort here
3140                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ' does not exist.');
3141                         exit;
3142                 } // END - if
3143
3144                 // Return it
3145                 return $this->genericArray[$keyGroup];
3146         }
3147
3148         /**
3149          * Setter for generic array key
3150          *
3151          * @param       $keyGroup       Key group to get
3152          * @param       $subGroup       Sub group for the key
3153          * @param       $key            Key to unset
3154          * @param       $value          Mixed value from generic array element
3155          * @return      void
3156          */
3157         protected final function setGenericArrayKey ($keyGroup, $subGroup, $key, $value) {
3158                 // Debug message
3159                 //* NOISY-DEBUG: */ if (!is_object($value)) $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',value[' . gettype($value) . ']=' . print_r($value, TRUE));
3160
3161                 // Set value here
3162                 $this->genericArray[$keyGroup][$subGroup][$key] = $value;
3163         }
3164
3165         /**
3166          * Getter for generic array key
3167          *
3168          * @param       $keyGroup       Key group to get
3169          * @param       $subGroup       Sub group for the key
3170          * @param       $key            Key to unset
3171          * @return      $value          Mixed value from generic array element
3172          */
3173         protected final function getGenericArrayKey ($keyGroup, $subGroup, $key) {
3174                 // Debug message
3175                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
3176
3177                 // Is it there?
3178                 if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
3179                         // Then abort here
3180                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' does not exist.');
3181                         exit;
3182                 } // END - if
3183
3184                 // Return it
3185                 return $this->genericArray[$keyGroup][$subGroup][$key];
3186         }
3187
3188         /**
3189          * Sets a value in given generic array key/element
3190          *
3191          * @param       $keyGroup       Main group for the key
3192          * @param       $subGroup       Sub group for the key
3193          * @param       $key            Key to set
3194          * @param       $element        Element to set
3195          * @param       $value          Value to set
3196          * @return      void
3197          */
3198         protected final function setGenericArrayElement ($keyGroup, $subGroup, $key, $element, $value) {
3199                 // Debug message
3200                 //* 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));
3201
3202                 // Then set it
3203                 $this->genericArray[$keyGroup][$subGroup][$key][$element] = $value;
3204         }
3205
3206         /**
3207          * Getter for generic array element
3208          *
3209          * @param       $keyGroup       Key group to get
3210          * @param       $subGroup       Sub group for the key
3211          * @param       $key            Key to look for
3212          * @param       $element        Element to look for
3213          * @return      $value          Mixed value from generic array element
3214          */
3215         protected final function getGenericArrayElement ($keyGroup, $subGroup, $key, $element) {
3216                 // Debug message
3217                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element);
3218
3219                 // Is it there?
3220                 if (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
3221                         // Then abort here
3222                         trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ' does not exist.');
3223                         exit;
3224                 } // END - if
3225
3226                 // Return it
3227                 return $this->genericArray[$keyGroup][$subGroup][$key][$element];
3228         }
3229
3230         /**
3231          * Checks if a given sub group is valid (array)
3232          *
3233          * @param       $keyGroup       Key group to get
3234          * @param       $subGroup       Sub group for the key
3235          * @return      $isValid        Whether given sub group is valid
3236          */
3237         protected final function isValidGenericArrayGroup ($keyGroup, $subGroup) {
3238                 // Debug message
3239                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup);
3240
3241                 // Determine it
3242                 $isValid = (($this->isGenericArrayGroupSet($keyGroup, $subGroup)) && (is_array($this->getGenericSubArray($keyGroup, $subGroup))));
3243
3244                 // Return it
3245                 return $isValid;
3246         }
3247
3248         /**
3249          * Checks if a given key is valid (array)
3250          *
3251          * @param       $keyGroup       Key group to get
3252          * @param       $subGroup       Sub group for the key
3253          * @param       $key            Key to check
3254          * @return      $isValid        Whether given sub group is valid
3255          */
3256         protected final function isValidGenericArrayKey ($keyGroup, $subGroup, $key) {
3257                 // Debug message
3258                 //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);
3259
3260                 // Determine it
3261                 $isValid = (($this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) && (is_array($this->getGenericArrayKey($keyGroup, $subGroup, $key))));
3262
3263                 // Return it
3264                 return $isValid;
3265         }
3266
3267         /**
3268          * Initializes the web output instance
3269          *
3270          * @return      void
3271          */
3272         protected function initWebOutputInstance () {
3273                 // Get application instance
3274                 $applicationInstance = Registry::getRegistry()->getInstance('app');
3275
3276                 // Is this a response instance?
3277                 if ($this instanceof Responseable) {
3278                         // Then set it in application instance
3279                         $applicationInstance->setResponseInstance($this);
3280                 } // END - if
3281
3282                 // Init web output instance
3283                 $outputInstance = ObjectFactory::createObjectByConfiguredName('output_class', array($applicationInstance));
3284
3285                 // Set it locally
3286                 $this->setWebOutputInstance($outputInstance);
3287         }
3288
3289         /**
3290          * Translates boolean TRUE to 'Y' and FALSE to 'N'
3291          *
3292          * @param       $boolean                Boolean value
3293          * @return      $translated             Translated boolean value
3294          */
3295         public static final function translateBooleanToYesNo ($boolean) {
3296                 // Make sure it is really boolean
3297                 assert(is_bool($boolean));
3298
3299                 // "Translate" it
3300                 $translated = ($boolean === TRUE) ? 'Y' : 'N';
3301
3302                 // ... and return it
3303                 return $translated;
3304         }
3305
3306         /**
3307          * Encodes raw data (almost any type) by "serializing" it and then pack it
3308          * into a "binary format".
3309          *
3310          * @param       $rawData        Raw data (almost any type)
3311          * @return      $encoded        Encoded data
3312          */
3313         protected function encodeData ($rawData) {
3314                 // Make sure no objects or resources pass through
3315                 assert(!is_object($rawData));
3316                 assert(!is_resource($rawData));
3317
3318                 // First "serialize" it (json_encode() is faster than serialize())
3319                 $encoded = $this->packString(json_encode($rawData));
3320
3321                 // And return it
3322                 return $encoded;
3323         }
3324
3325         /**
3326          * Pack a string into a "binary format". Please execuse me that this is
3327          * widely undocumented. :-(
3328          *
3329          * @param       $str            Unpacked string
3330          * @return      $packed         Packed string
3331          * @todo        Improve documentation
3332          */
3333         protected function packString ($str) {
3334                 // Debug message
3335                 //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('str=' . $str . ' - CALLED!');
3336
3337                 // First compress the string (gzcompress is okay)
3338                 $str = gzcompress($str);
3339
3340                 // Init variable
3341                 $packed = '';
3342
3343                 // And start the "encoding" loop
3344                 for ($idx = 0; $idx < strlen($str); $idx += $this->packingData[$this->archArrayElement]['step']) {
3345                         $big = 0;
3346                         for ($i = 0; $i < $this->packingData[$this->archArrayElement]['step']; $i++) {
3347                                 $factor = ($this->packingData[$this->archArrayElement]['step'] - 1 - $i);
3348
3349                                 if (($idx + $i) <= strlen($str)) {
3350                                         $ord = ord(substr($str, ($idx + $i), 1));
3351
3352                                         $add = $ord * pow(256, $factor);
3353
3354                                         $big += $add;
3355
3356                                         //print 'idx=' . $idx . ',i=' . $i . ',ord=' . $ord . ',factor=' . $factor . ',add=' . $add . ',big=' . $big . PHP_EOL;
3357                                 } // END - if
3358                         } // END - for
3359
3360                         $l = ($big & $this->packingData[$this->archArrayElement]['left']) >>$this->packingData[$this->archArrayElement]['factor'];
3361                         $r = $big & $this->packingData[$this->archArrayElement]['right'];
3362
3363                         $chunk = str_pad(pack($this->packingData[$this->archArrayElement]['format'], $l, $r), 8, '0', STR_PAD_LEFT);
3364                         //* NOISY-DEBUG */ print 'big=' . $big . ',chunk('.strlen($chunk) . ')='.md5($chunk).PHP_EOL;
3365
3366                         $packed .= $chunk;
3367                 } // END - for
3368
3369                 // Return it
3370                 //* NOISY-DEBUG */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('packed=' . $packed . ' - EXIT!');
3371                 return $packed;
3372         }
3373
3374         /**
3375          * Checks whether the given file/path is in open_basedir(). This does not
3376          * gurantee that the file is actually readable and/or writeable. If you need
3377          * such gurantee then please use isReadableFile() instead.
3378          *
3379          * @param       $filePathName   Name of the file/path to be checked
3380          * @return      $isReachable    Whether it is within open_basedir()
3381          */
3382         protected static function isReachableFilePath ($filePathName) {
3383                 // Is not reachable by default
3384                 $isReachable = FALSE;
3385
3386                 // Get open_basedir parameter
3387                 $openBaseDir = ini_get('open_basedir');
3388
3389                 // Is it set?
3390                 if (!empty($openBaseDir)) {
3391                         // Check all entries
3392                         foreach (explode(PATH_SEPARATOR, $openBaseDir) as $dir) {
3393                                 // Check on existence
3394                                 if (substr($filePathName, 0, strlen($dir)) == $dir) {
3395                                         // Is reachable
3396                                         $isReachable = TRUE;
3397                                 } // END - if
3398                         } // END - foreach
3399                 } else {
3400                         // If open_basedir is not set, all is allowed
3401                         $isReachable = TRUE;
3402                 }
3403
3404                 // Return status
3405                 return $isReachable;
3406         }
3407
3408         /**
3409          * Checks whether the give file is within open_basedir() (done by
3410          * isReachableFilePath()), is actually a file and is readable.
3411          *
3412          * @param       $fileName               Name of the file to be checked
3413          * @return      $isReadable             Whether the file is readable (and therefor exists)
3414          */
3415         public static function isReadableFile ($fileName) {
3416                 // Default is not readable
3417                 $isReadable = FALSE;
3418
3419                 // Is within parameters, so check if it is a file and readable
3420                 $isReadable = ((self::isReachableFilePath($fileName)) && (file_exists($fileName)) && (is_file($fileName)) && (is_readable($fileName)));
3421
3422                 // Return status
3423                 return $isReadable;
3424         }
3425
3426         /**
3427          * Creates a full-qualified file name (FQFN) for given file name by adding
3428          * a configured temporary file path to it.
3429          *
3430          * @param       $fileName       Name for temporary file
3431          * @return      $fqfn   Full-qualified file name
3432          * @throw       PathWriteProtectedException If the path in 'temp_file_path' is write-protected
3433          * @throws      FileIoException If the file cannot be written
3434          */
3435          protected static function createTempPathForFile ($fileName) {
3436                 // Get config entry
3437                 $basePath = FrameworkConfiguration::getSelfInstance()->getConfigEntry('temp_file_path');
3438
3439                 // Is the path writeable?
3440                 if (!is_writable($basePath)) {
3441                         // Path is write-protected
3442                         throw new PathWriteProtectedException($fileName, self::EXCEPTION_PATH_CANNOT_BE_WRITTEN);
3443                 } // END - if
3444
3445                 // Add it
3446                 $fqfn = $basePath . '/' . $fileName;
3447
3448                 // Is it reachable?
3449                 if (!self::isReachableFilePath($fqfn)) {
3450                         // Not reachable
3451                         throw new FileIoException($fqfn, self::EXCEPTION_FILE_NOT_REACHABLE);
3452                 } // END - if
3453
3454                 // Return it
3455                 return $fqfn;
3456          }
3457
3458         /**
3459          * "Getter" for a printable state name
3460          *
3461          * @return      $stateName      Name of the node's state in a printable format
3462          */
3463         public final function getPrintableState () {
3464                 // Default is 'null'
3465                 $stateName = 'null';
3466
3467                 // Get the state instance
3468                 $stateInstance = $this->getStateInstance();
3469
3470                 // Is it an instance of Stateable?
3471                 if ($stateInstance instanceof Stateable) {
3472                         // Then use that state name
3473                         $stateName = $stateInstance->getStateName();
3474                 } // END - if
3475
3476                 // Return result
3477                 return $stateName;
3478         }
3479
3480         /**
3481          * Handles socket error for given socket resource and peer data. This method
3482          * validates $socketResource if it is a valid resource (see is_resource())
3483          * but assumes valid data in array $recipientData, except that
3484          * count($recipientData) is always 2.
3485          *
3486          * @param       $method                         Value of __METHOD__ from calling method
3487          * @param       $line                           Value of __LINE__ from calling method
3488          * @param       $socketResource         A valid socket resource
3489          * @param       $socketData                     A valid socket data array (0 = IP/file name, 1 = port)
3490          * @return      void
3491          * @throws      InvalidSocketException  If $socketResource is no socket resource
3492          * @throws      NoSocketErrorDetectedException  If socket_last_error() gives zero back
3493          * @todo        Move all this socket-related stuff into own class, most of it resides in BaseListener
3494          */
3495         protected final function handleSocketError ($method, $line, $socketResource, array $socketData) {
3496                 // This method handles only socket resources
3497                 if (!is_resource($socketResource)) {
3498                         // No resource, abort here
3499                         throw new InvalidSocketException(array($this, $socketResource), BaseListener::EXCEPTION_INVALID_SOCKET);
3500                 } // END - if
3501
3502                 // Check socket array, 1st element is mostly IP address (or file name), 2nd is port number
3503                 //* DEBUG-DIE: */ die(__METHOD__ . ':socketData=' . print_r($socketData, TRUE));
3504                 assert(isset($socketData[0]));
3505                 assert(isset($socketData[1]));
3506
3507                 // Get error code for first validation (0 is not an error)
3508                 $errorCode = socket_last_error($socketResource);
3509
3510                 // If the error code is zero, someone called this method without an error
3511                 if ($errorCode == 0) {
3512                         // No error detected (or previously cleared outside this method)
3513                         throw new NoSocketErrorDetectedException(array($this, $socketResource), BaseListener::EXCEPTION_NO_SOCKET_ERROR);
3514                 } // END - if
3515
3516                 // Get handler (method) name
3517                 $handlerName = $this->getSocketErrorHandlerFromCode($errorCode);
3518
3519                 // Call-back the error handler method
3520                 call_user_func_array(array($this, $handlerName), array($socketResource, $socketData));
3521
3522                 // Finally clear the error because it has been handled
3523                 socket_clear_error($socketResource);
3524         }
3525
3526 }