inc/classes/main/class_BaseFrameworkSystem.php

   1 <?php
   2 /**
   3  * The simulator system class is the super class of all other classes. This
   4  * class handles saving of games etc.
   5  *
   6  * @author              Roland Haeder <webmaster@ship-simu.org>
   7  * @version             0.0.0
   8  * @copyright   Copyright(c) 2007, 2008 Roland Haeder, this is free software
   9  * @license             GNU GPL 3.0 or any newer version
  10  * @link                http://www.ship-simu.org
  11  *
  12  * This program is free software: you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation, either version 3 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  24  */
  25 class BaseFrameworkSystem extends stdClass implements FrameworkInterface {
  26         /**
  27          * The instance to the debug output handler (should be DebugConsoleOutput or DebugWebOutput)
  28          *
  29          * @see         DebugConsoleOutput
  30          * @see         DebugWebOutput
  31          */
  32         private static $debug       = null;
  33
  34         /**
  35          * The instance to the web output handler (should be WebOutput)
  36          *
  37          * @see         WebOutput
  38          */
  39         private static $webOutput   = null;
  40
  41         /**
  42          * The instance to the compression layer which should be CompressorChannel
  43          */
  44         private static $compressor  = null;
  45
  46         /**
  47          * The configuration instance which shall be FrameworkConfiguration
  48          */
  49         private static $cfgInstance = null;
  50
  51         /**
  52          * The instance to the database layer which should be DatabaseConnection
  53          */
  54         private $dbInstance  = null;
  55
  56         /**
  57          * Instance to an application helper class
  58          */
  59         private $applicationInstance = null;
  60
  61         /**
  62          * The real class name
  63          */
  64         private $realClass      = "FrameworkSystem";
  65
  66         /**
  67          * A human-readable description for this simulator part
  68          */
  69         private $objectDescription      = "Namenlose Framework-Einheit";
  70
  71         /**
  72          * The unique ID string for identifying all type of classes
  73          */
  74         private $uniqueID = "";
  75
  76         /**
  77          * Thousands seperator
  78          */
  79         private $thousands = "."; // German
  80
  81         /**
  82          * Decimal seperator
  83          */
  84         private $decimals  = ","; // German
  85
  86         /**
  87          * The language instance for the template loader
  88          */
  89         private $langInstance = null;
  90
  91         /**
  92          * The file I/O instance for the template loader
  93          */
  94         private $fileIOInstance = null;
  95
  96         /***********************
  97          * Exception codes.... *
  98          ***********************/
  99
 100         const EXCEPTION_IS_NULL_POINTER              = 0x001;
 101         const EXCEPTION_IS_NO_OBJECT                 = 0x002;
 102         const EXCEPTION_IS_NO_ARRAY                  = 0x003;
 103         const EXCEPTION_MISSING_METHOD               = 0x004;
 104         const EXCEPTION_CLASSES_NOT_MATCHING         = 0x005;
 105         const EXCEPTION_INDEX_OUT_OF_BOUNDS          = 0x006;
 106         const EXCEPTION_DIMENSION_ARRAY_INVALID      = 0x007;
 107         const EXCEPTION_ITEM_NOT_TRADEABLE           = 0x008;
 108         const EXCEPTION_ITEM_NOT_IN_PRICE_LIST       = 0x009;
 109         const EXCEPTION_GENDER_IS_WRONG              = 0x00a;
 110         const EXCEPTION_BIRTH_DATE_IS_INVALID        = 0x00b;
 111         const EXCEPTION_EMPTY_STRUCTURES_ARRAY       = 0x00c;
 112         const EXCEPTION_HAS_ALREADY_PERSONELL_LIST   = 0x00d;
 113         const EXCEPTION_NOT_ENOUGTH_UNEMPLOYEES      = 0x00e;
 114         const EXCEPTION_TOTAL_PRICE_NOT_CALCULATED   = 0x00f;
 115         const EXCEPTION_HARBOR_HAS_NO_SHIPYARDS      = 0x010;
 116         const EXCEPTION_CONTRACT_PARTNER_INVALID     = 0x011;
 117         const EXCEPTION_CONTRACT_PARTNER_MISMATCH    = 0x012;
 118         const EXCEPTION_CONTRACT_ALREADY_SIGNED      = 0x013;
 119         const EXCEPTION_UNEXPECTED_EMPTY_STRING      = 0x014;
 120         const EXCEPTION_PATH_NOT_FOUND               = 0x015;
 121         const EXCEPTION_INVALID_PATH_NAME            = 0x016;
 122         const EXCEPTION_READ_PROTECED_PATH           = 0x017;
 123         const EXCEPTION_WRITE_PROTECED_PATH          = 0x018;
 124         const EXCEPTION_DIR_POINTER_INVALID          = 0x019;
 125         const EXCEPTION_FILE_POINTER_INVALID         = 0x01a;
 126         const EXCEPTION_INVALID_DIRECTORY_POINTER    = 0x01b;
 127         const EXCEPTION_UNEXPECTED_OBJECT            = 0x01c;
 128         const EXCEPTION_LIMIT_ELEMENT_IS_UNSUPPORTED = 0x01d;
 129         const EXCEPTION_GETTER_IS_MISSING            = 0x01e;
 130         const EXCEPTION_ARRAY_EXPECTED               = 0x01f;
 131         const EXCEPTION_ARRAY_HAS_INVALID_COUNT      = 0x020;
 132         const EXCEPTION_ID_IS_INVALID_FORMAT         = 0x021;
 133         const EXCEPTION_MD5_CHECKSUMS_MISMATCH       = 0x022;
 134         const EXCEPTION_UNEXPECTED_STRING_SIZE       = 0x023;
 135         const EXCEPTION_SIMULATOR_ID_INVALID         = 0x024;
 136         const EXCEPTION_MISMATCHING_COMPRESSORS      = 0x025;
 137         const EXCEPTION_CONTAINER_ITEM_IS_NULL       = 0x026;
 138         const EXCEPTION_ITEM_IS_NO_ARRAY             = 0x027;
 139         const EXCEPTION_CONTAINER_MAYBE_DAMAGED      = 0x028;
 140         const EXCEPTION_INVALID_STRING               = 0x029;
 141         const EXCEPTION_VARIABLE_NOT_SET             = 0x02a;
 142         const EXCEPTION_ATTRIBUTES_ARE_MISSING       = 0x02b;
 143         const EXCEPTION_ARRAY_ELEMENTS_MISSING       = 0x02c;
 144         const EXCEPTION_TEMPLATE_ENGINE_UNSUPPORTED  = 0x02d;
 145         const EXCEPTION_MISSING_LANGUAGE_HANDLER     = 0x02e;
 146         const EXCEPTION_MISSING_FILE_IO_HANDLER      = 0x02f;
 147         const EXCEPTION_MISSING_ELEMENT              = 0x030;
 148         const EXCEPTION_INVALID_COMMAND              = 0x031;
 149         const EXCEPTION_INVALID_CONTROLLER           = 0x032;
 150         const EXCEPTION_HEADERS_ALREADY_SENT         = 0x033;
 151         const EXCEPTION_DEFAUL_CONTROLLER_GONE       = 0x034;
 152         const EXCEPTION_CLASS_NOT_FOUND              = 0x035;
 153         const EXCEPTION_REQUIRED_INTERFACE_MISSING   = 0x036;
 154
 155         /**
 156          * In the super constructor these system classes shall be ignored or else
 157          * we would get an endless calling loop.
 158          *
 159          *--------------------------------------------------------------------*
 160          * ATTENTION: IF YOU REMOVE ONE OF THEM YOU WILL SHOOT YOUR SERVER!!! *
 161          *--------------------------------------------------------------------*
 162          */
 163         private $systemClasses = array(
 164                 "DebugMiddleware",                              // Debug middleware output sub-system
 165                 "DebugWebOutput",                               // Debug web output sub-system
 166                 "DebugConsoleOutput",                   // Debug console output sub-system
 167                 "DebugErrorLogOutput",                  // Debug error_log() output sub-system
 168                 "CompressorChannel",                    // Compressor sub-system
 169                 "FrameworkDirectoryPointer",    // Directory handler sub-system
 170                 "NullCompressor",                               // Null compressor
 171                 "Bzip2Compressor",                              // BZIP2 compressor
 172                 "GzipCompressor",                               // GZIP compressor
 173                 "WebOutput",                                    // Web output sub-system
 174         );
 175
 176         /**
 177          * Private super constructor
 178          *
 179          * @return      void
 180          */
 181         protected function __construct ($class) {
 182                 // Set real class
 183                 $this->setRealClass($class);
 184
 185                 // Init this instance
 186                 $this->initInstance($class);
 187         }
 188
 189         /**
 190          * Destructor reached...
 191          *
 192          * @return      void
 193          */
 194         public function __destruct() {
 195                 // Is this object already destroyed?
 196                 if ($this->__toString() != "DestructedObject") {
 197                         // Debug message
 198                         if ((defined('DEBUG_DESTRUCTOR')) && (is_object($this->getDebugInstance()))) {
 199                                 $this->getDebugInstance()->output(sprintf("[%s:] Das Objekt <strong>%s</strong> wird zerst&ouml;rt.<br />\n",
 200                                         __CLASS__, $this->__toString()
 201                                 ));
 202                         }
 203
 204                         // Destroy all informations about this class but keep some text about it alive
 205                         $this->setObjectDescription(sprintf("Entferntes Objekt <em>%s</em>", $this->__toString()));
 206                         $this->setRealClass("DestructedObject");
 207                         $this->resetUniqueID();
 208                 } elseif ((defined('DEBUG_DESTRUCTOR')) && (is_object($this->getDebugInstance()))) {
 209                         // Already destructed object
 210                         $this->getDebugInstance()->output(sprintf("[%s:] Das Objekt <strong>%s</strong> wurde bereits zerst&ouml;rt.<br />\n",
 211                                 __CLASS__, $this->__toString()
 212                         ));
 213                 }
 214         }
 215
 216         /**
 217          * The call method where all non-implemented methods end up
 218          *
 219          * @return      void
 220          */
 221         public final function __call ($methodName, $args) {
 222                 // Implode all given arguments
 223                 $argsString = "";
 224                 if (empty($args)) {
 225                         // No arguments
 226                         $argsString = "NULL";
 227                 } elseif (is_array($args)) {
 228                         // Some arguments are there
 229                         foreach ($args as $arg) {
 230                                 // Check the type
 231                                 if (is_bool($arg)) {
 232                                         // Boolean!
 233                                         if ($arg) $argsString .= "true(bool)"; else $argsString .= "false(bool)";
 234                                 } elseif (is_int($arg)) {
 235                                         // Integer
 236                                         $argsString .= $arg."(int)";
 237                                 } elseif (is_float($arg)) {
 238                                         // Floating point
 239                                         $argsString .= $arg."(float)";
 240                                 } elseif ($arg instanceof BaseFrameworkSystem) {
 241                                         // Own object instance
 242                                         $argsString .= $arg->__toString()."(Object)";
 243                                 } elseif (is_object($arg)) {
 244                                         // External object
 245                                         $argsString .= "unknown object(!)";
 246                                 } elseif (is_array($arg)) {
 247                                         // Array
 248                                         $argsString .= "Array(array)";
 249                                 } elseif (is_string($arg)) {
 250                                         // String
 251                                         $argsString .= "\"".$arg."\"(string)";
 252                                 } else {
 253                                         // Unknown type (please report!)
 254                                         $argsString .= $arg."(unknown!)";
 255                                 }
 256
 257                                 // Add comma
 258                                 $argsString .= ", ";
 259                         }
 260
 261                         // Remove last comma
 262                         if (substr($argsString, -2, 1) === ",") $argsString = substr($argsString, 0, -2);
 263                 } else {
 264                         // Invalid arguments!
 265                         $argsString = sprintf("!INVALID:%s!", $args);
 266                 }
 267
 268                 $this->getDebugInstance()->output(sprintf("[%s::%s] Stub! Args: %s",
 269                         $this->__toString(),
 270                         $methodName,
 271                         $argsString
 272                 ));
 273
 274                 // Return nothing
 275                 return null;
 276         }
 277
 278         /**
 279          * Initializes the instance
 280          *
 281          * @return      void
 282          */
 283         public function initInstance ($class) {
 284                 // Get the current (singleton) configuration instance
 285                 $this->setConfigInstance(FrameworkConfiguration::createFrameworkConfiguration());
 286
 287                 // Is the class weather debug nor compressor channel?
 288                 if (!in_array($class, $this->systemClasses)) {
 289                         // Initialize debug instance
 290                         if (is_null($this->getDebugInstance())) {
 291                                 // Set the debug output system if it is not debug class ;)
 292                                 $this->setDebugInstance(DebugMiddleware::createDebugMiddleware($this->getConfigInstance()->readConfig('debug_engine')));
 293                         }
 294
 295                         // Initialize web instance
 296                         if (is_null($this->getWebOutputInstance())) {
 297                                 // Generate the eval() command
 298                                 $eval = sprintf("\$this->setWebOutputInstance(%s::create%s(\"%s\"));",
 299                                         $this->getConfigInstance()->readConfig('web_engine'),
 300                                         $this->getConfigInstance()->readConfig('web_engine'),
 301                                         $this->getConfigInstance()->readConfig('web_content_type')
 302                                 );
 303
 304                                 // Debug message
 305                                 if (defined('DEBUG_EVAL')) $this->getDebugInstance()->output(sprintf("[%s:] Constructed PHP command: <pre><em>%s</em></pre><br />\n",
 306                                         $this->__toString(),
 307                                         htmlentities($eval)
 308                                 ));
 309
 310                                 // Run the command
 311                                 eval($eval);
 312                         }
 313
 314                         // Initialize compressor channel
 315                         if (is_null($this->getCompressorChannel())) {
 316                                 // Set the compressor channel
 317                                 $this->setCompressorChannel(CompressorChannel::createCompressorChannel(sprintf("%s%s",
 318                                         PATH,
 319                                         $this->getConfigInstance()->readConfig('compressor_base_path')
 320                                 )));
 321                         }
 322
 323                         // Initialize database middleware
 324                         if (is_null($this->getDatabaseInstance())) {
 325                                 // Get the middleware instance
 326                                 $db = DatabaseConnection::getInstance();
 327                                 if (is_object($db)) {
 328                                         // Set the database middleware
 329                                         $this->setDatabaseInstance($db);
 330                                 }
 331                         }
 332                 }
 333         }
 334
 335         /**
 336          * Setter for language instance
 337          *
 338          * @param       $configInstance The configuration instance which shall
 339          *                                                      be FrameworkConfiguration
 340          * @return      void
 341          */
 342         public final function setConfigInstance (FrameworkConfiguration $configInstance) {
 343                 self::$cfgInstance = $configInstance;
 344         }
 345
 346         /**
 347          * Getter for configuration instance
 348          *
 349          * @return      $cfhInstance - Configuration instance
 350          */
 351         protected final function getConfigInstance () {
 352                 return self::$cfgInstance;
 353         }
 354
 355         /**
 356          * Setter for debug instance
 357          *
 358          * @param               $debugInstance  The instance for debug output class
 359          * @return      void
 360          */
 361         public final function setDebugInstance (DebugMiddleware $debugInstance) {
 362                 self::$debug = $debugInstance;
 363         }
 364
 365         /**
 366          * Getter for debug instance
 367          *
 368          * @return      $debug - Instance to class DebugConsoleOutput or DebugWebOutput
 369          */
 370         public final function getDebugInstance () {
 371                 return self::$debug;
 372         }
 373
 374         /**
 375          * Setter for web output instance
 376          *
 377          * @param               $webInstance    The instance for web output class
 378          * @return      void
 379          */
 380         public final function setWebOutputInstance (OutputStreamer $webInstance) {
 381                 self::$webOutput = $webInstance;
 382         }
 383
 384         /**
 385          * Getter for web output instance
 386          *
 387          * @return      $webOutput - Instance to class WebOutput
 388          */
 389         public final function getWebOutputInstance () {
 390                 return self::$webOutput;
 391         }
 392
 393         /**
 394          * Static setter for database instance
 395          *
 396          * @param               $dbInstance     The instance for the database connection
 397          *                                      (forced DatabaseConnection)
 398          * @return      void
 399          */
 400         public final function setDatabaseInstance (DatabaseConnection $dbInstance) {
 401                 $this->dbInstance = $dbInstance;
 402         }
 403
 404         /**
 405          * Getter for $realClass
 406          *
 407          * @return      $realClass The name of the real class (not BaseFrameworkSystem)
 408          */
 409         public final function __toString () {
 410                 return $this->realClass;
 411         }
 412
 413         /**
 414          * Setter for the real class name
 415          *
 416          * @param               $realClass      Class name (string)
 417          * @return      void
 418          */
 419         public final function setRealClass ($realClass) {
 420                 // Cast to string
 421                 $realClass = (string) $realClass;
 422
 423                 // Set real class
 424                 $this->realClass = $realClass;
 425         }
 426
 427         /**
 428          * Generate unique ID from a lot entropy
 429          *
 430          * @return      void
 431          */
 432         public final function createUniqueID () {
 433                 // Existiert noch keine?
 434                 if (empty($this->uniqueID)) {
 435
 436                         // Correct missing class name
 437                         $corrected = false;
 438                         if ($this->__toString() == "") {
 439                                 $this->setRealClass(__CLASS__);
 440                                 $corrected = true;
 441                         }
 442
 443                         // Neue ID erstellen
 444                         $tempID = false;
 445                         while (true) {
 446                                 // Generate a unique ID number
 447                                 $tempID = $this->generateIdNumber();
 448                                 $isUsed = false;
 449
 450                                 // Try to figure out if the ID number is not yet used
 451                                 try {
 452                                         if (is_object($this->getDatabaseInstance())) {
 453                                                 $isUsed = $this->getDatabaseInstance()->isUniqueIdUsed($tempID, true);
 454                                         }
 455                                 } catch (FrameworkException $e) {
 456                                         // Catches all and ignores all ;-)
 457                                 }
 458
 459                                 if (
 460                                         (
 461                                                 $tempID !== false
 462                                         ) && (
 463                                                 (
 464                                                         $this->getDatabaseInstance() === null
 465                                                 ) || (
 466                                                         (
 467                                                                 is_object($this->getDatabaseInstance())
 468                                                         ) && (
 469                                                                 !$isUsed
 470                                                         )
 471                                                 )
 472                                         )
 473                                 ) {
 474                                         // Abort the loop
 475                                         break;
 476                                 }
 477                         } // END - while
 478
 479                         // Apply the new ID
 480                         $this->setUniqueID($tempID);
 481
 482                         // Revert maybe corrected class name
 483                         if ($corrected) {
 484                                 $this->setRealClass("");
 485                         }
 486
 487                         // Remove system classes if we are in a system class
 488                         if ((isset($this->systemClasses)) && (in_array($this->__toString(), $this->systemClasses))) {
 489                                 // This may save some RAM...
 490                                 $this->removeSystemArray();
 491                         }
 492                 }
 493         }
 494
 495         /**
 496          * Generates a new ID number for classes based from the class' real name,
 497          * the description and some random data
 498          *
 499          * @return      $tempID The new (temporary) ID number
 500          */
 501         private final function generateIdNumber () {
 502                 return sprintf("%s@%s",
 503                         $this->__toString(),
 504                         md5(sprintf("%s:%s:%s:%s:%s:%s",
 505                                 $this->__toString(),
 506                                 $this->getObjectDescription(),
 507                                 time(),
 508                                 getenv('REMOTE_ADDR'),
 509                                 getenv('SERVER_ADDR'),
 510                                 mt_rand()
 511                         ))
 512                 );
 513         }
 514
 515         /**
 516          * Setter for unique ID
 517          *
 518          * @param               $uniqueID               The newly generated unique ID number
 519          * @return      void
 520          */
 521         private final function setUniqueID ($uniqueID) {
 522                 // Cast to string
 523                 $uniqueID = (string) $uniqueID;
 524
 525                 // Set the ID number
 526                 $this->uniqueID = $uniqueID;
 527         }
 528
 529         /**
 530          * Getter for unique ID
 531          *
 532          * @return      $uniqueID               The unique ID of this class
 533          */
 534         public final function getUniqueID () {
 535                 return $this->uniqueID;
 536         }
 537
 538         /**
 539          * Resets or recreates the unique ID number
 540          *
 541          * @return      void
 542          */
 543         public final function resetUniqueID() {
 544                 // Sweet and simple... ;-)
 545                 $newUniqueID = $this->generateIdNumber();
 546                 $this->setUniqueID($newUniqueID);
 547         }
 548
 549         /**
 550          * Getter for simulator description
 551          *
 552          * @return      $objectDescription      The description of this simulation part
 553          */
 554         public final function getObjectDescription () {
 555                 if (isset($this->objectDescription)) {
 556                         return $this->objectDescription;
 557                 } else {
 558                         return null;
 559                 }
 560         }
 561
 562         /**
 563          * Setter for simulation part description
 564          *
 565          * @param               $objectDescription      The description as string for this simulation part
 566          * @return      void
 567          */
 568         public final function setObjectDescription ($objectDescription) {
 569                 $this->objectDescription = (String) $objectDescription;
 570         }
 571
 572         /**
 573          * Validate if given object is the same as current
 574          *
 575          * @param               $object An object instance for comparison with this class
 576          * @return      boolean The result of comparing both's unique ID
 577          */
 578         public final function equals ($object) {
 579                 return ($this->getUniqueID() == $object->getUniqueID());
 580         }
 581
 582         /**
 583          * Compare if both simulation part description and class name matches
 584          * (shall be enougth)
 585          *
 586          * @param               $itemInstance   An object instance to an other class
 587          * @return      boolean         The result of comparing class name simulation part description
 588          */
 589         public function itemMatches ($itemInstance) {
 590                 return (
 591                         (
 592                                 $this->__toString()   == $itemInstance->__toString()
 593                         ) && (
 594                                 $this->getObjectDescription() == $itemInstance->getObjectDescription()
 595                         )
 596                 );
 597         }
 598
 599         /**
 600          * Compare class name of this and given class name
 601          *
 602          * @param               $class  The class name as string from the other class
 603          * @return      boolean The result of comparing both class names
 604          */
 605         public final function isClass ($class) {
 606                 return ($this->__toString() == $class);
 607         }
 608
 609         /**
 610          * Stub method (only real cabins shall override it)
 611          *
 612          * @return      boolean false = is no cabin, true = is a cabin
 613          */
 614         public function isCabin () {
 615                 return false;
 616         }
 617
 618         /**
 619          * Stub method for tradeable objects
 620          *
 621          * @return      boolean false = is not tradeable by the Merchant class,
 622          *                                      true  = is a tradeable object
 623          */
 624         public function isTradeable () {
 625                 return false;
 626         }
 627
 628         /**
 629          * Formats computer generated price values into human-understandable formats
 630          * with thousand and decimal seperators.
 631          *
 632          * @param               $value  The in computer format value for a price
 633          * @param               $currency       The currency symbol (use HTML-valid characters!)
 634          * @param               $decNum Number of decimals after commata
 635          * @return      $price  The for the current language formated price string
 636          * @throws      MissingDecimalsThousandsSeperatorException      If decimals or
 637          *                                                                                              thousands seperator
 638          *                                                                                              is missing
 639          */
 640         public function formatCurrency ($value, $currency = "&euro;", $decNum = 2) {
 641                 // Are all required attriutes set?
 642                 if ((!isset($this->decimals)) || (!isset($this->thousands))) {
 643                         // Throw an exception
 644                         throw new MissingDecimalsThousandsSeperatorException($this, self::EXCEPTION_ATTRIBUTES_ARE_MISSING);
 645                 }
 646
 647                 // Cast the number
 648                 $value = (float) $value;
 649
 650                 // Reformat the US number
 651                 $price = sprintf("%s %s",
 652                         number_format($value, $decNum, $this->decimals, $this->thousands),
 653                         $currency
 654                 );
 655
 656                 // Return as string...
 657                 return $price;
 658         }
 659
 660         /**
 661          * Removes number formating characters
 662          *
 663          * @return      void
 664          */
 665         public final function removeNumberFormaters () {
 666                 unset($this->thousands);
 667                 unset($this->decimals);
 668         }
 669
 670         /**
 671          * Getter for database layer
 672          *
 673          * @return      $dbInstance     The database layer instance
 674          */
 675         public final function getDatabaseInstance () {
 676                 return $this->dbInstance;
 677         }
 678
 679         /**
 680          * Setter for compressor channel
 681          *
 682          * @param               $compressorChannel      An instance of CompressorChannel
 683          * @return      void
 684          */
 685         public final function setCompressorChannel (CompressorChannel $compressorChannel) {
 686                 self::$compressor = $compressorChannel;
 687         }
 688
 689         /**
 690          * Getter for compressor channel
 691          *
 692          * @return      $compressor     The compressor channel
 693          */
 694         public final function getCompressorChannel () {
 695                 return self::$compressor;
 696         }
 697
 698         /**
 699          * Remove the $systemClasses array from memory
 700          *
 701          * @return      void
 702          */
 703         public final function removeSystemArray () {
 704                 unset($this->systemClasses);
 705         }
 706
 707         /**
 708          * Create a file name and path name from the object's unique ID number.
 709          * The left part of the ID shall always be a valid class name and the
 710          * right part an ID number.
 711          *
 712          * @return      $pfn            The file name with a prepended path name
 713          * @throws      NoArrayCreatedException If explode() fails to create an array
 714          * @throws      InvalidArrayCountException      If the array contains less or
 715          *                                                                      more than two elements
 716          */
 717         public final function getPathFileNameFromObject () {
 718                 // Get the main object's unique ID. We use this as a path/filename combination
 719                 $pathFile = $this->getUniqueID();
 720
 721                 // Split it up in path and file name
 722                 $pathFile = explode("@", $pathFile);
 723
 724                 // Are there two elements? Index 0 is the path, 1 the file name + global extension
 725                 if (!is_array($pathFile)) {
 726                         // No array found
 727                         throw new NoArrayCreatedException(array($this, "pathFile"), self::EXCEPTION_ARRAY_EXPECTED);
 728                 } elseif (count($pathFile) != 2) {
 729                         // Invalid ID returned!
 730                         throw new InvalidArrayCountException(array($this, "pathFile", count($pathFile), 2), self::EXCEPTION_ARRAY_HAS_INVALID_COUNT);
 731                 }
 732
 733                 // Auto-append missing trailing slash
 734                 $pathFile[0] = $this->addMissingTrailingSlash($pathFile[0]);
 735
 736                 // Create the file name and return it
 737                 $pfn = ($pathFile[0] . $pathFile[1]);
 738                 return $pfn;
 739         }
 740
 741         /**
 742          * Appends a trailing slash to a string
 743          *
 744          * @param       $str            A string (maybe) without trailing slash
 745          * @return      $str            A string with an auto-appended trailing slash
 746          */
 747         public final function addMissingTrailingSlash ($str) {
 748                 // Is there a trailing slash?
 749                 if (substr($str, -1, 1) != "/") $str .= "/";
 750                 return $str;
 751         }
 752
 753         /**
 754          * Private getter for language instance
 755          *
 756          * @return      $langInstance   An instance to the language sub-system
 757          */
 758         protected final function getLanguageInstance () {
 759                 return $this->langInstance;
 760         }
 761
 762         /**
 763          * Setter for language instance
 764          *
 765          * @param       $langInstance   An instance to the language sub-system
 766          * @return      void
 767          * @see         LanguageSystem
 768          */
 769         public final function setLanguageInstance (ManageableLanguage $langInstance) {
 770                 $this->langInstance = $langInstance;
 771         }
 772
 773         /**
 774          * Private getter for file IO instance
 775          *
 776          * @return      $fileIOInstance An instance to the file I/O sub-system
 777          */
 778         protected final function getFileIoInstance () {
 779                 return $this->fileIOInstance;
 780         }
 781
 782         /**
 783          * Setter for file I/O instance
 784          *
 785          * @param       $fileIOInstance An instance to the file I/O sub-system
 786          * @return      void
 787          */
 788         public final function setFileIoInstance (FileIoHandler $fileIOInstance) {
 789                 $this->fileIOInstance = $fileIOInstance;
 790         }
 791
 792         /**
 793          * Protected getter for a manageable application helper class
 794          *
 795          * @return      $applicationInstance    An instance of a manageable application helper class
 796          */
 797         protected final function getApplicationInstance () {
 798                 return $this->applicationInstance;
 799         }
 800
 801         /**
 802          * Setter for a manageable application helper class
 803          *
 804          * @param       $applicationInstance    An instance of a manageable application helper class
 805          * @return      void
 806          */
 807         public final function setApplicationInstance (ManageableApplication $applicationInstance) {
 808                 $this->applicationInstance = $applicationInstance;
 809         }
 810
 811         /**
 812          * Prepare the template engine (TemplateEngine by default) for a given
 813          * application helper instance (ApplicationHelper by default).
 814          *
 815          * @param               $appInstance                    An application helper instance or
 816          *                                                                              null if we shall use the default
 817          * @return              $tplEngine                              The template engine instance
 818          * @throws              NullPointerException    If the template engine could not
 819          *                                                                              be initialized
 820          * @throws              UnsupportedTemplateEngineException      If $tplEngine is an
 821          *                                                                              unsupported template engine
 822          * @throws              MissingLanguageHandlerException If the language sub-system
 823          *                                                                              is not yet initialized
 824          * @throws              NullPointerException    If the discovered application
 825          *                                                                              instance is still null
 826          */
 827         protected function prepareTemplateEngine (BaseFrameworkSystem $appInstance=null) {
 828                 // Is the application instance set?
 829                 if (is_null($appInstance)) {
 830                         // Get the current instance
 831                         $appInstance = $this->getApplicationInstance();
 832
 833                         // Still null?
 834                         if (is_null($appInstance)) {
 835                                 // Thrown an exception
 836                                 throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 837                         }
 838                 }
 839
 840                 // Generate FQFN for all application templates
 841                 $fqfn = sprintf("%s%s/%s/%s",
 842                         PATH,
 843                         $this->getConfigInstance()->readConfig('application_path'),
 844                         strtolower($appInstance->getAppShortName()),
 845                         $this->getConfigInstance()->readConfig('tpl_base_path')
 846                 );
 847
 848                 // Are both instances set?
 849                 if ($appInstance->getLanguageInstance() === null) {
 850                         // Invalid language instance
 851                         throw new MissingLanguageHandlerException($appInstance, self::EXCEPTION_MISSING_LANGUAGE_HANDLER);
 852                 } elseif ($appInstance->getFileIoInstance() === null) {
 853                         // Invalid language instance
 854                         throw new MissingFileIoHandlerException($appInstance, self::EXCEPTION_MISSING_FILE_IO_HANDLER);
 855                 }
 856
 857                 // Initialize the template engine
 858                 $tplEngine = null;
 859                 $eval = sprintf("\$tplEngine = %s::create%s(
 860         \"%s\",
 861         \$appInstance->getLanguageInstance(),
 862         \$appInstance->getFileIoInstance()
 863 );",
 864                         $this->getConfigInstance()->readConfig('tpl_engine'),
 865                         $this->getConfigInstance()->readConfig('tpl_engine'),
 866                         $fqfn
 867                 );
 868
 869                 // Debug message
 870                 if ((!is_null($this->getDebugInstance())) && (defined('DEBUG_EVAL'))) {
 871                         $this->getDebugInstance()->output(sprintf("[%s:] Constructed PHP command: <pre><em>%s</em></pre><br />\n",
 872                                 $this->__toString(),
 873                                 htmlentities($eval)
 874                         ));
 875                 }
 876
 877                 // Run the command
 878                 eval($eval);
 879
 880                 // Is it a valid instance?
 881                 if (is_null($tplEngine)) {
 882                         // No class returned
 883                         throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
 884                 } elseif (!$tplEngine instanceof CompileableTemplate) {
 885                         // Not an object! ;-(
 886                         throw new UnsupportedTemplateEngineException($tplEngine, self::EXCEPTION_TEMPLATE_ENGINE_UNSUPPORTED);
 887                 }
 888
 889                 // Return the prepared instance
 890                 return $tplEngine;
 891         }
 892
 893         /**
 894          * Debugs this instance by putting out it's full content
 895          *
 896          * @return      void
 897          */
 898         public final function debugInstance () {
 899                 // Generate the output
 900                 $content = sprintf("<pre>%s</pre>",
 901                         trim(print_r($this, true))
 902                 );
 903
 904                 // Output it
 905                 ApplicationEntryPoint::app_die(sprintf("<strong>%s debug output:</strong>%s", $this->__toString(), $content));
 906         }
 907
 908         /**
 909          * Output a partial stub message for the caller method
 910          *
 911          * @param       $message        An optional message to display
 912          * @return      void
 913          */
 914         protected function partialStub ($message = "") {
 915                 // Get the backtrace
 916                 $backtrace = debug_backtrace();
 917
 918                 // Generate the class::method string
 919                 $methodName = "UnknownClass::unknownMethod";
 920                 if ((isset($backtrace[1]['class'])) && (isset($backtrace[1]['function']))) {
 921                         $methodName = $backtrace[1]['class']."::".$backtrace[1]['function'];
 922                 }
 923
 924                 // Construct the full message
 925                 $stubMessage = sprintf("[%s:] Partial stub!",
 926                         $methodName
 927                 );
 928
 929                 // Is the extra message given?
 930                 if (!empty($message)) {
 931                         // Then add it as well
 932                         $stubMessage .= sprintf(" Message: <u>%s</u>", $message);
 933                 }
 934
 935                 // Debug instance is there?
 936                 if (!is_null($this->getDebugInstance())) {
 937                         // Output stub message
 938                         $this->getDebugInstance()->output($stubMessage);
 939                 } else {
 940                         // Trigger an error
 941                         trigger_error($stubMessage."<br />\n");
 942                 }
 943         }
 944
 945         /**
 946          * Converts e.g. a command from URL to a valid class by keeping out bad characters
 947          *
 948          * @param       $str            The string, what ever it is needs to be converted
 949          * @return      $className      Generated class name
 950          */
 951         public function convertToClassName ($str) {
 952                 $className = "";
 953                 foreach (explode("_", $str) as $strPart) {
 954                         $className .= ucfirst(strtolower($strPart));
 955                 }
 956                 return $className;
 957         }
 958
 959         /**
 960          * Outputs a debug backtrace and stops further script execution
 961          *
 962          * @return      void
 963          */
 964         public function debugBacktrace () {
 965                 // Sorry, there is no other way getting this nice backtrace
 966                 print "<pre>\n";
 967                 debug_print_backtrace();
 968                 print "</pre>";
 969                 exit;
 970         }
 971 }
 972
 973 // [EOF]
 974 ?>