com.isti.util

Class CfgProperties

java.lang.Object

com.isti.util.BaseProperties

com.isti.util.CfgProperties

All Implemented Interfaces:

java.util.Map

public class CfgProperties
extends BaseProperties

Class CfgProperties manages a table of configuration property items. Each item has a name, a value, a default value, a loaded-flag (set true if the item has been "loaded" from an input stream), a required-flag (set true if the item must be loaded from an input stream), and additional fields to support the item's use as a command-line parameter specification. A vector or array of 'CfgPropItem' objects may be used to define a set of property names and default-value objects; or they can be added individually. The default-value objects determine the data types for the items. The table of items may be loaded from and saved to an I/O stream, as a configuration file in which: Each item has the format name = value. String values should be enclosed in quotes (""). "Special" characters are "quoted" using a backslash (\), including \n \r \t \" \#. Comments may begin with # or //, or 'C'-style comments may be used.

Nested Class Summary

Nested classes/interfaces inherited from class com.isti.util.BaseProperties

BaseProperties.LoadSettingsType

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Field Summary

Fields inherited from class com.isti.util.BaseProperties

errMsgSetFlag, errorMessage, loadedCfgFname, SEPARATOR_STRING, SPECIAL_CHARS_STR

Constructor Summary

Constructors

Constructor and Description
CfgProperties() Creates an empty table of items.
CfgProperties(BaseProperties basePropObj) Creates a properties object that uses the same table of items as the given properties object.
CfgProperties(CfgPropItem[] itemsArr) Creates a table of items using the given array of 'CfgPropItem' objects.
CfgProperties(java.util.Vector vec) Creates a table of items using the given Vector of 'CfgPropItem' objects.

Method Summary

