com.digi.config.util
Class ConfigSettings

java.lang.Object
  java.util.Observable
      com.digi.config.util.ConfigSettings

public class ConfigSettings

extends java.util.Observable

ConfigSettings reads and parses the content of a user defined configuration file and provides a set of query functions to retrieve these configuration information.

The default configuration file pathname is config.ini in the classpath.

Environment Configuration File Definitions

1. Comment

         Syntax :    //
    

   • Comment is prefixed by "//" and can be anywhere in a line.
   • All text after the "//" to the end of the line is treated as comment.
2. Section Name

         Syntax :    [section_name]
    

   • Section name associates a group of tags of similar functions.
3. Tag

         Syntax :    tag  = value
    

   • Tag is used to associate value to a name.
   • Value is a text string.
   • All leading and trailing white space characters for tags and replacement text are ignored.
   • Only the first '=' character is significant and is used for the tag value assignment.
4. Tag Substitution

         Syntax :    $([[section_name]:]tag)
    

   • Text enclosed by "$(" and ")" is used as tag to search for replacement text and substitutes in the input text.
   • Nested tag substitution is not supported but multiple tag substitutions is allowed. For example "Tag1 = $(Tag2) follows by $(Tag3)"
   • If no section_name is defined, an "unnamed" section is used.
   • If no substitition text is found, empty string is replaced.
   • If no matching ')' is found for the "$(", no action is taken and input text remains as is. For example "$(tag1 $(tag2)" - try to find a tag with name "tag1 $(tag2".

This is also an observable and sends notifications to the registered observers, passing a modified settings object.

Field Summary

static java.lang.String	CATEGORY_CFG Constant to use when dealing with general configuration settings
static java.lang.String	CATEGORY_SYSTEM Constant to use when dealing with configuration settings in the System category.

Method Summary

