Configuration Class Reference

Collaboration diagram for Configuration:

Class Description

---

This class is a container of objects of type ConfigurationPlugin, sorted by their priority and provides a single user interface to query configuration data from those.

Interface methods are implemented synchronized.

By default, all category and variable names are case insensitive. This is at least true for the default plug-ins delivered with ALib.

Variables by default can contain other variables, which are recursively substituted by this method. For more information about the (adjustable) syntax, see Variable Substitution.

See documentation of namespace com.aworx.lib.config for more information on ALib external configuration variables.

Inner Classes
class	PluginAndPrio

Public Static Fields
static final int	PRIO_AUTO_DETECT = 500
static final int	PRIO_CLI_ARGS = 40000
static final int	PRIO_DEFAULT_VALUES = 10000
static final int	PRIO_ENVIRONMENT = 30000
static final int	PRIO_PROTECTED_VALUES = Integer.MAX_VALUE
static final int	PRIO_STANDARD = 20000

Public Fields
NumberFormat	numberFormat = new NumberFormat()
char[]	substitutionVariableDelimiters
AString	substitutionVariableEnd = new AString()
AString	substitutionVariableStart = new AString("$")
ArrayList< AString >	trueValues

Public Methods
	Configuration ()
	Configuration (boolean addDefaultPlugins)
int	fetchFromDefault (ConfigurationPlugin dest)
synchronized int	fetchFromDefault (ConfigurationPlugin dest, String sectionName)
synchronized ConfigurationPlugin	getPlugin (int priority)
boolean	hasPlugins ()
synchronized void	insertPlugin (ConfigurationPlugin plugin, int priority)
boolean	isTrue (AString value)
synchronized int	load (Variable variable)
int	loadFromString (Variable variable, Object externalizedValue)
int	loadImpl (Variable variable, boolean substitute)
int	protect (Variable variable)
int	protect (Variable variable, Object externalizedValue)
synchronized boolean	removePlugin (ConfigurationPlugin plugin)
synchronized void	setCommandLineArgs (String[] args)
int	store (Variable variable)
synchronized int	store (Variable variable, Object externalizedValue)
int	storeDefault (Variable variable)
int	storeDefault (Variable variable, Object externalizedValue)

Protected Fields
ArrayList< PluginAndPrio >	plugins = new ArrayList<PluginAndPrio>()
AString	tmpConversion = new AString()
Substring	tmpReplVarAll = new Substring()
Substring	tmpReplVarCategory = new Substring()
Substring	tmpReplVarName = new Substring()

Package Access Methods
synchronized public< TPluginType extends ConfigurationPlugin > TPluginType	getPluginTypeSafe (Class< TPluginType > classT)
synchronized public< TPluginType extends ConfigurationPlugin > TPluginType	getPluginTypeSafe (int priority, Class< TPluginType > classT)

Constructor & Destructor Documentation

Configuration() [1/2]

Configuration

(

boolean

addDefaultPlugins

)

---

Constructs a Configuration. If addDefaultPlugins is true, registers the initial plug-ins as follows

Priority	Plug-in Type
Configuration.PRIO_DEFAULT_VALUES	InMemoryPlugin
Configuration.PRIO_ENVIRONMENT	Environment
Configuration.PRIO_CLI_ARGS	CLIArgs
Configuration.PRIO_PROTECTED_VALUES	InMemoryPlugin

Parameters

addDefaultPlugins

If true, the default plugins are added. Defaults to true.

Configuration() [2/2]

Configuration

(

)

---

Overloaded constructor providing default parameter.

Member Function Documentation

fetchFromDefault() [1/2]

int fetchFromDefault

(

ConfigurationPlugin

dest

)

---

Overloaded version providing default parameter sectionName.

Parameters

dest	The destination plug-in.

Returns

The number of variables fetched.

fetchFromDefault() [2/2]

synchronized int fetchFromDefault	(	ConfigurationPlugin	dest,
		String	sectionName
	)

---

This method fetches all values from a plug-in of priority PRIO_DEFAULT_VALUES, which are not present in the given plug-in dest and stores them in that. This is useful to collect all generated default values and store them in a users' configuration file. This way, the user can identify configurable options easily.

Note

Applications might want to copy only a portion of the default values (of a section) to not blow up a users' configuration. To achieve this, a custom method to fetch selected values has to be implemented. In this respect, this method is a very simple default and its source might be used as a jump start.