Modifier and Type	Method and Description
CfgPropItem	add(java.lang.String nameStr, java.lang.Object valueObj, boolean requiredFlag, java.lang.String cmdLnParamName, java.lang.String descriptionStr) Creates a new property item and adds it to the table.
CfgPropItem	add(java.lang.String nameStr, java.lang.Object valueObj, boolean requiredFlag, java.lang.String cmdLnParamName, java.lang.String descriptionStr, boolean cmdLnEnbFlag, boolean helpScreenFlag, boolean cmdLnOnlyFlag) Creates a new property item and adds it to the table.
CfgPropItem	add(java.lang.String nameStr, java.lang.Object valueObj, java.lang.String cmdLnParamName) Creates a new property item and adds it to the table.
CfgPropItem	add(java.lang.String nameStr, java.lang.Object valueObj, java.lang.String cmdLnParamName, java.lang.String descriptionStr) Creates a new property item and adds it to the table.
CfgPropItem	add(java.lang.String nameStr, java.lang.Object valueObj, java.lang.String cmdLnParamName, java.lang.String descriptionStr, boolean cmdLnEnbFlag, boolean helpScreenFlag) Creates a new property item and adds it to the table.
CfgPropItem	add(java.lang.String nameStr, java.lang.Object valueObj, java.lang.String cmdLnParamName, java.lang.String descriptionStr, boolean cmdLnEnbFlag, boolean helpScreenFlag, boolean cmdLnOnlyFlag) Creates a new property item and adds it to the table.
void	addGroupDataChangedListener(java.lang.Object groupSelObj, DataChangedListener listenerObj) Registers the given 'DataChangedListener' object with all items that have the specified group selection object.
boolean	areCompressedFlagsEnabled() Determines if compressed flags are enabled.
protected CfgPropItem	getCfgPropItem(java.lang.String nameStr, boolean cmdLnParamFlag) Get the configuration property item.
java.util.Vector	getExtraCmdLnParamsVec() Returns Vector of "extra" command-line parameters Strings filled in by the 'processCmdLnParams()' method; or null if no "extra" command-line parameters were found.
java.lang.String	getHelpScreenData() Returns a String of data for use on a command-line parameters "help" screen.
java.lang.String	getHelpScreenData(boolean displayPropertyName) Returns a String of data for use on a command-line parameters "help" screen.
java.lang.String	getHelpScreenData(boolean displayPropertyName, java.lang.String preText) Returns a String of data for use on a command-line parameters "help" screen.
java.lang.String	getHelpScreenData(boolean displayPropertyName, java.lang.String preText, java.lang.String postText) Returns a String of data for use on a command-line parameters "help" screen.
java.lang.String	getHelpScreenData(boolean displayPropertyName, java.lang.String preText, java.lang.String postText, java.lang.String preDescText) Returns a String of data for use on a command-line parameters "help" screen.
static boolean	isSwitchChar(char c) Determines if the specified character is a switch character ('-' or '/').
boolean	processCmdLnParams(java.lang.String[] args, boolean allowExtrasFlag) Processes the given command-line parameter strings using the table of configuration property items.
boolean	processCmdLnParams(java.lang.String[] args, boolean allowExtrasFlag, java.lang.String vInfoParam1, java.lang.String vInfoParam2) Processes the given command-line parameter strings using the table of configuration property items.
boolean	processCmdLnParams(java.lang.String[] args, boolean allowExtrasFlag, java.lang.String cfgFnParam1, java.lang.String cfgFnParam2, java.lang.String defCfgFnStr) Processes the given command-line parameter strings using the table of configuration property items.
boolean	processCmdLnParams(java.lang.String[] args, boolean allowExtrasFlag, java.lang.String cfgFnParam1, java.lang.String cfgFnParam2, java.lang.String defCfgFnStr, java.lang.String vInfoParam1, java.lang.String vInfoParam2) Processes the given command-line parameter strings using the table of configuration property items.
protected boolean	processExtraCmdLnParam(boolean allowExtrasFlag, java.lang.String paramStr) Process the extra command line parameter.
void	removeGroupDataChangedListener(java.lang.Object groupSelObj, DataChangedListener listenerObj) Unregisters the given 'DataChangedListener' object with all items that have the specified group selection object.
static java.lang.String	removeSwitchChars(java.lang.String str) Returns a copy of the given String with 1 to 2 leading switch characters ('-' or '/') removed; or the original String if no leading switch characters are found.
CfgProperties	setCompressedFlagsEnabled(boolean b) Determines if compressed flags should be enabled.
CfgProperties	setDescriptionSeparatorString(java.lang.String s) Set the description separator text.
CfgProperties	setEmptyStringDefaultFlag(boolean flg) Sets the default empty-string-default flag for the property items.
CfgProperties	setStoreEmptyStringsFlag(boolean flg) Set the store empty strings flag.

Methods inherited from class com.isti.util.BaseProperties

add, add, add, clear, containsKey, containsKey, containsValue, elements, entrySet, equals, get, get, getDisplayString, getDisplayString, getEmptyStringDefaultFlag, getErrorMessage, getLoadedCfgFname, hashCode, insertQuoteChars, isEmpty, isErrorAddAlreadyExist, isIgnoreUnknownPropertyNames, isStoreEmptyStringsFlag, keys, keySet, load, load, load, load, load, put, putAll, remove, remove, remove, setAllToDefaults, setErrorAddAlreadyExist, setErrorMessage, setIgnoreUnknownPropertyNames, setIllegalCharMsg, setLoadedFlags, setUnexpectedEOFMsg, size, store, store, store, store, values

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll

Constructor Detail

CfgProperties

public CfgProperties()

Creates an empty table of items.

CfgProperties

public CfgProperties(java.util.Vector vec)

Creates a table of items using the given Vector of 'CfgPropItem' objects. Any object in the vector that is not a 'CfgPropItem' object is ignored.

Parameters:

vec - vector

CfgProperties

public CfgProperties(CfgPropItem[] itemsArr)

Creates a table of items using the given array of 'CfgPropItem' objects.

Parameters:

itemsArr - items array

CfgProperties

public CfgProperties(BaseProperties basePropObj)

