ALox  V. 2402 R. 0
Home ALox for C++ ALox for C# ALox for Java Download
Inner Classes | Public Static Fields | Public Fields | Public Methods | Protected Fields | List of all members
Configuration Class Reference
Collaboration diagram for Configuration:
[legend]

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 cs.aworx.lib.config for more information on ALib external configuration variables.

Inner Classes

class  PluginAndPrio
 

Public Static Fields

const int PrioAutodetect = 500
 
const int PrioCLIArgs = 40000
 
const int PrioDefaultValues = 10000
 
const int PrioEnvironment = 30000
 
const int PrioProtectedValues = int.MaxValue
 
const int PrioStandard = 20000
 

Public Fields

NumberFormat NumberFormat = new NumberFormat()
 
char[] SubstitutionVariableDelimiters
 
AString SubstitutionVariableEnd = new AString()
 
AString SubstitutionVariableStart = new AString("$")
 
List< AStringTrueValues
 

Public Methods

 Configuration (bool addDefaultPlugins=true)
 
int FetchFromDefault (ConfigurationPlugin dest, String sectionName=null)
 
ConfigurationPlugin GetPlugin (int priority)
 
TPluginType GetPluginTypeSafe< TPluginType > ()
 
TPluginType GetPluginTypeSafe< TPluginType > (int priority)
 
bool HasPlugins ()
 
void InsertPlugin (ConfigurationPlugin plugin, int priority)
 
bool IsTrue (AString value)
 
int Load (Variable variable)
 
int LoadFromString (Variable variable, Object externalizedValue)
 
int loadImpl (Variable variable, bool substitute)
 
int Protect (Variable variable, Object externalizedValue=null)
 
bool RemovePlugin (ConfigurationPlugin plugin)
 
void SetCommandLineArgs (String[] args=null)
 
int Store (Variable variable, Object externalizedValue=null)
 
int StoreDefault (Variable variable, Object externalizedValue=null)
 

Protected Fields

List< PluginAndPrioplugins = new List<PluginAndPrio>()
 
AString tmpConversion = new AString()
 
Substring tmpReplVarAll = new Substring()
 
Substring tmpReplVarCategory = new Substring()
 
Substring tmpReplVarName = new Substring()
 

Constructor & Destructor Documentation

◆ Configuration()

Configuration ( bool  addDefaultPlugins = true)
inline

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

Priority Plug-in Type
Configuration.PrioDefaultValues InMemoryPlugin
Configuration.PrioEnvironment Environment
Configuration.PrioCLIArgs CLIArgs
Configuration.PrioProtectedValues InMemoryPlugin
Parameters
addDefaultPluginsIf true, the default plugins are added. Defaults to true.

Member Function Documentation

◆ FetchFromDefault()

int FetchFromDefault ( ConfigurationPlugin  dest,
String  sectionName = null 
)
inline

This method fetches all values from a plug-in of priority PrioDefaultValues, 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
destThe destination plug-in.
sectionNameOptional string denoting a section to fetch. Defaults to null.
Returns
The number of variables fetched.

◆ GetPlugin()

ConfigurationPlugin GetPlugin ( int  priority)
inline

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
priorityThe priority of the plug-in to return.
Returns
The plug-in requested or null if not available.

◆ GetPluginTypeSafe< TPluginType >() [1/2]

TPluginType GetPluginTypeSafe< TPluginType > ( )
inline

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

Template Parameters
TPluginTypeThe type of the plugin to search.
Returns
The plug-in of requested type. null if not available.
Type Constraints
TPluginType :ConfigurationPlugin 

◆ GetPluginTypeSafe< TPluginType >() [2/2]

TPluginType GetPluginTypeSafe< TPluginType > ( int  priority)
inline

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
priorityThe priority of the plug-in to return.
Template Parameters
TPluginTypeThe type of the plugin to search.
Returns
The plug-in of requested type and priority. null if not available.
Type Constraints
TPluginType :ConfigurationPlugin 

◆ HasPlugins()

bool HasPlugins ( )
inline

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

void InsertPlugin ( ConfigurationPlugin  plugin,
int  priority 
)
inline

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 PrioCLIArgs, PrioEnvironment and PrioStandard.

Parameters
pluginThe plug-in to insert.
priorityThe priority of the plug-in.

◆ IsTrue()

bool IsTrue ( AString  value)
inline

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

Parameters
valueThe value to check
Returns
Returns true, if the value represents 'true', false if not.

◆ Load()

int Load ( Variable  variable)
inline

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 PrioDefaultValues, (respectively to the plug-in found at or below PrioDefaultValues). For the conversion of the value, field ConfigurationPlugin.StringConverter of field a plug-in of priority PrioDefaultValues, is used. (Which has to be present.)

Parameters
variableThe 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 
)
inline

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 PrioDefaultValues, is used.

Parameters
variableThe variable object.
externalizedValueThe new value to write.
Returns
The size of the variable after parsing.

◆ loadImpl()

int loadImpl ( Variable  variable,
bool  substitute 
)
inline

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

Parameters
variableThe variable to get.
substituteIf 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()

int Protect ( Variable  variable,
Object  externalizedValue = null 
)
inline

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

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
variableThe variable object.
externalizedValueOptional externalized value string. If given, the variable is set prior to writing.
Returns
The result of Configuration.Default.Store(this).

◆ RemovePlugin()

bool RemovePlugin ( ConfigurationPlugin  plugin)
inline

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
pluginThe plug-in to be deleted.
Returns
true if the plug-in was removed, else false.

◆ SetCommandLineArgs()

void SetCommandLineArgs ( String[]  args = null)
inline

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 found in ALIB.Config.
Parameters
argsParameters taken from standard C# method main() (the list of command line arguments). Defaults to null.

◆ Store()

int Store ( Variable  variable,
Object  externalizedValue = null 
)
inline

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, PrioDefaultValues 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 PrioProtectedValues, 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 PrioDefaultValues, 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 PrioProtectedValues allows to protect the variable value in respect to external manipulation.
  • Setting the field to PrioProtectedValues - 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 PrioDefaultValues (but greater than 0),
  • the detected priority was PrioProtectedValues. (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
variableThe variable object.
externalizedValueOptional 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()

int StoreDefault ( Variable  variable,
Object  externalizedValue = null 
)
inline

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

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
variableThe variable object.
externalizedValueOptional externalized value string. If given, the variable is set prior to writing.
Returns
The result of Configuration.Default.Store(this).

Member Data Documentation

◆ NumberFormat

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

◆ plugins

List<PluginAndPrio> plugins = new List<PluginAndPrio>()
protected

The plug-ins we have in our portfolio

◆ PrioAutodetect

const int PrioAutodetect = 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 core 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.

◆ PrioCLIArgs

const int PrioCLIArgs = 40000
static

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

◆ PrioDefaultValues

const int PrioDefaultValues = 10000
static

Constant providing a low priority. This is used with PrioDefaultValues

◆ PrioEnvironment

const int PrioEnvironment = 30000
static

Constant providing default priority for environment variables plug-in.

◆ PrioProtectedValues

const int PrioProtectedValues = int.MaxValue
static

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

◆ PrioStandard

const int PrioStandard = 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 SubstitutionVariableDelimiters 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

List<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: