Continued:

[core.git] / framework / main / classes / class_BaseFrameworkSystem.php

<?php
// Own namespace
namespace Org\Mxchange\CoreFramework\Object;

// Import framework stuff
use Org\Mxchange\CoreFramework\Bootstrap\FrameworkBootstrap;
use Org\Mxchange\CoreFramework\Criteria\Criteria;
use Org\Mxchange\CoreFramework\Crypto\Cryptable;
use Org\Mxchange\CoreFramework\Database\Frontend\DatabaseWrapper;
use Org\Mxchange\CoreFramework\EntryPoint\ApplicationEntryPoint;
use Org\Mxchange\CoreFramework\Factory\Database\Wrapper\DatabaseWrapperFactory;
use Org\Mxchange\CoreFramework\Factory\ObjectFactory;
use Org\Mxchange\CoreFramework\Filesystem\PathWriteProtectedException;
use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
use Org\Mxchange\CoreFramework\Generic\NullPointerException;
use Org\Mxchange\CoreFramework\Generic\UnsupportedOperationException;
use Org\Mxchange\CoreFramework\Handler\Handleable;
use Org\Mxchange\CoreFramework\Loader\ClassLoader;
use Org\Mxchange\CoreFramework\Manager\ManageableApplication;
use Org\Mxchange\CoreFramework\Middleware\Debug\DebugMiddleware;
use Org\Mxchange\CoreFramework\Registry\GenericRegistry;
use Org\Mxchange\CoreFramework\Result\Database\CachedDatabaseResult;
use Org\Mxchange\CoreFramework\Result\Search\SearchableResult;
use Org\Mxchange\CoreFramework\State\Stateable;
use Org\Mxchange\CoreFramework\Stream\Input\InputStream;
use Org\Mxchange\CoreFramework\Stream\Output\OutputStreamer;
use Org\Mxchange\CoreFramework\Stream\Output\OutputStream;
use Org\Mxchange\CoreFramework\User\ManageableAccount;
use Org\Mxchange\CoreFramework\Utils\String\StringUtils;

// Import SPL stuff
use \stdClass;
use \InvalidArgumentException;
use \Iterator;
use \ReflectionClass;
use \SplFileInfo;

/**
 * The simulator system class is the super class of all other classes. This
 * class handles saving of games etc.
 *
 * @author              Roland Haeder <webmaster@shipsimu.org>
 * @version             0.0.0
 * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2020 Core Developer Team
 * @license             GNU GPL 3.0 or any newer version
 * @link                http://www.shipsimu.org
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */
abstract class BaseFrameworkSystem extends stdClass implements FrameworkInterface {
        /**
         * Length of output from hash()
         */
        private static $hashLength = NULL;

        /**
         * Self-referencing instance
         */
        private static $instance = NULL;

        /**
         * The real class name
         */
        private $realClass = __CLASS__;

        /**
         * Database result instance
         */
        private $resultInstance = NULL;

        /**
         * Instance for user class
         */
        private $userInstance = NULL;

        /**
         * Instance of a crypto helper
         */
        private $cryptoInstance = NULL;

        /**
         * Instance of an Iterator class
         */
        private $iteratorInstance = NULL;

        /**
         * An instance of a InputStream class
         */
        private $inputStreamInstance = NULL;

        /**
         * An instance of a OutputStream class
         */
        private $outputStreamInstance = NULL;

        /**
         * Handler instance
         */
        private $handlerInstance = NULL;

        /**
         * An instance of a database wrapper class
         */
        private $wrapperInstance = NULL;

        /**
         * State instance
         */
        private $stateInstance = NULL;

        /**
         * Call-back instance
         */
        private $callbackInstance = NULL;

        /**
         * Generic array
         */
        private $genericArray = [];

        /***********************
         * Exception codes.... *
         ***********************/

        // @todo Try to clean these constants up
        const EXCEPTION_IS_NULL_POINTER              = 0x001;
        const EXCEPTION_IS_NO_OBJECT                 = 0x002;
        const EXCEPTION_IS_NO_ARRAY                  = 0x003;
        const EXCEPTION_MISSING_METHOD               = 0x004;
        const EXCEPTION_CLASSES_NOT_MATCHING         = 0x005;
        const EXCEPTION_INDEX_OUT_OF_BOUNDS          = 0x006;
        const EXCEPTION_DIMENSION_ARRAY_INVALID      = 0x007;
        const EXCEPTION_ITEM_NOT_TRADEABLE           = 0x008;
        const EXCEPTION_ITEM_NOT_IN_PRICE_LIST       = 0x009;
        const EXCEPTION_GENDER_IS_WRONG              = 0x00a;
        const EXCEPTION_BIRTH_DATE_IS_INVALID        = 0x00b;
        const EXCEPTION_EMPTY_STRUCTURES_ARRAY       = 0x00c;
        const EXCEPTION_HAS_ALREADY_PERSONELL_LIST   = 0x00d;
        const EXCEPTION_NOT_ENOUGTH_UNEMPLOYEES      = 0x00e;
        const EXCEPTION_TOTAL_PRICE_NOT_CALCULATED   = 0x00f;
        const EXCEPTION_HARBOR_HAS_NO_SHIPYARDS      = 0x010;
        const EXCEPTION_CONTRACT_PARTNER_INVALID     = 0x011;
        const EXCEPTION_CONTRACT_PARTNER_MISMATCH    = 0x012;
        const EXCEPTION_CONTRACT_ALREADY_SIGNED      = 0x013;
        const EXCEPTION_UNEXPECTED_EMPTY_STRING      = 0x014;
        const EXCEPTION_PATH_NOT_FOUND               = 0x015;
        const EXCEPTION_INVALID_PATH_NAME            = 0x016;
        const EXCEPTION_READ_PROTECED_PATH           = 0x017;
        const EXCEPTION_WRITE_PROTECED_PATH          = 0x018;
        const EXCEPTION_DIR_POINTER_INVALID          = 0x019;
        const EXCEPTION_FILE_POINTER_INVALID         = 0x01a;
        const EXCEPTION_INVALID_RESOURCE             = 0x01b;
        const EXCEPTION_UNEXPECTED_OBJECT            = 0x01c;
        const EXCEPTION_LIMIT_ELEMENT_IS_UNSUPPORTED = 0x01d;
        const EXCEPTION_GETTER_IS_MISSING            = 0x01e;
        const EXCEPTION_ARRAY_EXPECTED               = 0x01f;
        const EXCEPTION_ARRAY_HAS_INVALID_COUNT      = 0x020;
        const EXCEPTION_ID_IS_INVALID_FORMAT         = 0x021;
        const EXCEPTION_MD5_CHECKSUMS_MISMATCH       = 0x022;
        const EXCEPTION_UNEXPECTED_STRING_SIZE       = 0x023;
        const EXCEPTION_SIMULATOR_ID_INVALID         = 0x024;
        const EXCEPTION_MISMATCHING_COMPRESSORS      = 0x025;
        const EXCEPTION_CONTAINER_ITEM_IS_NULL       = 0x026;
        const EXCEPTION_ITEM_IS_NO_ARRAY             = 0x027;
        const EXCEPTION_CONTAINER_MAYBE_DAMAGED      = 0x028;
        const EXCEPTION_INVALID_STRING               = 0x029;
        const EXCEPTION_VARIABLE_NOT_SET             = 0x02a;
        const EXCEPTION_ATTRIBUTES_ARE_MISSING       = 0x02b;
        const EXCEPTION_ARRAY_ELEMENTS_MISSING       = 0x02c;
        const EXCEPTION_TEMPLATE_ENGINE_UNSUPPORTED  = 0x02d;
        const EXCEPTION_UNSPPORTED_OPERATION         = 0x02e;
        const EXCEPTION_FACTORY_REQUIRE_PARAMETER    = 0x02f;
        const EXCEPTION_MISSING_ELEMENT              = 0x030;
        const EXCEPTION_HEADERS_ALREADY_SENT         = 0x031;
        const EXCEPTION_DEFAULT_CONTROLLER_GONE      = 0x032;
        const EXCEPTION_CLASS_NOT_FOUND              = 0x033;
        const EXCEPTION_REQUIRED_INTERFACE_MISSING   = 0x034;
        const EXCEPTION_FATAL_ERROR                  = 0x035;
        const EXCEPTION_FILE_NOT_FOUND               = 0x036;
        const EXCEPTION_ASSERTION_FAILED             = 0x037;
        const EXCEPTION_FILE_NOT_REACHABLE           = 0x038;
        const EXCEPTION_FILE_CANNOT_BE_READ          = 0x039;
        const EXCEPTION_FILE_CANNOT_BE_WRITTEN       = 0x03a;
        const EXCEPTION_PATH_CANNOT_BE_WRITTEN       = 0x03b;
        const EXCEPTION_DATABASE_UPDATED_NOT_ALLOWED = 0x03c;
        const EXCEPTION_FILTER_CHAIN_INTERCEPTED     = 0x03d;
        const EXCEPTION_INVALID_SOCKET               = 0x03e;
        const EXCEPTION_SELF_INSTANCE                = 0x03f;