Creates a properties object that uses the same table of items as the given properties object.

Parameters:

basePropObj - base property object

Method Detail

add

public CfgPropItem add(java.lang.String nameStr,
                       java.lang.Object valueObj,
                       boolean requiredFlag,
                       java.lang.String cmdLnParamName,
                       java.lang.String descriptionStr,
                       boolean cmdLnEnbFlag,
                       boolean helpScreenFlag,
                       boolean cmdLnOnlyFlag)

Creates a new property item and adds it to the table. If an item with the same name already exists in the table, it is replaced.

Parameters:

nameStr - the name for the property item.

valueObj - the default value object for the property item.

requiredFlag - the value for the item's required-flag (see 'CfgPropItem.setRequiredFlag()').

cmdLnParamName - command-line parameter name for item.

descriptionStr - description text for item.

cmdLnEnbFlag - true to enable use of item as command-line parameter.

helpScreenFlag - true to include item in help screen data.

cmdLnOnlyFlag - true for item via command line only.

Returns:

The newly created property item.

add

public CfgPropItem add(java.lang.String nameStr,
                       java.lang.Object valueObj,
                       boolean requiredFlag,
                       java.lang.String cmdLnParamName,
                       java.lang.String descriptionStr)

Creates a new property item and adds it to the table. If an item with the same name already exists in the table, it is replaced.

Parameters:

nameStr - the name for the property item.

valueObj - the default value object for the property item.

requiredFlag - the value for the item's required-flag (see 'CfgPropItem.setRequiredFlag()').

cmdLnParamName - command-line parameter name for item.

descriptionStr - description text for item.

Returns:

The newly created property item.

add

public CfgPropItem add(java.lang.String nameStr,
                       java.lang.Object valueObj,
                       java.lang.String cmdLnParamName,
                       java.lang.String descriptionStr,
                       boolean cmdLnEnbFlag,
                       boolean helpScreenFlag)

Creates a new property item and adds it to the table. If an item with the same name already exists in the table, it is replaced.

Parameters:

nameStr - the name for the property item.

valueObj - the default value object for the property item.

cmdLnParamName - command-line parameter name for item.

descriptionStr - description text for item.

cmdLnEnbFlag - true to enable use of item as command-line parameter.

helpScreenFlag - true to include item in help screen data.

Returns:

The newly created property item.

add

public CfgPropItem add(java.lang.String nameStr,
                       java.lang.Object valueObj,
                       java.lang.String cmdLnParamName,
                       java.lang.String descriptionStr,
                       boolean cmdLnEnbFlag,
                       boolean helpScreenFlag,
                       boolean cmdLnOnlyFlag)

Creates a new property item and adds it to the table. If an item with the same name already exists in the table, it is replaced.

Parameters:

nameStr - the name for the property item.

valueObj - the default value object for the property item.

cmdLnParamName - command-line parameter name for item.

descriptionStr - description text for item.

cmdLnEnbFlag - true to enable use of item as command-line parameter.

helpScreenFlag - true to include item in help screen data.

cmdLnOnlyFlag - true for item via command line only.

Returns:

The newly created property item.

add

public CfgPropItem add(java.lang.String nameStr,
                       java.lang.Object valueObj,
                       java.lang.String cmdLnParamName,
                       java.lang.String descriptionStr)

Creates a new property item and adds it to the table. If an item with the same name already exists in the table, it is replaced.

Parameters:

nameStr - the name for the property item.

valueObj - the default value object for the property item.

cmdLnParamName - command-line parameter name for item.

descriptionStr - description text for item.

Returns:

The newly created property item.

add

public CfgPropItem add(java.lang.String nameStr,
                       java.lang.Object valueObj,
                       java.lang.String cmdLnParamName)

Creates a new property item and adds it to the table. If an item with the same name already exists in the table, it is replaced.

Parameters:

nameStr - the name for the property item.

valueObj - the default value object for the property item.

cmdLnParamName - command-line parameter name for item.

Returns:

