Variable Class Reference

Collaboration diagram for Variable:

Class Description

---

This class is used to load and store external configuration data with objects of class Configuration and its plug-ins ConfigurationPlugin.

Note

For general information about external configuration variables, see namespace documentation com.aworx.lib.config.

Construction/Redeclaration:
While constructors accepting attributes of a variable exist, it is recommended to declare all external configuration variables in a central place, using statically or dynamically allocated objects of type VariableDecl and pass such record to the constructor of a variable.

The class is designed to be 'reused' to avoid repeated allocation/de-allocation of memory. After invoking one of the overloaded methods declare, which share the same signatures as the overloaded constructors, a variable is freshly initialized. Internally, the memory allocated for values remains allocated.

Values:
A variable can contain zero, one or several values. If zero, then the variable was either not loaded, yet or the load operation failed (no configuration plug-in defined the variable). Method size reports the currently available values and methods getString(int), getInteger(int) and getFloat(int) return a value. Internally all values are stored as strings. If field config is set, its field Configuration.numberFormat is used for floating point conversion.

When storing a variable that contains more than one value, field delim has to be set. Conversely, when reading a variable that contains multiple values, the delimiter has to be set prior to the load operation.

Note

This is not true when loading/storing a variable directly in a plug-in of type InMemoryPlugin or might also not be true with custom configuration plug-in types which for example might store the values in a database.
However, with the default plug-ins CLIArgs, Environment and IniFile the delimiter is needed! Therefore, it is best practice to always define a proper delimiter if a variable is multi-valued.

Loading and Storing:
There are two ways of loading and storing a variable:

• Using the interface of class Configuration which allows to load and store variables from different sources (plug-ins) in a prioritized way.
• Using the interface of class ConfigurationPlugin which may be used if the decision about the source or drain of a load/store operation is explicitly made by a code unit.

Storing empty variables (method size returns 0) deletes a variable from the those configuration plug-ins that are write enabled.

Public Static Fields
static final int	FORMAT_HINT_CUSTOM = 1 << 16
static final int	FORMAT_HINT_MULTILINE = 1 << 0
static final int	FORMAT_HINT_NO_DELIM_SPACES = 1 << 1
static final int	FORMAT_HINT_NONE = 0

Public Fields
AString	category = new AString()
AString	comments = new AString()
Configuration	config = null
AString	defaultValue = new AString()
char	delim = '\0'
String	formatAttrAlignment
int	formatHints
AString	fullname = new AString()
AString	name = new AString()
int	priority = 0

Public Methods
	Variable ()
	Variable (CharSequence category, CharSequence name)
	Variable (CharSequence category, CharSequence name, char delim)
	Variable (CharSequence category, CharSequence name, char delim, CharSequence comments)
	Variable (Variable variable)
	Variable (VariableDecl declaration, Object... replacements)
AString	add ()
AString	add (boolean value)
AString	add (Object value)
Variable	clearValues ()
Variable	clearValues (int startIdx)
Variable	declare (CharSequence category, CharSequence name)
Variable	declare (CharSequence category, CharSequence name, char delim)
Variable	declare (CharSequence category, CharSequence name, char delim, CharSequence comments)
Variable	declare (Variable variable)
Variable	declare (VariableDecl declaration, Object... replacements)
boolean	getAttribute (String attrName, Substring result)
double	getDouble ()
double	getFloat (int idx)
long	getInteger ()
long	getInteger (int idx)
AString	getString ()
AString	getString (int idx)
boolean	isTrue ()
boolean	isTrue (int idx)
void	ReplaceValue (int idx, Variable replVariable)
int	size ()

Protected Fields
int	qtyValues = 0
ArrayList< AString >	values = new ArrayList<AString>()

Protected Methods
void	clear ()

Package Access Methods
boolean	getAttribute (String attrName, Substring result, char attrDelim)

Constructor & Destructor Documentation

Variable() [1/6]

Variable

(

)

---

Constructs an undefined Variable. Prior to using this, declare has to be invoked.

Variable() [2/6]

Variable	(	VariableDecl	declaration,
		Object...	replacements
	)

---

Constructs a variable from a declaration. Strings named "%1", "%2" ... "%N" found in the fields category, name, comments and defaultValue are replaced with given replacement strings found in array replacements.

Parameters

declaration	The declaration data of the variable.
replacements	List of objects that will be converted to strings using AString.__(Object).

Variable() [3/6]

Variable

(

Variable

variable

)

---

Constructs a variable using the declaration of another variable. The values are not copied.

Parameters

variable

A variable to copy the declaration (which is comprised with fields category, name, fullname, delim, comments and defaultValue) from.

Variable() [4/6]

Variable	(	CharSequence	category,
		CharSequence	name,
		char	delim,
		CharSequence	comments
	)

---

Constructs a variable from the given values

Parameters

category	The category of the variable.
name	The name of the variable
comments	Comment lines that might be added in the configuration storage (plug-in implementation dependent).
delim	A proposal for a delimiter that might be used by some plug-ins to delimit different values from each other (e.g. INI files).

