ApplicationConfig (Nuiton Utils :: Nuiton Config 2.6.11 API)

java.lang.Object
- org.nuiton.util.config.ApplicationConfig

Direct Known Subclasses:

ApplicationConfig.SubApplicationConfig
```
public class ApplicationConfig
extends Object
```
Application configuration.

A finir...
- Ajout d'annotations sur les methodes pour preciser plus de chose pour les options (pattern, min/max, alias, description, ...)
- 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.
- Prise en compte du flag useOnlyAliases
- 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 :(
- Ajouter de la documentation pour getOptionAsList(String)
Bonnes pratiques

Vous devez créer une factory pour créer les instances d'ApplicationConfig qui contiendra par exemple une méthode :
```
   public static 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;
   }

 
```
- MyAppConfigOption doit étendre ConfigOptionDef et décrir la configuration de l'application.
- MyAppConfigAction doit étendre ConfigActionDef et décrir la liste des options et de leur alias disponible pour l'application.
Lecture des fichiers de configuration

La lecture des fichiers de configuration se fait durant l'appel de la methode parse(String...) en utilisant la valeur de qui doit être définit dans les options avec pour clef CONFIG_FILE_NAME pour trouver les fichiers (voir Les options de configuration pour l'ordre de chargement des fichiers)

La sauvegarde
La sauvegarde des options se fait via une des trois methodes disponibles :
- save(File, boolean, String...) sauve les données dans le fichier demandé
- saveForSystem(String...) sauvegarde les donnees dans /etc
- saveForUser(String...) sauvegarde les donnees dans $HOME
Lors de l'utilisation de la methode saveForSystem(String...) ou saveForUser(String...) seules les options lues dans un fichier ou modifiées par programmation (setOption(String, String) seront sauvegardées. Par exemple les options passees sur la ligne de commande ne seront pas sauvees.

Les options de configuration

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 le suivant (le premier le plus important) :
- options ajoutees par programmation: setOption(String, String)
- ligne de commande
- variable d'environnement de la JVM: java -Dkey=value
- variable d'environnement; export key=value
- fichier de configuration du repertoire courant: $user.dir/filename
- fichier de configuration du repertoire home de l'utilisateur: $user.home/.filename
- fichier de configuration du repertoire /etc: /etc/filename
- fichier de configuration trouve dans le classpath: $CLASSPATH/filename
- options ajoutees par programmation: defaults.put(key, value)
Les options sur la ligne de commande sont de la forme:
```
 --option key value
 --monOption key value1 value2
 
```
- --option key value: est la syntaxe par defaut
- --monOption key value1 value2: est la syntaxe si vous avez ajouter une methode setMonOption(key, value1, value2) sur votre classe de configuration qui herite de ApplicationConfig. Dans ce cas vous pouvez mettre les arguments que vous souhaitez du moment qu'ils soient convertibles de la representation String vers le type que vous avez mis.
Les actions

Les actions ne peuvent etre que sur la ligne de commande. Elles sont de la forme:
```
 --le.package.LaClass#laMethode arg1 arg2 arg3 ... argN
 
```
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 parametre du constructeur la classe de configuration utilisee pour permettre a l'action d'avoir a sa disposition les options de configuration. Si aucun constructeur avec comme seul parametre une classe heritant de ApplicationConfig n'existe alors le constructeur par defaut est utilise (il doit etre accessible). Toutes methodes d'actions faisant parties d'un meme objet utiliseront la meme instance de cette objet lors de leur execution.
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.
Les arguments sont automatiquement converti dans le bon type reclame par la methode.
Si l'on veut des arguments optionnels le seul moyen actuellement est d'utiliser une methode avec des arguments variants
Les actions ne sont pas execute mais seulement parsees. Pour les executer il faut utiliser la méthode doAction(int) qui prend en argument un numero de 'step' ou doAllAction() qui fait les actions dans l'ordre de leur 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 ApplicationConfig.Action.Step sur la methode qui fera l'action en precisant une autre valeur que 0.
```
 doAction(0);
 ... do something ...
 doAction(1);
 
```
dans cette exemple on fait un traitement entre l'execution des actions de niveau 0 et les actions de niveau 1.

Les arguments non parsées
Tout ce qui n'est pas option ou action est considere comme non parse et peut etre recupere par la methode getUnparsed(). Si l'on souhaite forcer la fin du parsing de la ligne de commande il est possible de mettre --. Par exemple:
```
 monProg "mon arg" --option k1 v1 -- --option k2 v2 -- autre
 
```
Dans cet exemple seule la premiere option sera considere comme une option. On retrouvera dans unparsed: "mon arg", "--option", "k2", "v2", "--", "autre"

Les alias
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 addAlias(String, String...).
```
 addAlias("-v", "--option", "verbose", "true");
 addAlias("-o", "--option", "outputfile");
 addAlias("-i", "--mon.package.MaClass#MaMethode", "import");
 
```
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:
```
 addAlias("cl", "Code Lutin");
 addAlias("bp", "Benjamin POUSSIN);
 
```
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 la conversion de type nous utilisons common-beans. Les types supportes sont:
- les primitif (byte, short, int, long, float, double, char, boolean)
- String
- File
- URL
- Class
- SqlDate
- SqlTime
- SqlTimestamp
- les tableaux d'un type primitif ou String. Chaque element doit etre separe par une virgule.
Pour suporter d'autre type, il vous suffit d'enregistrer de nouveau converter dans commons-beans.

Les substitutions de variable
ApplicationConfig supporte les substition de variables de la forme ${xxx} où xxx est une autre variable de la configuration.
Exemple (dans un fichier de configuration):
```
 firstname = John
 lastname = Doe
 fullname = ${firstname} ${lastname}
 
```
getOption("fullname") retournera "John Doe".
Since:

