com.isti.util
Class BaseProperties

java.lang.Object
  com.isti.util.BaseProperties

All Implemented Interfaces:

java.util.Map

Direct Known Subclasses:

AppletProperties, CfgProperties

public class BaseProperties

extends java.lang.Object

implements java.util.Map

Class BaseProperties is the base class for classes that manage a table of configuration property items. The 'CfgProperties' class extends this class to add stream loading and saving. The 'AppletProperties' class adds loading of properties as parameters from a host HTML file. 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), and a required-flag (set true if the item must be loaded from an input stream). A vector or array of 'CfgPropItem' objects may be used to define a set of property names and default-value objects; or they be added individually. The default-value objects determine the data types for the items.

Nested Class Summary

Nested classes inherited from class java.util.Map

java.util.Map.Entry

Field Summary

protected boolean	errMsgSetFlag
protected java.lang.String	errorMessage
protected java.lang.String	loadedCfgFname
static java.lang.String	SEPARATOR_STRING The separator string to use to separate values.
static java.lang.String	SPECIAL_CHARS_STR String of special characters for 'insertQuoteChars()' method.

Constructor Summary

BaseProperties()
Creates an empty table of items.

BaseProperties(CfgPropItem[] itemsArr)
Creates a table of items using the given array of 'CfgPropItem' objects.

BaseProperties(java.util.Map itemsMap)
Creates a properties object that uses the specified map of items or creates a new one if no map was specified (null).

BaseProperties(java.util.Vector vec)
Creates a table of items using the given Vector of 'CfgPropItem' objects.

Method Summary

