Author: echatellier Date: 2010-02-23 11:38:40 +0100 (Tue, 23 Feb 2010) New Revision: 1767 Modified: trunk/src/main/java/org/nuiton/util/ApplicationConfig.java trunk/src/main/java/org/nuiton/util/ArgumentsParserException.java Log: Update ApplicationConfig javadoc Modified: trunk/src/main/java/org/nuiton/util/ApplicationConfig.java =================================================================== --- trunk/src/main/java/org/nuiton/util/ApplicationConfig.java 2010-02-21 19:37:40 UTC (rev 1766) +++ trunk/src/main/java/org/nuiton/util/ApplicationConfig.java 2010-02-23 10:38:40 UTC (rev 1767) @@ -50,68 +50,64 @@ import java.beans.PropertyChangeListener; /** - * <h1>To do</h1> - * <p/> + * Application configuration. + * + * <h3>TODO</h3> * <ul> - * <li> ajout d'annotations sur les methodes - * pour precisser plus de chose pour les options (pattern, min/max, alias, + * <li>Ajout d'annotations sur les methodes + * pour preciser plus de chose pour les options (pattern, min/max, alias, * description, ...) - * <li> trouver un moyen de document les options et actions pour automatiquement + * <li>Trouver un moyen de document les options et actions pour automatiquement * generer l'aide en ligne. Pour eviter de devoir maintenir une methode * dans lequel est ecrit l'aide en plus des options. - * <li> prise en compte du flag {@link #useOnlyAliases} - * <li> vu qu'en java on ne peut pas pointer une methode mais seulement une classe + * <li>Prise en compte du flag {@link #useOnlyAliases} + * <li>Vu qu'en java on ne peut pas pointer une methode mais seulement une classe * 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 :( * </ul> - * <p/> - * <h1>Usage</h1> - * <li> create subclass of ApplicationConfig, where in constructor you call - * addAliases, setConfigFileName, setDefaultActionPackage, setDefaultActionClass, setDefaultActionMethod + * + * <h3>Usage</h3> + * Create subclass of {@link ApplicationConfig}, where in constructor you call + * {@link #addAlias(String, String[])}, {@link #setConfigFileName(String)} * to have properly value. - * <p/> - * <li> conf = new MonAppConfig(); - * <li> conf.parse(args); - * <li> here you can used conf.getOption(key); - * <li> conf.doAction(0); - * <li> ... - * <li> conf.doAction(n); - * <p/> - * <h1>Lecture des fichiers de configuration</h1> - * <p/> - * <p/> + * <pre> + * conf = new MonAppConfig(); + * conf.parse(args); + * here you can used conf.getOption(key); + * conf.doAction(0); + * ... + * conf.doAction(n); + * </pre> + * + * <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 * trouver les fichiers (voir Les options de configuration pour l'ordre de * chargement des fichiers) - * <p/> - * <h1>La sauvegarde</h1> - * <p/> - * <p/> - * La sauvegarde des options se fait via une des trois methodes disponible - * <p/> + * + * <h3>La sauvegarde</h3> + * 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 * </ul> - * <p/> - * Lors de l'utilisation de la methode {@link #saveForSystem(String[])} ou - * {@link #saveForUser(String[])} seul les options lu dans un fichier ou modifier par - * programmation ({@link #setOption} seront sauvegardees. Par exemple les + * + * 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 * options passees sur la ligne de commande ne seront pas sauvees. - * <p/> - * <h1>Les options de configuration</h1> - * <p/> - * <p/> + * + * <h3>Les options de configuration</h3> + * * Cette classe permet de lire les fichiers de configuration, utiliser les * variable d'environnement et de parser la ligne de commande. L'ordre de prise - * en compte des informations trouvées est la suivante (le premier le plus - * important). - * <p/> + * en compte des informations trouvées est le suivant (le premier le plus + * important) : * <ul> - * <li>options ajoutees par programmation: {@link #setOption}(key, value)</li> + * <li>options ajoutees par programmation: {@link #setOption(String, String)}</li> * <li>ligne de commande</li> * <li>variable d'environnement de la JVM: java -Dkey=value</li> * <li>variable d'environnement; export key=value</li> @@ -121,14 +117,14 @@ * <li>fichier de configuration trouve dans le classpath: $CLASSPATH/filename</li> * <li>options ajoutees par programmation: {@link #defaults}.put(key, value)</li> * </ul> - * <p/> - * <p/> + * + * * Les options sur la ligne de commande sont de la forme: * <pre> * --option key value * --monOption key value1 value2 * </pre> - * <p/> + * * <ul> * <li>--option key value: est la syntaxe par defaut * <li>--monOption key value1 value2: est la syntaxe si vous avez ajouter une @@ -137,16 +133,15 @@ * arguments que vous souhaitez du moment qu'ils soient convertibles de la * representation String vers le type que vous avez mis. * </ul> - * <p/> - * <h1>Les actions</h1> - * <p/> - * Les actions ne peuvent etre que sur la ligne de commande. Ils sont de la + * + * <h3>Les actions</h3> + * + * Les actions ne peuvent etre que sur la ligne de commande. Elles sont de la * forme: * <pre> * --le.package.LaClass#laMethode arg1 arg2 arg3 ... argN * </pre> - * <p/> - * <p/> + * * Une action est donc defini par le chemin complet vers la methode qui traitera * l'action. Cette methode peut-etre une methode static ou non. Si la methode * n'est pas static lors de l'instanciation de l'objet on essaie de passer en @@ -158,40 +153,32 @@ * parties d'un meme objet utiliseront la meme instance de cette objet lors * de leur execution. * <p/> - * <p/> * Si la methode utilise les arguments variants alors tous les arguments * jusqu'au prochain -- ou la fin de la ligne de commande sont utilises. Sinon * Le nombre exact d'argument necessaire a la methode sont utilises. * <p/> - * <p/> * Les arguments sont automatiquement converti dans le bon type reclame par la * methode. * <p/> - * <p/> * Si l'on veut des arguments optionnels le seul moyen actuellement est * d'utiliser une methode avec des arguments variants * <p/> - * <p> Les actions ne sont pas execute mais seulement parsees. Pour les executer - * il faut utiilser la methode {@link #doAction} qui prend en argument un numero + * 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 * 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 * {@link ApplicationConfig.Action.Step} sur la methode qui fera l'action en * precisant une autre valeur que 0. - * <p/> * <pre> * doAction(0); * ... do something ... * doAction(1); * </pre> - * <p/> - * <p/> * dans cette exemple on fait un traitement entre l'execution des actions * de niveau 0 et les actions de niveau 1. - * <p/> - * <h1>Les arguments non parses</h1> - * <p/> - * <p/> + * + * <h3>Les arguments non parsées</h3> * Tout ce qui n'est pas option ou action est considere comme non parse et peut * etre recupere par la methode {@link #getUnparsed}. Si l'on souhaite forcer * la fin du parsing de la ligne de commande il est possible de mettre --. @@ -199,45 +186,36 @@ * <pre> * monProg "mon arg" --option k1 v1 -- --option k2 v2 -- autre * </pre> - * <p/> - * <p/> * Dans cet exemple seule la premiere option sera considere comme une option. - * On retrouvera dans unparsed: "mon arg", "--option", "k2", "v2", "--", "autre" - * <p/> - * <h1>Les alias</h1> - * <p/> + * On retrouvera dans {@code unparsed}: "mon arg", "--option", "k2", "v2", "--", + * "autre" + * + * <h3>Les alias</h3> * 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}. - * <p/> * <pre> * addAlias("-v", "--option", "verbose", "true"); * addAlias("-o", "--option", "outputfile"); * addAlias("-i", "--mon.package.MaClass#MaMethode", "import"); * </pre> - * <p/> - * <p/> * En faite avant le parsing de la ligne de commande tous les alias trouves sont * automatiquement remplacer par leur correspondance. Il est donc possible * d'utiliser ce mecanisme pour autre chose par exemple: - * <p/> * <pre> * addAlias("cl", "Code Lutin"); * addAlias("bp", "Benjamin POUSSIN); * </pre> - * <p/> - * <p/> * 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". - * <p/> - * <h1>Conversion de type</h1> - * Pour la conversion de type nous utilisons common-beans. Les types supporte + * + * <h3>Conversion de type</h3> + * Pour la conversion de type nous utilisons common-beans. Les types supportes * sont: - * <p/> * <ul> * <li> les primitif (byte, short, int, long, float, double, char, boolean) * <li> String @@ -250,29 +228,44 @@ * <li> les tableaux d'un type primitif ou String. Chaque element doit etre * separe par une virgule * </ul> + * + * Pour suporter d'autre type, il vous suffit d'enregistrer de nouveau + * converter dans commons-beans. + * + * <h3>Les substitutions de variable</h3> + * {@link ApplicationConfig} supporte les substition de variables de la forme + * <tt>${xxx}</tt> où {@code xxx} est une autre variable de la configuration. * <p/> - * Pour suporter d'autre type, il vous suffit d'enregistrer de nouveau - * converter dans commons-beans - * + * Exemple (dans un fichier de configuration): + * <pre> + * firstname = John + * lastname = Doe + * fullname = ${firstname} ${lastname} + * </pre> + * <tt>getOption("fullname")</tt> retournera <tt>"John Doe"</tt>. + * * @author poussin * @version $Revision$ * @since 0.30 - * <p/> - * Last update $Date$ - * by $Author$ + * + * <p/> + * Last update $Date$ by $Author$ */ public class ApplicationConfig { /** to use log facility, just put in your code: log.info(\"...\"); */ static private Log log = LogFactory.getLog(ApplicationConfig.class); - /** - * used to know what is separator between la class et la method sur la - * ligne de commande - */ + + /** Used to know what is separator between class and method on command line. */ static final private String CLASS_METHOD_SEPARATOR = "#"; + + /** Configuration file key option. */ static final public String CONFIG_FILE_NAME = "config.file"; + protected boolean useOnlyAliases = false; + protected Map<String, List<String>> aliases = new HashMap<String, List<String>>(); + /** file /etc/[filename] */ String systemPath = File.separator + "etc" + File.separator; /** file $user.home/.[filename] */ @@ -280,8 +273,10 @@ String userPath = getUserHome() + File.separator + "."; /** file $user.home/.local/[filename] */ //String userPath2 = getUserHome() + File.separator + ".config" + File.separator; - /** vrai si on est en train de parser les options de la ligne de commande */ + + /** vrai si on est en train de parser les options de la ligne de commande. */ protected boolean inParseOptionPhase = false; + protected Properties defaults = new Properties(); protected Properties classpath = new Properties(defaults); protected Properties etcfile = new Properties(classpath); @@ -296,7 +291,8 @@ /** contient apres l'appel de parse, la liste des arguments non utilises */ protected List<String> unparsed = new ArrayList<String>(); protected Map<Integer, List<Action>> actions = new HashMap<Integer, List<Action>>(); - /** suport of config modification */ + + /** suport of config modification. */ protected PropertyChangeSupport pcs = new PropertyChangeSupport(this); /** @@ -384,17 +380,31 @@ } } + /** + * Init ApplicationConfig with current simple class name as config file. + * + * Also init converters. + * @see ConverterUtil#initConverters() + */ public ApplicationConfig() { setConfigFileName(this.getClass().getSimpleName()); // init extra-converters ConverterUtil.initConverters(); } + /** + * Get user home directory (system property {@code user.home}). + * @return user home directory + */ static public String getUserHome() { String result = System.getProperty("user.home"); return result; } + /** + * Get user name (system property {@code user.name}). + * @return user name + */ public String getUsername() { String result = getOption("user.name"); return result; @@ -412,7 +422,7 @@ } /** - * Save configuration, in specified file + * Save configuration, in specified file. * * @param file file where config will be writen * @param forceAll if true save all config option @@ -515,6 +525,18 @@ } } + /** + * Do action in specified step. + * + * @param step do action only defined in this step + * + * @throws IllegalAccessException + * @throws IllegalArgumentException + * @throws InvocationTargetException + * @throws InstantiationException + * + * @see Action.Step + */ public void doAction(int step) throws IllegalAccessException, IllegalArgumentException, InvocationTargetException, InstantiationException { List<Action> list = actions.get(step); if (list != null) { @@ -533,7 +555,7 @@ } /** - * All argument in aliases as key is substitued by target + * All argument in aliases as key is substitued by target. * * @param alias alias string as '-v' * @param target substitution as '--option verbose true' @@ -564,13 +586,17 @@ setDefaultOption(CONFIG_FILE_NAME, name); } + /** + * Get name of file where options are read (in /etc, $HOME, $CURDIR). + * @return name of file + */ public String getConfigFileName() { String result = getOption(CONFIG_FILE_NAME); return result; } /** - * Set option value + * Set option value. * * @param key property key * @param value property value @@ -584,7 +610,9 @@ } /** - * get option value as string + * get option value as string. + * + * Replace inner ${xxx} value. * * @param key the option's key * @return String representation value @@ -643,7 +671,7 @@ /** * Permet de recuperer l'ensemble des options commencant par une certaine - * chaine + * chaine. * * @param prefix debut de cle a recuperer * @return la liste des options filtrées @@ -661,7 +689,7 @@ } /** - * get option value from a option definition + * Get option value from a option definition. * * @param key the definition of the option * @return the value for the given option @@ -672,14 +700,13 @@ } /** - * get option value as typed value + * Get option value as typed value. * * @param <T> type of the object wanted as return type * @param clazz type of object wanted as return type * @param key the option's key * @return typed value */ - @SuppressWarnings("unchecked") public <T> T getOption(Class<T> clazz, String key) { T result = null; String cacheKey = key + "-" + clazz.getName(); @@ -695,7 +722,7 @@ if (cacheItem == null || cacheItem.hash != hash) { // prefer use our convertert method (auto-register more converters) result = ConverterUtil.convert(clazz, value); -// result = (T) ConvertUtils.convert(value, clazz); + // result = (T) ConvertUtils.convert(value, clazz); cacheItem = new CacheItem<T>(result, hash); cacheOption.put(cacheKey, cacheItem); } else { @@ -706,10 +733,10 @@ } /** - * get option value as typed value + * Get option value as {@link File}. * * @param key the option's key - * @return typed value + * @return value as file */ public File getOptionAsFile(String key) { File result = getOption(File.class, key); @@ -718,10 +745,10 @@ } /** - * get option value as typed value + * Get option value as {@link URL}. * * @param key the option's key - * @return typed value + * @return value as URL */ public URL getOptionAsURL(String key) { URL result = getOption(URL.class, key); @@ -729,10 +756,10 @@ } /** - * get option value as typed value + * Get option value as {@link Class}. * * @param key the option's key - * @return typed value + * @return value as Class */ public Class<?> getOptionAsClass(String key) { Class<?> result = getOption(Class.class, key); @@ -740,10 +767,10 @@ } /** - * get option value as typed value + * Get option value as {@link Date}. * * @param key the option's key - * @return typed value + * @return value as Date */ public Date getOptionAsDate(String key) { Date result = getOption(Date.class, key); @@ -751,10 +778,10 @@ } /** - * get option value as typed value + * Get option value as {@link Time}. * * @param key the option's key - * @return typed value + * @return value as Time */ public Time getOptionAsTime(String key) { Time result = getOption(Time.class, key); @@ -762,10 +789,10 @@ } /** - * get option value as typed value + * Get option value as {@link Timestamp}. * * @param key the option's key - * @return typed value + * @return value as Timestamp */ public Timestamp getOptionAsTimestamp(String key) { Timestamp result = getOption(Timestamp.class, key); @@ -773,10 +800,10 @@ } /** - * get option value as typed value + * Get option value as {@code int}. * * @param key the option's key - * @return typed value + * @return value as {@code int} */ public int getOptionAsInt(String key) { Integer result = getOption(Integer.class, key); @@ -784,10 +811,10 @@ } /** - * get option value as typed value + * Get option value as {@code double}. * * @param key the option's key - * @return typed value + * @return value as {@code double} */ public double getOptionAsDouble(String key) { Double result = getOption(Double.class, key); @@ -795,10 +822,10 @@ } /** - * get option value as typed value + * Get option value as {@code boolean}. * * @param key the option's key - * @return typed value + * @return value as {@code boolean}. */ public boolean getOptionAsBoolean(String key) { Boolean result = getOption(Boolean.class, key); @@ -816,7 +843,7 @@ /** * Set manually options when you don't want to use parse method to check - * properties file configured by setConfigFileName. + * properties file configured by {@link #setConfigFileName}. * * @param options Properties which contains all options to set */ @@ -825,7 +852,7 @@ } /** - * Get all set method on this object or super object + * Get all set method on this object or super object. * * @return map with method name without set and in lower case as key, and * method as value @@ -962,7 +989,6 @@ * * @param args argument as main(String[] args) * @throws ArgumentsParserException - * */ public void parse(String[] args) throws ArgumentsParserException { try { Property changes on: trunk/src/main/java/org/nuiton/util/ApplicationConfig.java ___________________________________________________________________ Deleted: svn:mergeinfo - Added: svn:keywords + Author Date Id Revision HeadURL Modified: trunk/src/main/java/org/nuiton/util/ArgumentsParserException.java =================================================================== --- trunk/src/main/java/org/nuiton/util/ArgumentsParserException.java 2010-02-21 19:37:40 UTC (rev 1766) +++ trunk/src/main/java/org/nuiton/util/ArgumentsParserException.java 2010-02-23 10:38:40 UTC (rev 1767) @@ -18,7 +18,7 @@ package org.nuiton.util; /** - * Argument parsing exception + * Argument parsing exception. * * @author Benjamin Poussin <poussin@codelutin.com> * Copyright Code Lutin @@ -32,10 +32,21 @@ /** serialVersionUID. */ private static final long serialVersionUID = 8265924907001359910L; + /** + * Constructs a new exception with the specified detail message. + * + * @param msg message + */ public ArgumentsParserException(String msg) { super(msg); } + /** + * Constructs a new exception with the specified detail message and cause. + * + * @param msg message + * @param eee cause + */ public ArgumentsParserException(String msg, Throwable eee) { super(msg, eee); } Property changes on: trunk/src/main/java/org/nuiton/util/ArgumentsParserException.java ___________________________________________________________________ Deleted: svn:mergeinfo - Deleted: svn:eol-style - native