inc/classes/main/class_BaseFrameworkSystem.php

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