CfgPropItem	add(CfgPropItem item) Adds the given property item to the table.
CfgPropItem	add(java.lang.String nameStr, java.lang.Object valueObj) Creates a new property item and adds it to the table.
CfgPropItem	add(java.lang.String nameStr, java.lang.Object valueObj, boolean requiredFlag) Creates a new property item and adds it to the table.
void	clear() Removes all mappings from this map (optional operation).
boolean	containsKey(java.lang.Object key) Returns true if this map contains a mapping for the specified key.
boolean	containsKey(java.lang.String name) Returns true if the table contains an item whose name matches the given name.
boolean	containsValue(java.lang.Object value) Returns true if this map maps one or more keys to the specified value.
java.util.Enumeration	elements() Returns an enumeration of items in the table.
java.util.Set	entrySet() Returns a set view of the mappings contained in this map.
boolean	equals(java.lang.Object o) Compares the specified object with this map for equality.
java.lang.Object	get(java.lang.Object key) Returns the value to which this map maps the specified key.
CfgPropItem	get(java.lang.String name) Returns the item in the table matching the given name, or null if no matching item could be found.
java.lang.String	getDisplayString() Returns a string containing a display of the names and values for all the property items in the table.
java.lang.String	getDisplayString(java.lang.String equalsStr, java.lang.String newlineStr) Returns a string containing a display of the names and values for all the property items in the table.
java.lang.String	getErrorMessage() Returns the text message string corresponding to the first error generated by the 'load()' method, or "No error" if no errors have occurred.
java.lang.String	getLoadedCfgFname() Returns the name of the configuration file that was loaded; or null if no file was loaded.
int	hashCode() Returns the hash code value for this map.
protected static java.lang.String	insertQuoteChars(java.lang.Object valueObj, java.lang.String stringValue) Returns a string with a backslash quote character ('\') inserted in front of each occurance of a "special" character in the given source string if needed.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
java.util.Enumeration	keys() Returns an enumeration of item names in the table.
java.util.Set	keySet() Returns a set view of the keys contained in this map.
boolean	load(java.io.InputStream inStm) Reads a set of property items from the given input stream.
boolean	load(java.io.InputStream inStm, boolean defaultFlag) Reads a set of property items from the given input stream.
boolean	load(java.lang.String inStr) Reads a set of property items from the given input string.
boolean	load(java.lang.String inStr, boolean defaultFlag) Reads a set of property items from the given input string.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Associates the specified value with the specified key in this map (optional operation).
void	putAll(java.util.Map t) Copies all of the mappings from the specified map to this map (optional operation).
CfgPropItem	remove(CfgPropItem item) Removes the given property item from the table.
java.lang.Object	remove(java.lang.Object key) Removes the mapping for this key from this map if present (optional operation).
CfgPropItem	remove(java.lang.String name) Removes the item in the table matching the given name.
void	setAllToDefaults() Sets value on all items to the default value.
protected void	setErrorMessage(java.lang.String str) Returns the text message string corresponding to the last error generated by the 'load()' method, or "No error" if no errors have occurred.
protected void	setIllegalCharMsg(int charVal)
void	setLoadedFlags(boolean flgVal) Sets the 'loadedFlag' field for all items to the given flag value.
protected void	setUnexpectedEOFMsg()
int	size() Returns the number of key-value mappings in this map.
void	store(java.io.OutputStream outStm, java.lang.String header, boolean skipUnloadedFlag) Stores the properties table to the given output stream in a manner suitable to loading via the 'load()' method.
void	store(java.io.OutputStream outStm, java.lang.String header, boolean skipUnloadedFlag, boolean showHeadersFlag, boolean showCmdLnOnlyFlag) Stores the properties table to the given output stream in a manner suitable to loading via the 'load()' method.
void	store(java.io.OutputStream outStm, java.lang.String header, boolean skipUnloadedFlag, boolean showHeadersFlag, boolean showCmdLnOnlyFlag, java.lang.String equalsStr) Stores the properties table to the given output stream in a manner suitable to loading via the 'load()' method.
void	store(java.io.OutputStream outStm, java.lang.String header, boolean skipUnloadedFlag, boolean showHeadersFlag, boolean showCmdLnOnlyFlag, java.lang.String equalsStr, java.lang.String newlineStr) Stores the properties table to the given output stream in a manner suitable to loading via the 'load()' method.
java.util.Collection	values() Returns a collection view of the values contained in this map.

Methods inherited from class java.lang.Object

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

Field Detail

SEPARATOR_STRING

public static final java.lang.String SEPARATOR_STRING

The separator string to use to separate values.

See Also:

Constant Field Values

SPECIAL_CHARS_STR

public static final java.lang.String SPECIAL_CHARS_STR

String of special characters for 'insertQuoteChars()' method.

See Also:

Constant Field Values

errorMessage

protected java.lang.String errorMessage

errMsgSetFlag

protected boolean errMsgSetFlag

loadedCfgFname

protected java.lang.String loadedCfgFname

Constructor Detail

BaseProperties

public BaseProperties(java.util.Map itemsMap)

Creates a properties object that uses the specified map of items or creates a new one if no map was specified (null).

Parameters:

itemsMap - items map

BaseProperties

public BaseProperties()

Creates an empty table of items.

BaseProperties

public BaseProperties(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 of items

BaseProperties

public BaseProperties(CfgPropItem[] itemsArr)

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

Parameters:

itemsArr - array of items

Method Detail

add

public final CfgPropItem add(CfgPropItem item)

Adds the given property item to the table. If an item with the same name already exists in the table, it is replaced.

Parameters:

item - the item to add

Returns:

The given property item.

add

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

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. The new item's required-flag is set to false (see 'CfgPropItem.setRequiredFlag()').

Parameters:

nameStr - the name for the property item.

valueObj - the default value object for the property item.

Returns:

The newly created property item.

add

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

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

Returns:

The newly created property item.

remove

public CfgPropItem remove(java.lang.String name)

Removes the item in the table matching the given name.

Parameters:

name - item name

Returns:

The matching item, or null if none could be found.

get

public CfgPropItem get(java.lang.String name)

Returns the item in the table matching the given name, or null if no matching item could be found.

Parameters:

name - item name

Returns:

the item

containsKey

public boolean containsKey(java.lang.String name)

Returns true if the table contains an item whose name matches the given name.

Parameters:

name - key name

Returns:

true if the table contains an item whose name matches the given name.

elements

public java.util.Enumeration elements()

Returns an enumeration of items in the table. The items will be enumerated in same order as they were added to the table.

Returns:

enumeration of items

keys

public java.util.Enumeration keys()

Returns an enumeration of item names in the table. The names will be enumerated in same order as they were added to the table.

Returns:

enumeration of keys

remove

public CfgPropItem remove(CfgPropItem item)

Removes the given property item from the table.

Parameters:

item - the item to remove

Returns:

The given property item.

store

public void store(java.io.OutputStream outStm,
                  java.lang.String header,
                  boolean skipUnloadedFlag,
                  boolean showHeadersFlag,
                  boolean showCmdLnOnlyFlag,
                  java.lang.String equalsStr,
                  java.lang.String newlineStr)
           throws java.io.IOException

Stores the properties table to the given output stream in a manner suitable to loading via the 'load()' method. The items in the table are stored in the same order that they were added. The name and value fields of each item are stored (but not the default-value field). The current date and time is stored as a comment line (if 'showHeadersFlag' is true).

Parameters:

outStm - an output stream.

header - a descriptive string which, if not null and contains data, is written as a leading comment line.

skipUnloadedFlag - if true then only items with their 'loadedFlag' set will be stored, if false then all items will be stored.

showHeadersFlag - if true then the headers are outputted.

showCmdLnOnlyFlag - if true then items set as "command line only" will also be stored.

equalsStr - a String containing the characters to be placed between each name and value; or if null then the characters " = " will be used.

newlineStr - a String containing the characters to be used to separate items; or if null then the system default newline character(s) will be used.

Throws:

java.io.IOException - if an I/O error is detected.

store

public void store(java.io.OutputStream outStm,
                  java.lang.String header,
                  boolean skipUnloadedFlag,
                  boolean showHeadersFlag,
                  boolean showCmdLnOnlyFlag,
                  java.lang.String equalsStr)
           throws java.io.IOException

Stores the properties table to the given output stream in a manner suitable to loading via the 'load()' method. The items in the table are stored in the same order that they were added. The name and value fields of each item are stored (but not the default-value field). The current date and time is stored as a comment line (if 'showHeadersFlag' is true).

Parameters:

outStm - an output stream.

header - a descriptive string which, if not null and contains data, is written as a leading comment line.

skipUnloadedFlag - if true then only items with their 'loadedFlag' set will be stored, if false then all items will be stored.

showHeadersFlag - if true then the headers are outputted.

showCmdLnOnlyFlag - if true then items set as "command line only" will also be stored.

equalsStr - a String containing the characters to be placed between each name and value; or if null then the characters " = " will be used.

Throws:

java.io.IOException - if an I/O error is detected.

store

public void store(java.io.OutputStream outStm,
                  java.lang.String header,
                  boolean skipUnloadedFlag,
                  boolean showHeadersFlag,
                  boolean showCmdLnOnlyFlag)
           throws java.io.IOException

Stores the properties table to the given output stream in a manner suitable to loading via the 'load()' method. The items in the table are stored in the same order that they were added. The name and value fields of each item are stored (but not the default-value field). The current date and time is stored as a comment line (if 'showHeadersFlag' is true).

Parameters:

outStm - an output stream.

header - a descriptive string which, if not null and contains data, is written as a leading comment line.

skipUnloadedFlag - if true then only items with their 'loadedFlag' set will be stored, if false then all items will be stored.

showHeadersFlag - if true then the headers are outputted.

showCmdLnOnlyFlag - if true then items set as "command line only" will also be stored.

Throws:

java.io.IOException - if an I/O error is detected.

store

public void store(java.io.OutputStream outStm,
                  java.lang.String header,
                  boolean skipUnloadedFlag)
           throws java.io.IOException

Stores the properties table to the given output stream in a manner suitable to loading via the 'load()' method. The items in the table are stored in the same order that they were added. The name and value fields of each item are stored (but not the default-value field). The current date and time is stored as a comment line.

Parameters:

outStm - an output stream.

header - a descriptive string which, if not null and contains data, is written as a leading comment line.

skipUnloadedFlag - if true then only items with their 'loadedFlag' set will be stored, if false then all items will be stored.

Throws:

java.io.IOException - if an I/O error is detected.

load

public boolean load(java.io.InputStream inStm)

Reads a set of property items from the given input stream. Each item name read must match an existing property item name in the current table, and the read item's value must be a valid ASCII representation of the item's type. The loading continues even after an error has been detected; the text error message corresponding to the first error detected is saved.

Parameters:

inStm - an input stream.

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.

load

public boolean load(java.io.InputStream inStm,
                    boolean defaultFlag)

Reads a set of property items from the given input stream. Each item name read must match an existing property item name in the current table, and the read item's value must be a valid ASCII representation of the item's type. The loading continues even after an error has been detected; the text error message corresponding to the first error detected is saved.

Parameters:

inStm - an input stream.

defaultFlag - true if property items are the defaults, false otherwise.

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.

load

public boolean load(java.lang.String inStr)

Reads a set of property items from the given input string. Each item name read must match an existing property item name in the current table, and the read item's value must be a valid ASCII representation of the item's type. The loading continues even after an error has been detected; the text error message corresponding to the first error detected is saved.

Parameters:

inStr - the string containing the data to read.

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.

load

public boolean load(java.lang.String inStr,
                    boolean defaultFlag)

Reads a set of property items from the given input string. Each item name read must match an existing property item name in the current table, and the read item's value must be a valid ASCII representation of the item's type. The loading continues even after an error has been detected; the text error message corresponding to the first error detected is saved.

Parameters:

inStr - the string containing the data to read.

defaultFlag - true if property items are the defaults, false otherwise.

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.

setLoadedFlags

public void setLoadedFlags(boolean flgVal)

Sets the 'loadedFlag' field for all items to the given flag value.

Parameters:

flgVal - flag value

setErrorMessage

protected void setErrorMessage(java.lang.String str)

Returns the text message string corresponding to the last error generated by the 'load()' method, or "No error" if no errors have occurred.

Parameters:

str - error message string

setIllegalCharMsg

protected void setIllegalCharMsg(int charVal)

setUnexpectedEOFMsg

protected void setUnexpectedEOFMsg()

getErrorMessage

public java.lang.String getErrorMessage()

Returns the text message string corresponding to the first error generated by the 'load()' method, or "No error" if no errors have occurred.

Returns:

the error message string

getLoadedCfgFname

public java.lang.String getLoadedCfgFname()

Returns the name of the configuration file that was loaded; or null if no file was loaded.

Returns:

the name of the configuration file that was loaded; or null if no file was loaded.

getDisplayString

public java.lang.String getDisplayString(java.lang.String equalsStr,
                                         java.lang.String newlineStr)

Returns a string containing a display of the names and values for all the property items in the table.

Parameters:

equalsStr - a String containing the characters to be placed between each name and value; or if null then the characters " = " will be used.

newlineStr - a String containing the characters to be used to separate items; or if null then the system default newline character(s) will be used.

Returns:

A string containing a display of the names and values for all the property items in the table.

getDisplayString

public java.lang.String getDisplayString()

Returns a string containing a display of the names and values for all the property items in the table.

Returns:

A string containing a display of the names and values for all the property items in the table.

size

public int size()

Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:

size in interface java.util.Map

Returns:

the number of key-value mappings in this map.

isEmpty

public boolean isEmpty()

Returns true if this map contains no key-value mappings.

Specified by:

isEmpty in interface java.util.Map

Returns:

true if this map contains no key-value mappings.

containsKey

public boolean containsKey(java.lang.Object key)

Returns true if this map contains a mapping for the specified key.

Specified by:

containsKey in interface java.util.Map

Parameters:

key - key whose presence in this map is to be tested.

Returns:

true if this map contains a mapping for the specified key.

Throws:

java.lang.ClassCastException - if the key is of an inappropriate type for this map.

java.lang.NullPointerException - if the key is null and this map does not not permit null keys.

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this map maps one or more keys to the specified value. More formally, returns true if and only if this map contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)). This operation will probably require time linear in the map size for most implementations of the Map interface.