void	addDefaultValueFinderListener(DefaultValueFinder def) This method adds a defaultvalue finder listener.
static boolean	getBoolean(java.lang.String category, java.lang.String key) Gets boolean value of the specified key in the specified category.
static boolean	getBoolean(java.lang.String category, java.lang.String key, java.lang.String fallbackSection, java.lang.String fallbackTag) Gets boolean value of the specified key in the specified category.
boolean	getBooleanProfileProperty(java.lang.String section, java.lang.String tag) Returns the Profile Property as a boolean.
boolean	getBooleanProfileProperty(java.lang.String section, java.lang.String tag, java.lang.String fallbackSection, java.lang.String fallbackTag) Returns the Profile Property as a boolean.
static java.awt.Color	getColor(java.lang.String category, java.lang.String key) Gets color value of the specified key in the specified category.
static java.awt.Color	getColor(java.lang.String category, java.lang.String key, java.lang.String fallbackSection, java.lang.String fallbackTag) Gets color value of the specified key in the specified category.
java.awt.Color	getColorProfileProperty(java.lang.String section, java.lang.String tag) Returns the Profile property as a color.
java.awt.Color	getColorProfileProperty(java.lang.String section, java.lang.String tag, java.lang.String fallbackSection, java.lang.String fallbackTag) Returns the Profile property as a color.
java.lang.String	getConfigFileName() Returns environment configuration file pathname.
static java.awt.Font	getFont(java.lang.String section, java.lang.String tag) Gets font value of the specified tag.
static java.awt.Font	getFont(java.lang.String section, java.lang.String tag, java.lang.String fallbackSection, java.lang.String fallbackTag) Gets font value of the specified tag.
java.awt.Font	getFontProfileProperty(java.lang.String section, java.lang.String tag) Returns the Profile property as a font.
java.awt.Font	getFontProfileProperty(java.lang.String section, java.lang.String tag, java.lang.String fallbackSection, java.lang.String fallbackTag) Returns the Profile property as a color.
static ConfigSettings	getInstance() This method returns the only instance of the configsettings object
static int	getInteger(java.lang.String category, java.lang.String key) Gets integer value of the specified key in the specified category.
static int	getInteger(java.lang.String category, java.lang.String key, java.lang.String fallbackSection, java.lang.String fallbackTag) Gets integer value of the specified key in the specified category.
int	getIntegerProfileProperty(java.lang.String section, java.lang.String tag) Returns the Profile property as integer.
int	getIntegerProfileProperty(java.lang.String section, java.lang.String tag, java.lang.String fallbackSection, java.lang.String fallbackTag) Returns the Profile property as integer.
java.lang.String	getProfileProperty(java.lang.String section, java.lang.String tag) Returns value of specified ProfileProperty as a string.
java.lang.String	getProfileProperty(java.lang.String section, java.lang.String tag, java.lang.String defRetVal) Returns the Profile Property as a String.
java.lang.String	getProfileProperty(java.lang.String section, java.lang.String tag, java.lang.String fallbackSection, java.lang.String fallbackTag) Returns value of specified ProfileProperty as a string.
static java.lang.String	getProperty(java.lang.String category, java.lang.String key) Gets value of the specified key within the specified category in the ConfigSettings.
static java.lang.String	getProperty(java.lang.String category, java.lang.String key, java.lang.String dftRetValue) Gets value of the specified key within the specified category in the ConfigSettings.
static java.lang.String	getProperty(java.lang.String category, java.lang.String key, java.lang.String fallbackSection, java.lang.String fallbackTag) Gets value of the specified key within the specified category in the ConfigSettings.
void	list(java.io.PrintWriter out) List properties, for debugging.
void	load_profile() Loads configuration file contents into the ConfigSettings object.
java.io.BufferedReader	openProfile() Locates the configuration profile and returns a BufferedReader to it.
void	save_profile() This method saves the config settings to the file
static void	save() This method saves the config settings to the ini file
static void	setBoolean(java.lang.String category, java.lang.String key, boolean value) Sets the boolean value of the specified key in the specified category.
void	setBooleanProfileProperty(java.lang.String section, java.lang.String tag, boolean value) Sets value of the specified tag.
static void	setColor(java.lang.String category, java.lang.String key, java.awt.Color value) Sets the color value of the specified key in the specified category.
void	setColorProfileProperty(java.lang.String section, java.lang.String tag, java.awt.Color c) Sets value of the specified tag.
static void	setInteger(java.lang.String category, java.lang.String key, int value) Sets the integer value of the specified key in the specified category.
void	setIntegerProfileProperty(java.lang.String section, java.lang.String tag, int value) Sets value of the specified tag.
void	setProfileProperty(java.lang.String section, java.lang.String tag, java.lang.String value) Sets value of the specified tag.
static void	setProperty(java.lang.String category, java.lang.String key, java.lang.String value) Sets the provided value under the specified key within the specified category in the ConfigSettings.

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

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

Field Detail

CATEGORY_SYSTEM

public static final java.lang.String CATEGORY_SYSTEM

Constant to use when dealing with configuration settings in the System category. NOTE: this actually points to the System Properties.

See Also:

Constant Field Values

CATEGORY_CFG

public static final java.lang.String CATEGORY_CFG

Constant to use when dealing with general configuration settings

See Also:

Constant Field Values

Method Detail

getInstance

public static ConfigSettings getInstance()

This method returns the only instance of the configsettings object

Returns:

ConfigSettings

addDefaultValueFinderListener

public void addDefaultValueFinderListener(DefaultValueFinder def)

This method adds a defaultvalue finder listener.

Parameters:

def - the default value finder class

getConfigFileName

public java.lang.String getConfigFileName()

Returns environment configuration file pathname.

Returns:

the configuration file name

getProfileProperty

public java.lang.String getProfileProperty(java.lang.String section,
                                           java.lang.String tag)

Returns value of specified ProfileProperty as a string. Returns null if section/tag is not found.

Parameters:

section - Section name in the profile

tag - Tag name

Returns:

Replacement text of the input tag

getProfileProperty

public java.lang.String getProfileProperty(java.lang.String section,
                                           java.lang.String tag,
                                           java.lang.String fallbackSection,
                                           java.lang.String fallbackTag)

Returns value of specified ProfileProperty as a string. Returns null if section/tag is not found. Caller specifies both a primary and fallback set of section/tag pairs. The search order is:

1. primary section/tag ini entry
2. fallback section/tag ini entry
3. primary section/tag defaultValueFinder
4. fallback section/tag defaultValueFinder

Parameters:

section - First section name in the profile to look for

tag - First tag name to look for

fallbackSection - Second section name in the profile to look for

fallbackTag - Second tag name to look for

Returns:

Replacement text of the input tag

getProfileProperty

public java.lang.String getProfileProperty(java.lang.String section,
                                           java.lang.String tag,
                                           java.lang.String defRetVal)

Returns the Profile Property as a String. Returns value of defRetVal if section/tag not found.

Parameters:

section - Section name in the profile

tag - Tag name

defRetVal - Default return String if none is found.

Returns:

Replacement text of the input tag

getBooleanProfileProperty

public boolean getBooleanProfileProperty(java.lang.String section,
                                         java.lang.String tag)

Returns the Profile Property as a boolean. Returns value of false if section/tag not found.

Parameters:

section - Section name in the profile

tag - Tag name

Returns:

boolean value of property

getBooleanProfileProperty

public boolean getBooleanProfileProperty(java.lang.String section,
                                         java.lang.String tag,
                                         java.lang.String fallbackSection,
                                         java.lang.String fallbackTag)

Returns the Profile Property as a boolean. Returns value of false if section/tag not found. Caller specifies both a primary and fallback set of section/tag pairs. The search order is:

1. primary section/tag ini entry
2. fallback section/tag ini entry
3. primary section/tag defaultValueFinder
4. fallback section/tag defaultValueFinder

Parameters:

section - First section name in the profile to look for

tag - First tag name to look for

fallbackSection - Second section name in the profile to look for

fallbackTag - Second tag name to look for

Returns:

boolean value of property

getIntegerProfileProperty

public int getIntegerProfileProperty(java.lang.String section,
                                     java.lang.String tag)

Returns the Profile property as integer. Returns value of -1 if section/tag not found.

Parameters:

section - Section of the property

tag - Key of the property

Returns:

integer value

getIntegerProfileProperty

public int getIntegerProfileProperty(java.lang.String section,
                                     java.lang.String tag,
                                     java.lang.String fallbackSection,
                                     java.lang.String fallbackTag)

Returns the Profile property as integer. Returns value of -1 if section/tag not found. Caller specifies both a primary and fallback set of section/tag pairs. The search order is:

1. primary section/tag ini entry
2. fallback section/tag ini entry
3. primary section/tag defaultValueFinder
4. fallback section/tag defaultValueFinder

Parameters:

section - First section name in the profile to look for

tag - First tag name to look for

fallbackSection - Second section name in the profile to look for

fallbackTag - Second tag name to look for

Returns:

integer value

getColorProfileProperty

public java.awt.Color getColorProfileProperty(java.lang.String section,
                                              java.lang.String tag)

Returns the Profile property as a color. Returns null if the section/tag is not found.

Parameters:

section - First section name in the profile to look for

tag - First tag name to look for

Returns:

Color Color

getColorProfileProperty

public java.awt.Color getColorProfileProperty(java.lang.String section,
                                              java.lang.String tag,
                                              java.lang.String fallbackSection,
                                              java.lang.String fallbackTag)

Returns the Profile property as a color. Returns null if the section/tag is not found. Caller specifies both a primary and fallback set of section/tag pairs. The search order is:

1. primary section/tag ini entry
2. fallback section/tag ini entry
3. primary section/tag defaultValueFinder
4. fallback section/tag defaultValueFinder

Parameters:

section - First section name in the profile to look for

tag - First tag name to look for

fallbackSection - Second section name in the profile to look for