Variable() [5/6]

Variable	(	CharSequence	category,
		CharSequence	name,
		char	delim
	)

---

Overloaded constructor providing default parameters.

Parameters

category	The category of the variable.
name	The name of the variable
delim	A proposal for a delimiter that might be used by some plug-ins to delimit different values from each other (e.g. INI files).

Variable() [6/6]

Variable	(	CharSequence	category,
		CharSequence	name
	)

---

Overloaded constructor providing default parameters.

Parameters

category	The category of the variable.
name	The name of the variable

Member Function Documentation

add() [1/3]

AString add

(

)

---

Adds an empty value to the end of the list of values.

Returns

A reference to the string which can be manipulated to set the value.

add() [2/3]

AString add

(

boolean

value

)

---

Adds the given boolean value to the end of the list of values. For true values string "true" is set, otherwise "false".

Note

Other, depending on the variable semantics, more user friendly values may be set using the string interface add. String values recognized for boolean variables are defined in Configuration.trueValues.

Parameters

value

The value to set.

Returns

A reference to the string representing the boolean value.

add() [3/3]

AString add

(

Object

value

)

---

Adds the given string value to the end of the list of values.

Parameters

value

The value to set.

Returns

A reference to the string which can be further manipulated to set the value.

clear()

void clear ( )

protected

---

Clears all values.

clearValues() [1/2]

Variable clearValues

(

)

---

Clears the value, respectively the list of values set. After invoking this method, size will return 0 and getString will return null for any index.

Returns

this to allow concatenated operations.

clearValues() [2/2]

Variable clearValues

(

int

startIdx

)

---

Clears the value, respectively the list of values set. After invoking this method, size will return startIdx and getString will return null for any index greater or equal to startIdx.

Parameters

startIdx

The index of the first value to be cleared. Defaults to 0.

Returns

this to allow concatenated operations.

declare() [1/5]

Variable declare	(	CharSequence	category,
		CharSequence	name
	)

---

Overloaded version providing default parameters.

Parameters

category	The category of the variable.
name	The name of the variable

Returns

this to allow concatenated operations.

declare() [2/5]

Variable declare	(	CharSequence	category,
		CharSequence	name,
		char	delim
	)

---

Overloaded version providing default parameters.

Parameters

category	The category of the variable.
name	The name of the variable
delim	A proposal for a delimiter that might be used by some plug-ins to delimit different values from each other (e.g. INI files). Defaults to '\0'.

Returns

this to allow concatenated operations.

declare() [3/5]

Variable declare	(	CharSequence	category,
		CharSequence	name,
		char	delim,
		CharSequence	comments
	)

---

Clears the variable resets its declaration.

Parameters

category	The category of the variable.
name	The name of the variable
delim	A proposal for a delimiter that might be used by some plug-ins to delimit different values from each other (e.g. INI files). Defaults to '\0'.
comments	Comment lines that might be added in the configuration storage (plug-in implementation dependent). Defaults to null.

Returns

this to allow concatenated operations.

declare() [4/5]

Variable declare

(

Variable

variable

)

---

Constructs a variable using the declaration of another variable. The values are not copied.

Parameters

variable

A variable to copy the declaration (which is comprised with fields category, name, fullname, delim, comments and defaultValue) from.

Returns

this to allow concatenated operations.

declare() [5/5]

Variable declare	(	VariableDecl	declaration,
		Object...	replacements
	)

---

Clears the variable resets its declaration. Strings named "%1", "%2" ... "%N" found in the fields category, name, comments and defaultValue are replaced with given replacement string arguments in array replacements.

Parameters

declaration	The declaration data of the variable.
replacements	List of objects that will be converted to strings using AString.__(Object).

Returns

this to allow concatenated operations.

getAttribute() [1/2]

boolean getAttribute	(	String	attrName,
		Substring	result
	)

---

Overloaded version providing default value '=' for parameter attrDelim.

Parameters

	attrName	The name of the attribute searched.
[out]	result	A substring with the result.

Returns

true if the attribute was found, false otherwise.

getAttribute() [2/2]

boolean getAttribute ( String  attrName, Substring  result, char  attrDelim  )

package

---

Searches in the values of this variable for the pattern attrName = result and sets parameter result to the string following this pattern.

Parameters

	attrName	The name of the attribute searched.
[out]	result	A substring with the result.
	attrDelim	The delimiter to search for. Defaults to '='.

Returns

true if the attribute was found, false otherwise.

getDouble()

double getDouble

(

)

---

Returns the value at index 0 interpreted as a double value. If no value is defined, 0.0 is returned. Parsing is done using field numberFormat of field config, respectively, if this is not set, the static singleton NumberFormat.global.

Returns

The value at idx interpreted as a double value.

getFloat()

double getFloat

(

int

idx

)

---

Returns the value at idx interpreted as a double value. If the index is invalid, 0.0 is returned. Parsing is done using field numberFormat of field config, respectively, if this is not set, the static singleton NumberFormat.global.