Specified by:

containsValue in interface java.util.Map

Parameters:

value - value whose presence in this map is to be tested.

Returns:

true if this map maps one or more keys to the specified value.

get

public java.lang.Object get(java.lang.Object key)

Returns the value to which this map maps the specified key. Returns null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.

Specified by:

get in interface java.util.Map

Parameters:

key - key whose associated value is to be returned.

Returns:

the value to which this map maps the specified key, or null if the map contains no mapping for this key.

Throws:

java.lang.ClassCastException - if the key is of an inappropriate type for this map.

java.lang.NullPointerException - key is null and this map does not not permit null keys.

See Also:

containsKey(Object)

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for this key, the old value is replaced.

Specified by:

put in interface java.util.Map

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

Throws:

java.lang.UnsupportedOperationException - if the put operation is not supported by this map.

java.lang.ClassCastException - if the class of the specified key or value prevents it from being stored in this map.

java.lang.IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this map.

java.lang.NullPointerException - this map does not permit null keys or values, and the specified key or value is null.

remove

public java.lang.Object remove(java.lang.Object key)

Removes the mapping for this key from this map if present (optional operation).

Specified by:

remove in interface java.util.Map

Parameters:

key - key whose mapping is to be removed from the map.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values.

Throws:

java.lang.UnsupportedOperationException - if the remove method is not supported by this map.

