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