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