putAll

public void putAll(java.util.Map t)

Copies all of the mappings from the specified map to this map (optional operation). These mappings will replace any mappings that this map had for any of the keys currently in the specified map.

Specified by:

putAll in interface java.util.Map

Parameters:

t - Mappings to be stored in this map.

Throws:

java.lang.UnsupportedOperationException - if the putAll method is not supported by this map.

java.lang.ClassCastException - if the class of a key or value in the specified map prevents it from being stored in this map.

java.lang.IllegalArgumentException - some aspect of a key or value in the specified map prevents it from being stored in this map.

java.lang.NullPointerException - this map does not permit null keys or values, and the specified key or value is null.

clear

public void clear()

Removes all mappings from this map (optional operation).

Specified by:

clear in interface java.util.Map

Throws:

java.lang.UnsupportedOperationException - clear is not supported by this map.

setAllToDefaults

public void setAllToDefaults()

Sets value on all items to the default value.

keySet

public java.util.Set keySet()

Returns a set view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll retainAll, and clear operations. It does not support the add or addAll operations.

Specified by:

keySet in interface java.util.Map

Returns:

a set view of the keys contained in this map.

values

public java.util.Collection values()

Returns a collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress, the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Specified by:

values in interface java.util.Map

Returns:

a collection view of the values contained in this map.