fallbackTag - Second tag name to look for

Returns:

Color Color

getFontProfileProperty

public java.awt.Font getFontProfileProperty(java.lang.String section,
                                            java.lang.String tag)

Returns the Profile property as a font. Returns null if the section/tag is not found.

Parameters:

section - Section name in the profile

tag - Tag name

Returns:

font

getFontProfileProperty

public java.awt.Font getFontProfileProperty(java.lang.String section,
                                            java.lang.String tag,
                                            java.lang.String fallbackSection,
                                            java.lang.String fallbackTag)

Returns the Profile property as a color. Returns null if the section/tag is not found. Caller specifies both a primary and fallback set of section/tag pairs. The search order is:

1. primary section/tag ini entry
2. fallback section/tag ini entry
3. primary section/tag defaultValueFinder
4. fallback section/tag defaultValueFinder

Parameters:

section - First section name in the profile to look for

tag - First tag name to look for

fallbackSection - Second section name in the profile to look for

fallbackTag - Second tag name to look for

Returns:

font

setProfileProperty

public void setProfileProperty(java.lang.String section,
                               java.lang.String tag,
                               java.lang.String value)

Sets value of the specified tag. This method returns null if the tag is not found.

Parameters:

section - Section name in the profile

tag - Tag name

value - Value to set

setBooleanProfileProperty

public void setBooleanProfileProperty(java.lang.String section,
                                      java.lang.String tag,
                                      boolean value)

Sets value of the specified tag. This method returns null if the tag is not found.

Parameters:

section - Section name in the profile

tag - Tag name

value - Value to set

setColorProfileProperty

public void setColorProfileProperty(java.lang.String section,
                                    java.lang.String tag,
                                    java.awt.Color c)

Sets value of the specified tag. This method returns null if the tag is not found.

Parameters:

section - Section name in the profile

tag - Tag name

c - Color to set

setIntegerProfileProperty

public void setIntegerProfileProperty(java.lang.String section,
                                      java.lang.String tag,
                                      int value)

Sets value of the specified tag. This method returns null if the tag is not found.

Parameters:

section - Section name in the profile

tag - Tag name

value - Value to set

save_profile

public void save_profile()
                  throws java.io.IOException

This method saves the config settings to the file

Throws:

java.io.IOException

list

public void list(java.io.PrintWriter out)

List properties, for debugging.

Parameters:

out - Output Stream

openProfile

public java.io.BufferedReader openProfile()

Locates the configuration profile and returns a BufferedReader to it. If the profile file is not found, then null is returned.

load_profile

public void load_profile()
                  throws java.io.IOException

Loads configuration file contents into the ConfigSettings object.

Throws:

java.io.FileNotFoundException - File not found

java.io.IOException - File read or close error

getBoolean

public static boolean getBoolean(java.lang.String category,
                                 java.lang.String key)

Gets boolean value of the specified key in the specified category. This method returns false if the value associated with the category/key is not actually a boolean value.

The logic will first look for the value by searching the specified category in the ConfigSettings for the specified key. If either the category or the key cannot be found, the logic will perform the same search in the DefaultConfigSettings. If a value is still not found, a MissingResourceException is thrown.

Parameters:

category - is the name of the setting category to search

key - is the name of the key to the value within the category

Returns:

true if and only if the value associated with the category/key is true.

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

java.util.MissingResourceException - if a value for the specified category/key is not found.

getBoolean

public static boolean getBoolean(java.lang.String category,
                                 java.lang.String key,
                                 java.lang.String fallbackSection,
                                 java.lang.String fallbackTag)

Gets boolean value of the specified key in the specified category. This method returns false if the value associated with the category/key is not actually a boolean value.

The logic will first look for the value by searching the specified category in the ConfigSettings for the specified key. If either the category or the key cannot be found, the logic will perform the same search in the DefaultConfigSettings. If a value is still not found, a MissingResourceException is thrown.

Parameters:

category - is the name of the setting category to search

