Author: athimel Date: 2013-02-26 16:30:54 +0100 (Tue, 26 Feb 2013) New Revision: 2520 Url: http://nuiton.org/projects/nuiton-utils/repository/revisions/2520 Log: Fix spelling and conjugation in nuiton-config's index documentation Modified: trunk/nuiton-config/src/site/apt/index.apt Modified: trunk/nuiton-config/src/site/apt/index.apt =================================================================== --- trunk/nuiton-config/src/site/apt/index.apt 2013-02-26 14:48:17 UTC (rev 2519) +++ trunk/nuiton-config/src/site/apt/index.apt 2013-02-26 15:30:54 UTC (rev 2520) @@ -30,23 +30,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 classe ApplicationConfig a pour but de gérer les options et actions + disponibles au sein d'une application. Elle gère aussi bien : - * la lecture de fichier de configuration + * la lecture de fichier de configuration ; - * le parsage de la ligne de commande + * le parsage de la ligne de commande ; - * l'execution des actions + * l'execution des actions ; - * la sauvegarde de la configuration + * 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 lecture des fichiers de configuration est effectuée lors de l'appel à la methode <<<parse(String...)>>> en utilisant la valeur de <<<getConfigFileName()>>> pour trouver les fichiers à lire. @@ -54,27 +54,27 @@ La sauvegarde des options se fait via une des trois methodes disponibles : - * <<<save>>> : sauvegarde dans un fichier specifique + * <<<save>>> : sauvegarde dans un fichier specifique ; - * <<<saveForSystem>>> : sauvegarde les donnees dans /etc + * <<<saveForSystem>>> : sauvegarde les donnees dans /etc ; - * <<<saveForUser>>> : sauvegarde les donnees dans $HOME + * <<<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. + <<<setOption()>>>) seront sauvegardées. Les variables d'environnement, les + arguments de la ligne de commandes(etc...) ne seront pas sauvegardés. * Configuration multi instance - Il est possible d'associé un nom de contexte a une configuration via la + Il est possible d'associer un nom de contexte à 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 + dans le dossier défini par l'option <<<azerty.config.path>>> si elle existe + (sinon, dans le dossier par défaut) et le nom du fichier cherché defini par l'option <<<azerty.config.file>>>. - Cett option est utilise par exemple pour installer plusieurs instance + Cette option est utilisée par exemple pour installer plusieurs instances d'application dans un serveur web et que chaque instance aille chercher ses fichiers de configuration à son propre endroit. @@ -82,30 +82,29 @@ * Les options de configuration - L'ordre de prise en compte des options suivant les différentes sources est - le suivant : + L'ordre de prise en compte des options est le suivant : - * Option renseignées par programmation + * Option renseignée par programmation ; - * Ligne de commandes + * Ligne de commande ; - * Propriétés systèmes (System.getProperties()) + * Propriétés système (System.getProperties()) ; - * Propriétés d'envirronement (System.getenv()) + * Propriétés d'environnement (System.getenv()) ; - * Fichier du dossier courant ( ./ + nom du fichier) + * Fichier du dossier courant ( ./ + nom du fichier) ; - * Fichier de configuration globale ( /etc/ + nom du fichier) + * Fichier de configuration globale ( /etc/ + nom du fichier) ; - * Fichier dans le classpath ( / + nom du fichier) + * Fichier dans le classpath ( / + nom du fichier) ; - * Valeur par défaut (renseignés à l'init) + * Valeur par défaut (renseignée à 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. + Cela signifie par exemple que si une option a une valeur par défaut et qu'elle + est renseignée dans le fichier /etc et sur la ligne de commande, c'est la + valeur présente sur la ligne de commande qui sera prise en compte. * Les actions @@ -117,25 +116,25 @@ 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. + cas contraire, la classe contenant la méthode sera instanciée à partir + d'un constructeur prenant en paramètre seulement la configuration, ou, s'il + n'est pas disponible, le constructeur par défaut. La méthode sera ensuite + appelée sur cette instance. Les diverses instances sont conservées pour + effectuer 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é. + Les arguments de la méthode utilisés lors de l'appel sont convertis + dans le bon type. Si la méthode a des arguments de taille variante (...) + tous les arguments jusqu'à la prochaine option ou à la fin de la ligne + seront utilisés. - Si vous avez des parametres optionnels, le seul moyen est d'utiliser des - arguments variant. + Si vous avez des paramètres optionnels, le seul moyen est d'utiliser des + arguments variants. - Par exemple, la ligne de commande précédente appelera la methode + Par exemple, la ligne de commande précédente appelera la methode : +------------------------------------------- public class Test { - public goLogin(String login, String password, boolean dryRun) { + public doLogin(String login, String password, boolean dryRun) { [...] } } @@ -144,10 +143,10 @@ 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 + Par défaut, 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>>> + Il est possible de différencier les différentes actions en utilisant + l'annotation <<<@Step>>> +------------------------------------------- doAction(0); @@ -156,13 +155,13 @@ +------------------------------------------- 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... + C'est très utile par exemple pour éxecuter certaines actions avant le démarrage + de l'UI par exemple, et d'autres après... -* Les arguments non parsées +* Les arguments non parsés - 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 + La configuration 'consomme' les arguments de la ligne de commande qu'elle a + réussie à traiter. Pour recupérer 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 <<<-->>>. @@ -173,7 +172,7 @@ monApplication "mon arg" --option k1 v1 -- --option k2 v2 -- autre +------------------------------------------- - Renvera la liste suivante via <<<getUnparsed()>>> : + Renverra la liste suivante via <<<getUnparsed()>>> : +------------------------------------------- "mon arg", "--option", "k2", "v2", "--", "autre" @@ -190,7 +189,13 @@ addAlias("-i", "--mon.package.MaClass#MaMethode", "import"); +------------------------------------------- - Lors du parsing de la ligne de commande, tous les alias sont remplacé par + 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 à être "import". + + Lors du parsing de la ligne de commande, tous les alias sont remplacés par leur correspondance. Il est donc possible d'utiliser ce mecanisme pour autre chose : @@ -198,49 +203,43 @@ 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, + Pour convertir les types des options et arguments de méthodes, {{{http://commons.apache.org/beanutils/}commons-beanutils}} est utilisé. Les types actuellement supporté sont : - * <<<java.lang.String>>> + * <<<java.lang.String>>> ; - * <<<java.io.File>>> + * <<<java.io.File>>> ; - * <<<java.net.URL>>> + * <<<java.net.URL>>> ; - * <<<java.lang.Class>>> + * <<<java.lang.Class>>> ; - * <<<java.sql.Date>>> + * <<<java.sql.Date>>> ; - * <<<java.sql.Time>>> + * <<<java.sql.Time>>> ; - * <<<java.sql.Timestamp>>> + * <<<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)>>> + Pour utiliser d'autres types, il suffit de les enregistrer dans beanutils via + la méthode <<<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 + La configuration de variable supporte la substitution par d'autres variables + via la syntaxe <<<$\{xxx\}>>> où <<<xxx>>> est une autre variable de + la configuration. - Par exemple (fichier de configuration): + Par exemple (fichier de configuration) : +------------------------------------------- application.name = Mon Appli @@ -249,13 +248,13 @@ +------------------------------------------- L'appel de l'option <<<application.info>>> via la methode <<<getOption()>>> - retournera une chaine de la forme: + retournera une chaîne 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 + À noter que les substitutions ne sont remplacées qu'a leur lecture, la sauvegarde de l'option <<<application.info>>> se fera sans remplacement. Mise en oeuvre @@ -265,13 +264,13 @@ Voici l'ensemble des tâches à effectuer pour définir une configuration d'application : - * Creation d'une sous classes d'<<<ApplicationConfig>>> + * Creation d'une sous classe d'<<<ApplicationConfig>>> ; - * Ajout des options par défaut + * Ajout des options par défaut ; - * Creation des classes et méthodes d'actions + * Création des classes et méthodes d'actions ; - * Déclaration des alias des options et actions + * Déclaration des alias des options et actions. [] @@ -280,33 +279,33 @@ +------------------------------------------- public class MyConfig extends ApplicationConfig { - public final static int AFTER_LOGIN = 1; + public static final 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"); + // options par défaut + 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); + setOption("user", user); } public void setUser(String user) { - setOption("user", user); + setOption("user", user); } public void doLogin(String user, String password) { - [...] + [...] } @Step(AFTER_LOGIN) public void doSomething() { - [...] + [...] } } +------------------------------------------- @@ -314,7 +313,7 @@ * Usage La configuration doit principalement être initilalisée grâce à la méthode - <<<parse(String[])>>> avant d'être utilisé. + <<<parse(String[])>>> avant d'être utilisée. +------------------------------------------- public static void main(String[] args) { @@ -365,11 +364,11 @@ +------------------------------------------- Puis ajouter le fichier <META-INF/services/org.nuiton.util.ApplicationConfigProvider> - dans les resources du projet : + 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. + Cela permet ensuite, par exemple, de générer un rapport contenant toutes les + options disponibles dans l'application.