Parameters

idx	The index of the value to be retrieved. Defaults to 0.

Returns

The value at idx interpreted as a double value.

getInteger() [1/2]

long getInteger

(

)

---

Returns the first (in most cases the only) value interpreted as an integer. If no value is set 0 is returned.

Returns

The value at idx interpreted as an integer value.

getInteger() [2/2]

long getInteger

(

int

idx

)

---

Returns the value at idx interpreted as an integer. If the index is invalid, 0 is returned.

Parameters

idx	The index of the value to be retrieved. Defaults to 0.

Returns

The value at idx interpreted as an integer value.

getString() [1/2]

AString getString

(

)

---

Returns the first (in most cases the only) value. If no value is set null is returned.

Note

It is explicitly allowed to change the contents of the AString object returned, e.g. for a subsequent store operation.

Returns

The value at idx.

getString() [2/2]

AString getString

(

int

idx

)

---

Returns the value with the given index. Valid values for parameter idx are between 0 and size - 1. If no value is set for the given index, null is returned.

Note

It is explicitly allowed to change the contents of the AString object returned, e.g. for a subsequent store operation.

Parameters

idx	The index of the value to be retrieved. Defaults to 0.

Returns

The value at idx.

isTrue() [1/2]

boolean isTrue

(

)

---

Returns true if the first value represents a boolean 'true'. Evaluation is done using field config, respectively if this is not set, the static singleton ALIB.config.

If no value is set false is returned.

Returns

The value at idx interpreted as a boolean value.

isTrue() [2/2]

boolean isTrue

(

int

idx

)

---

Returns true if the value at the given idx represents a boolean 'true'. Evaluation is done using field config, respectively if this is not set, the static singleton ALIB.config.

If the index is invalid, false is returned.

Parameters

idx	The index of the value to be retrieved. Defaults to 0.

Returns

The value at idx interpreted as a boolean value.

ReplaceValue()

void ReplaceValue	(	int	idx,
		Variable	replVariable
	)

---

Replaces the value at idx with the values of the given other variable.

Parameters

idx	The index of the value to replace.
replVariable	The variable providing the replacement values.

size()

int size

(

)

---

Returns the number of values set in this object.

Returns

The number of values set.

Member Data Documentation

category

AString category = new AString()

The configuration variable category.

comments

AString comments = new AString()

The configuration variable comments with placeholders replaced

config

Configuration config = null

The Configuration that was recently used to request or store the value.

defaultValue

AString defaultValue = new AString()

The default value provided as an externalized string.

The only occasion that this value is used is with method Configuration.load. If no plug-in has this variable defined and this field is not nulled, then the value is written into plug-in of priority Configuration.PRIO_DEFAULT_VALUES, respectively - if this default plug-in was replaced by the user - into a plug-in found at or below this priority.

In this case, the value is parsed using method XTernalizer.loadFromString of field ConfigurationPlugin.stringConverter of the plug-in writing the value.

Note

The field is ignored when using the plug-in interface ConfigurationPlugin.load directly. To store this value 'manually' directly to a plug-in, invoke ConfigurationPlugin.store with providing value explicitly.

delim

char delim = '\0'

The delimiter used for parsing and storing values by simple textual plug-ins which use the default version of XTernalizer for in- and externalizing variables.

FORMAT_HINT_CUSTOM

final int FORMAT_HINT_CUSTOM = 1 << 16

static

This and upward bits are reserved for custom plug-ins

FORMAT_HINT_MULTILINE

final int FORMAT_HINT_MULTILINE = 1 << 0

static

Write each argument in a new line

FORMAT_HINT_NO_DELIM_SPACES

final int FORMAT_HINT_NO_DELIM_SPACES = 1 << 1

static

Suppress spaces around the delimiter (only used in single line mode)

FORMAT_HINT_NONE

final int FORMAT_HINT_NONE = 0

static

No hints

formatAttrAlignment

String formatAttrAlignment

If set, attributes written in multi-lines are vertically aligned by this character or string. Use cases are "=", ":" or "->".
Used by IniFile and potentially by custom plug-ins.

formatHints

int formatHints

Hints for formatting textual configuration files. (Used by class IniFile and potentially by custom plug-ins.

fullname

AString fullname = new AString()

The configuration variable category and name concatenated with an underscore character '_'. This is useful e.g. for naming variables in log messages.

name

AString name = new AString()

The configuration variable name.

priority

int priority = 0

A value related to the priority of a configuration plug-in. The following values apply:

• 0 after creation or declaration (reuse).
• The priority of the plug-in that loaded the value (after calling Configuration.load).
• The priority of the plug-in that stored the value (after calling Configuration.store).
• 0, if the last load or store operation failed. In addition prior to storing a variable, the value might be manually set. See documentation of Configuration.store) for details.

qtyValues

int qtyValues = 0

protected

The number of values currently stored. This may be less than items found in values as those are reused objects.

values

ArrayList<AString> values = new ArrayList<AString>()

protected

The values

---

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

• Variable.java