From 0ffd98d58a9add40b642e9888f6f4d57a58ed4b5 Mon Sep 17 00:00:00 2001 From: Roland Haeder Date: Wed, 27 May 2015 03:17:43 +0200 Subject: [PATCH] Added new FrameworkFeature class + missing exception: - Features can be enabled or disabled by the user - Their availability depends on if the feature is enabled and if all requirements are found. This can be anything like loaded PHP extensions (PECL) or anything else. - Features can have methods that can be called (publicly) where their actual "feature" is being written. - This can be again a class with static or non-static methods that will be called. - Generally feature classes shall not contain the actual implementation, they shall only call implementing classes. - So basicly a feature class "hides" the actual implementation and can be understood as a generic facade. MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Roland Häder --- contrib/mindmaps/Local File Database - NG.mm | 1330 +++++++++-------- ...ss_ConfigValueTypeUnsupportedException.php | 49 + inc/classes/exceptions/feature/.htaccess | 1 + ...lass_FeatureMethodNotCallableException.php | 46 + inc/classes/interfaces/feature/.htaccess | 1 + .../interfaces/feature/class_Feature.php | 34 + inc/classes/main/feature/.htaccess | 1 + inc/classes/main/feature/class_ | 68 + .../main/feature/class_BaseFeature.php | 38 + .../main/feature/class_FrameworkFeature.php | 160 ++ 10 files changed, 1089 insertions(+), 639 deletions(-) create mode 100644 inc/classes/exceptions/config/class_ConfigValueTypeUnsupportedException.php create mode 100644 inc/classes/exceptions/feature/.htaccess create mode 100644 inc/classes/exceptions/feature/class_FeatureMethodNotCallableException.php create mode 100644 inc/classes/interfaces/feature/.htaccess create mode 100644 inc/classes/interfaces/feature/class_Feature.php create mode 100644 inc/classes/main/feature/.htaccess create mode 100644 inc/classes/main/feature/class_ create mode 100644 inc/classes/main/feature/class_BaseFeature.php create mode 100644 inc/classes/main/feature/class_FrameworkFeature.php diff --git a/contrib/mindmaps/Local File Database - NG.mm b/contrib/mindmaps/Local File Database - NG.mm index 55d1a8a9..b125ac9a 100644 --- a/contrib/mindmaps/Local File Database - NG.mm +++ b/contrib/mindmaps/Local File Database - NG.mm @@ -1,7 +1,8 @@ - - - - + + + + + @@ -16,1064 +17,1115 @@ Short name: LFDB2

- Work in progress! + Work in progress!

+ - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + - - + + - - + + - - + - + - - + + - + + - - + + - - - + + - + - + - + - + - + - - + + - + - - + + - + + - - + - + + - - + - - + + - - + + - + - - + + - + - - + + - + + - - + + - - + - + - + - + - + - + - + - + - + + - - - - + + + - + - + - + - + - + - + - + - + - - + + - + + - - + + - - + + - - + + - - + + - - + - + - + - - - + + + - + - - + + - + - - - - + + + + - + - - - + + + - - - + + + - + - + - + - - + + - + + - - - - - - - - + + + + + + - + + - - - + + + - + - + - + - + - - + - + + - - + + - + - + - - + + - - - - + + + + - - + + - - - - - - - - - - - - + + + + + + + + + + + + - - - + + + - - - + + + - - - - + + + + - + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - + + + + + + + - - + + - - - + + + - - - - - - - + + + + + + + - + - - - + + + - - - - - - - - - - - + + + + + + + + + + + - - - + + + - - - - - - + + + + + + - + - - + + - - - + + + - + - + - + - - + + - + - + - + - + - + - + - + - + - - + + - - - - + + + + - + - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + - + - - + + - + - + + - - - - - - - - - - + + + + + + + + + - - - - + + + + - - - - - - + + + + + + - - - - - + + + + + - - - - + + + + - - - + + + - - - - + + + + - - - + + + - - - + + + - - - - - - + + + + + + - - - + + + - + - - - - - + + + + + - - - - + + + + - + - - - - + + + + - - - - - + + + + + - + - - - - - - + + + + + + - - - + + + - + - - - + + + - - + + - + - - - + + + - + - + - - - - - - - - + + + + + + + + - - + + - - - - + + + + - - - - + + + + - + - + - - - - - + + + + + - - - - + + + + - - - - - + + + + + - - + + - + - + - - - + + + - + - - - - - - + + + + + + - - - - + + + + - - - - + + + + - - - - + + + + - + - + - - + + - - - + + + - + - - - - - + + + + + - + - - - - + + + + - - - + + + - - - - + + + + - - + + - - - - - + + + + + - - + + - - + + - + - - - - - - - - - - + + + + + + + + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - - - - - - + + + + + + + - - + + - + - - - - - - - + + + + + + + + - - - - - + + + + - - + + - - - + + + - - + + - - - - - + + + + + - - - + + + - - - + + + - - + + - - - - + + + + - - - - - - - + + + + + + + - + - - - - + + + + - - - + + + - - - + + + - + - - - + + + - - - - - - - + + + + + + + - - - + + + - - - + + + - - + + - - + + - + + - - + + - - + + - - - + - - + + + diff --git a/inc/classes/exceptions/config/class_ConfigValueTypeUnsupportedException.php b/inc/classes/exceptions/config/class_ConfigValueTypeUnsupportedException.php new file mode 100644 index 00000000..b39fc811 --- /dev/null +++ b/inc/classes/exceptions/config/class_ConfigValueTypeUnsupportedException.php @@ -0,0 +1,49 @@ + + * @version 0.0.0 + * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2015 Core Developer Team + * @license GNU GPL 3.0 or any newer version + * @link http://www.ship-simu.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 . + */ +class ConfigValueTypeUnsupportedException extends FrameworkException { + /** + * The super constructor for all exceptions + * + * @param $message Message data array + * @param $code Error code + * @return void + */ + public function __construct (array $messageArray, $code) { + // Construct message + $message = sprintf('[%s:%d] Configuration key %s has unspported value type %s.', + $messageArray[0]->__toString(), + $this->getLine(), + $messageArray[1], + gettype($messageArray[2]) + ); + + // Call parent exception constructor + parent::__construct($message, $code); + } +} + +// [EOF] +?> diff --git a/inc/classes/exceptions/feature/.htaccess b/inc/classes/exceptions/feature/.htaccess new file mode 100644 index 00000000..3a428827 --- /dev/null +++ b/inc/classes/exceptions/feature/.htaccess @@ -0,0 +1 @@ +Deny from all diff --git a/inc/classes/exceptions/feature/class_FeatureMethodNotCallableException.php b/inc/classes/exceptions/feature/class_FeatureMethodNotCallableException.php new file mode 100644 index 00000000..5a7224b7 --- /dev/null +++ b/inc/classes/exceptions/feature/class_FeatureMethodNotCallableException.php @@ -0,0 +1,46 @@ + + * @version 0.0.0 + * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2015 Core Developer Team + * @license GNU GPL 3.0 or any newer version + * @link http://www.ship-simu.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 . + */ +class FeatureMethodNotCallableException extends FrameworkException { + /** + * The super constructor for all exceptions + * + * @param $messageArray Error message array + * @param $code Error code + * @return void + */ + public function __construct (array $messageArray, $code) { + // Construct message + $message = sprintf('[%s:%d] Method %s cannot be called.', + $messageArray[0], + $this->getLine(), + $messageArray[1] + ); + + // Call parent exception constructor + parent::__construct($message, $code); + } +} + +// [EOF] +?> diff --git a/inc/classes/interfaces/feature/.htaccess b/inc/classes/interfaces/feature/.htaccess new file mode 100644 index 00000000..3a428827 --- /dev/null +++ b/inc/classes/interfaces/feature/.htaccess @@ -0,0 +1 @@ +Deny from all diff --git a/inc/classes/interfaces/feature/class_Feature.php b/inc/classes/interfaces/feature/class_Feature.php new file mode 100644 index 00000000..9fa497fe --- /dev/null +++ b/inc/classes/interfaces/feature/class_Feature.php @@ -0,0 +1,34 @@ + + * @version 0.0.0 + * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2015 Core Developer Team + * @license GNU GPL 3.0 or any newer version + * @link http://www.ship-simu.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 . + */ +interface Feature extends FrameworkInterface { + /** + * Checks whether this feature can be made available to other classes. + * + * @return $isAvailable Whether this feature is available + */ + function isFeatureAvailable (); +} + +// [EOF] +?> diff --git a/inc/classes/main/feature/.htaccess b/inc/classes/main/feature/.htaccess new file mode 100644 index 00000000..3a428827 --- /dev/null +++ b/inc/classes/main/feature/.htaccess @@ -0,0 +1 @@ +Deny from all diff --git a/inc/classes/main/feature/class_ b/inc/classes/main/feature/class_ new file mode 100644 index 00000000..1a9b0f0c --- /dev/null +++ b/inc/classes/main/feature/class_ @@ -0,0 +1,68 @@ + + * @version 0.0.0 + * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2015 Core Developer Team + * @license GNU GPL 3.0 or any newer version + * @link http://www.ship-simu.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 . + */ +class ???Feature extends BaseFeature implements Feature { + /** + * Protected constructor + * + * @return void + */ + protected function __construct () { + // Call parent constructor + parent::__construct(__CLASS__); + } + + /** + * Creates an instance of this Feature class and prepares it for usage + * + * @param $appInstance A manageable application + * @return $featureInstance An instance of this Feature class + */ + public final static function create???Feature (ManageableApplication $appInstance) { + // Get a new instance + $featureInstance = new ???Feature(); + + // Return the prepared instance + return $featureInstance; + } + + /** + * Checks whether this feature can be made available to other classes. + * + * @return $isAvailable Whether this feature is available + * @todo 0% done + */ + public function isFeatureAvailable () { + // Default is not available + $isAvailable = FALSE; + + // Unfinished: + $this->partialSub('Please implement this method.'); + + // Return status + return $isAvailable; + } +} + +// [EOF] +?> diff --git a/inc/classes/main/feature/class_BaseFeature.php b/inc/classes/main/feature/class_BaseFeature.php new file mode 100644 index 00000000..11870cff --- /dev/null +++ b/inc/classes/main/feature/class_BaseFeature.php @@ -0,0 +1,38 @@ + + * @version 0.0.0 + * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2015 Core Developer Team + * @license GNU GPL 3.0 or any newer version + * @link http://www.ship-simu.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 . + */ +class BaseFeature extends BaseFrameworkSystem { + /** + * Protected constructor + * + * @param $className Name of the class + * @return void + */ + protected function __construct ($className) { + // Call parent constructor + parent::__construct($className); + } +} + +// [EOF] +?> diff --git a/inc/classes/main/feature/class_FrameworkFeature.php b/inc/classes/main/feature/class_FrameworkFeature.php new file mode 100644 index 00000000..46d61ff0 --- /dev/null +++ b/inc/classes/main/feature/class_FrameworkFeature.php @@ -0,0 +1,160 @@ + + * @version 0.0.0 + * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2015 Core Developer Team + * @license GNU GPL 3.0 or any newer version + * @link http://www.ship-simu.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 . + */ +class FrameworkFeature extends BaseFrameworkSystem implements Feature { + // Exception code constants + const EXCEPTION_FEATURE_METHOD_NOT_CALLABLE = 0x400; + + /** + * "Cache" for enabled, available feature instances + * + * A typical available entry looks like this: + * + * array( + * 'is_enabled' => TRUE, + * 'is_available' => TRUE, + * 'instance' => SomeFeature Object + * ) + * + * And a typical disabled entry looks like this: + * + * array( + * 'is_enabled' => FALSE, + * 'is_available' => FALSE, + * 'instance' => NULL + * ) + */ + private static $enabledFeatures = array(); + + /** + * Protected constructor + * + * @return void + */ + protected function __construct () { + // Call parent constructor + parent::__construct(__CLASS__); + } + + /** + * Checks whether the given feature is enabled in configuration. The user + * shall be able to disable features, even when they *could* be available. + * + * @param $featureName Name of the feature to be checked + * @return $isEnabled Whether the given feature is enabled + */ + public static function isFeatureEnabled ($featureName) { + // Is the cache set? + if (!isset(self::$enabledFeatures[$featureName]['is_enabled'])) { + // Generate config key + $configKey = sprintf('enable_feature_%s', $featureName); + + // Check configuration + self::$enabledFeatures[$featureName]['is_enabled'] = (FrameworkConfiguration::getSelfInstance()->getConfigEntry($configKey) === 'Y'); + } // END - if + + // Return "cached" status + return self::$enabledFeatures[$featureName]['is_enabled']; + } + + /** + * Checks whether the given feature is enabled and available. It may be + * enabled by the user, but is not available due to e.g. a missing PECL + * extension or whatever is needed to have this feature available. If you + * don't write a pre filters for checking PHP requirements, this is the + * method you want to use. + * + * @param $featureName Name of the feature to be checked on availability + * @return $isAvailable Whether the given feature is available + */ + public static function isFeatureAvailable ($featureName) { + // Is the cache set? + if (!isset(self::$enabledFeatures[$featureName]['is_available'])) { + // Default is not available + self::$enabledFeatures[$featureName]['is_available'] = FALSE; + self::$enabledFeatures[$featureName]['instance'] = NULL; + + // Is the feature enabled? + if (!self::isFeatureEnabled($featureName)) { + // Then it can't be available + return FALSE; + } // END - if + + // Create config key (for feature class lookup) + $configKey = sprintf('feature_%s_class', $featureName); + + // Now try to get the instance + try { + // Try to get an instance + self::$enabledFeatures[$featureName]['instance'] = ObjectFactory::createObjectByConfiguredName($configKey); + + // Now let the feature test itself's availability + self::$enabledFeatures[$featureName]['is_available'] = self::$enabledFeatures[$featureName]['instance']->isFeatureAvailable(); + } catch (NoClassException $e) { + // Feature class not found + self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d]: Feature %s not available due to missing feature class. Disabling feature ...', __METHOD__, __LINE__, $featureName)); + } + } // END - if + + // Return "cached" status + return self::$enabledFeatures[$featureName]['is_available']; + } + + /** + * Calls the feature's method and handles some arguments (if not given, + * NULL) to it. Any returned value is being forwarded to the caller, even + * when the doc-tag says 'void' as returned value. + * + * @param $featureName Name of the feature, it must be available at this point + * @param $featureMethod Method name of the feature's class + * @param $args Any arguments that should be handled over + * @return $return Anything the feature's method has returned + * @throws FeatureMethodNotCallableException If the requested method cannot be called + */ + public static function callFeature ($featureName, $featureMethod, array $args = NULL) { + /* + * Please make sure that isFeatureAvailable() has been called and it has + * returned TRUE before calling this method. + */ + assert(self::isFeatureAvailable($featureName)); + + // Array for call-back + $callable = array(self::$enabledFeatures[$featureName]['instance'], $featureMethod); + + // So is the feature's method callable? + if (!is_callable($callable)) { + // Not callable method requested + throw new FeatureMethodNotCallableException(array(self::$enabledFeatures[$featureName]['instance'], $featureMethod), self::EXCEPTION_FEATURE_METHOD_NOT_CALLABLE); + } // END - if + + // Then call it + $return = call_user_func_array($callable, $args); + + // Return any returned value + return $return; + } +} + +// [EOF] +?> -- 2.30.2