org.nuiton.config

Class ApplicationConfig

java.lang.Object

org.nuiton.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.
org.nuiton.util.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)
                   throws ApplicationConfigSaveException

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

Throws:

ApplicationConfigSaveException

saveForUser

public void saveForUser(String... excludeKeys)
                 throws ApplicationConfigSaveException

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

Throws:

ApplicationConfigSaveException

cleanUserConfig

public void cleanUserConfig(String... excludeKeys)
                     throws ApplicationConfigSaveException

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.

Throws:

ApplicationConfigSaveException

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 org.nuiton.util.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()