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 inherited from class java.util.Map

java.util.Map.Entry

Field Summary

Fields inherited from class com.isti.util.BaseProperties

errMsgSetFlag, errorMessage, loadedCfgFname, SEPARATOR_STRING, SPECIAL_CHARS_STR

Constructor Summary

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

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.
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.
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.
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.

Methods inherited from class com.isti.util.BaseProperties

add, add, add, clear, containsKey, containsKey, containsValue, elements, entrySet, equals, get, get, getDisplayString, getDisplayString, getErrorMessage, getLoadedCfgFname, hashCode, insertQuoteChars, isEmpty, keys, keySet, load, load, load, load, put, putAll, remove, remove, remove, setAllToDefaults, setErrorMessage, 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

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

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

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.

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.