Author: sletellier Date: 2011-04-22 18:36:21 +0200 (Fri, 22 Apr 2011) New Revision: 2114 Url: http://nuiton.org/repositories/revision/nuiton-utils/2114 Log: Fix and update configuration with best practice and simple exemple Modified: trunk/nuiton-utils/src/main/java/org/nuiton/util/ApplicationConfig.java Modified: trunk/nuiton-utils/src/main/java/org/nuiton/util/ApplicationConfig.java =================================================================== --- trunk/nuiton-utils/src/main/java/org/nuiton/util/ApplicationConfig.java 2011-04-16 13:12:15 UTC (rev 2113) +++ trunk/nuiton-utils/src/main/java/org/nuiton/util/ApplicationConfig.java 2011-04-22 16:36:21 UTC (rev 2114) @@ -85,26 +85,45 @@ * il y a un bout des actions qui sont des chaines (nom de la methode). Il faudrait * faire un plugin maven qui check que l'action existe bien durant la compilation. * Il est simple de le faire a l'execution mais c trop tard :( + * <li>Ajouter de la documentation pour {@link #getOptionAsList(String)} * </ul> * - * <h3>Usage</h3> - * Create subclass of {@link ApplicationConfig}, where in constructor you call - * {@link #setConfigFileName(String)}, {@link #setDefaultOption(String, String)}, - * {@link #addAlias(String, String...)}, {@link #addActionAlias(String, String)}, - * to have properly value. - * <pre> - * conf = new MonAppConfig(); - * conf.parse(args); - * here you can used conf.getOption(key); - * conf.doAction(0); - * ... - * conf.doAction(n); + * <h3>Bonnes pratiques</h3> + * + * Vous devez créer une factory pour créer les ApplicationConfig qui contiendra par exemple une méthode : + * + * <pre> + * + * static public ApplicationConfig getConfig( + * Properties props, String configFilename, String ... args) { + * + * ApplicationConfig conf = new ApplicationConfig( + * MyAppConfigOption.class, MyAppConfigAction.class, + * props, configFilename); + * + * try { + * conf.parse(args); + * } catch (ArgumentsParserException eee) { + * if (log.isErrorEnabled()) { + * log.error("Can't load app configuration", eee); + * } + * } + * return conf; + * } + * * </pre> - * + * + * <ul> + * <li>MyAppConfigOption doit étendre {@link OptionDef} et décrir la configuration de l'application. + * <li>MyAppConfigAction doit étendre {@link ActionDef} et décrir la liste des options + * et de leur alias disponible pour l'application. + * </ul> + * * <h3>Lecture des fichiers de configuration</h3> * * La lecture des fichiers de configuration se fait durant l'appel de la methode - * {@link #parse} en utilisant la valeur de {@link #getConfigFileName} pour + * {@link #parse(String...)} en utilisant la valeur de qui doit être définit + * dans les options avec pour clef {@link ApplicationConfig#CONFIG_FILE_NAME} pour * trouver les fichiers (voir Les options de configuration pour l'ordre de * chargement des fichiers) * @@ -112,13 +131,13 @@ * La sauvegarde des options se fait via une des trois methodes disponibles : * <ul> * <li> {@link #save(File, boolean,String...)} sauve les données dans le fichier demandé - * <li> {@link #saveForSystem} sauvegarde les donnees dans /etc - * <li> {@link #saveForUser} sauvegarde les donnees dans $HOME + * <li> {@link #saveForSystem(String...)} sauvegarde les donnees dans /etc + * <li> {@link #saveForUser(String...)} sauvegarde les donnees dans $HOME * </ul> * - * Lors de l'utilisation de la methode {@link #saveForSystem} ou - * {@link #saveForUser} seules les options lues dans un fichier ou modifiées par - * programmation ({@link #setOption} seront sauvegardées. Par exemple les + * Lors de l'utilisation de la methode {@link #saveForSystem(String...)} ou + * {@link #saveForUser(String...)} seules les options lues dans un fichier ou modifiées par + * programmation ({@link #setOption(String, String)} seront sauvegardées. Par exemple les * options passees sur la ligne de commande ne seront pas sauvees. * * <h3>Les options de configuration</h3> @@ -185,7 +204,7 @@ * d'utiliser une methode avec des arguments variants * <p/> * Les actions ne sont pas execute mais seulement parsees. Pour les executer - * il faut utiliser la méthode {@link #doAction} qui prend en argument un numero + * il faut utiliser la méthode {@link #doAction(int)} qui prend en argument un numero * de 'step'. Par defaut toutes les actions sont de niveau 0 et sont executee * dans l'ordre d'apparition sur la ligne de commande. Si l'on souhaite * distinguer les actions il est possible d'utiliser l'annotation @@ -215,7 +234,7 @@ * On voit qu'aussi bien pour les actions que pour les options, le nom de la * methode doit etre utilise. Pour eviter ceci il est possible de definir * des alias ce qui permet de creer des options courtes par exemple. Pour cela, - * on utilise la methode {@link #addAlias}. + * on utilise la methode {@link #addAlias(String, String...)}. * <pre> * addAlias("-v", "--option", "verbose", "true"); * addAlias("-o", "--option", "outputfile"); @@ -404,7 +423,7 @@ * * @param configFilename name of config to use */ - public ApplicationConfig(String configFilename) throws ArgumentsParserException { + public ApplicationConfig(String configFilename) { this(null, null, null, configFilename); } @@ -428,7 +447,6 @@ * @param actionClass class that describe action, can be null * @param defaults properties that override default value of optionClass, can be null * @param configFilename override default config filename, can be null - * @param args command line argument can be empty */ public <O extends OptionDef, A extends ActionDef> ApplicationConfig( Class<O> optionClass, Class<A> actionClass, @@ -1278,7 +1296,7 @@ /** * Set manually options when you don't want to use parse method to check - * properties file configured by {@link #setConfigFileName}. + * properties file configured by {@link #setConfigFileName(String)}. * * @param options Properties which contains all options to set */ @@ -1494,6 +1512,7 @@ * Load configuration file and prepare Action. * * @param args argument as main(String[] args) + * @return ApplicationConfig instance * @throws ArgumentsParserException if parsing failed */ public ApplicationConfig parse(String... args) throws ArgumentsParserException { @@ -1838,6 +1857,85 @@ * Le contrat de marquage des options, on utilise cette interface pour * caracteriser une option de configuration. * + * <pre> + * public enum MyConfigOption implements OptionDef { + * + * APP_CONFIG_FILE( + * ApplicationConfig.CONFIG_FILE_NAME, + * "Main configuration app file", + * "myApp-config.properties", + * String.class, true, true), + * + * APP_NAME( + * ApplicationConfig.CONFIG_FILE_NAME, + * Application name, + * "MyApp", + * String.class, true, true); + * + * public String key; + * public String description; + * public String defaultValue; + * public Class<?> type; + * public boolean isTransient; + * public boolean isFinal; + * + * private WikittyConfigOption(String key, String description, + * String defaultValue, Class<?> type, boolean isTransient, boolean isFinal) { + * this.key = key; + * this.description = description; + * this.defaultValue = defaultValue; + * this.type = type; + * this.isTransient = isTransient; + * this.isFinal = isFinal; + * } + * + * @Override + * public boolean isFinal() { + * return isFinal; + * } + * + * @Override + * public boolean isTransient() { + * return isTransient; + * } + * + * @Override + * public String getDefaultValue() { + * return defaultValue; + * } + * + * @Override + * public String getDescription() { + * return description; + * } + * + * @Override + * public String getKey() { + * return key; + * } + * + * @Override + * public Class<?> getType() { + * return type; + * } + * + * @Override + * public void setDefaultValue(String defaultValue) { + * this.defaultValue = defaultValue; + * } + * + * @Override + * public void setTransient(boolean isTransient) { + * this.isTransient = isTransient; + * } + * + * @Override + * public void setFinal(boolean isFinal) { + * this.isFinal = isFinal; + * } + * } + * </pre> + * * @since 1.0.0-rc-9 */ public interface OptionDef extends Serializable { @@ -1901,6 +1999,32 @@ * Le contrat de marquage des action, on utilise cette interface pour * caracteriser une action. * + * Ex : + * + * <pre> + * public enum MyAppConfigAction implements ActionDef { + * HELP(MyAppHelpAction.class.getName() + "#show", "-h", "--help"); + * public String action; + * public String[] aliases; + * + * private WikittyConfigAction(String action, String... aliases) { + * this.action = action; + * this.aliases = aliases; + * } + * + * @Override + * public String getAction() { + * return action; + * } + * + * @Override + * public String[] getAliases() { + * return aliases; + * } + * + * } + * </pre> + * * @author sletellier * @since 1.5.2 */