key - is the name of the key to the value within the category

Returns:

true if and only if the value associated with the category/key is true.

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

java.util.MissingResourceException - if a value for the specified category/key is not found.

setBoolean

public static void setBoolean(java.lang.String category,
                              java.lang.String key,
                              boolean value)

Sets the boolean value of the specified key in the specified category. If the key already exists in this category, the provided value will replace the existing value.

Parameters:

category - is the name of the setting category into which the key/value pair is inserted. If it does not exist, it will be created.

key - is the name of the key to the value within the category

value - is the boolean value to be inserted into the ConfigSettings

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

getInteger

public static int getInteger(java.lang.String category,
                             java.lang.String key)

Gets integer value of the specified key in the specified category.

The logic will first look for the value by searching the specified category in the ConfigSettings for the specified key. If either the category or the key cannot be found, the logic will perform the same search in the DefaultConfigSettings. If a value is still not found, false is returned.

Parameters:

category - is the name of the setting category to search

key - is the name of the key to the value within the category

Returns:

true if and only if the value associated with the category/key is true.

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

java.util.MissingResourceException - if a value for the specified category/key is not found.

java.lang.NumberFormatException - if the requested value is not actually an integer.

getInteger

public static int getInteger(java.lang.String category,
                             java.lang.String key,
                             java.lang.String fallbackSection,
                             java.lang.String fallbackTag)

Gets integer value of the specified key in the specified category.

The logic will first look for the value by searching the specified category in the ConfigSettings for the specified key. If either the category or the key cannot be found, the logic will perform the same search in the DefaultConfigSettings. If a value is still not found, false is returned.

Parameters:

category - is the name of the setting category to search

key - is the name of the key to the value within the category

Returns:

true if and only if the value associated with the category/key is true.

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

java.util.MissingResourceException - if a value for the specified category/key is not found.

java.lang.NumberFormatException - if the requested value is not actually an integer.

setInteger

public static void setInteger(java.lang.String category,
                              java.lang.String key,
                              int value)

Sets the integer value of the specified key in the specified category. If the key already exists in this category, the provided value will replace the existing value.

Parameters:

category - is the name of the setting category into which the key/value pair is inserted. If it does not exist, it will be created.

key - is the name of the key to the value within the category

value - is the integer value to be inserted into the ConfigSettings

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

getFont

public static java.awt.Font getFont(java.lang.String section,
                                    java.lang.String tag)

Gets font value of the specified tag. This method returns null if the tag is not found.

Parameters:

section - Section name in the profile

tag - Tag name

Returns:

font

getFont

public static java.awt.Font getFont(java.lang.String section,
                                    java.lang.String tag,
                                    java.lang.String fallbackSection,
                                    java.lang.String fallbackTag)

Gets font value of the specified tag. This method returns null if the tag is not found.

Parameters:

section - Section name in the profile

tag - Tag name

Returns:

font

getColor

public static java.awt.Color getColor(java.lang.String category,
                                      java.lang.String key)

Gets color value of the specified key in the specified category. This method returns false if the value associated with the category/key is not actually a color value.

The logic will first look for the value by searching the specified category in the ConfigSettings for the specified key. If either the category or the key cannot be found, the logic will perform the same search in the DefaultConfigSettings. If a value is still not found, a MissingResourceException is thrown.

Parameters:

category - is the name of the setting category to search

key - is the name of the key to the value within the category

Returns:

true if and only if the value associated with the category/key is true.

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

java.util.MissingResourceException - if a value for the specified category/key is not found.

getColor

public static java.awt.Color getColor(java.lang.String category,
                                      java.lang.String key,
                                      java.lang.String fallbackSection,
                                      java.lang.String fallbackTag)

Gets color value of the specified key in the specified category. This method returns false if the value associated with the category/key is not actually a color value.

The logic will first look for the value by searching the specified category in the ConfigSettings for the specified key. If either the category or the key cannot be found, the logic will perform the same search in the DefaultConfigSettings. If a value is still not found, a MissingResourceException is thrown.