0.30

Author:

Benjamin Poussin , tchemit

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`ApplicationConfig.Action` Defines a runtime action to be launched via the `ApplicationConfig.Action.doAction()` method.
`protected static class`	`ApplicationConfig.CacheItem<T>` Item used for cacheOption
`static class`	`ApplicationConfig.OptionList`
`static class`	`ApplicationConfig.SubApplicationConfig` Permet de masquer un prefix.

Field Summary

Fields
Modifier and Type	Field and Description
`protected Map<Integer,List<ApplicationConfig.Action>>`	`actions` TODO
`static String`	`ADJUSTING_PROPERTY` Property name of `adjusting` internal state.
`protected Map<String,List<String>>`	`aliases` TODO
`static String`	`APP_NAME` Permet d'associer un nom de contexte pour prefixer les options `CONFIG_PATH` et `CONFIG_FILE_NAME`.
`protected Map<Class<?>,Object>`	`cacheAction` TODO
`protected Map<String,ApplicationConfig.CacheItem<?>>`	`cacheOption` TODO
`protected Properties`	`classpath` TODO
`static String`	`CONFIG_ENCODING` Configuration encoding key option.
`static String`	`CONFIG_FILE_NAME` Configuration file key option.
`static String`	`CONFIG_PATH` Configuration directory where config path in located.
`protected Map<String,Object>`	`context` permet de conserver des objets associe avec ce ApplicationConfig
`protected Properties`	`curfile` TODO
`protected Properties`	`defaults` TODO
`protected Properties`	`env` TODO
`protected Properties`	`etcfile` TODO
`protected Properties`	`homefile` TODO
`protected boolean`	`inParseOptionPhase` vrai si on est en train de parser les options de la ligne de commande.
`protected Properties`	`jvm` TODO
`protected Properties`	`line` TODO
`static String`	`LIST_SEPARATOR`
`protected Properties`	`options` TODO
`protected String`	`osName` System os name.
`protected PropertyChangeSupport`	`pcs` suport of config modification.
`protected List<String>`	`unparsed` contient apres l'appel de parse, la liste des arguments non utilises
`protected boolean`	`useOnlyAliases` TODO

Constructor Summary