Parameters

dest	The destination plug-in.
sectionName	Optional string denoting a section to fetch. Defaults to null.

Returns

The number of variables fetched.

getPlugin()

synchronized ConfigurationPlugin getPlugin

(

int

priority

)

---

Returns the plug-in with the given priority. If the plug-in does not exist, null is returned.

Note

The method is not thread-safe. At least, the returned plugin may become invalid after the method returned. For thread-safe operations, this object needs to be acquired and released explicitly.

Usually this method is used in the termination section of a software, when no parallel threads are active.

It may be used for example to fetch default variables into a configuration file.

Parameters

priority

The priority of the plug-in to return.

Returns

The plug-in requested or null if not available.

getPluginTypeSafe() [1/2]

synchronized public<TPluginType extends ConfigurationPlugin> TPluginType getPluginTypeSafe ( Class< TPluginType >  classT )

package

---

Searches all plug-ins for the first found with type TPluginType.

Parameters

classT

The class object of TPluginType (use TPluginType.class when calling).

Template Parameters

TPluginType

The type of the plugin to search.

Returns

The plug-in of requested type. null if not available.

getPluginTypeSafe() [2/2]

synchronized public<TPluginType extends ConfigurationPlugin> TPluginType getPluginTypeSafe ( int  priority, Class< TPluginType >  classT  )

package

---

Same as getPlugin, but converts the plug-in found to the template type. A type-check is performed. If the plugin has a different type, null is returned.

Parameters

priority	The priority of the plug-in to return.
classT	The class object of TPluginType (use TPluginType.class when calling).

Template Parameters

TPluginType

The type of the plugin to search.

Returns

The plug-in of requested type and priority. null if not available.

hasPlugins()

boolean hasPlugins

(

)

---

Checks if any plug-in is attached. This is useful if optional configuration objects are used. In case no plug-in was attached (by a third party), the effort to declare and search a variable can be omitted.

Returns

true if this object has any plugin set, false otherwise.

insertPlugin()

synchronized void insertPlugin	(	ConfigurationPlugin	plugin,
		int	priority
	)

---

Adds the given plug-in to the list of plug-ins used to query configuration values. Higher numbers for parameter priority, prioritize this plug-in against those with lower values. Default values are provided with static constant fields PRIO_CLI_ARGS, PRIO_ENVIRONMENT and PRIO_STANDARD.

Parameters

plugin	The plug-in to insert.
priority	The priority of the plug-in.

isTrue()

boolean isTrue

(

AString

value

)

---

Utility method that checks if a given value represents boolean true. Uses field trueValues. Comparisons are made case insensitive.

Parameters

value

The value to check

Returns

Returns true, if the value represents 'true', false if not.

load()

synchronized int load

(

Variable

variable

)

---

Receives and optionally creates configuration variable.

If the variable was not found and Variable.defaultValue in variable is set, the method adds the value value to a plug-in of priority PRIO_DEFAULT_VALUES, (respectively to the plug-in found at or below PRIO_DEFAULT_VALUES). For the conversion of the value, field ConfigurationPlugin.stringConverter of field a plug-in of priority PRIO_DEFAULT_VALUES, is used. (Which has to be present.)

Parameters

variable

The variable to receive.

Returns

The priority of the configuration plug-in that provided the result. 0 if not found.

loadFromString()

int loadFromString	(	Variable	variable,
		Object	externalizedValue
	)

---

Convenience method to set values according to the provided string. For the conversion of the "externalized" string, method XTernalizer.loadFromString of field ConfigurationPlugin.stringConverter of a plug-in of priority PRIO_DEFAULT_VALUES, is used.

Parameters

variable	The variable object.
externalizedValue	The new value to write.

Returns

The size of the variable after parsing.

loadImpl()

int loadImpl	(	Variable	variable,
		boolean	substitute
	)

---

Implementation of get method. No locking is performed (has to be done before invoking this method)

Parameters

variable	The variable to get.
substitute	If false, automatic variable substitutions are suppressed.

Returns

Zero if the variable was not found. Otherwise it returns the priority of the (first) plug-in that contained the variable.

protect() [1/2]

int protect

(

Variable

variable

)

---

Overloaded version providing default value null for parameter externalizedValue.