Parameters:

category - is the name of the setting category to search

key - is the name of the key to the value within the category

Returns:

true if and only if the value associated with the category/key is true.

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

java.util.MissingResourceException - if a value for the specified category/key is not found.

setColor

public static void setColor(java.lang.String category,
                            java.lang.String key,
                            java.awt.Color value)

Sets the color value of the specified key in the specified category. If the key already exists in this category, the provided value will replace the existing value.

Parameters:

category - is the name of the setting category into which the key/value pair is inserted. If it does not exist, it will be created.

key - is the name of the key to the value within the category

value - is the color value to be inserted into the ConfigSettings

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

getProperty

public static java.lang.String getProperty(java.lang.String category,
                                           java.lang.String key)

Gets value of the specified key within the specified category in the ConfigSettings. If a value is not found, the same search will be repeated in the DefaultConfigSettings. If a value is still not found, a MissingResourceException will be thrown. An exception to this search order occurs when the category = 'System'. In that case, only the System properties are searched. NOTE: the category and key parameters are case sensitive.

Parameters:

category - is the name of the setting category to search

key - is the name of the key to the value within the category

Returns:

the String associated with the specified category/key.

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

java.util.MissingResourceException - if a value for the specified category/key is not found.

getProperty

public static java.lang.String getProperty(java.lang.String category,
                                           java.lang.String key,
                                           java.lang.String fallbackSection,
                                           java.lang.String fallbackTag)

Gets value of the specified key within the specified category in the ConfigSettings. If a value is not found, the same search will be repeated in the DefaultConfigSettings. If a value is still not found, a MissingResourceException will be thrown. An exception to this search order occurs when the category = 'System'. In that case, only the System properties are searched. NOTE: the category and key parameters are case sensitive.

Parameters:

category - is the name of the setting category to search

key - is the name of the key to the value within the category

Returns:

the String associated with the specified category/key.

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

java.util.MissingResourceException - if a value for the specified category/key is not found.

getProperty

public static java.lang.String getProperty(java.lang.String category,
                                           java.lang.String key,
                                           java.lang.String dftRetValue)

Gets value of the specified key within the specified category in the ConfigSettings. If a value is not found, the same search will be repeated in the DefaultConfigSettings. If a value is still not found, the provided dftRetValue will be returned. An exception to this search order occurs when the category = 'System'. In that case, only the System properties are searched (but the provided dftRetValue is still returned if a value is not found in the System Properties). NOTE: the category and key parameters are case sensitive. It is suggested that callers always use the constants provided by this class when specifying the category.

Parameters:

category - is the name of the setting category to search

key - is the name of the key to the value within the category

dftRetValue - is the default return String if a value for the specified category/key is not found in the configSettings.

Returns:

the String associated with the specified category/key. If one is not found in the configSettings, the provided default value will be returned.

Throws:

java.lang.IllegalArgumentException - if the category or key values are either not provided or are empty Strings.

java.util.MissingResourceException - if a value for the specified category/key is not found.

setProperty

public static void setProperty(java.lang.String category,
                               java.lang.String key,
                               java.lang.String value)

Sets the provided value under the specified key within the specified category in the ConfigSettings. If the key/value already exists in the specified category, the value will be replaced. If the specified category does not already exist, it will be created. NOTE: the category and key parameters are case sensitive. It is strongly suggested that the constants for the categories provided by this class are used when specifying the category parameter. NOTE: values placed in the System or CFG categories will NOT be persisted between restarts of this application.

Parameters:

category - is the name of the setting category to search

key - is the name of the key to the value within the category

value - is the String value to be placed in the ConfigSettings

Throws:

java.lang.IllegalArgumentException - if the category or key values are empty Strings.

java.lang.NullPointerException - if the category, key or value are null.

save

public static void save()
                 throws java.io.IOException

This method saves the config settings to the ini file

Throws:

java.io.IOException