Constructors
Constructor and Description
`ApplicationConfig()` Init ApplicationConfig with current simple class name as config file.
`ApplicationConfig(Class<O> optionClass, Class<A> actionClass, Properties defaults, String configFilename)` Deprecated. since 2.4.8, prefer use `ApplicationConfig(Properties, String)`
`ApplicationConfig(Properties defaults)` Init ApplicationConfig with current simple class name as config file and use Properties parameter as defaults Also init converters.
`ApplicationConfig(Properties defaults, String configFilename)` All in one, this constructor allow to pass all necessary argument to initialise ApplicationConfig and parse command line
`ApplicationConfig(String configFilename)` Create configuration for a particular configuration filename

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addAction(ApplicationConfig.Action action)` Add action to list of action to do.
`void`	`addActionAlias(String alias, String actionMethod)` Add alias for action.
`void`	`addAlias(String alias, String... target)` All argument in aliases as key is substitued by target.
`void`	`addPropertyChangeListener(PropertyChangeListener listener)`
`void`	`addPropertyChangeListener(String propertyName, PropertyChangeListener listener)`
`void`	`cleanUserConfig(String... excludeKeys)` Clean the user configuration file (The one in user home) and save it in user config file.
`protected <T> Object`	`convertOption(Class<T> clazz, String key, String value, boolean asList)` Convert value in instance of clazz or List if asList is true example: convertOption(Boolean.class, "toto", "true,true", false) => false convertOption(Boolean.class, "toto", null, false) => ? ConverterUtil dependant convertOption(Boolean.class, "toto", "true,true", true) => [true, true] convertOption(Boolean.class, "toto", null, true) => []
`protected ApplicationConfig.Action`	`createAction(String name, ListIterator<String> args)` Create action from string, string must be [package.][class][#][method] if package, class or method missing, default is used
`void`	`doAction(int step)` Do action in specified step.
`void`	`doAllAction()` Do all action in specified order step (first 0).
`protected void`	`firePropertyChange(String propertyName, Object oldValue, Object newValue)`
`List<Integer>`	`getActionStep()` Return ordered action step number.
`String`	`getConfigFileName()` Get name of file where options are read (in /etc, $HOME, $CURDIR).
`protected String`	`getConfigFileNameOption()`
`String`	`getConfigPath()` Get configuration file path to use.
`String`	`getEncoding()` Get the encoding used to read/write resources.
`protected String`	`getEncodingOption()` Obtains the key used to store the option encoding.
`Properties`	`getFlatOptions()` Get all options as flat `Properties` object (replace inner options).
`Properties`	`getFlatOptions(boolean replaceInner)` Get all options as flat `Properties` object.
`protected Map<String,Method>`	`getMethods()` Get all set method on this object or super object.
`<E> E`	`getObject(Class<E> clazz)` recupere un objet de la class, s'il n'existe pas encore, il est cree (il faut donc que class soit instanciable E peut prendre en argument du contruteur un objet de type ApplicationConfig
`<E> E`	`getObject(Class<E> clazz, String name)` recupere un objet ayant le nom 'name', s'il n'existe pas encore, il est cree en utilisant la class, sinon il est simplement caster vers cette classe.
`<T> T`	`getOption(Class<T> clazz, String key)` Get option value as typed value.
`Object`	`getOption(ConfigOptionDef key)` Get option value from a option definition.
`String`	`getOption(String key)` get option value as string.
`boolean`	`getOptionAsBoolean(String key)` Get option value as `boolean`.
`Class<?>`	`getOptionAsClass(String key)` Get option value as `Class`.
`Color`	`getOptionAsColor(String key)` Get option value as `Color`.
`Date`	`getOptionAsDate(String key)` Get option value as `Date`.
`double`	`getOptionAsDouble(String key)` Get option value as `double`.
`File`	`getOptionAsFile(String key)` Get option value as `File`.
`float`	`getOptionAsFloat(String key)` Get option value as `float`.
`int`	`getOptionAsInt(String key)` Get option value as `int`.
`KeyStroke`	`getOptionAsKeyStroke(String key)` Get option value as `KeyStroke`.
`ApplicationConfig.OptionList`	`getOptionAsList(String key)` Help to convert value to list of object.
`Locale`	`getOptionAsLocale(String key)` Get option value as `Locale`.
`long`	`getOptionAsLong(String key)` Get option value as `long`.
`<E> E`	`getOptionAsObject(Class<E> clazz, String key)` retourne une nouvelle instance d'un objet dont on recupere la la class dans la configuration via la cle 'key' et le cast en E.
`Object`	`getOptionAsObject(String key)` retourne une nouvelle instance d'un objet dont on recupere la la class dans la configuration via la cle 'key'.
`Properties`	`getOptionAsProperties(String key)` Get option value as `Properties`, this property must be a filepath and file must be a properties.
`<E> E`	`getOptionAsSingleton(Class<E> clazz, String key)` retourne l'objet caster en 'E', instancier via la classe recupere dans la configuration via la cle 'key'.
`Object`	`getOptionAsSingleton(String key)` retourne l'objet instancier via la classe recupere dans la configuration via la cle 'key'.
`Time`	`getOptionAsTime(String key)` Get option value as `Time`.
`Timestamp`	`getOptionAsTimestamp(String key)` Get option value as `Timestamp`.
`URL`	`getOptionAsURL(String key)` Get option value as `URL`.
`Version`	`getOptionAsVersion(String key)` Get option value as `Version`.
`Properties`	`getOptions()` Get all options from configuration.
`Properties`	`getOptionStartsWith(String prefix)` Permet de recuperer l'ensemble des options commencant par une certaine chaine.
`String`	`getOsArch()` Get os arch (system property `os.arch`).
`String`	`getOsName()` Get os name (system property `os.name`).
`protected String[]`	`getParams(Method m, ListIterator<String> args)` Take required argument for method in args.
`String`	`getPrintableConfig(String includePattern, int padding)` Return all configuration used with value, that respect includePattern
`PropertyChangeListener[]`	`getPropertyChangeListeners()`
`PropertyChangeListener[]`	`getPropertyChangeListeners(String propertyName)`
`ApplicationConfig.SubApplicationConfig`	`getSubConfig(String prefix)` Returns a sub config that encapsulate this ApplicationConfig.
`File`	`getSystemConfigFile()` Obtain the system config file location.
`protected String`	`getSystemConfigurationPath()` Get system configuration path.
`List<String>`	`getUnparsed()` Return list of unparsed command line argument
`String`	`getUserConfigDirectory()` Get user configuration path.
`File`	`getUserConfigFile()` Obtain the user config file location.
`static String`	`getUserHome()` Get user home directory (system property `user.home`).
`String`	`getUsername()` Get user name (system property `user.name`).
`boolean`	`hasListeners(String propertyName)`
`boolean`	`hasOption(ConfigOptionDef key)` Teste si un option existe ou non
`boolean`	`hasOption(String key)` Teste si un option existe ou non.
`protected void`	`init(Properties defaults, String configFilename)` On separt l'init du corps du constructeur, car les sous classes ne doivent pas l'executer.
`protected void`	`installSaveUserAction(String... properties)` Install the `saveUserAction` on givne `properties`.
`boolean`	`isAdjusting()`
`boolean`	`isUseOnlyAliases()`
`<A extends ConfigActionDef> void`	`loadActions(A[] actions)` Load given actions.
`<A extends ConfigActionDef> void`	`loadActions(Class<A> actionClass)` Deprecated. since 2.4.8, prefer use now `loadActions(ConfigActionDef[])`
`<O extends ConfigOptionDef> void`	`loadDefaultOptions(Class<O> optionClass)` Deprecated. since 2.4.8, prefer use now `loadDefaultOptions(ConfigOptionDef[])`
`<O extends ConfigOptionDef> void`	`loadDefaultOptions(O[] options)` Load default given options.
`protected void`	`loadResource(URI uri, Properties properties)` Load a resources given by his `uri` to the given `properties` argument.
`protected void`	`migrateUserConfigurationFile(File oldHomeConfig, File homeConfig)` Move old user configuration file `oldHomeConfig` to `homeConfig`.
`ApplicationConfig`	`parse(String... args)` Parse option and call set necessary method, read jvm, env variable, Load configuration file and prepare Action.
`void`	`printConfig()` For debugging.
`void`	`printConfig(PrintStream output)` Print out current configuration in specified output.
`void`	`putObject(Object o)` ajoute un objet dans le context, la classe de l'objet est utilise comme cle
`void`	`putObject(String name, Object o)` ajoute un objet dans le context, 'name' est utilise comme cle
`void`	`removePropertyChangeListener(PropertyChangeListener listener)`
`void`	`removePropertyChangeListener(String propertyName, PropertyChangeListener listener)`
`protected String`	`replaceRecursiveOptions(String option)` Replace included ${xxx} suboptions by their values.
`void`	`save(File file, boolean forceAll, String... excludeKeys)` Save configuration, in specified file.
`void`	`saveForSystem(String... excludeKeys)` Save configuration, in system directory (/etc/) using the `getConfigFileName()`.
`void`	`saveForUser(String... excludeKeys)` Save configuration, in user home directory using the `getConfigFileName()`.
`protected void`	`saveResource(File file, Properties properties, String comment)` Save the given `properties` into the given `file` with the given `comment`.
`void`	`setAdjusting(boolean adjusting)`
`void`	`setAppName(String appName)` Use appName to add a context in config.file and config.path options.
`void`	`setConfigFileName(String name)` Set name of file where options are read (in /etc, $HOME, $CURDIR) This set used `setDefaultOption(String, String)`.
`void`	`setDefaultOption(String key, String value)` Used to put default configuration option in config option.
`void`	`setEncoding(String encoding)` Set the new encoding option.
`void`	`setOption(String key, String value)` Set option value.
`void`	`setOptions(Properties options)` Set manually options when you don't want to use parse method to check properties file configured by `setConfigFileName(String)`.
`void`	`setUseOnlyAliases(boolean useOnlyAliases)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - LIST_SEPARATOR
```
public static final String LIST_SEPARATOR
```
    See Also:
    Constant Field Values
  - CONFIG_FILE_NAME