Parameters

variable

The variable object.

Returns

The result of store(this).

protect() [2/2]

int protect	(	Variable	variable,
		Object	externalizedValue
	)

---

Convenience method that stores the variable with priority Configuration.PRIO_PROTECTED_VALUES.

The variable value is determined as follows:

• If optional parameter externalizedValue is provided and not nulled, the values are loaded from that string.
• Otherwise, if the variable has no values set but field Variable.defaultValue is not nulled, then values are loaded from this field.
• If all is unset (the variable values, parameter externalizedValue and field Variable.defaultValue), then the unset variable is stored, which results in removing an existing protection value from the configuration.

Parameters

variable	The variable object.
externalizedValue	Optional externalized value string. If given, the variable is set prior to writing.

Returns

The result of store(this).

removePlugin()

synchronized boolean removePlugin

(

ConfigurationPlugin

plugin

)

---

Remove the given plug-in from the list of plug-ins. Responsibility for deletion of removed plug-ins moves to the remover. Active (inserted) plug-ins get deleted by class' destructor.

Parameters

plugin

The plug-in to be deleted.

Returns

true if the plug-in was removed, else false.

setCommandLineArgs()

synchronized void setCommandLineArgs

(

String[]

args

)

---

Sets the command line arguments for default plug-in CLIArgs.

Note

This method should be called for instances of this class after construction.
In standard application scenarios, this method is invoked by method ALIB.init for the static singleton ALIB.config.

Parameters

args	Parameters taken from standard Java method main() (the list of command line arguments). Accepts null to ignore command line parameters.

store() [1/2]

int store

(

Variable

variable

)

---

Overloaded version that provides default value null for parameter externalizedValue.

Parameters

variable

The variable object.

Returns

The priority of the configuration plug-in that the value was written to.

store() [2/2]

synchronized int store	(	Variable	variable,
		Object	externalizedValue
	)

---

Writes the variable into one of the plug-ins registered with this configuration object. The plug-ins are looped in descending order of priority, until a first plug-in confirms the variable to be written.

The first (most highly prioritized) plug-in to start the loop with, is defined by field Variable::priority of the given variable.

If this is unset (0), which is the default value of the field for freshly declared variable objects, the starting priority value of the loop is detected.

Detection is made by searching the variable in the plug-ins prior to storing it. The search order is likewise by priority, starting with the highest. If the variable was not found, PRIO_DEFAULT_VALUES is chosen. Usually the writing loop then will also already end there, because standard configuration sets have a write-enabled in-memory plug-in at that priority.

If the variable was found in the plug-in of priority PRIO_PROTECTED_VALUES, the method stops without storing anything.

This approach of storing variables, supports various use cases very nicely. Some of the frequent ones shall be named here:

• By setting the field to PRIO_DEFAULT_VALUES, the value becomes just a default and does not overwrite externally specified values.
• Leaving the field to its uninitialized state (0), allows to store the variable in the plug-in that it was originally read from, or - if not stored already - in default values.
• Setting the field to PRIO_PROTECTED_VALUES allows to protect the variable value in respect to external manipulation.
• Setting the field to PRIO_PROTECTED_VALUES - 1, allows to store the variable just in the plug-in with highest possible priority.
• Finally, an application specific reason might motivate a caller of this method to preset a distinct priority value prior to invoking this method. For example, a variable might be related to a second one. If the priority of the second one is known, that priority might be set prior to invoking this message, to have both variables potentially stored in the same plug-in.

The method returns the priority of the configuration plug-in that the value was written to. This value is as well stored in field Variable::priority of the given object.

A result of 0 (no priority) indicates that the variable was not written. This might only happen if

