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