```
public static final String CONFIG_FILE_NAME
```
    Configuration file key option.
    
    See Also:
    Constant Field Values
  - CONFIG_ENCODING
```
public static final String CONFIG_ENCODING
```
    Configuration encoding key option.
    
    See Also:
    Constant Field Values
  - APP_NAME
```
public static final String APP_NAME
```
    Permet d'associer un nom de contexte pour prefixer les options CONFIG_PATH et CONFIG_FILE_NAME.
    
    See Also:
    Constant Field Values
  - ADJUSTING_PROPERTY
```
public static final String ADJUSTING_PROPERTY
```
    Property name of adjusting internal state.
    
    Since:
    
    1.3
    
    See Also:
    Constant Field Values
  - CONFIG_PATH
```
public static final String CONFIG_PATH
```
    Configuration directory where config path in located.
    Use default system configuration if nothing is defined:
    - Linux : /etc/xxx.properties
    - Windows : C:\\Windows\\System32\\xxx.properties
    - Mac OS : /etc/
    See Also:
    Constant Field Values
  - osName
```
protected String osName
```
    System os name. (windows, linux, max os x)
  - useOnlyAliases
```
protected boolean useOnlyAliases
```
    TODO
  - inParseOptionPhase
```
protected boolean inParseOptionPhase
```
    vrai si on est en train de parser les options de la ligne de commande.
  - defaults
```
protected Properties defaults
```
    TODO
  - classpath
```
protected Properties classpath
```
    TODO
  - etcfile
```
protected Properties etcfile
```
    TODO
  - homefile
```
protected Properties homefile
```
    TODO
  - curfile
```
protected Properties curfile
```
    TODO
  - env
```
protected Properties env
```
    TODO
  - jvm
```
protected Properties jvm
```
    TODO
  - line
```
protected Properties line
```
    TODO
  - options
```
protected Properties options
```
    TODO
  - cacheOption
```
protected Map<String,ApplicationConfig.CacheItem<?>> cacheOption
```
    TODO
  - cacheAction
```
protected Map<Class<?>,Object> cacheAction
```
    TODO
  - unparsed
```
protected List<String> unparsed
```
    contient apres l'appel de parse, la liste des arguments non utilises
  - aliases
```
protected Map<String,List<String>> aliases
```
    TODO
  - actions
```
protected Map<Integer,List<ApplicationConfig.Action>> actions
```
    TODO
  - pcs
```
protected PropertyChangeSupport pcs
```
    suport of config modification.
  - context
```
protected Map<String,Object> context
```
    permet de conserver des objets associe avec ce ApplicationConfig
- Constructor Detail
  - ApplicationConfig
```
public ApplicationConfig()
```
    Init ApplicationConfig with current simple class name as config file.
    Also init converters.
    
    See Also:
    ConverterUtil.initConverters()
  - ApplicationConfig
```
public ApplicationConfig(String configFilename)
```
    Create configuration for a particular configuration filename
    
    Parameters:
    configFilename - name of config to use
  - ApplicationConfig
```
public ApplicationConfig(Properties defaults)
```
    Init ApplicationConfig with current simple class name as config file and use Properties parameter as defaults
    Also init converters.
    
    Parameters:
    defaults - properties
    See Also:
    ConverterUtil.initConverters()
  - ApplicationConfig
```
public ApplicationConfig(Properties defaults,
                 String configFilename)
```
    All in one, this constructor allow to pass all necessary argument to initialise ApplicationConfig and parse command line
    
    Parameters:
    defaults - properties that override default value of optionClass, can be null
    configFilename - override default config filename, can be null
    Since:
    
    2.4.8
  - ApplicationConfig
```
@Deprecated
public ApplicationConfig(Class<O> optionClass,
                            Class<A> actionClass,
                            Properties defaults,
                            String configFilename)
```
    Deprecated. since 2.4.8, prefer use ApplicationConfig(Properties, String)
    
    All in one, this constructor allow to pass all necessary argument to initialise ApplicationConfig and parse command line
    
    Parameters:
    optionClass - class that describe option, can be null
    actionClass - class that describe action, can be null
    defaults - properties that override default value of optionClass, can be null
    configFilename - override default config filename, can be null
- Method Detail
  - init