The newly created property item.

processCmdLnParams

public boolean processCmdLnParams(java.lang.String[] args,
                                  boolean allowExtrasFlag,
                                  java.lang.String cfgFnParam1,
                                  java.lang.String cfgFnParam2,
                                  java.lang.String defCfgFnStr,
                                  java.lang.String vInfoParam1,
                                  java.lang.String vInfoParam2)

Processes the given command-line parameter strings using the table of configuration property items. All parameter names must be preceded by 1 to 2 switch characters ('-' or '/'). Non-boolean parameters must take one of the following forms: 'name value', 'name=value' or 'name:value'. Boolean parameters must take one of the following forms: 'name', 'name-', 'name0', 'name1', 'name=0', 'name=1', 'name=true', 'name=false', 'name:0', 'name:1', 'name:true', 'name:false'; where no parameter or '1' translates to 'true', and a trailing '-' or '0' translates to 'false'. A configuration file of property items may also be loaded (if given).

Parameters:

args - the array of command-line parameter strings to process.

allowExtrasFlag - if false then all unmatched parameter names are flagged as errors; if true then all unmatched parameter names are stored in a Vector that can be retrieved via the 'getExtraCmdLnParamsVec()' method.

cfgFnParam1 - a parameter name that may be used to specify a configuration file name on the command line (or null for none).

cfgFnParam2 - a second parameter name that may be used to specify a configuration file name on the command line (or null for none).

defCfgFnStr - a default configuration file name, used if no other configuration file name is specified on the command line (or null for none). This configuration file is loaded before any other command line parameters are processed. If the file cannot be found, no error is flagged.

vInfoParam1 - a parameter name that may be used to display program version information (or null for none).

vInfoParam2 - a second parameter name that may be used to display program version information (or null for none).

Returns:

true if successful, false if any errors are detected, in which case a text error message is generated that may be fetched via the 'getErrorMessage()' method.

processCmdLnParams

public boolean processCmdLnParams(java.lang.String[] args,
                                  boolean allowExtrasFlag,
                                  java.lang.String cfgFnParam1,
                                  java.lang.String cfgFnParam2,
                                  java.lang.String defCfgFnStr)

Processes the given command-line parameter strings using the table of configuration property items. All parameter names must be preceded by 1 to 2 switch characters ('-' or '/'). Non-boolean parameters must take one of the following forms: 'name value', 'name=value' name:value'. Boolean parameters must take one of the following forms: 'name', 'name-', 'name0', 'name1', 'name=0', 'name=1', 'name=true', 'name=false', 'name:0', 'name:1', 'name:true', 'name:false'; where no parameter or '1' translates to 'true', and a trailing '-' or '0' translates to 'false'. A configuration file of property items may also be loaded (if given).

Parameters:

args - the array of command-line parameter strings to process.

allowExtrasFlag - if false then all unmatched parameter names are flagged as errors; if true then all unmatched parameter names are stored in a Vector that can be retrieved via the 'getExtraCmdLnParamsVec()' method.

cfgFnParam1 - a parameter name that may be used to specify a configuration file name on the command line (or null for none).

cfgFnParam2 - a second parameter name that may be used to specify a configuration file name on the command line (or null for none).

defCfgFnStr - a default configuration file name, used if no other configuration file name is specified on the command line (or null for none). This configuration file is loaded before any other command line parameters are processed. If the file cannot be found, no error is flagged.

Returns:

true if successful, false if any errors are detected, in which case a text error message is generated that may be fetched via the 'getErrorMessage()' method.

processCmdLnParams

public boolean processCmdLnParams(java.lang.String[] args,
                                  boolean allowExtrasFlag,
                                  java.lang.String vInfoParam1,
                                  java.lang.String vInfoParam2)