• the default plug-in of this configuration is not configured or does not support writing variables,
• field Priority of the variable was set below PRIO_DEFAULT_VALUES (but greater than 0),
• the detected priority was PRIO_PROTECTED_VALUES. (In this case, obviously the application does not want to allow changes and writing the variable into a different plug-in has no effect. This way, such variables also do not appear in a users' configuration in the case that on program termination, new default values are copied there.)

Optional parameter externalizedValue allows to provide a string that is parsed by the storing plug-in to reset the variables' values prior to writing.

See also

Default variables are often to be stored with the termination of a process. For this, see method fetchFromDefault.

Parameters

variable	The variable object.
externalizedValue	Optional externalized value string. If given, the variable is set prior to writing.

Returns

The priority of the configuration plug-in that the value was written to.

storeDefault() [1/2]

int storeDefault

(

Variable

variable

)

---

Overloaded version providing default value null for parameter externalizedValue.

Parameters

variable

The variable object.

Returns

The result of store(this).

storeDefault() [2/2]

int storeDefault	(	Variable	variable,
		Object	externalizedValue
	)

---

Convenience method that stores the variable with priority Configuration.PRIO_DEFAULT_VALUES.

The variable value is determined as follows:

• If optional parameter externalizedValue is provided and not nulled, the values are loaded from that string.
• Otherwise, if the variable has no values set but field Variable.defaultValue is not nulled, then values are loaded from this field.
• If all is unset (the variable values, parameter externalizedValue and field Variable.defaultValue, then the unset variable is stored, which results in removing an existing default value from the configuration.

Parameters

variable	The variable object.
externalizedValue	Optional externalized value string. If given, the variable is set prior to writing.

Returns

The result of ALIB.config.store(this).

Member Data Documentation

numberFormat

NumberFormat numberFormat = new NumberFormat()

Number format definition used to read and write int and float values.

plugins

ArrayList<PluginAndPrio> plugins = new ArrayList<PluginAndPrio>()

protected

The plug-ins we have attached

PRIO_AUTO_DETECT

final int PRIO_AUTO_DETECT = 500

static

Constant providing a priority which is even lower than default. This priority is not used by any standard plug-ins and currently not even anywhere in detail ALib. The rational to provide it is for third party libraries that may use this value in cases where values are estimated or detected - instead of defaulted. A user of the library may then overwrite such auto-detection by setting a default value in the configuration.

PRIO_CLI_ARGS

final int PRIO_CLI_ARGS = 40000

static

Constant providing default priority for IniFile (or similar) external plug-in.

PRIO_DEFAULT_VALUES

final int PRIO_DEFAULT_VALUES = 10000

static

Constant providing a low priority. This is used with PRIO_DEFAULT_VALUES

PRIO_ENVIRONMENT

final int PRIO_ENVIRONMENT = 30000

static

Constant providing default priority for environment variables plug-in.

PRIO_PROTECTED_VALUES

final int PRIO_PROTECTED_VALUES = Integer.MAX_VALUE

static

Constant providing the highest possible priority. This is used with PRIO_PROTECTED_VALUES

PRIO_STANDARD

final int PRIO_STANDARD = 20000

static

Constant providing default priority for command-line parameters plug-in.

substitutionVariableDelimiters

char [] substitutionVariableDelimiters

Initial value:

= { ' ','$','@',',','.',';',':','\"','\'','+','-','*','/','\\',
            '§','%','&','(',')','[',']','{','}','<','>','=','?','\'','`','~','#' }

The delimiters used to identify the end of a substitutable variable. If field substitutionVariableEnd is not empty, this field is ignored. Otherwise, all characters defined in this string are used to identify the end of a substitution variable.

substitutionVariableEnd

AString substitutionVariableEnd = new AString()

The end of a substitution variables. If this field is set, then field sSubstitutionVariableDelimiters is ignored. If this field is null (the default) or empty, it is ignored and characters in field substitutionVariableDelimiters are used to identify the end of the variable.

substitutionVariableStart

AString substitutionVariableStart = new AString("$")

The start string to identify substitution variables. Defaults to single character '$'. If a string is set, i.e. "${", then field substitutionVariableEnd may be set accordingly, i.e. "}"

tmpConversion

AString tmpConversion = new AString()

protected

A temporary object used for conversion

tmpReplVarAll

Substring tmpReplVarAll = new Substring()

protected

A temporary object used with variable substitution

tmpReplVarCategory

Substring tmpReplVarCategory = new Substring()

protected

A temporary object used with variable substitution

tmpReplVarName

Substring tmpReplVarName = new Substring()

protected

A temporary object used with variable substitution

trueValues

ArrayList<AString> trueValues

Values considered to indicate "true". Defaults to { "1", "true", "t", "yes", "y", "on", "ok" }. See methods isTrue.

Application specific values (e.g. localization languages) might be added by publicly accessing this field and adding new values (or removing existing).

---

The documentation for this class was generated from the following file:

• Configuration.java