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