Author: tchemit Date: 2013-07-19 19:39:44 +0200 (Fri, 19 Jul 2013) New Revision: 2585 Url: http://nuiton.org/projects/nuiton-utils/repository/revisions/2585 Log: fixes #2778: Remove all deprecated code in the nuiton-utils module Removed: trunk/nuiton-utils/src/site/apt/ApplicationConfig.apt Modified: trunk/nuiton-utils/src/site/apt/index.apt Deleted: trunk/nuiton-utils/src/site/apt/ApplicationConfig.apt =================================================================== --- trunk/nuiton-utils/src/site/apt/ApplicationConfig.apt 2013-07-19 17:37:58 UTC (rev 2584) +++ trunk/nuiton-utils/src/site/apt/ApplicationConfig.apt 2013-07-19 17:39:44 UTC (rev 2585) @@ -1,378 +0,0 @@ - ---- - ApplicationConfig - ---- - ---- - 2010-02-23 - ---- - -~~~ -~~ #%L -~~ Nuiton Utils -~~ -~~ $Id$ -~~ $HeadURL$ -~~ %% -~~ Copyright (C) 2004 - 2011 CodeLutin, Chatellier Eric -~~ %% -~~ This program is free software: you can redistribute it and/or modify -~~ it under the terms of the GNU Lesser 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 Lesser Public License for more details. -~~ -~~ You should have received a copy of the GNU General Lesser Public -~~ License along with this program. If not, see -~~ <http://www.gnu.org/licenses/lgpl-3.0.html>. -~~ #L% -~~~ - - -Présentation - - La classe ApplicationConfig a pour but de gérer les options et action - disponible au sein d'une application. Elle gère aussi bien : - - * la lecture de fichier de configuration - - * le parsage de la ligne de commande - - * l'execution des actions - - * la sauvegarde de la configuration - - -Lecture/écriture - -* Lecture des fichiers de configuration - - La lecture des fichiers de configuration est effectuées lors de l'appel - à la methode <<<parse(String...)>>> en utilisant la valeur de - <<<getConfigFileName()>>> pour trouver les fichiers à lire. - -* La sauvegarde - - La sauvegarde des options se fait via une des trois methodes disponibles : - - * <<<save>>> : sauvegarde dans un fichier specifique - - * <<<saveForSystem>>> : sauvegarde les donnees dans /etc - - * <<<saveForUser>>> : sauvegarde les donnees dans $HOME - - [] - - Seules les options qui ont été modifiées par l'application (par la methode - <<<setOption()>>> seront sauvegardée. Les variable d'envirronement, les - arguments de la ligne de commandes(etc...) ne seront pas sauvegardées. - -* Configuration multi instance - - Il est possible d'associé un nom de contexte a une configuration via la - methode <<<setAppName("azerty")>>>. Ainsi, les fichiers seront cherchés - dans le dossier définit par l'option <<<azerty.config.path>>> si elle existe - (sinon, dans le dossier par defaut) et le nom du fichier cherché defini - par l'option <<<azerty.config.file>>>. - - Cett option est utilise par exemple pour installer plusieurs instance - d'application dans un serveur web et que chaque instance aille - chercher ses fichiers de configuration à son propre endroit. - -Fonctionnalités - -* Les options de configuration - - L'ordre de prise en compte des options suivant les différentes sources est - le suivant : - - * Option renseignées par programmation - - * Ligne de commandes - - * Propriétés systèmes (System.getProperties()) - - * Propriétés d'envirronement (System.getenv()) - - * Fichier du dossier courant ( ./ + nom du fichier) - - * Fichier de configuration globale ( /etc/ + nom du fichier) - - * Fichier dans le classpath ( / + nom du fichier) - - * Valeur par défaut (renseignés à l'init) - - [] - - Cela signifie par exemple que si une option à une valeur par défaut, est renseignée - dans le fichier /etc et sur la ligne de commande, la valeur presente sur la - ligne de commande sera prise en compte. - -* Les actions - - Les actions ne peuvent être renseignées que sur la ligne de commande. Exemple : - -+------------------------------------------------ ---org.nuiton.test.Test#doLogin user password true -+------------------------------------------------ - - Une action est donc définie par le chemin complet de la methode qui traitera - l'action. Si la methode est statique, elle sera appelée directement. Dans le - cas contraire, la classe contenant la methode sera instancié à partir - d'un constructeur prenant en parametre seulement la configuration, ou, s'il - n'est pas disponible, le constructeur par defaut. La methode sera ensuite - appelée sur cette instance. Les divers instances sont conservés pour effectué - plusieurs actions. - - Les arguments de la methode sont utilisé lors de l'appel. On sont convertit - dans le bon type. Si la méthode avec des arguments de taille variante (...) - tous les arguments jusqu'a la prochaine option ou à la fin de la ligne - seront utilisé. - - Si vous avez des parametres optionnels, le seul moyen est d'utiliser des - arguments variant. - - Par exemple, la ligne de commande précédente appelera la methode - -+------------------------------------------- -public class Test { - public goLogin(String login, String password, boolean dryRun) { - [...] - } -} -+------------------------------------------- - - Les actions ne sont pas executées, mais seulement parsées. Cela signifie - qu'elles seront executées seulement lorsque l'application appelera la méthode - <<<doAction(int)>>>. - Par defaut, toutes les actions sont de niveau 0 et sont executées dans leur - ordre d'apparition sur la ligne de commande. - Il est possible de differencier les differentes action en utilisant l'annotation - <<<@Step>>> - -+------------------------------------------- -doAction(0); -... do something ... -doAction(1); -+------------------------------------------- - - Dans cet exemple, les actions 0 et 1 ne sont pas effectuées au même moment. - C'est très utile par exemple pour executer certaines actions avant le démarrage - de l'UI par exemple, et d'autre après... - -* Les arguments non parsées - - La configuration 'consome' les arguments de la ligne de commande qu'elle a - réussie a traiter. Pour recuperer les autres arguments propres à l'application - il est possible de les obtenir grace à la méthode <<<getUnparsed()>>>. - Si l'on souhaite forcer la fin du parsing de la ligne de commande il est - possible de mettre <<<-->>>. - - Par exemple, la ligne suivante : - -+------------------------------------------- -monApplication "mon arg" --option k1 v1 -- --option k2 v2 -- autre -+------------------------------------------- - - Renvera la liste suivante via <<<getUnparsed()>>> : - -+------------------------------------------- -"mon arg", "--option", "k2", "v2", "--", "autre" -+------------------------------------------- - -* Les alias - - Il est possible d'utiliser des alias pour definir les options et les actions. - Ces alias doivent être renseignés par la methode <<<addAlias(String, String>>>: - -+------------------------------------------- -addAlias("-v", "--option", "verbose", "true"); -addAlias("-o", "--option", "outputfile"); -addAlias("-i", "--mon.package.MaClass#MaMethode", "import"); -+------------------------------------------- - - Lors du parsing de la ligne de commande, tous les alias sont remplacé par - leur correspondance. Il est donc possible d'utiliser ce mecanisme pour - autre chose : - -+------------------------------------------- -addAlias("cl", "Code Lutin"); -+------------------------------------------- - - Dans le premier exemple on simplifie une option de flags l'option -v n'attend - donc plus d'argument. Dans le second exemple on simplifie une option qui - attend encore un argment de type File. Enfin dans le troisieme exemple - on simplifie la syntaxe d'une action et on force le premier argument de - l'action a etre "import". - - -* Conversion de type - - Pour convertir les types des options et arguments de methodes, - {{{http://commons.apache.org/beanutils/}commons-beanutils}} est utilisé. - - Les types actuellement supporté sont : - - * <<<java.lang.String>>> - - * <<<java.io.File>>> - - * <<<java.net.URL>>> - - * <<<java.lang.Class>>> - - * <<<java.sql.Date>>> - - * <<<java.sql.Time>>> - - * <<<java.sql.Timestamp>>> - - * Les tableaux d'un type primitif ou {@link String}. Chaque élément doit - être séparé par une virgule. - - [] - - Pour utiliser d'autre type, il suffit de le enregistrer dans beanutils via - la mézthode <<<ConvertUtils.register(Converter, Class)>>> - -* Les substitutions de variable - - La configuration de variable supporte la substitution par d'autre variable - via la synthaxe <<<$\{xxx\}>>> où <<<xxx>>> est une autre variable de - la configuration - - Par exemple (fichier de configuration): - -+------------------------------------------- -application.name = Mon Appli -application.version = 1.2.3 -application.info = ${application.name} ${application.version} (${java.version}) -+------------------------------------------- - - L'appel de l'option <<<application.info>>> via la methode <<<getOption()>>> - retournera une chaine de la forme: - -+------------------------------------------- -Mon Appli 1.2.3 (1.6.0_18) -+------------------------------------------- - - À noter que les substitutions ne sont remplacée qu'a leur lecture, la sauvegarde - de l'option <<<application.info>>> se fera sans remplacement. - -Mise en oeuvre - -* Définition - - Voici l'ensemble des tâches à effectuer pour définir une configuration - d'application : - - * Creation d'une sous classes d'<<<ApplicationConfig>>> - - * Ajout des options par défaut - - * Creation des classes et méthodes d'actions - - * Déclaration des alias des options et actions - - [] - - Exemple : - -+------------------------------------------- -public class MyConfig extends ApplicationConfig { - - public final static int AFTER_LOGIN = 1; - - public MyConfig () { - // options par defaut - setDefaultOption("user", "anonymous"); - setDefaultOption("password", ""); - // ajout des alias - addAlias("-u", "--user"); - addAlias("-p", "--password"); - addActionAlias("--login", MyConfig.class.getName + "#" + doLogin"); - } - - public void setUser(String user) { - setOption("user", user); - } - - public void setUser(String user) { - setOption("user", user); - } - - public void doLogin(String user, String password) { - [...] - } - - @Step(AFTER_LOGIN) - public void doSomething() { - [...] - } -} -+------------------------------------------- - -* Usage - - La configuration doit principalement être initilalisée grâce à la méthode - <<<parse(String[])>>> avant d'être utilisé. - -+------------------------------------------- -public static void main(String[] args) { - MyConfig config = new MyConfig(); - config.setConfigFileName("myconfig.conf"); - config.parse(args); - - System.out.println("Connecting with " : + config.getOption("user")); - config.doAction(0); - System.out.println("Connected, do something..."); - config.doAction(MyConfig.AFTER_LOGIN); -} -+------------------------------------------- - -* Utilisation du ApplicationConfigProvider - - Ce contrat ajouté en version <2.4.8> permet de spécifier qu'une librairie - ou une application offre des options. - - Il suffit d'implanter ce contrat et de le rendre disponible via le mécanisme - de ServiceLoader. - -** Exemple - -+------------------------------------------- -public class PollenApplicationConfigProvider implements ApplicationConfigProvider { - - @Override - public String getName() { - return "pollen"; - } - - @Override - public String getDescription(Locale locale) { - return l_(locale, "pollen.application.config"); - } - - @Override - public ApplicationConfig.OptionDef[] getOptions() { - return PollenConfigurationOption.values(); - } - - @Override - public ApplicationConfig.ActionDef[] getActions() { - return new ApplicationConfig.ActionDef[0]; - } -} -+------------------------------------------- - - Puis ajouter le fichier <META-INF/services/org.nuiton.util.ApplicationConfigProvider> - dans les resources du projet : - -+------------------------------------------- -org.chorem.pollen.PollenApplicationConfigProvider -+------------------------------------------- - - Cela permet ensuite par exemple de générer un rapport contenant toutes les - options disnible dans l'application. Modified: trunk/nuiton-utils/src/site/apt/index.apt =================================================================== --- trunk/nuiton-utils/src/site/apt/index.apt 2013-07-19 17:37:58 UTC (rev 2584) +++ trunk/nuiton-utils/src/site/apt/index.apt 2013-07-19 17:39:44 UTC (rev 2585) @@ -69,25 +69,6 @@ * {{{/nuiton-utils/nuiton-utils/apidocs/org/nuiton/util/ZipUtil.html}ZipUtil}} -ApplicationConfig - - Permet de lire les options de configuration pour une application par tous les - moyens disponibles : - - * fichiers de configuration (système, utilisateur, classpath) - - * variables d'environnement du système - - * variables d'environnement de la JVM - - * ligne de commande - - Elle permet ensuite de sauvegarder dans le fichier utilisateur les modifications - faites durant l'exécution de l'application. Ainsi que de lancer automatiquement - des actions demandées sur la ligne de commande. - - {{{./ApplicationConfig.html}Plus d'infos}} - Autres Collection * {{{/nuiton-utils/nuiton-utils/apidocs/org/nuiton/util/BoundedList.html}BoundedList}} :