entrySet

public java.util.Set entrySet()

Returns a set view of the mappings contained in this map. Each element in the returned set is a Map.Entry. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Specified by:

entrySet in interface java.util.Map

Returns:

a set view of the mappings contained in this map.

equals

public boolean equals(java.lang.Object o)

Compares the specified object with this map for equality. Returns true if the given object is also a map and the two Maps represent the same mappings. More formally, two maps t1 and t2 represent the same mappings if t1.entrySet().equals(t2.entrySet()). This ensures that the equals method works properly across different implementations of the Map interface.

Specified by:

equals in interface java.util.Map

Parameters:

o - object to be compared for equality with this map.

Returns:

true if the specified object is equal to this map.

hashCode

public int hashCode()

Returns the hash code value for this map. The hash code of a map is defined to be the sum of the hashCodes of each entry in the map's entrySet view. This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two maps t1 and t2, as required by the general contract of Object.hashCode.

Specified by:

hashCode in interface java.util.Map

Returns:

the hash code value for this map.

See Also:

Map.Entry#hashCode(), Object.hashCode(), Object.equals(Object), equals(Object)

insertQuoteChars

protected static java.lang.String insertQuoteChars(java.lang.Object valueObj,
                                                   java.lang.String stringValue)

Returns a string with a backslash quote character ('\') inserted in front of each occurance of a "special" character in the given source string if needed.

Parameters:

valueObj - the value object.

stringValue - the string value of the item.

Returns:

a new string with its "special" characters quoted, or the original string if no matching "special" characters were found.