```
protected void init(Properties defaults,
        String configFilename)
```
    On separt l'init du corps du constructeur, car les sous classes ne doivent pas l'executer.
    
    Parameters:
    defaults - properties that override default value of optionClass, can be null
    configFilename - override default config filename, can be null
    Since:
    
    2.4.9
  - getUserHome
```
public static String getUserHome()
```
    Get user home directory (system property user.home).
    
    Returns:
    user home directory
  - getUsername
```
public String getUsername()
```
    Get user name (system property user.name).
    
    Returns:
    user name
  - getOsName
```
public String getOsName()
```
    Get os name (system property os.name).
    
    Returns:
    os name
    Since:
    
    2.6.6
  - getOsArch
```
public String getOsArch()
```
    Get os arch (system property os.arch).
    
    Returns:
    os arch
    Since:
    
    2.6.6
  - loadDefaultOptions
```
@Deprecated
public <O extends ConfigOptionDef> void loadDefaultOptions(Class<O> optionClass)
```
    Deprecated. since 2.4.8, prefer use now loadDefaultOptions(ConfigOptionDef[])
    
    Load default options of enum pass in param (enum must extend ConfigOptionDef)
    
    Type Parameters:
    O - type of enum extend ConfigOptionDef
    Parameters:
    optionClass - to load
  - loadDefaultOptions
```
public <O extends ConfigOptionDef> void loadDefaultOptions(O[] options)
```
    Load default given options.
    
    Type Parameters:
    O - type of enum extend ConfigOptionDef
    Parameters:
    options - options to load
    Since:
    
    2.4.8
  - loadActions
```
@Deprecated
public <A extends ConfigActionDef> void loadActions(Class<A> actionClass)
```
    Deprecated. since 2.4.8, prefer use now loadActions(ConfigActionDef[])
    
    Load actions of enum pass in param (enum must extend ConfigActionDef)
    
    Type Parameters:
    A - type of enum extend ConfigActionDef
    Parameters:
    actionClass - to load
  - loadActions
```
public <A extends ConfigActionDef> void loadActions(A[] actions)
```
    Load given actions.
    
    Type Parameters:
    A - type of enum extend ConfigActionDef
    Parameters:
    actions - actions to load
    Since:
    
    2.4.8
  - setDefaultOption
```
public void setDefaultOption(String key,
                    String value)
```
    Used to put default configuration option in config option. Those options are used as fallback value.
    
    Parameters:
    key - default property key
    value - default property value
  - save
```
public void save(File file,
        boolean forceAll,
        String... excludeKeys)
          throws IOException
```
    Save configuration, in specified file.
    
    Parameters:
    file - file where config will be writen
    forceAll - if true save all config option (with defaults, classpath, env, command line)
    excludeKeys - optional list of keys to exclude from
    
    Throws:
    
    IOException - if IO pb
  - saveForSystem
```
public void saveForSystem(String... excludeKeys)
```
    Save configuration, in system directory (/etc/) using the getConfigFileName(). Default, env and commande line note saved.
    
    Parameters:
    excludeKeys - optional list of keys to exclude from
  - saveForUser
```
public void saveForUser(String... excludeKeys)
```
    Save configuration, in user home directory using the getConfigFileName(). Default, env and commande line note saved
    
    Parameters:
    excludeKeys - optional list of keys to exclude from
  - cleanUserConfig
```
public void cleanUserConfig(String... excludeKeys)
```
    Clean the user configuration file (The one in user home) and save it in user config file.
    All options with an empty value will be removed from this file.
    Moreover, like saveForUser(String...) the given excludeKeys will never be saved.
    This method can be useful when migrating some configuration from a version to another one with deprecated options (otherwise they will stay for ever in the configuration file with an empty value which is not acceptable).
    Important note: Using this method can have some strange side effects, since it could then allow to reuse default configurations from other level (default, env, jvm,...). Use with care only!
    
    Parameters:
    excludeKeys - optional list of key to not treat in cleaning process, nor save in user user config file.
    Since:
    
    2.6.6
  - getSystemConfigFile
```
public File getSystemConfigFile()
```
    Obtain the system config file location.
    
    Returns:
    the system config file location
  - getUserConfigFile
```
public File getUserConfigFile()
```
    Obtain the user config file location.
    
    Returns:
    the user config file location
  - getUnparsed
```
public List<String> getUnparsed()
```
    Return list of unparsed command line argument
    
    Returns:
    list of unparsed arguments
  - addAction
```
public void addAction(ApplicationConfig.Action action)
```
    Add action to list of action to do.
    
    Parameters:
    action - action to add, can be null.
  - getActionStep
```
public List<Integer> getActionStep()
```
    Return ordered action step number. example: 0,1,5,6
    
    Returns:
    ordered action step number
    Since:
    
    2.4
  - doAllAction
```
public void doAllAction()
                 throws IllegalAccessException,
                        IllegalArgumentException,
                        InvocationTargetException,
                        InstantiationException
```
    Do all action in specified order step (first 0).
    
    Throws:
    
    IllegalAccessException - if action invocation failed
    
    IllegalArgumentException - if action invocation failed
    
    InvocationTargetException - if action invocation failed
    
    InstantiationException - if action invocation failed
    Since:
    
    2.4
    
    See Also:
    ApplicationConfig.Action.Step
  - doAction
```
public void doAction(int step)
              throws IllegalAccessException,
                     IllegalArgumentException,
                     InvocationTargetException,
                     InstantiationException
```
    Do action in specified step.
    
    Parameters:
    step - do action only defined in this step
    
    Throws:
    
    IllegalAccessException - if action invocation failed
    
    IllegalArgumentException - if action invocation failed
    
    InvocationTargetException - if action invocation failed
    
    InstantiationException - if action invocation failed
    See Also:
    ApplicationConfig.Action.Step
  - setUseOnlyAliases