Processes the given command-line parameter strings using the table of configuration property items. All parameter names must be preceded by 1 to 2 switch characters ('-' or '/'). Non-boolean parameters must take one of the following forms: 'name value', 'name=value' name:value'. Boolean parameters must take one of the following forms: 'name', 'name-', 'name0', 'name1', 'name=0', 'name=1', 'name=true', 'name=false', 'name:0', 'name:1', 'name:true', 'name:false'; where no parameter or '1' translates to 'true', and a trailing '-' or '0' translates to 'false'. A configuration file of property items may also be loaded (if given).

Parameters:

args - the array of command-line parameter strings to process.

allowExtrasFlag - if false then all unmatched parameter names are flagged as errors; if true then all unmatched parameter names are stored in a Vector that can be retrieved via the 'getExtraCmdLnParamsVec()' method.

vInfoParam1 - a parameter name that may be used to display program version information (or null for none).

vInfoParam2 - a second parameter name that may be used to display program version information (or null for none).

Returns:

true if successful, false if any errors are detected, in which case a text error message is generated that may be fetched via the 'getErrorMessage()' method.

processCmdLnParams

public boolean processCmdLnParams(java.lang.String[] args,
                                  boolean allowExtrasFlag)

Processes the given command-line parameter strings using the table of configuration property items. All parameter names must be preceded by 1 to 2 switch characters ('-' or '/'). Non-boolean parameters must take one of the following forms: 'name value', 'name=value' name:value'. Boolean parameters must take one of the following forms: 'name', 'name-', 'name0', 'name1', 'name=0', 'name=1', 'name=true', 'name=false', 'name:0', 'name:1', 'name:true', 'name:false'; where no parameter or '1' translates to 'true', and a trailing '-' or '0' translates to 'false'. A configuration file of property items may also be loaded (if given).

Parameters:

args - the array of command-line parameter strings to process.

allowExtrasFlag - if false then all unmatched parameter names are flagged as errors; if true then all unmatched parameter names are stored in a Vector that can be retrieved via the 'getExtraCmdLnParamsVec()' method.

Returns:

true if successful, false if any errors are detected, in which case a text error message is generated that may be fetched via the 'getErrorMessage()' method.

removeSwitchChars

public static java.lang.String removeSwitchChars(java.lang.String str)

Returns a copy of the given String with 1 to 2 leading switch characters ('-' or '/') removed; or the original String if no leading switch characters are found.

Parameters:

str - string

Returns:

string copy

setCompressedFlagsEnabled

public CfgProperties setCompressedFlagsEnabled(boolean b)

Determines if compressed flags should be enabled. If enabled this allows specifying multiple single character command line switches with a single parameter, such as "-ab" rather than "-a -b").

Parameters:

b - true if compressed flags should be enabled, false otherwise.

Returns:

the table of configuration property items.

setDescriptionSeparatorString

public CfgProperties setDescriptionSeparatorString(java.lang.String s)

Set the description separator text.

Parameters:

s - the the description separator text or null if none.

Returns:

the table of configuration property items.

getExtraCmdLnParamsVec

public java.util.Vector getExtraCmdLnParamsVec()

Returns Vector of "extra" command-line parameters Strings filled in by the 'processCmdLnParams()' method; or null if no "extra" command-line parameters were found.

Returns:

vector of "extra" command-line parameters

getHelpScreenData

public java.lang.String getHelpScreenData()

Returns a String of data for use on a command-line parameters "help" screen. The configuration file parameter names given to the 'processCndLnParams()' method are also included.

Returns:

help screen text

getHelpScreenData

public java.lang.String getHelpScreenData(boolean displayPropertyName)

Returns a String of data for use on a command-line parameters "help" screen. The configuration file parameter names given to the 'processCndLnParams()' method are also included.

Parameters:

displayPropertyName - true to always display the property name (as well as the command-line parameter name), false to only display it when there is no command-line parameter name.

Returns:

help screen text

getHelpScreenData

public java.lang.String getHelpScreenData(boolean displayPropertyName,
                                          java.lang.String preText)

Returns a String of data for use on a command-line parameters "help" screen. The configuration file parameter names given to the 'processCndLnParams()' method are also included.

