Author: echatellier Date: 2010-02-23 18:27:18 +0100 (Tue, 23 Feb 2010) New Revision: 1772 Added: trunk/src/site/apt/ApplicationConfig.apt Removed: trunk/src/site/apt/CommandLineArgumentApplication.apt trunk/src/site/apt/Todo.apt Modified: trunk/src/site/apt/nuitonUtil.apt trunk/src/site/site_fr.xml Log: Add ApplicationConfig doc. Added: trunk/src/site/apt/ApplicationConfig.apt =================================================================== --- trunk/src/site/apt/ApplicationConfig.apt (rev 0) +++ trunk/src/site/apt/ApplicationConfig.apt 2010-02-23 17:27:18 UTC (rev 1772) @@ -0,0 +1,294 @@ + ---- + ApplicationConfig + ---- + ---- + 2010-02-23 + ---- + +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. + +Fonctionnalités + +* Les options de configuration + + Le chargement de la configuration s'effectue dans cet ordre : + + * Valeur par défaut (renseignés à l'init) + + * Fichier dans le classpath ( / + nom du fichier) + + * Fichier de configuration globale ( /etc/ + nom du fichier) + + * Fichier du dossier courant ( ./ + nom du fichier) + + * Propriétés d'envirronement (System.getenv()) + + * Propriétés systèmes (System.getProperties()) + + * Ligne de commandes + + * Option renseignées par programmation + + [] + + 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); +} ++------------------------------------------- \ No newline at end of file Deleted: trunk/src/site/apt/CommandLineArgumentApplication.apt =================================================================== --- trunk/src/site/apt/CommandLineArgumentApplication.apt 2010-02-23 14:26:46 UTC (rev 1771) +++ trunk/src/site/apt/CommandLineArgumentApplication.apt 2010-02-23 17:27:18 UTC (rev 1772) @@ -1,133 +0,0 @@ - ---- - Argument d'application - ---- - -Cette documentation n'est plus maintenu, faire la documentation de -ApplicationConfig à la place. - -Argument d'application - - Il y a deux type d'argument d'application: - - * les arguments permettant de modifier la configuration qui peuvent aussi - être dans un fichier de configuration ou en variable d'environnement. - - * les arguments permettant d'indiquer des actions a faire a l'application - -Les options de configuration - - Les options de configuration peuvent être décrit directement par un POJO - avec des annotations:: - ------------------------------------------------------------------------------------ - @OptionConfigOrder("resource MonApp.properties", "file /etc/MonApp.properties", - "optionfile configFile", "env", "line") - public class MonAppConfig extends OptionConfig { - - @Option - @OptionSaveFile - public File configFile = new File("$HOME/.MonApp"); - - @Option(pattern [^\s]+) - public String username = "anonyous"; - - @Option(pattern ..) - public String lang = "fr"; - - @Option(pattern ..) - public String country = "FR"; - - @Option - public boolean showGui = true; - - @Option(min=10, max=10) - public List<Integer> value; - - @Unparsed - public List<String> other; - } ------------------------------------------------------------------------------------ - -La classe OptionConfig - - La classe OptionConfig contient plusieurs méthodes: - - * load sans argument qui permet de charger le POJO en fonction de - OptionConfigOrder - - * load(File) qui permet de charger le POJO seulement en fonction d'un - fichier. Il bien sur possible d'appeler load() puis load(File). - - * save qui permet de sauver les informations du POJO, le fichier ou sauver - les options est indiqué par l'annotation <<<@OptionSaveFile>>> - -Annotation OptionConfigOrder - - OptionConfigOrder permet de déterminer l'ordre de recherche de la bonne - valeur des options. Le dernier indiqué sera le dernier lu et donc celui qui - aura raison. - - * resource - indique un fichier resource a rechercher dans le classpath - - * file - indique un fichier sur le systeme de fichier - - * optionfile - indique un fichier dont le chemin est indiqué par une option - - * env - indique les variables d'environnement du processus - - * sline - indique les options sur la ligne de commande - -Implantation - - * On charge dans un objet <<Properties>> chaque entre de - <<OptionConfigOrder>> sauf <<optionfile>> s'il y en a. - - * On chaine tous les fichiers de proprietes pour pouvoir demander - l'information au dernier qui recherchera lui meme dans son pere s'il n'a pas - l'information. - - * Pour chaque <<optionfile>> on demande sa valeur, on crée le fichier de - propriété et on l'ajoute dans la chaine à la bonne place - - * Pour chaque option trouvé dans le POJO on met a jour sa valeur avec la - valeur trouvé dans les propriétés. - -Annotation Option - - Indique une option possible. Elle peut contenir: - - * description - - * pattern - - * alias - - * min - - * max - - Par defaut l'option sur la ligne de commande sera le nom de la variable precedé de -- - -Annotation Unparsed - - Indique que toutes les options de la ligne de commande non reconnu finisse dans ce champs - Il est possible de type la collection autrement que par String. - -Annotation OptionSaveFile - - Indique le fichier a utiliser pour sauver les options - -* Les actions - - TODO: comment différencier les actions des options ? comment reutiliser le travail de tony ? - -* Amélioration possible - - - Générer automatiquement par un plugin maven les methodes get/set sur les options - - Gérer les options read/write et read - - un plugin maven qui verifie la coherence des options Deleted: trunk/src/site/apt/Todo.apt =================================================================== --- trunk/src/site/apt/Todo.apt 2010-02-23 14:26:46 UTC (rev 1771) +++ trunk/src/site/apt/Todo.apt 2010-02-23 17:27:18 UTC (rev 1772) @@ -1,91 +0,0 @@ - ---- - TODO - ---- - ---- - 2009-08-23 - ---- - -Un nouveau parser d'argument - - L'idée est d'avoir une description simple des arguments et de leur type et - que soit généré une classe à partir de cette description. Dans le - programme il suffirat de demander à la classe généré les inforamtions. - - Les options sont chargées par leur valeur par defaut, puis sont surchargées - par les valeurs des fichiers de configurations, puis surchargé - par les valeurs des variables d'environnement, et enfin surchargé par les - valeurs de la ligne de commande. - - Les fichiers de configuraiton sont lu dans l'ordre suivant: /etc/ + chemin - indiqué, puis $HOME/. + chemin indiqué. - - si le chemin indiqué est titi/toto.conf et que l'on est sur un système Linux - les fichiers de configuration seront: /etc/titi/toto.conf et - ~/.titi/toto.conf - -* exemple de description - - Par exemple on pourrait avoir le fichier Toto.java.conf dans les sources du - projet qui fournirait le fichier Toto.java:: - ----------------------------------------------------------------------------- - configfile: titi/toto.conf - - outFile: le fichier de sortie - short: o - long: outfile - default: - - type: File - environment: toto - - number: Le nombre de fichier à produire - required: 1 - short: n - default: 1 - long: number - condition: 0<Number && Number<10 - type: int ----------------------------------------------------------------------------- - - La description commence l'option non obligatoire *configfile* qui donne le - nom du fichier de configuration à utiliser pour l'application. Puis on - trouve les options. Une option commence par un nom, puis sa description - ensuite l'option peut avoir plusieurs options: - - - * short: l'option courte sur la ligne de commande. Si absente pas d'option - courte - - * long: l'option longue sur la ligne de commande, si pas d'option, on - reprend le nom de l'option - - * type: le type de l'option (int, Float, String, char, File, ...) - - * default: la valeur par default, si elle n'est pas specifier sur la ligne - de commande, ni dans les variables d'environnement ni dans le fichier de - configuration. Pour une option de type File si default faut -, alors - le fichier est la sortie standard. - - * condition: la condition que doit respecter l'option pour être valide - la condition est une expression java contenant le nom de l'option comme - valeur de variable. - - * environment: le nom de la variable d'environnement qu'il faut utiliser - si l'option n'est pas retrouve sur la ligne de commande. Si cette option - n'est pas indiqué alors, la variable d'environnement recherchée est le nom - du fichier de description suivi d'un point, suivi du nom de l'option. - par exemple toto.outfile - - - L'objet résultat sera Toto placé dans le fichier Toto.java. L'extension - java.conf est obligatoire pour détecter un fichier de configuration à - parser. Cet objet aurai les méthodes getOutputFile():File et getNumber():int - -* Librairies utilisé - - Sans doute utilisé, le parser redwood pour le fichier de configuration - {{http://www.isellrenohomes.com/parser/}}. Il lit directement des EBNF. - -* projet de parsage d'argument - - {{http://www.martiansoftware.com/jsap/}} Modified: trunk/src/site/apt/nuitonUtil.apt =================================================================== --- trunk/src/site/apt/nuitonUtil.apt 2010-02-23 14:26:46 UTC (rev 1771) +++ trunk/src/site/apt/nuitonUtil.apt 2010-02-23 17:27:18 UTC (rev 1772) @@ -31,59 +31,6 @@ classpath, et si elle n'est toujours pas trouvée une exception est alors levée. -ArgumentsParser - - Cette librairie permet de traiter les arguments de la ligne de commande de - façon simple mais évoluable. Son principe de fonctionnement est que l'on - déclare les arguements que l'on attend sur la ligne de commande avec le nombre - de paramètre qu'ils prennent et une petite description de l'option. Ensuite - on dispose de toutes les fonctions utiles pour le traitement de la ligne de - commande. - - Voici un exemple d'utilisation - ------------------------------------------------------------------------------- - import org.nuiton.util.ArgumentsParser; - ... - ArgumentsParser parser = new ArgumentsParser("ToPIA"); - - parser.addOption("version", "affiche le numéro de version", new String[]{"--version", "-v"}, 0).setRepetitionMax(1); - - parser.addOption("help", "affiche l'aide de topia", new String[]{"--help", "-h"}, 0).setRepetitionMax(1); - - parser.addOption("start", "Lancement d'une application", new - String[]{"--start", "-s"}, 1).setRepetitionMax(1); - - System.out.println(parser.checkCoherence()); - parser.parse(args); - - if(parser.hasParsedOption("help")){ - System.out.println(parser.usage()); - }else if (parser.hasParsedOption("start")){ - System.out.println ("--> Executing application: "); - String arg = parser.getParsedOption("start") - new Application(arg); - }else if (parser.hasParsedOption("version")){ - System.out.println( "- Topia version 0.01 - " + - "Get new release at http://www.codelutin.com/ -" ); - } ------------------------------------------------------------------------------- - - Cette librairie permet d'afficher l'aide de la ligne de commande:: - ------------------------------------------------------------------------------- - System.out.println(parser.usage()); ------------------------------------------------------------------------------- - - Elle permet aussi de vérifier le nombre de fois qu'une option de la ligne de - commande est présente et que ce nombre est bien compris dans l'ensemble des - valeurs acceptées, grâce au méthode *setRepetitionMax*, et *setRepetitionMin*. - - Si l'implantation par défaut du parseur d'option ne convient pas pour une de vos - option, par exemple si le nombre de paramètre de l'option varie suivant la valeur - du premier paramètre vous pouvez alors écrire votre propre Parser pour cette - Option et l'utilisée avec les autres. - Log Cette objet permet de suivre ce que fait une application simplement. Le @@ -313,10 +260,18 @@ MD5 dans un flux. -** DateUtils (since 1.1.2) +** DateUtils //(since 1.1.2)// Boîte à outils sur les dates (plus spécialisé que org.apache.commons.lang.DateUils) -** PeriodDates (since 1.1.2) +** PeriodDates //(since 1.1.2)// Objet correspondant à une période entre deux dates avec contraintes et méthodes utilitaires. + +** FileUtil#grep() //(since 1.1.2)// + + Unix like grep command + +** FileUtil#sed() //(since 1.1.2)// + + Unix like sed command Modified: trunk/src/site/site_fr.xml =================================================================== --- trunk/src/site/site_fr.xml 2010-02-23 14:26:46 UTC (rev 1771) +++ trunk/src/site/site_fr.xml 2010-02-23 17:27:18 UTC (rev 1772) @@ -19,7 +19,7 @@ <menu name="Utilisateur"> <item name="Accueil" href="index.html"/> <item name="Documentation" href="/nuitonUtil.html"/> - <item name="Application config" href="/CommandLineArgumentApplication.html"/> + <item name="Application config" href="/ApplicationConfig.html"/> <item name="War launcher" href="/Warlauncher.html"/> </menu>