        /**
         * Startup time in miliseconds
         */
        private static $startupTime = 0;

        /**
         * Protected super constructor
         *
         * @param       $className      Name of the class
         * @return      void
         */
        protected function __construct (string $className) {
                // Set real class
                $this->setRealClass($className);

                // Is the startup time set? (0 cannot be true anymore)
                if (self::$startupTime == 0) {
                        // Then set it
                        self::$startupTime = microtime(true);
                }
        }

        /**
         * Destructor for all classes. You should not call this method on your own.
         *
         * @return      void
         */
        public function __destruct () {
                // Flush any updated entries to the database
                $this->flushPendingUpdates();

                // Is this object already destroyed?
                if ($this->__toString() != 'DestructedObject') {
                        // Destroy all informations about this class but keep some text about it alive
                        $this->setRealClass('DestructedObject');
                } elseif ((defined('DEBUG_DESTRUCTOR')) && (is_object($this->getDebugInstance()))) {
                        // Already destructed object
                        self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('The object <span class="object_name">%s</span> is already destroyed.',
                                $this->__toString()
                        ));
                } else {
                        // Do not call this twice
                        trigger_error(__METHOD__ . ': Called twice.');
                        exit;
                }
        }

        /**
         * The __call() method where all non-implemented methods end up
         *
         * @param       $methodName             Name of the missing method
         * @args        $args                   Arguments passed to the method
         * @return      void
         */
        public final function __call (string $methodName, array $args = NULL) {
                // Set self-instance
                self::$instance = $this;

                // Call static method
                self::__callStatic($methodName, $args);

                // Clear self-instance
                self::$instance = NULL;
        }

        /**
         * The __callStatic() method where all non-implemented static methods end up
         *
         * @param       $methodName             Name of the missing method
         * @param       $args                   Arguments passed to the method
         * @return      void
         * @throws      InvalidArgumentException If self::$instance is not a framework's own object
         */
        public static final function __callStatic (string $methodName, array $args = NULL) {
                // Init argument string and class name
                //* PRINT-DEBUG: */ printf('[%s:%d]: methodName=%s,args[]=%s - CALLED!' . PHP_EOL, __METHOD__, __LINE__, $methodName, gettype($args));
                $argsString = '';
                $className = 'unknown';

                // Is self-instance set?
                if (self::$instance instanceof FrameworkInterface) {
                        // Framework's own instance
                        $className = self::$instance->__toString();
                } elseif (!is_null(self::$instance)) {
                        // Invalid argument!
                        throw new InvalidArgumentException(sprintf('self::instance[%s] is not expected.', gettype(self::$instance)), self::EXCEPTION_SELF_INSTANCE);
                }

                // Is it NULL, empty or an array?
                if (is_null($args)) {
                        // No arguments
                        $argsString = 'NULL';
                } elseif (is_array($args)) {
                        // Start braces
                        $argsString = '(';

                        // Some arguments are there
                        foreach ($args as $arg) {
                                // Add data about the argument
                                $argsString .= gettype($arg) . ':';

                                if (is_null($arg)) {
                                        // Found a NULL argument
                                        $argsString .= 'NULL';
                                } elseif (is_string($arg)) {
                                        // Add length for strings
                                        $argsString .= strlen($arg);
                                } elseif ((is_int($arg)) || (is_float($arg))) {
                                        // ... integer/float
                                        $argsString .= $arg;
                                } elseif (is_array($arg)) {
                                        // .. or size if array
                                        $argsString .= count($arg);
                                } elseif (is_object($arg)) {
                                        // Get reflection
                                        $reflection = new ReflectionClass($arg);

                                        // Is an other object, maybe no __toString() available
                                        $argsString .= $reflection->getName();
                                } elseif ($arg === true) {
                                        // ... is boolean 'true'
                                        $argsString .= 'true';
                                } elseif ($arg === false) {
                                        // ... is boolean 'false'
                                        $argsString .= 'false';
                                }

                                // Comma for next one
                                $argsString .= ', ';
                        }

                        // Last comma found?
                        if (substr($argsString, -2, 1) == ',') {
                                // Remove last comma
                                $argsString = substr($argsString, 0, -2);
                        }

                        // Close braces
                        $argsString .= ')';
                }

                // Output stub message
                // @TODO __CLASS__ does always return BaseFrameworkSystem but not the extending (=child) class
                self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s::%s]: Stub! Args: %s',
                        $className,
                        $methodName,
                        $argsString
                ));

                // Return nothing
                return NULL;
        }

        /**
         * Getter for $realClass
         *
         * @return      $realClass The name of the real class (not BaseFrameworkSystem)
         */
        public function __toString () {
                return $this->realClass;
        }

        /**
         * Magic method to catch setting of missing but set class fields/attributes
         *
         * @param       $name   Name of the field/attribute
         * @param       $value  Value to store
         * @return      void
         */
        public final function __set (string $name, $value) {
                $this->debugBackTrace(sprintf('Tried to set a missing field. name=%s, value[%s]=%s',
                        $name,
                        gettype($value),
                        print_r($value, true)
                ));
        }

        /**
         * Magic method to catch getting of missing fields/attributes
         *
         * @param       $name   Name of the field/attribute
         * @return      void
         */
        public final function __get (string $name) {
                $this->debugBackTrace(sprintf('Tried to get a missing field. name=%s',
                        $name
                ));
        }

        /**
         * Magic method to catch unsetting of missing fields/attributes
         *
         * @param       $name   Name of the field/attribute
         * @return      void
         */
        public final function __unset (string $name) {
                $this->debugBackTrace(sprintf('Tried to unset a missing field. name=%s',
                        $name
                ));
        }

        /**
         * Magic method to catch object serialization
         *
         * @return      $unsupported    Unsupported method
         * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
         */
        public final function __sleep () {
                throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
        }

        /**
         * Magic method to catch object deserialization
         *
         * @return      $unsupported    Unsupported method
         * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
         */
        public final function __wakeup () {
                throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
        }

        /**
         * Magic method to catch calls when an object instance is called
         *
         * @return      $unsupported    Unsupported method
         * @throws      UnsupportedOperationException   Objects of this framework cannot be serialized
         */
        public final function __invoke () {
                throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
        }

        /**
         * Setter for the real class name
         *
         * @param       $realClass      Class name (string)
         * @return      void
         */
        public final function setRealClass (string $realClass) {
                // Set real class
                $this->realClass = $realClass;
        }

        /**
         * Setter for database result instance
         *
         * @param       $resultInstance         An instance of a database result class
         * @return      void
         * @todo        SearchableResult and UpdateableResult shall have a super interface to use here
         */
        protected final function setResultInstance (SearchableResult $resultInstance) {
                $this->resultInstance =  $resultInstance;
        }

        /**
         * Getter for database result instance
         *
         * @return      $resultInstance         An instance of a database result class
         */
        public final function getResultInstance () {
                return $this->resultInstance;
        }

        /**
         * Setter for debug instance
         *
         * @param       $debugInstance  The instance for debug output class
         * @return      void
         */
        public final function setDebugInstance (DebugMiddleware $debugInstance) {
                GenericRegistry::getRegistry()->addInstance('debug', $debugInstance);
        }

        /**
         * Getter for debug instance
         *
         * @return      $debugInstance  Instance to class DebugConsoleOutput or DebugWebOutput
         */
        public final function getDebugInstance () {
                // Get debug instance
                $debugInstance = GenericRegistry::getRegistry()->getInstance('debug');

                // Return it
                return $debugInstance;
        }

        /**
         * Setter for web output instance
         *
         * @param       $webInstance    The instance for web output class
         * @return      void
         */
        public final function setWebOutputInstance (OutputStreamer $webInstance) {
                GenericRegistry::getRegistry()->addInstance('web_output', $webInstance);
        }

        /**
         * Getter for web output instance
         *
         * @return      $webOutputInstance - Instance to class WebOutput
         */
        public final function getWebOutputInstance () {
                $webOutputInstance = GenericRegistry::getRegistry()->getInstance('web_output');
                return $webOutputInstance;
        }

        /**
         * Protected setter for user instance
         *
         * @param       $userInstance   An instance of a user class
         * @return      void
         */
        protected final function setUserInstance (ManageableAccount $userInstance) {
                $this->userInstance = $userInstance;
        }

        /**
         * Getter for user instance
         *
         * @return      $userInstance   An instance of a user class
         */
        public final function getUserInstance () {
                return $this->userInstance;
        }

        /**
         * Setter for Cryptable instance
         *
         * @param       $cryptoInstance An instance of a Cryptable class
         * @return      void
         */
        protected final function setCryptoInstance (Cryptable $cryptoInstance) {
                $this->cryptoInstance = $cryptoInstance;
        }

        /**
         * Getter for Cryptable instance
         *
         * @return      $cryptoInstance An instance of a Cryptable class
         */
        public final function getCryptoInstance () {
                return $this->cryptoInstance;
        }

        /**
         * Setter for DatabaseWrapper instance
         *
         * @param       $wrapperInstance        An instance of an DatabaseWrapper
         * @return      void
         */
        public final function setWrapperInstance (DatabaseWrapper $wrapperInstance) {
                $this->wrapperInstance = $wrapperInstance;
        }

        /**
         * Getter for DatabaseWrapper instance
         *
         * @return      $wrapperInstance        An instance of an DatabaseWrapper
         */
        public final function getWrapperInstance () {
                return $this->wrapperInstance;
        }

        /**
         * Getter for a InputStream instance
         *
         * @param       $inputStreamInstance    The InputStream instance
         */
        protected final function getInputStreamInstance () {
                return $this->inputStreamInstance;
        }

        /**
         * Setter for a InputStream instance
         *
         * @param       $inputStreamInstance    The InputStream instance
         * @return      void
         */
        protected final function setInputStreamInstance (InputStream $inputStreamInstance) {
                $this->inputStreamInstance = $inputStreamInstance;
        }

        /**
         * Getter for a OutputStream instance
         *
         * @param       $outputStreamInstance   The OutputStream instance
         */
        protected final function getOutputStreamInstance () {
                return $this->outputStreamInstance;
        }

        /**
         * Setter for a OutputStream instance
         *
         * @param       $outputStreamInstance   The OutputStream instance
         * @return      void
         */
        protected final function setOutputStreamInstance (OutputStream $outputStreamInstance) {
                $this->outputStreamInstance = $outputStreamInstance;
        }

        /**
         * Setter for handler instance
         *
         * @param       $handlerInstance        An instance of a Handleable class
         * @return      void
         */
        protected final function setHandlerInstance (Handleable $handlerInstance) {
                $this->handlerInstance = $handlerInstance;
        }

        /**
         * Getter for handler instance
         *
         * @return      $handlerInstance        A Handleable instance
         */
        protected final function getHandlerInstance () {
                return $this->handlerInstance;
        }

        /**
         * Setter for Iterator instance
         *
         * @param       $iteratorInstance       An instance of an Iterator
         * @return      void
         */
        protected final function setIteratorInstance (Iterator $iteratorInstance) {
                $this->iteratorInstance = $iteratorInstance;
        }

        /**
         * Getter for Iterator instance
         *
         * @return      $iteratorInstance       An instance of an Iterator
         */
        public final function getIteratorInstance () {
                return $this->iteratorInstance;
        }

        /**
         * Setter for state instance
         *
         * @param       $stateInstance  A Stateable instance
         * @return      void
         */
        public final function setStateInstance (Stateable $stateInstance) {
                $this->stateInstance = $stateInstance;
        }

        /**
         * Getter for state instance
         *
         * @return      $stateInstance  A Stateable instance
         */
        public final function getStateInstance () {
                return $this->stateInstance;
        }

        /**
         * Setter for call-back instance
         *
         * @param       $callbackInstance       An instance of a FrameworkInterface class
         * @return      void
         */
        public final function setCallbackInstance (FrameworkInterface $callbackInstance) {
                $this->callbackInstance = $callbackInstance;
        }

        /**
         * Getter for call-back instance
         *
         * @return      $callbackInstance       An instance of a FrameworkInterface class
         */
        protected final function getCallbackInstance () {
                return $this->callbackInstance;
        }

        /**
         * Checks whether an object equals this object. You should overwrite this
         * method to implement own equality checks
         *
         * @param       $objectInstance         An instance of a FrameworkInterface object
         * @return      $equals                         Whether both objects equals
         */
        public function equals (FrameworkInterface $objectInstance) {
                // Now test it
                $equals = ((
                        $this->__toString() == $objectInstance->__toString()
                ) && (
                        $this->hashCode() == $objectInstance->hashCode()
                ));

                // Return the result
                return $equals;
        }

        /**
         * Generates a generic hash code of this class. You should really overwrite
         * this method with your own hash code generator code. But keep KISS in mind.
         *
         * @return      $hashCode       A generic hash code respresenting this whole class
         */
        public function hashCode () {
                // Simple hash code
                return crc32($this->__toString());
        }

        /**
         * Appends a trailing slash to a string
         *
         * @param       $str    A string (maybe) without trailing slash
         * @return      $str    A string with an auto-appended trailing slash
         */
        public final function addMissingTrailingSlash ($str) {
                // Is there a trailing slash?
                if (substr($str, -1, 1) != '/') {
                        $str .= '/';
                }

                // Return string with trailing slash
                return $str;
        }

        /**
         * Debugs this instance by putting out it's full content
         *
         * @param       $message        Optional message to show in debug output
         * @return      void
         */
        public final function debugInstance ($message = '') {
                // Restore the error handler to avoid trouble with missing array elements or undeclared variables
                restore_error_handler();

                // Init content
                $content = '';

                // Is a message set?
                if (!empty($message)) {
                        // Construct message
                        $content = sprintf('<div class="debug_message">
        Message: %s
</div>' . PHP_EOL, $message);
                }

                // Generate the output
                $content .= sprintf('<pre>%s</pre>',
                        trim(
                                htmlentities(
                                        print_r($this, true)
                                )
                        )
                );

                // Output it
                ApplicationEntryPoint::exitApplication(sprintf('<div class="debug_header">
        %s debug output:
</div>
<div class="debug_content">
        %s
</div>
Loaded includes:
<div class="debug_include_list">
        %s
</div>',
                        $this->__toString(),
                        $content,
                        ClassLoader::getSelfInstance()->getPrintableIncludeList()
                ));
        }

        /**
         * Replaces control characters with printable output
         *
         * @param       $str    String with control characters
         * @return      $str    Replaced string
         */
        protected function replaceControlCharacters ($str) {
                // Replace them
                $str = str_replace(
                        chr(13), '[r]', str_replace(
                        chr(10), '[n]', str_replace(
                        chr(9) , '[t]',
                        $str
                )));

                // Return it
                return $str;
        }

        /**
         * Output a partial stub message for the caller method
         *
         * @param       $message        An optional message to display
         * @return      void
         */
        protected function partialStub ($message = '') {
                // Init variable
                $stubMessage = 'Partial stub!';

                // Is an extra message given?
                if (!empty($message)) {
                        // Then add it as well
                        $stubMessage .= ' Message: ' . $message;
                }

                // Debug instance is there?
                if (!is_null($this->getDebugInstance())) {
                        // Output stub message
                        self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($stubMessage);
                } else {
                        // Trigger an error
                        trigger_error($stubMessage);
                        exit;
                }
        }

        /**
         * Outputs a debug backtrace and stops further script execution
         *
         * @param       $message        An optional message to output
         * @param       $doExit         Whether exit the program (true is default)
         * @return      void
         */
        public function debugBackTrace ($message = '', $doExit = true) {
                // Sorry, there is no other way getting this nice backtrace
                if (!empty($message)) {
                        // Output message
                        printf('Message: %s<br />' . PHP_EOL, $message);
                }

                print('<pre>');
                debug_print_backtrace();
                print('</pre>');

                // Exit program?
                if ($doExit === true) {
                        exit();
                }
        }

        /**
         * Creates an instance of a debugger instance
         *
         * @param       $className              Name of the class (currently unsupported)
         * @param       $lineNumber             Line number where the call was made
         * @return      $debugInstance  An instance of a debugger class
         * @deprecated  Not fully, as the new Logger facilities are not finished yet.
         */
        public final static function createDebugInstance ($className, $lineNumber = NULL) {
                // Is the instance set?
                if (!GenericRegistry::getRegistry()->instanceExists('debug')) {
                        // Init debug instance
                        $debugInstance = NULL;

                        // Try it
                        try {
                                // Get a debugger instance
                                $debugInstance = DebugMiddleware::createDebugMiddleware(FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('debug_' . FrameworkBootstrap::getRequestTypeFromSystem() . '_class'), $className);
                        } catch (NullPointerException $e) {
                                // Didn't work, no instance there
                                exit(sprintf('Cannot create debugInstance! Exception=%s,message=%s,className=%s,lineNumber=%d' . PHP_EOL, $e->__toString(), $e->getMessage(), $className, $lineNumber));
                        }

                        // Empty string should be ignored and used for testing the middleware
                        DebugMiddleware::getSelfInstance()->output('');

                        // Set it in registry
                        GenericRegistry::getRegistry()->addInstance('debug', $debugInstance);
                } else {
                        // Get instance from registry
                        $debugInstance = GenericRegistry::getRegistry()->getDebugInstance();
                }

                // Return it
                return $debugInstance;
        }

        /**
         * Simple output of a message with line-break
         *
         * @param       $message        Message to output
         * @return      void
         */
        public function outputLine ($message) {
                // Simply output it
                print($message . PHP_EOL);
        }

        /**
         * Outputs a debug message whether to debug instance (should be set!) or
         * dies with or ptints the message. Do NEVER EVER rewrite the exit() call to
         * ApplicationEntryPoint::app_exit(), this would cause an endless loop.
         *
         * @param       $message        Message we shall send out...
         * @param       $doPrint        Whether print or die here (default: print)
         * @paran       $stripTags      Whether to strip tags (default: false)
         * @return      void
         */
        public function debugOutput ($message, $doPrint = true, $stripTags = false) {
                // Set debug instance to NULL
                $debugInstance = NULL;

                // Get backtrace
                $backtrace = debug_backtrace(!DEBUG_BACKTRACE_PROVIDE_OBJECT);

                // Is function partialStub/__callStatic ?
                if (in_array($backtrace[1]['function'], array('partialStub', '__call', '__callStatic'))) {
                        // Prepend class::function:line from 3rd element
                        $message = sprintf('[%s::%s:%d]: %s',
                                $backtrace[2]['class'],
                                $backtrace[2]['function'],
                                (isset($backtrace[2]['line']) ? $backtrace[2]['line'] : '0'),
                                $message
                        );
                } else {
                        // Prepend class::function:line from 2nd element
                        $message = sprintf('[%s::%s:%d]: %s',
                                $backtrace[1]['class'],
                                $backtrace[1]['function'],
                                (isset($backtrace[1]['line']) ? $backtrace[1]['line'] : '0'),
                                $message
                        );
                }

                // Try it:
                try {
                        // Get debug instance
                        $debugInstance = $this->getDebugInstance();
                } catch (NullPointerException $e) {
                        // The debug instance is not set (yet)
                }

                // Is the debug instance there?
                if (is_object($debugInstance)) {
                        // Use debug output handler
                        $debugInstance->output($message, $stripTags);

                        if ($doPrint === false) {
                                // Die here if not printed
                                exit();
                        }
                } else {
                        // Are debug times enabled?
                        if (FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('debug_' . FrameworkBootstrap::getRequestTypeFromSystem() . '_output_timings') == 'Y') {
                                // Prepent it
                                $message = $this->getPrintableExecutionTime() . $message;
                        }

                        // Put directly out
                        if ($doPrint === true) {
                                // Print message
                                $this->outputLine($message);
                        } else {
                                // Die here
                                exit($message);
                        }
                }
        }

        /**
         * Marks up the code by adding e.g. line numbers
         *
         * @param       $phpCode                Unmarked PHP code
         * @return      $markedCode             Marked PHP code
         */
        public function markupCode ($phpCode) {
                // Init marked code
                $markedCode = '';

                // Get last error
                $errorArray = error_get_last();

                // Init the code with error message
                if (is_array($errorArray)) {
                        // Get error infos
                        $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>',
                                basename($errorArray['file']),
                                $errorArray['line'],
                                $errorArray['message'],
                                $errorArray['type']
                        );
                }

                // Add line number to the code
                foreach (explode(chr(10), $phpCode) as $lineNo => $code) {
                        // Add line numbers
                        $markedCode .= sprintf('<span id="code_line">%s</span>: %s' . PHP_EOL,
                                ($lineNo + 1),
                                htmlentities($code, ENT_QUOTES)
                        );
                }

                // Return the code
                return $markedCode;
        }

        /**
         * "Getter" for databse entry
         *
         * @return      $entry  An array with database entries
         * @throws      NullPointerException    If the database result is not found
         * @throws      InvalidDatabaseResultException  If the database result is invalid
         */
        protected final function getDatabaseEntry () {
                // Is there an instance?
                if (!$this->getResultInstance() instanceof SearchableResult) {
                        // Throw an exception here
                        throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
                }

                // Rewind it
                $this->getResultInstance()->rewind();

                // Do we have an entry?
                if ($this->getResultInstance()->valid() === false) {
                        // @TODO Move the constant to e.g. BaseDatabaseResult when there is a non-cached database result available
                        throw new InvalidDatabaseResultException(array($this, $this->getResultInstance()), CachedDatabaseResult::EXCEPTION_INVALID_DATABASE_RESULT);
                }

                // Get next entry
                $this->getResultInstance()->next();

                // Fetch it
                $entry = $this->getResultInstance()->current();

                // And return it
                return $entry;
        }

        /**
         * Getter for field name
         *
         * @param       $fieldName              Field name which we shall get
         * @return      $fieldValue             Field value from the user
         * @throws      NullPointerException    If the result instance is null
         */
        public final function getField (string $fieldName) {
                // Default field value
                $fieldValue = NULL;

                // Get result instance
                $resultInstance = $this->getResultInstance();

                // Is this instance null?
                if (is_null($resultInstance)) {
                        // Then the user instance is no longer valid (expired cookies?)
                        throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
                }

                // Get current array
                $fieldArray = $resultInstance->current();
                //* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($fieldName.':<pre>'.print_r($fieldArray, true).'</pre>');

                // Convert dashes to underscore
                $fieldName2 = StringUtils::convertDashesToUnderscores($fieldName);

                // Does the field exist?
                if ($this->isFieldSet($fieldName)) {
                        // Get it
                        $fieldValue = $fieldArray[$fieldName2];
                } elseif (defined('DEVELOPER')) {
                        // Missing field entry, may require debugging
                        self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']:fieldArray<pre>=' . print_r($fieldArray, true) . '</pre>,fieldName=' . $fieldName . ' not found!');
                } else {
                        // Missing field entry, may require debugging
                        self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . ']:fieldName=' . $fieldName . ' not found!');
                }

                // Return it
                return $fieldValue;
        }

        /**
         * Checks if given field is set
         *
         * @param       $fieldName      Field name to check
         * @return      $isSet          Whether the given field name is set
         * @throws      NullPointerException    If the result instance is null
         */
        public function isFieldSet (string $fieldName) {
                // Get result instance
                $resultInstance = $this->getResultInstance();

                // Is this instance null?
                if (is_null($resultInstance)) {
                        // Then the user instance is no longer valid (expired cookies?)
                        throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER);
                }

                // Get current array
                $fieldArray = $resultInstance->current();
                //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . $this->__toString() . ':' . __LINE__ . '] fieldName=' . $fieldName . ',fieldArray=<pre>'.print_r($fieldArray, true).'</pre>');

                // Convert dashes to underscore
                $fieldName = StringUtils::convertDashesToUnderscores($fieldName);

                // Determine it
                $isSet = isset($fieldArray[$fieldName]);

                // Return result
                return $isSet;
        }

        /**
         * Flushs all pending updates to the database layer
         *
         * @return      void
         */
        public function flushPendingUpdates () {
                // Get result instance
                $resultInstance = $this->getResultInstance();

                // Do we have data to update?
                if ((is_object($resultInstance)) && ($resultInstance->ifDataNeedsFlush())) {
                        // Get wrapper class name config entry
                        $configEntry = $resultInstance->getUpdateInstance()->getWrapperConfigEntry();

                        // Create object instance
                        $wrapperInstance = DatabaseWrapperFactory::createWrapperByConfiguredName($configEntry);

                        // Yes, then send the whole result to the database layer
                        $wrapperInstance->doUpdateByResult($this->getResultInstance());
                }
        }

        /**
         * Outputs a deprecation warning to the developer.
         *
         * @param       $message        The message we shall output to the developer
         * @return      void
         * @todo        Write a logging mechanism for productive mode
         */
        public function deprecationWarning ($message) {
                // Is developer mode active?
                if (defined('DEVELOPER')) {
                        // Debug instance is there?
                        if (!is_null($this->getDebugInstance())) {
                                // Output stub message
                                self::createDebugInstance(__CLASS__, __LINE__)->debugOutput($message);
                        } else {
                                // Trigger an error
                                trigger_error($message . "<br />\n");
                                exit;
                        }
                } else {
                        // @TODO Finish this part!
                        $this->partialStub('Developer mode inactive. Message:' . $message);
                }
        }

        /**
         * Checks whether the given PHP extension is loaded
         *
         * @param       $phpExtension   The PHP extension we shall check
         * @return      $isLoaded       Whether the PHP extension is loaded
         */
        public final function isPhpExtensionLoaded ($phpExtension) {
                // Is it loaded?
                $isLoaded = in_array($phpExtension, get_loaded_extensions());

                // Return result
                return $isLoaded;
        }

        /**
         * "Getter" as a time() replacement but with milliseconds. You should use this
         * method instead of the encapsulated getimeofday() function.
         *
         * @return      $milliTime      Timestamp with milliseconds
         */
        public function getMilliTime () {
                // Get the time of day as float
                $milliTime = gettimeofday(true);

                // Return it
                return $milliTime;
        }

        /**
         * Idles (sleeps) for given milliseconds
         *
         * @return      $hasSlept       Whether it goes fine
         */
        public function idle ($milliSeconds) {
                // Sleep is fine by default
                $hasSlept = true;

                // Idle so long with found function
                if (function_exists('time_sleep_until')) {
                        // Get current time and add idle time
                        $sleepUntil = $this->getMilliTime() + abs($milliSeconds) / 1000;

                        // New PHP 5.1.0 function found, ignore errors
                        $hasSlept = @time_sleep_until($sleepUntil);
                } else {
                        /*
                         * My Sun station doesn't have that function even with latest PHP
                         * package. :(
                         */
                        usleep($milliSeconds * 1000);
                }

                // Return result
                return $hasSlept;
        }

        /**
         * Checks whether the given encoded data was encoded with Base64
         *
         * @param       $encodedData    Encoded data we shall check
         * @return      $isBase64               Whether the encoded data is Base64
         */
        protected function isBase64Encoded ($encodedData) {
                // Determine it
                $isBase64 = (@base64_decode($encodedData, true) !== false);

                // Return it
                return $isBase64;
        }

        /**
         * Gets a cache key from Criteria instance
         *
         * @param       $criteriaInstance       An instance of a Criteria class
         * @param       $onlyKeys                       Only use these keys for a cache key
         * @return      $cacheKey                       A cache key suitable for lookup/storage purposes
         */
        protected function getCacheKeyByCriteria (Criteria $criteriaInstance, array $onlyKeys = []) {
                // Generate it
                //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-FRAMEWORK-SYSTEM: criteriaInstance=' . $criteriaInstance->__toString() . ',onlyKeys()=' . count($onlyKeys) . ' - CALLED!');
                $cacheKey = sprintf('%s@%s',
                        $this->__toString(),
                        $criteriaInstance->getCacheKey($onlyKeys)
                );

                // And return it
                //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-FRAMEWORK-SYSTEM: cacheKey=' . $cacheKey . ' - EXIT!');
                return $cacheKey;
        }

        /**
         * Getter for startup time in miliseconds
         *
         * @return      $startupTime    Startup time in miliseconds
         */
        protected function getStartupTime () {
                return self::$startupTime;
        }

        /**
         * "Getter" for a printable currently execution time in nice braces
         *
         * @return      $executionTime  Current execution time in nice braces
         */
        protected function getPrintableExecutionTime () {
                // Caculate the execution time
                $executionTime = microtime(true) - $this->getStartupTime();

                // Pack it in nice braces
                $executionTime = sprintf('[ %01.5f ] ', $executionTime);

                // And return it
                return $executionTime;
        }

        /**
         * Hashes a given string with a simple but stronger hash function (no salt)
         * and hex-encode it.
         *
         * @param       $str    The string to be hashed
         * @return      $hash   The hash from string $str
         */
        public static final function hash ($str) {
                // Hash given string with (better secure) hasher
                $hash = bin2hex(mhash(MHASH_SHA256, $str));

                // Return it
                return $hash;
        }

        /**
         * "Getter" for length of hash() output. This will be "cached" to speed up
         * things.
         *
         * @return      $length         Length of hash() output
         */
        public static final function getHashLength () {
                // Is it cashed?
                if (is_null(self::$hashLength)) {
                        // No, then hash a string and save its length.
                        self::$hashLength = strlen(self::hash('abc123'));
                }

                // Return it
                return self::$hashLength;
        }

        /**
         * Checks whether the given number is really a number (only chars 0-9).
         *
         * @param       $num            A string consisting only chars between 0 and 9
         * @param       $castValue      Whether to cast the value to double. Do only use this to secure numbers from Requestable classes.
         * @param       $assertMismatch         Whether to assert mismatches
         * @return      $ret            The (hopefully) secured numbered value
         */
        public function bigintval ($num, $castValue = true, $assertMismatch = false) {
                // Filter all numbers out
                $ret = preg_replace('/[^0123456789]/', '', $num);

                // Shall we cast?
                if ($castValue === true) {
                        // Cast to biggest numeric type
                        $ret = (double) $ret;
                }

                // Assert only if requested
                if ($assertMismatch === true) {
                        // Has the whole value changed?
                        assert(('' . $ret . '' != '' . $num . '') && (!is_null($num)));
                }

                // Return result
                return $ret;
        }

        /**
         * Checks whether the given hexadecimal number is really a hex-number (only chars 0-9,a-f).
         *
         * @param       $num    A string consisting only chars between 0 and 9
         * @param       $assertMismatch         Whether to assert mismatches
         * @return      $ret    The (hopefully) secured hext-numbered value
         */
        public function hexval ($num, $assertMismatch = false) {
                // Filter all numbers out
                $ret = preg_replace('/[^0123456789abcdefABCDEF]/', '', $num);

                // Assert only if requested
                if ($assertMismatch === true) {
                        // Has the whole value changed?
                        assert(('' . $ret . '' != '' . $num . '') && (!is_null($num)));
                }

                // Return result
                return $ret;
        }

        /**
         * Determines if an element is set in the generic array
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to check
         * @param       $element        Element to check
         * @return      $isset          Whether the given key is set
         */
        protected final function isGenericArrayElementSet ($keyGroup, $subGroup, $key, $element) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element);

                // Is it there?
                $isset = isset($this->genericArray[$keyGroup][$subGroup][$key][$element]);

                // Return it
                return $isset;
        }
        /**
         * Determines if a key is set in the generic array
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to check
         * @return      $isset          Whether the given key is set
         */
        protected final function isGenericArrayKeySet ($keyGroup, $subGroup, $key) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);

                // Is it there?
                $isset = isset($this->genericArray[$keyGroup][$subGroup][$key]);

                // Return it
                return $isset;
        }


        /**
         * Determines if a group is set in the generic array
         *
         * @param       $keyGroup       Main group
         * @param       $subGroup       Sub group
         * @return      $isset          Whether the given group is set
         */
        protected final function isGenericArrayGroupSet ($keyGroup, $subGroup) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup);

                // Is it there?
                $isset = isset($this->genericArray[$keyGroup][$subGroup]);

                // Return it
                return $isset;
        }

        /**
         * Getter for sub key group
         *
         * @param       $keyGroup       Main key group
         * @param       $subGroup       Sub key group
         * @return      $array          An array with all array elements
         */
        protected final function getGenericSubArray ($keyGroup, $subGroup) {
                // Is it there?
                if (!$this->isGenericArrayGroupSet($keyGroup, $subGroup)) {
                        // No, then abort here
                        trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' not found.');
                        exit;
                }

                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',value=' . print_r($this->genericArray[$keyGroup][$subGroup], true));

                // Return it
                return $this->genericArray[$keyGroup][$subGroup];
        }

        /**
         * Unsets a given key in generic array
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to unset
         * @return      void
         */
        protected final function unsetGenericArrayKey ($keyGroup, $subGroup, $key) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);

                // Remove it
                unset($this->genericArray[$keyGroup][$subGroup][$key]);
        }

        /**
         * Unsets a given element in generic array
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to unset
         * @param       $element        Element to unset
         * @return      void
         */
        protected final function unsetGenericArrayElement ($keyGroup, $subGroup, $key, $element) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element);

                // Remove it
                unset($this->genericArray[$keyGroup][$subGroup][$key][$element]);
        }

        /**
         * Append a string to a given generic array key
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to unset
         * @param       $value          Value to add/append
         * @return      void
         */
        protected final function appendStringToGenericArrayKey ($keyGroup, $subGroup, $key, $value, $appendGlue = '') {
                // Debug message
                //* 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);

                // Is it already there?
                if ($this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
                        // Append it
                        $this->genericArray[$keyGroup][$subGroup][$key] .= $appendGlue . (string) $value;
                } else {
                        // Add it
                        $this->genericArray[$keyGroup][$subGroup][$key] = (string) $value;
                }
        }

        /**
         * Append a string to a given generic array element
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to unset
         * @param       $element        Element to check
         * @param       $value          Value to add/append
         * @return      void
         */
        protected final function appendStringToGenericArrayElement ($keyGroup, $subGroup, $key, $element, $value, $appendGlue = '') {
                // Debug message
                //* 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);

                // Is it already there?
                if ($this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
                        // Append it
                        $this->genericArray[$keyGroup][$subGroup][$key][$element] .= $appendGlue . (string) $value;
                } else {
                        // Add it
                        $this->setStringGenericArrayElement($keyGroup, $subGroup, $key, $element, $value);
                }
        }

        /**
         * Sets a string in a given generic array element
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to unset
         * @param       $element        Element to check
         * @param       $value          Value to add/append
         * @return      void
         */
        protected final function setStringGenericArrayElement ($keyGroup, $subGroup, $key, $element, $value, $appendGlue = '') {
                // Debug message
                //* 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);

                // Set it
                $this->genericArray[$keyGroup][$subGroup][$key][$element] = (string) $value;
        }

        /**
         * Initializes given generic array group
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to use
         * @param       $forceInit      Optionally force initialization
         * @return      void
         */
        protected final function initGenericArrayGroup ($keyGroup, $subGroup, $forceInit = false) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',forceInit=' . intval($forceInit));

                // Is it already set?
                if (($forceInit === false) && ($this->isGenericArrayGroupSet($keyGroup, $subGroup))) {
                        // Already initialized
                        trigger_error(__METHOD__ . ':keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' already initialized.');
                        exit;
                }

                // Initialize it
                $this->genericArray[$keyGroup][$subGroup] = [];
        }

        /**
         * Initializes given generic array key
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to use
         * @param       $forceInit      Optionally force initialization
         * @return      void
         */
        protected final function initGenericArrayKey ($keyGroup, $subGroup, $key, $forceInit = false) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',forceInit=' . intval($forceInit));

                // Is it already set?
                if (($forceInit === false) && ($this->isGenericArrayKeySet($keyGroup, $subGroup, $key))) {
                        // Already initialized
                        trigger_error(__METHOD__ . ':keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' already initialized.');
                        exit;
                }

                // Initialize it
                $this->genericArray[$keyGroup][$subGroup][$key] = [];
        }

        /**
         * Initializes given generic array element
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to use
         * @param       $element        Element to use
         * @param       $forceInit      Optionally force initialization
         * @return      void
         */
        protected final function initGenericArrayElement ($keyGroup, $subGroup, $key, $element, $forceInit = false) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ',forceInit=' . intval($forceInit));

                // Is it already set?
                if (($forceInit === false) && ($this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element))) {
                        // Already initialized
                        trigger_error(__METHOD__ . ':keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ' already initialized.');
                        exit;
                }

                // Initialize it
                $this->genericArray[$keyGroup][$subGroup][$key][$element] = [];
        }

        /**
         * Pushes an element to a generic key
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to use
         * @param       $value          Value to add/append
         * @return      $count          Number of array elements
         */
        protected final function pushValueToGenericArrayKey ($keyGroup, $subGroup, $key, $value) {
                // Debug message
                //* NOISY-DEBUG: */ if (!is_object($value)) $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',value[' . gettype($value) . ']=' . print_r($value, true));

                // Is it set?
                if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
                        // Initialize array
                        $this->initGenericArrayKey($keyGroup, $subGroup, $key);
                }

                // Then push it
                $count = array_push($this->genericArray[$keyGroup][$subGroup][$key], $value);

                // Return count
                //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
                //* DEBUG: */ print(__METHOD__ . ': count=' . $count . PHP_EOL);
                return $count;
        }

        /**
         * Pushes an element to a generic array element
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to use
         * @param       $element        Element to check
         * @param       $value          Value to add/append
         * @return      $count          Number of array elements
         */
        protected final function pushValueToGenericArrayElement ($keyGroup, $subGroup, $key, $element, $value) {
                // Debug message
                //* 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));

                // Is it set?
                if (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
                        // Initialize array
                        $this->initGenericArrayElement($keyGroup, $subGroup, $key, $element);
                }

                // Then push it
                $count = array_push($this->genericArray[$keyGroup][$subGroup][$key][$element], $value);

                // Return count
                //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
                //* DEBUG: */ print(__METHOD__ . ': count=' . $count . PHP_EOL);
                return $count;
        }

        /**
         * Pops an element from  a generic group
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to unset
         * @return      $value          Last "popped" value
         */
        protected final function popGenericArrayElement ($keyGroup, $subGroup, $key) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);

                // Is it set?
                if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
                        // Not found
                        trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' not found.');
                        exit;
                }

                // Then "pop" it
                $value = array_pop($this->genericArray[$keyGroup][$subGroup][$key]);

                // Return value
                //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
                //* DEBUG: */ print(__METHOD__ . ': value[' . gettype($value) . ']=' . print_r($value, true) . PHP_EOL);
                return $value;
        }

        /**
         * Shifts an element from  a generic group
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to unset
         * @return      $value          Last "popped" value
         */
        protected final function shiftGenericArrayElement ($keyGroup, $subGroup, $key) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);

                // Is it set?
                if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
                        // Not found
                        trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' not found.');
                        exit;
                }

                // Then "shift" it
                $value = array_shift($this->genericArray[$keyGroup][$subGroup][$key]);

                // Return value
                //* DEBUG: */ print(__METHOD__ . ': genericArray=' . print_r($this->genericArray[$keyGroup][$subGroup][$key], true));
                //* DEBUG: */ print(__METHOD__ . ': value[' . gettype($value) . ']=' . print_r($value, true) . PHP_EOL);
                return $value;
        }

        /**
         * Count generic array group
         *
         * @param       $keyGroup       Main group for the key
         * @return      $count          Count of given group
         */
        protected final function countGenericArray ($keyGroup) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup);

                // Is it there?
                if (!isset($this->genericArray[$keyGroup])) {
                        // Abort here
                        trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ' not found.');
                        exit;
                }

                // Then count it
                $count = count($this->genericArray[$keyGroup]);

                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',count=' . $count);

                // Return it
                return $count;
        }

        /**
         * Count generic array sub group
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @return      $count          Count of given group
         */
        protected final function countGenericArrayGroup ($keyGroup, $subGroup) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup);

                // Is it there?
                if (!$this->isGenericArrayGroupSet($keyGroup, $subGroup)) {
                        // Abort here
                        trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' not found.');
                        exit;
                }

                // Then count it
                $count = count($this->genericArray[$keyGroup][$subGroup]);

                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',count=' . $count);

                // Return it
                return $count;
        }

        /**
         * Count generic array elements
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @para        $key            Key to count
         * @return      $count          Count of given key
         */
        protected final function countGenericArrayElements ($keyGroup, $subGroup, $key) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);

                // Is it there?
                if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
                        // Abort here
                        trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' not found.');
                        exit;
                } elseif (!$this->isValidGenericArrayGroup($keyGroup, $subGroup)) {
                        // Not valid
                        trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ' is not an array.');
                        exit;
                }

                // Then count it
                $count = count($this->genericArray[$keyGroup][$subGroup][$key]);

                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',count=' . $count);

                // Return it
                return $count;
        }

        /**
         * Getter for whole generic group array
         *
         * @param       $keyGroup       Key group to get
         * @return      $array          Whole generic array group
         */
        protected final function getGenericArray ($keyGroup) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup);

                // Is it there?
                if (!isset($this->genericArray[$keyGroup])) {
                        // Then abort here
                        trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ' does not exist.');
                        exit;
                }

                // Return it
                return $this->genericArray[$keyGroup];
        }

        /**
         * Setter for generic array key
         *
         * @param       $keyGroup       Key group to get
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to unset
         * @param       $value          Mixed value from generic array element
         * @return      void
         */
        protected final function setGenericArrayKey ($keyGroup, $subGroup, $key, $value) {
                // Debug message
                //* NOISY-DEBUG: */ if (!is_object($value)) $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',value[' . gettype($value) . ']=' . print_r($value, true));

                // Set value here
                $this->genericArray[$keyGroup][$subGroup][$key] = $value;
        }

        /**
         * Getter for generic array key
         *
         * @param       $keyGroup       Key group to get
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to unset
         * @return      $value          Mixed value from generic array element
         */
        protected final function getGenericArrayKey ($keyGroup, $subGroup, $key) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);

                // Is it there?
                if (!$this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) {
                        // Then abort here
                        trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ' does not exist.');
                        exit;
                }

                // Return it
                return $this->genericArray[$keyGroup][$subGroup][$key];
        }

        /**
         * Sets a value in given generic array key/element
         *
         * @param       $keyGroup       Main group for the key
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to set
         * @param       $element        Element to set
         * @param       $value          Value to set
         * @return      void
         */
        protected final function setGenericArrayElement ($keyGroup, $subGroup, $key, $element, $value) {
                // Debug message
                //* 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));

                // Then set it
                $this->genericArray[$keyGroup][$subGroup][$key][$element] = $value;
        }

        /**
         * Getter for generic array element
         *
         * @param       $keyGroup       Key group to get
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to look for
         * @param       $element        Element to look for
         * @return      $value          Mixed value from generic array element
         */
        protected final function getGenericArrayElement ($keyGroup, $subGroup, $key, $element) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element);

                // Is it there?
                if (!$this->isGenericArrayElementSet($keyGroup, $subGroup, $key, $element)) {
                        // Then abort here
                        trigger_error(__METHOD__ . ': keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key . ',element=' . $element . ' does not exist.');
                        exit;
                }

                // Return it
                return $this->genericArray[$keyGroup][$subGroup][$key][$element];
        }

        /**
         * Checks if a given sub group is valid (array)
         *
         * @param       $keyGroup       Key group to get
         * @param       $subGroup       Sub group for the key
         * @return      $isValid        Whether given sub group is valid
         */
        protected final function isValidGenericArrayGroup ($keyGroup, $subGroup) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup);

                // Determine it
                $isValid = (($this->isGenericArrayGroupSet($keyGroup, $subGroup)) && (is_array($this->getGenericSubArray($keyGroup, $subGroup))));

                // Return it
                return $isValid;
        }

        /**
         * Checks if a given key is valid (array)
         *
         * @param       $keyGroup       Key group to get
         * @param       $subGroup       Sub group for the key
         * @param       $key            Key to check
         * @return      $isValid        Whether given sub group is valid
         */
        protected final function isValidGenericArrayKey ($keyGroup, $subGroup, $key) {
                // Debug message
                //* NOISY-DEBUG: */ $this->outputLine('[' . __METHOD__ . ':' . __LINE__ . '] keyGroup=' . $keyGroup . ',subGroup=' . $subGroup . ',key=' . $key);

                // Determine it
                $isValid = (($this->isGenericArrayKeySet($keyGroup, $subGroup, $key)) && (is_array($this->getGenericArrayKey($keyGroup, $subGroup, $key))));

                // Return it
                return $isValid;
        }

        /**
         * Initializes the web output instance
         *
         * @return      void
         */
        protected function initWebOutputInstance () {
                // Get application instance
                $applicationInstance = GenericRegistry::getRegistry()->getInstance('application');

                // Init web output instance
                $outputInstance = ObjectFactory::createObjectByConfiguredName('output_class', array($applicationInstance));

                // Set it locally
                $this->setWebOutputInstance($outputInstance);
        }

        /**
         * Translates boolean true to 'Y' and false to 'N'
         *
         * @param       $boolean                Boolean value
         * @return      $translated             Translated boolean value
         */
        public static final function translateBooleanToYesNo (bool $boolean) {
                // Make sure it is really boolean
                assert(is_bool($boolean));

                // "Translate" it
                $translated = ($boolean === true) ? 'Y' : 'N';

                // ... and return it
                return $translated;
        }

        /**
         * Creates a full-qualified file name (FQFN) for given file name by adding
         * a configured temporary file path to it.
         *
         * @param       $infoInstance   An instance of a SplFileInfo class
         * @return      $tempInstance   An instance of a SplFileInfo class (temporary file)
         * @throw       PathWriteProtectedException If the path in 'temp_file_path' is write-protected
         * @throws      FileIoException If the file cannot be written
         */
         protected static function createTempPathForFile (SplFileInfo $infoInstance) {
                // Get config entry
                $basePath = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('temp_file_path');

                // Is the path writeable?
                if (!is_writable($basePath)) {
                        // Path is write-protected
                        throw new PathWriteProtectedException($infoInstance, self::EXCEPTION_PATH_CANNOT_BE_WRITTEN);
                }

                // Add it
                $tempInstance = new SplFileInfo($basePath . DIRECTORY_SEPARATOR . $infoInstance->getBasename());

                // Is it reachable?
                if (!FrameworkBootstrap::isReachableFilePath($tempInstance)) {
                        // Not reachable
                        throw new FileIoException($tempInstance, self::EXCEPTION_FILE_NOT_REACHABLE);
                }

                // Return it
                return $tempInstance;
         }

        /**
         * "Getter" for a printable state name
         *
         * @return      $stateName      Name of the node's state in a printable format
         */
        public final function getPrintableState () {
                // Default is 'null'
                $stateName = 'null';

                // Get the state instance
                $stateInstance = $this->getStateInstance();

                // Is it an instance of Stateable?
                if ($stateInstance instanceof Stateable) {
                        // Then use that state name
                        $stateName = $stateInstance->getStateName();
                }

                // Return result
                return $stateName;
        }

}