Parameters:

displayPropertyName - true to always display the property name (as well as the command-line parameter name), false to only display it when there is no command-line parameter name.

preText - text to be displayed before each command-line parameter line or null for none.

Returns:

help screen text

getHelpScreenData

public java.lang.String getHelpScreenData(boolean displayPropertyName,
                                          java.lang.String preText,
                                          java.lang.String postText)

Returns a String of data for use on a command-line parameters "help" screen. The configuration file parameter names given to the 'processCndLnParams()' method are also included.

Parameters:

displayPropertyName - true to always display the property name (as well as the command-line parameter name), false to only display it when there is no command-line parameter name.

preText - text to be displayed before each command-line parameter line or null for none.

postText - text to be displayed after each command-line parameter line or null for none.

Returns:

help screen text

getHelpScreenData

public java.lang.String getHelpScreenData(boolean displayPropertyName,
                                          java.lang.String preText,
                                          java.lang.String postText,
                                          java.lang.String preDescText)

Returns a String of data for use on a command-line parameters "help" screen. The configuration file parameter names given to the 'processCndLnParams()' method are also included.

Parameters:

displayPropertyName - true to always display the property name (as well as the command-line parameter name), false to only display it when there is no command-line parameter name.

preText - text to be displayed before each command-line parameter line or null for none.

postText - text to be displayed after each command-line parameter line or null for none.

preDescText - the text to be displayed before the description.

Returns:

help screen text

isSwitchChar

public static boolean isSwitchChar(char c)

Determines if the specified character is a switch character ('-' or '/').

Parameters:

str - string

Returns:

true if the specified character is a switch character, false otherwise.

addGroupDataChangedListener

public void addGroupDataChangedListener(java.lang.Object groupSelObj,
                                        DataChangedListener listenerObj)

Registers the given 'DataChangedListener' object with all items that have the specified group selection object.

Parameters:

groupSelObj - group selection object.

listenerObj - the 'DataChangedListener' object.

areCompressedFlagsEnabled

public boolean areCompressedFlagsEnabled()

Determines if compressed flags are enabled.

Returns:

true if compressed flags are enabled, false otherwise.

removeGroupDataChangedListener

public void removeGroupDataChangedListener(java.lang.Object groupSelObj,
                                           DataChangedListener listenerObj)

Unregisters the given 'DataChangedListener' object with all items that have the specified group selection object.

Parameters:

groupSelObj - group selection object.

listenerObj - the 'DataChangedListener' object.

getCfgPropItem

protected CfgPropItem getCfgPropItem(java.lang.String nameStr,
                                     boolean cmdLnParamFlag)

Get the configuration property item.

Parameters:

nameStr - the name for the property item.

cmdLnParamFlag - true to only return a command line property item.

Returns:

the configuration property item or null if none.

processExtraCmdLnParam

protected boolean processExtraCmdLnParam(boolean allowExtrasFlag,
                                         java.lang.String paramStr)

Process the extra command line parameter.

Parameters:

allowExtrasFlag - true if unmatched parameter names are allowed, false otherwise.

paramStr - the parameter string.

Returns:

true if successful, false otherwise.

setEmptyStringDefaultFlag

public CfgProperties setEmptyStringDefaultFlag(boolean flg)

Description copied from class: BaseProperties

Sets the default empty-string-default flag for the property items. A value of 'true' will make an empty string read from the configuration file be converted to the default value for the item, and it will make an item value equal to the default value be converted to the empty string when written to the configuration file.

Overrides:

setEmptyStringDefaultFlag in class BaseProperties

Parameters:

flg - the flag value to use.

Returns:

A handle to this object.

setStoreEmptyStringsFlag

public CfgProperties setStoreEmptyStringsFlag(boolean flg)

Description copied from class: BaseProperties

Set the store empty strings flag.

Overrides:

setStoreEmptyStringsFlag in class BaseProperties

Parameters:

flg - the flag value to use.

Returns:

A handle to this object.