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(a)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
