framework/main/classes/class_BaseFrameworkSystem.php

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