```
public void setUseOnlyAliases(boolean useOnlyAliases)
```
  - isUseOnlyAliases
```
public boolean isUseOnlyAliases()
```
  - getEncoding
```
public String getEncoding()
```
    Get the encoding used to read/write resources.
    This value is stored as an option using the getEncodingOption() key.
    
    Returns:
    the encoding used to read/write resources.
    Since:
    
    2.3
  - setEncoding
```
public void setEncoding(String encoding)
```
    Set the new encoding option.
    
    Parameters:
    encoding - the new value of the option encoding
    Since:
    
    2.3
  - addAlias
```
public void addAlias(String alias,
            String... target)
```
    All argument in aliases as key is substitued by target.
    
    Parameters:
    alias - alias string as '-v'
    target - substitution as '--option verbose true'
  - addActionAlias
```
public void addActionAlias(String alias,
                  String actionMethod)
```
    Add alias for action. This method put just -- front the actionMethod and call addAlias(String, String...).
    
    Parameters:
    alias - the alias to add for the given method action
    actionMethod - must be fully qualified method path: package.Class#method
  - setConfigFileName
```
public void setConfigFileName(String name)
```
    Set name of file where options are read (in /etc, $HOME, $CURDIR) This set used setDefaultOption(String, String).
    
    Parameters:
    name - file name
  - getConfigFileName
```
public String getConfigFileName()
```
    Get name of file where options are read (in /etc, $HOME, $CURDIR).
    
    Returns:
    name of file
  - isAdjusting
```
public boolean isAdjusting()
```
  - setAdjusting
```
public void setAdjusting(boolean adjusting)
```
  - getConfigFileNameOption
```
protected String getConfigFileNameOption()
```
  - getEncodingOption
```
protected String getEncodingOption()
```
    Obtains the key used to store the option encoding.
    
    Returns:
    the encoding option'key
    Since:
    
    2.3
  - setAppName
```
public void setAppName(String appName)
```
    Use appName to add a context in config.file and config.path options.
    Ex for an application named 'pollen' : config.file option becomes pollen.config.file and config.path becomes pollen.config.path
    
    Parameters:
    appName - to use as application context
    Since:
    
    1.2.1
  - getConfigPath
```
public String getConfigPath()
```
    Get configuration file path to use.
    Use (in order) one of the following definition:
    - CONFIG_PATH option
    - system dependant path
    Returns:
    path to use with endind File.separator
    Since:
    
    1.2.1
  - getSystemConfigurationPath
```
protected String getSystemConfigurationPath()
```
    Get system configuration path.
    Currently supported:
    - Windows : C:\Windows\System32
    - Unix : /etc/
    Returns:
    the system path
    Since:
    
    1.2.1
  - getUserConfigDirectory
```
public String getUserConfigDirectory()
```
    Get user configuration path.
    Currently supported:
    - Windows : ${user.home}\\Application Data\\
    - Max os x : ${user.home}/Library/Application Support
    - Unix : ${user.home}/.config
    Unix norm is based on freedesktop concept explained here : http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
    Returns:
    the user configuration path
    Since:
    
    1.2.1
  - hasOption
```
public boolean hasOption(String key)
```
    Teste si un option existe ou non.
    
    Parameters:
    key - la clef de l'option à tester
    
    Returns:
    true si l'option existe, false sinon.
  - hasOption
```
public boolean hasOption(ConfigOptionDef key)
```
    Teste si un option existe ou non
    
    Parameters:
    key - la clef de l'option à tester
    
    Returns:
    true si 'loption existe, false sinon.
  - putObject
```
public void putObject(Object o)
```
    ajoute un objet dans le context, la classe de l'objet est utilise comme cle
    
    Since:
    
    2.4.2
  - putObject
```
public void putObject(String name,
             Object o)
```
    ajoute un objet dans le context, 'name' est utilise comme cle
    
    Since:
    
    2.4.2
  - getObject
```
public <E> E getObject(Class<E> clazz)
```
    recupere un objet de la class, s'il n'existe pas encore, il est cree (il faut donc que class soit instanciable
    E peut prendre en argument du contruteur un objet de type ApplicationConfig
    
    Since:
    
    2.4.2
  - getObject
```
public <E> E getObject(Class<E> clazz,
              String name)
```
    recupere un objet ayant le nom 'name', s'il n'existe pas encore, il est cree en utilisant la class, sinon il est simplement caster vers cette classe.
    E peut prendre en argument du contruteur un objet de type ApplicationConfig
    
    Since:
    
    2.4.2
  - getOptionAsObject
```
public Object getOptionAsObject(String key)
```
    retourne une nouvelle instance d'un objet dont on recupere la la class dans la configuration via la cle 'key'. Retourne null si la cle n'est pas retrouve
    
    Since:
    
    2.4.2
  - getOptionAsObject
```
public <E> E getOptionAsObject(Class<E> clazz,
                      String key)
```
    retourne une nouvelle instance d'un objet dont on recupere la la class dans la configuration via la cle 'key' et le cast en E. Retourne null si la cle n'est pas retrouve
    E peut prendre en argument du contruteur un objet de type ApplicationConfig
    
    Since:
    
    2.4.2
  - getOptionAsSingleton
```
public Object getOptionAsSingleton(String key)
```
    retourne l'objet instancier via la classe recupere dans la configuration via la cle 'key'. Une fois instancie, le meme objet est toujours retourne. On null si key n'est pas retrouve.
    La classe peut avoir un constructeur prenant un ApplicationConfig
    
    Since:
    
    2.4.2
  - getOptionAsSingleton
```
public <E> E getOptionAsSingleton(Class<E> clazz,
                         String key)
```
    retourne l'objet caster en 'E', instancier via la classe recupere dans la configuration via la cle 'key'. Une fois instancie, le meme objet est toujours retourne. On null si key n'est pas retrouve
    La classe peut avoir un constructeur prenant un ApplicationConfig
    
    Since:
    
    2.4.2
  - setOption
```
public void setOption(String key,
             String value)
```
    Set option value.
    
    Parameters:
    key - property key
    value - property value
  - getOption
```
public String getOption(String key)
```
    get option value as string.
    Replace inner ${xxx} value.
    
    Parameters:
    key - the option's key
    
    Returns:
    String representation value
  - replaceRecursiveOptions
```
protected String replaceRecursiveOptions(String option)
```
    Replace included ${xxx} suboptions by their values.
    
    Parameters:
    option - option to replace into
    
    Returns:
    replaced option
    Since:
    
    1.1.3
  - getSubConfig
```
public ApplicationConfig.SubApplicationConfig getSubConfig(String prefix)
```
    Returns a sub config that encapsulate this ApplicationConfig.
    
    Parameters:
    prefix - prefix to put automaticaly at beginning of all key
    
    Returns:
    sub config that encapsulate this ApplicationConfig
    Since:
    
    2.4.9
  - getOptionStartsWith
```
public Properties getOptionStartsWith(String prefix)
```
    Permet de recuperer l'ensemble des options commencant par une certaine chaine.
    
    Parameters:
    prefix - debut de cle a recuperer
    
    Returns:
    la liste des options filtrées
  - getOption
```
public Object getOption(ConfigOptionDef key)
```
    Get option value from a option definition.
    
    Parameters:
    key - the definition of the option
    
    Returns:
    the value for the given option
  - getOption
```
public <T> T getOption(Class<T> clazz,
              String key)
```
    Get option value as typed value.
    
    Type Parameters:
    T - type of the object wanted as return type
    Parameters:
    clazz - type of object wanted as return type
    key - the option's key
    
    Returns:
    typed value
  - convertOption
```
protected <T> Object convertOption(Class<T> clazz,
                       String key,
                       String value,
                       boolean asList)
```
    Convert value in instance of clazz or List if asList is true
    example:
  - convertOption(Boolean.class, "toto", "true,true", false) => false
  - convertOption(Boolean.class, "toto", null, false) => ? ConverterUtil dependant
  - convertOption(Boolean.class, "toto", "true,true", true) => [true, true]
  - convertOption(Boolean.class, "toto", null, true) => []

Parameters:: clazz - result type expected; key - option key; value - value to convert; asList - value is string that represente a list
Returns:: the converted option in the required type

getOptionAsList
```
public ApplicationConfig.OptionList getOptionAsList(String key)
```
Help to convert value to list of object. If no option for this key empty List is returned finaly

Parameters:
key - the key of searched option

Returns:
value of option list

getOptionAsFile
```
public File getOptionAsFile(String key)
```
Get option value as File.

Parameters:
key - the option's key

Returns:
value as file

getOptionAsColor
```
public Color getOptionAsColor(String key)
```
Get option value as Color.

Parameters:
key - the option's key

Returns:
value as color

getOptionAsProperties
```
public Properties getOptionAsProperties(String key)
                                 throws IOException
```
Get option value as Properties, this property must be a filepath and file must be a properties.
Returned Properties is RecursiveProperties.

Parameters:
key - the option's key

Returns:
Properties object loaded with value pointed by file

Throws:

IOException - if exception occured on read file

getOptionAsURL
```
public URL getOptionAsURL(String key)
```
Get option value as URL.

Parameters:
key - the option's key

Returns:
value as URL

getOptionAsClass
```
public Class<?> getOptionAsClass(String key)
```
Get option value as Class.

Parameters:
key - the option's key

Returns:
value as Class

getOptionAsDate
```
public Date getOptionAsDate(String key)
```
Get option value as Date.

Parameters:
key - the option's key

Returns:
value as Date

getOptionAsTime
```
public Time getOptionAsTime(String key)
```
Get option value as Time.

Parameters:
key - the option's key

Returns:
value as Time

getOptionAsTimestamp
```
public Timestamp getOptionAsTimestamp(String key)
```
Get option value as Timestamp.

Parameters:
key - the option's key

Returns:
value as Timestamp

getOptionAsInt
```
public int getOptionAsInt(String key)
```
Get option value as int.

Parameters:
key - the option's key

Returns:
value as int

getOptionAsLong
```
public long getOptionAsLong(String key)
```
Get option value as long.

Parameters:
key - the option's key

Returns:
value as long

getOptionAsFloat
```
public float getOptionAsFloat(String key)
```
Get option value as float.

Parameters:
key - the option's key

Returns:
value as float
Since:

2.2

getOptionAsDouble
```
public double getOptionAsDouble(String key)
```
Get option value as double.

Parameters:
key - the option's key

Returns:
value as double

getOptionAsBoolean
```
public boolean getOptionAsBoolean(String key)
```
Get option value as boolean.

Parameters:
key - the option's key

Returns:
value as boolean.

getOptionAsLocale
```
public Locale getOptionAsLocale(String key)
```
Get option value as Locale.

Parameters:
key - the option's key

Returns:
value as Locale.
Since:

2.0

getOptionAsVersion
```
public Version getOptionAsVersion(String key)
```
Get option value as Version.

Parameters:
key - the option's key

Returns:
value as Version.
Since:

2.0

getOptionAsKeyStroke
```
public KeyStroke getOptionAsKeyStroke(String key)
```
Get option value as KeyStroke.

Parameters:
key - the option's key

Returns:
value as KeyStroke.
Since:

2.5.1

getOptions
```
public Properties getOptions()
```
Get all options from configuration.

Returns:
Properties which contains all options

setOptions
```
public void setOptions(Properties options)
```
Set manually options when you don't want to use parse method to check properties file configured by setConfigFileName(String).

Parameters:
options - Properties which contains all options to set

getFlatOptions
```
public Properties getFlatOptions()
```
Get all options as flat Properties object (replace inner options).

Returns:
flat Properties object
Since:

1.2.2

getFlatOptions
```
public Properties getFlatOptions(boolean replaceInner)
```
Get all options as flat Properties object.

Parameters:
replaceInner - if true replace imbricated options by theirs values

Returns:
flat Properties object
Since:

1.2.2

installSaveUserAction
```
protected void installSaveUserAction(String... properties)
```
Install the saveUserAction on givne properties.

Parameters:
properties - properties on which insalls the saveUserAction

getMethods
```
protected Map<String,Method> getMethods()
```
Get all set method on this object or super object.

Returns:
map with method name without set and in lower case as key, and method as value

getParams
```
protected String[] getParams(Method m,
                 ListIterator<String> args)
```
Take required argument for method in args. Argument used is removed from args. If method has varArgs, we take all argument to next '--'

Parameters:
m - the method to call
args - iterator with many argument (equals or more than necessary

Returns:
the arguments found for the given method

createAction

protected ApplicationConfig.Action createAction(String name,
                                    ListIterator<String> args)
                                         throws ArgumentsParserException,
                                                InstantiationException,
                                                IllegalAccessException,
                                                IllegalArgumentException,
                                                InvocationTargetException

Create action from string, string must be [package.][class][#][method] if package, class or method missing, default is used

Parameters:: name - name of the action; args - arguments for action invocation
Returns:: the created action
Throws:: ArgumentsParserException - if parsing failed; IllegalAccessException - if could not create action; IllegalArgumentException - if could not create action; InstantiationException - if could not create action; InvocationTargetException - if could not create action

parse
```
public ApplicationConfig parse(String... args)
                        throws ArgumentsParserException
```
Parse option and call set necessary method, read jvm, env variable, Load configuration file and prepare Action.

Parameters:
args - argument as main(String[] args)

Returns:
ApplicationConfig instance

Throws:

ArgumentsParserException - if parsing failed

migrateUserConfigurationFile
```
protected void migrateUserConfigurationFile(File oldHomeConfig,
                                File homeConfig)
                                     throws IOException
```
Move old user configuration file oldHomeConfig to homeConfig.

Parameters:
oldHomeConfig - old configuration file path
homeConfig - new configuration file path

Throws:

IOException - if could not move configuration file

loadResource
```
protected void loadResource(URI uri,
                Properties properties)
                     throws IOException
```
Load a resources given by his uri to the given properties argument.

Parameters:
uri - the uri to load
properties - the properties file to load

Throws:

IOException - if something occurs bad while loading resource
Since:

2.3

See Also:
Properties.load(Reader)

saveResource
```
protected void saveResource(File file,
                Properties properties,
                String comment)
                     throws IOException
```
Save the given properties into the given file with the given comment.

Parameters:
file - the location where to store the properties
properties - the properties file to save
comment - the comment to add in the saved file

Throws:

IOException - if something occurs bad while saving resource
Since:

2.3

See Also:
Properties.store(Writer, String)

printConfig
```
public void printConfig()
```
For debugging.

printConfig
```
public void printConfig(PrintStream output)
```
Print out current configuration in specified output.

Parameters:
output - output to write config to
Since:

1.1.4

getPrintableConfig
```
public String getPrintableConfig(String includePattern,
                        int padding)
```
Return all configuration used with value, that respect includePattern

Parameters:
includePattern - null for all value, or config key pattern (ex: "wikitty.*")
padding - for better presentation, you can use padding to align '=' sign

Returns:
string that represent config
Since:

1.5.2

firePropertyChange

protected void firePropertyChange(String propertyName,
                      Object oldValue,
                      Object newValue)

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                             PropertyChangeListener listener)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                PropertyChangeListener listener)

hasListeners

public boolean hasListeners(String propertyName)

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners(String propertyName)

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners()

Class ApplicationConfig

A finir...

Bonnes pratiques

Lecture des fichiers de configuration

La sauvegarde

Les options de configuration

Les actions

Les arguments non parsées

Les alias

Conversion de type

Les substitutions de variable

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LIST_SEPARATOR

CONFIG_FILE_NAME

CONFIG_ENCODING

APP_NAME

ADJUSTING_PROPERTY

CONFIG_PATH

osName

useOnlyAliases

inParseOptionPhase

defaults

classpath

etcfile

homefile

curfile

env

jvm

line

options

cacheOption

cacheAction

unparsed

aliases

actions

pcs

context

Constructor Detail

ApplicationConfig

ApplicationConfig

ApplicationConfig

ApplicationConfig

ApplicationConfig

Method Detail

init

getUserHome

getUsername

getOsName

getOsArch

loadDefaultOptions

loadDefaultOptions

loadActions

loadActions

setDefaultOption

save

saveForSystem

saveForUser

cleanUserConfig

getSystemConfigFile

getUserConfigFile

getUnparsed

addAction

getActionStep

doAllAction

doAction

setUseOnlyAliases

isUseOnlyAliases

getEncoding

setEncoding

addAlias

addActionAlias

setConfigFileName

getConfigFileName

isAdjusting

setAdjusting