net.lucidviews.util
Class Properties

java.lang.Object
  java.util.Dictionary<K,V>
      java.util.Hashtable<Object,Object>
          java.util.Properties
              net.lucidviews.util.Properties

All Implemented Interfaces:

Serializable, Cloneable, Map<Object,Object>

public class Properties
extends Properties

An extension to the java.util.Properties class, which parses and validates non-String values.

A net.lucidviews.util.Properties class can be instantiated in a number of ways:

• Using the default constructor to create an empty table of values.
• With a File to load an initial set of property values from a .properties file. (See the file format described in the java.util.Properties JavaDoc.)
• With a java.util.Properties object. Effectively using the net.lucidviews.util.Properties class to wrapper the basic properties table and provide more advanced access to the values therein.

The net.lucidviews.util.Properties class provides access methods to set and get values of various types, including:

• java.lang.Boolean (and boolean)
• java.lang.Class
• java.awt.Color
• java.lang.Double (and double)
• net.lucidviews.util.EnumValue
• java.io.File
• java.lang.Long (and long)

Each getter method is overloaded to allow the caller the option of providing default values, giving total flexibility in error handling.

The

Since:

1.0

Version:

$Revision: 1.6 $

Author:

Stephen Battey

See Also:

PropertyException, Properties, Serialized Form

Nested Class Summary

private static class	Properties.ClassParamMustExist Helper class required for exported constant CLASS_PARAM_MUST_EXIST, which must be unique/different to avoid confusion with any other value a client may use.
private static class	Properties.EnumParamMustExist Helper class required for exported constant ENUM_PARAM_MUST_EXIST, which must be unique/different to avoid confusion with any other value a client may use.

Field Summary

protected String	_sourceDescription A description of where the properties were defined.
protected File	_sourceFile The file used to persist these property values.
static Boolean	BOOLEAN_MUST_BE_VALID Special default value that ensures a valid Boolean value is parsed (i.e.
static Boolean	BOOLEAN_PARAM_MUST_EXIST Special default value that ensures a property has been defined for a given Boolean value.
static Class	CLASS_MUST_BE_VALID Special default value that ensures a valid Class is parsed (i.e.
static Class	CLASS_PARAM_MUST_EXIST Special default value that ensures a property has been defined for a given class reference.
static Color	COLOR_MUST_BE_VALID Special default value that ensures a valid Color is parsed (i.e.
static Color	COLOR_PARAM_MUST_EXIST Special default value that ensures a property has been defined for a given colour value.
static Double	DOUBLE_MUST_BE_VALID Special default value that ensures a valid floating-point value is parsed (i.e.
static Double	DOUBLE_PARAM_MUST_EXIST Special default value that ensures a property has been defined for a given floating-point value.
static File	ENSURE_FILE_EXISTS Special default value that ensures a valid File is parsed and references an existing file or a location where a new file can be created.
static File	ENSURE_FOLDER_EXISTS Special default value that ensures a valid File is parsed and references an existing folder or a location where a new folder can be created.
static File	ENSURE_PARENT_FOLDER_EXISTS Special default value that ensures a valid File is parsed and references a location within an existing folder or in a folder that can be created.
static EnumValue	ENUM_PARAM_MUST_EXIST Special default value that ensures a property has been defined for a given enumeration value.
static EnumValue	ENUM_VALUE_MUST_BE_VALID Special default value that ensures a valid Enumeration value is parsed (i.e.
static File	FILE_MUST_EXIST Special default value that ensures a valid File is parsed and references a file that already exists on the file system.
static File	FILE_PARAM_MUST_EXIST Special default value that ensures a property has been defined for a given file location.
static File	FOLDER_MUST_EXIST Special default value that ensures a valid File is parsed and references a folder that already exists on the file system.
static File	FOLDER_PARAM_MUST_EXIST Special default value that ensures a property has been defined for a given folder location.
static Long	LONG_MUST_BE_VALID Special default value that ensures a valid integer value is parsed (i.e.
static Long	LONG_PARAM_MUST_EXIST Special default value that ensures a property has been defined for a given integer value.
static File	PARENT_FOLDER_MUST_EXIST Special default value that ensures a valid File is parsed and references a location within an existing folder on the file system.
protected static long	serialVersionUID Version of class serialisation.
protected static String	UNDEFINED_SOURCE A default source description.

Fields inherited from class java.util.Properties

defaults

Constructor Summary

Properties()
Set-up an empty table of property values.

Properties(File sourceFile)
Set-up a table of property values loaded from a given source file.

Properties(Properties properties)
Set-up a table of property values copying values from another Properties table.

Properties(Properties properties, String sourceDescription)
Set-up a table of property values copying values from another Properties table, with a description of the source of the property values.

Properties(String sourceDescription)
Set-up an empty table of property values, with a description of the source of the property values.

Method Summary

Boolean	getBooleanProperty(String key) Parse a Boolean value from the property with given key.
boolean	getBooleanProperty(String key, boolean defaultValue) Parse a Boolean value from the property with given key, returning the default value if the property is missing or invalid.
Boolean	getBooleanProperty(String key, Boolean defaultValue) Parse a Boolean value from the property with given key, returning the default value if the property is missing or invalid.
boolean	getBooleanProperty(String key, boolean defaultIfMissing, boolean defaultIfInvalid) Parse a Boolean value from the property with given key, returning one of the default values if the property is missing or invalid.
Boolean	getBooleanProperty(String key, Boolean defaultIfMissing, Boolean defaultIfInvalid) Parse a Boolean value from the property with given key, returning one of the default values if the property is missing or invalid.
Class	getClassProperty(String key) Parse a Java class from the property with given key.
Class	getClassProperty(String key, Class defaultValue) Parse a Java class from the property with given key, returning the default value if the property is missing or invalid.
Class	getClassProperty(String key, Class defaultIfMissing, Class defaultIfInvalid) Parse a Java class from the property with given key, returning one of the default values if the property is missing or invalid.
Class	getClassProperty(String key, String basePackage) Parse a Java class from the property with given key.
Class	getClassProperty(String key, String basePackage, Class defaultValue) Parse a Java class from the property with given key, returning the default value if the property is missing or invalid.
Class	getClassProperty(String key, String basePackage, Class defaultIfMissing, Class defaultIfInvalid) Parse a Java class from the property with given key, returning one of the default values if the property is missing or invalid.
Color	getColorProperty(String key) Parse a Color from the property with given key.
Color	getColorProperty(String key, Color defaultValue) Parse a Color from the property with given key, returning the default value if the property is missing or invalid.
Color	getColorProperty(String key, Color defaultIfMissing, Color defaultIfInvalid) Parse a Color from the property with given key, returning one of the default values if the property is missing or invalid.
Double	getDoubleProperty(String key) Parse a numeric, floating-point value from the property with given key.
double	getDoubleProperty(String key, double defaultValue) Parse a numeric, floating-point value from the property with given key, returning the default value if the property is missing or invalid.
Double	getDoubleProperty(String key, Double defaultValue) Parse a numeric, floating-point value from the property with given key, returning the default value if the property is missing or invalid.
double	getDoubleProperty(String key, double defaultIfMissing, double defaultIfInvalid) Parse a numeric, floating-point value from the property with given key, returning one of the default values if the property is missing or invalid.
Double	getDoubleProperty(String key, Double defaultIfMissing, Double defaultIfInvalid) Parse a numeric, floating-point value from the property with given key, returning one of the default values if the property is missing or invalid.
EnumValue	getEnumProperty(String key, Enumeration enumeration) Parse an enumeration value from the property with given key.
EnumValue	getEnumProperty(String key, Enumeration enumeration, EnumValue defaultValue) Parse an enumeration value from the property with given key, returning the default value if the property is missing or invalid.
EnumValue	getEnumProperty(String key, Enumeration enumeration, EnumValue defaultIfMissing, EnumValue defaultIfInvalid) Parse an enumeration value from the property with given key, returning one of the default values if the property is missing or invalid.
File	getFileProperty(File baseFolder, String key) Parse a file reference from the property with given key.
File	getFileProperty(File baseFolder, String key, File defaultValue) Parse a file reference from the property with given key, returning the default value if the property is missing or invalid.
File	getFileProperty(File baseFolder, String key, File defaultIfMissing, File defaultIfInvalid) Parse a file reference from the property with given key, returning one of the default values if the property is missing or invalid.
File	getFileProperty(File baseFolder, String key, String defaultIfMissing, File defaultIfInvalid) Parse a file reference from the property with given key, returning one of the default values if the property is missing or invalid.
File	getFileProperty(String key) Parse a file reference from the property with given key.
File	getFileProperty(String key, File defaultValue) Parse a file reference from the property with given key, returning the default value if the property is missing or invalid.
File	getFileProperty(String key, File defaultIfMissing, File defaultIfInvalid) Parse a file reference from the property with given key, returning one of the default values if the property is missing or invalid.
File	getFileProperty(String key, String defaultPath) Parse a file reference from the property with given key, using the default file path if the property is missing or invalid.
File	getFileProperty(String key, String defaultIfMissing, File defaultIfInvalid) Parse a file reference from the property with given key, returning one of the default values if the property is missing or invalid.
File	getFolderProperty(File baseFolder, String key) Parse a folder reference from the property with given key.
File	getFolderProperty(File baseFolder, String key, File defaultValue) Parse a folder reference from the property with given key, returning the default value if the property is missing or invalid.
File	getFolderProperty(File baseFolder, String key, File defaultIfMissing, File defaultIfInvalid) Parse a folder reference from the property with given key, returning one of the default values if the property is missing or invalid.
File	getFolderProperty(File baseFolder, String key, String defaultIfMissing, File defaultIfInvalid) Parse a folder reference from the property with given key, returning one of the default values if the property is missing or invalid.
File	getFolderProperty(String key) Parse a folder reference from the property with given key.
File	getFolderProperty(String key, File defaultValue) Parse a folder reference from the property with given key, returning the default value if the property is missing or invalid.
File	getFolderProperty(String key, File defaultIfMissing, File defaultIfInvalid) Parse a folder reference from the property with given key, returning one of the default values if the property is missing or invalid.
File	getFolderProperty(String key, String defaultIfMissing, File defaultIfInvalid) Parse a folder reference from the property with given key, returning one of the default values if the property is missing or invalid.
Long	getLongProperty(String key) Parse a numeric, integer value from the property with given key.
long	getLongProperty(String key, long defaultValue) Parse a numeric, integer value from the property with given key, returning the default value if the property is missing or invalid.
Long	getLongProperty(String key, Long defaultValue) Parse a numeric, integer value from the property with given key, returning the default value if the property is missing or invalid.
long	getLongProperty(String key, long defaultIfMissing, long defaultIfInvalid) Parse a numeric, integer value from the property with given key, returning one of the default values if the property is missing or invalid.
Long	getLongProperty(String key, Long defaultIfMissing, Long defaultIfInvalid) Parse a numeric, integer value from the property with given key, returning one of the default values if the property is missing or invalid.
String	getStringProperty(String key) Retrieve a String value from the property with given key.
String	getStringProperty(String key, String defaultValue) Retrieve a String value from the property with given key, returning the default value if the property is missing.
void	load() Load property values from the source file.
void	load(File inFile) Load property values from a specified file.
void	load(URL inUrl) Load property values from a specified URL.
void	setBooleanProperty(String key, boolean value) Assign a Boolean value to a given property.
void	setBooleanProperty(String key, Boolean value) Assign a Boolean value to a given property.
void	setClassProperty(String key, Class value) Assign the name of a Java class to a given property.
void	setColorProperty(String key, Color value) Assign a color value to a given property.
void	setDoubleProperty(String key, double value) Assign a (floating-point) numeric value to a given property.
void	setDoubleProperty(String key, Double value) Assign a (floating-point) numeric value to a given property.
void	setEnumProperty(String key, EnumValue value) Assign an enumeration value to a given property.
void	setFileProperty(String key, File value) Assign a file path to a given property.
void	setFolderProperty(String key, File value) Assign a folder path to a given property.
void	setLongProperty(String key, long value) Assign an integer value to a given property.
void	setLongProperty(String key, Long value) Assign an integer value to a given property.
void	setSourceFile(File sourceFile) Set the file that is used to persist these properties.
void	setStringProperty(String key, String value) Assign a text value to a given property.
void	store() Store the property values into the source file.
void	store(File outFile, String header) Store the property values into a file at the given location.
void	store(String header) Store the property values into the source file.

Methods inherited from class java.util.Properties

getProperty, getProperty, list, list, load, loadFromXML, propertyNames, save, setProperty, store, storeToXML, storeToXML

Methods inherited from class java.util.Hashtable

clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, size, toString, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

BOOLEAN_PARAM_MUST_EXIST

public static final Boolean BOOLEAN_PARAM_MUST_EXIST

Special default value that ensures a property has been defined for a given Boolean value.

See Also:

getBooleanProperty(String,Boolean,Boolean)

LONG_PARAM_MUST_EXIST

public static final Long LONG_PARAM_MUST_EXIST

Special default value that ensures a property has been defined for a given integer value.

See Also:

getLongProperty(String,Long,Long)

DOUBLE_PARAM_MUST_EXIST

public static final Double DOUBLE_PARAM_MUST_EXIST

Special default value that ensures a property has been defined for a given floating-point value.

See Also:

getDoubleProperty(String,Double,Double)

FILE_PARAM_MUST_EXIST

public static final File FILE_PARAM_MUST_EXIST

Special default value that ensures a property has been defined for a given file location.

See Also:

getFileProperty(String,File,File)

FOLDER_PARAM_MUST_EXIST

public static final File FOLDER_PARAM_MUST_EXIST

Special default value that ensures a property has been defined for a given folder location.

See Also:

getFolderProperty(String,File,File)

CLASS_PARAM_MUST_EXIST

public static final Class CLASS_PARAM_MUST_EXIST

Special default value that ensures a property has been defined for a given class reference.

See Also:

getClassProperty(String,Class,Class)

ENUM_PARAM_MUST_EXIST

public static final EnumValue ENUM_PARAM_MUST_EXIST

Special default value that ensures a property has been defined for a given enumeration value.

See Also:

getEnumProperty(String,Enumeration,EnumValue)

COLOR_PARAM_MUST_EXIST

public static final Color COLOR_PARAM_MUST_EXIST

Special default value that ensures a property has been defined for a given colour value.

See Also:

getColorProperty(String,Color,Color)

BOOLEAN_MUST_BE_VALID

public static final Boolean BOOLEAN_MUST_BE_VALID

Special default value that ensures a valid Boolean value is parsed (i.e. to be used when no default value is applicable).

See Also:

getBooleanProperty(String,Boolean,Boolean)

LONG_MUST_BE_VALID

public static final Long LONG_MUST_BE_VALID

Special default value that ensures a valid integer value is parsed (i.e. to be used when no default value is applicable).

See Also:

getLongProperty(String,Long,Long)

DOUBLE_MUST_BE_VALID

public static final Double DOUBLE_MUST_BE_VALID

Special default value that ensures a valid floating-point value is parsed (i.e. to be used when no default value is applicable).

See Also:

getDoubleProperty(String,Double,Double)

FILE_MUST_EXIST

public static final File FILE_MUST_EXIST

Special default value that ensures a valid File is parsed and references a file that already exists on the file system.

See Also:

getFileProperty(String,File,File)

ENSURE_FILE_EXISTS

public static final File ENSURE_FILE_EXISTS

Special default value that ensures a valid File is parsed and references an existing file or a location where a new file can be created.

See Also:

getFileProperty(String,File,File)

FOLDER_MUST_EXIST

public static final File FOLDER_MUST_EXIST

Special default value that ensures a valid File is parsed and references a folder that already exists on the file system.

See Also:

getFolderProperty(String,File,File)

ENSURE_FOLDER_EXISTS

public static final File ENSURE_FOLDER_EXISTS

Special default value that ensures a valid File is parsed and references an existing folder or a location where a new folder can be created.

See Also:

getFolderProperty(String,File,File)

PARENT_FOLDER_MUST_EXIST

public static final File PARENT_FOLDER_MUST_EXIST

Special default value that ensures a valid File is parsed and references a location within an existing folder on the file system.

See Also:

getFileProperty(String,File,File), getFolderProperty(String,File,File)

ENSURE_PARENT_FOLDER_EXISTS

public static final File ENSURE_PARENT_FOLDER_EXISTS

Special default value that ensures a valid File is parsed and references a location within an existing folder or in a folder that can be created.

See Also:

getFileProperty(String,File,File), getFolderProperty(String,File,File)

CLASS_MUST_BE_VALID

public static final Class CLASS_MUST_BE_VALID

Special default value that ensures a valid Class is parsed (i.e. to be used when no default value is applicable).

See Also:

getClassProperty(String,Class,Class)

ENUM_VALUE_MUST_BE_VALID

public static final EnumValue ENUM_VALUE_MUST_BE_VALID

Special default value that ensures a valid Enumeration value is parsed (i.e. to be used when no default value is applicable).

See Also:

getEnumProperty(String, Enumeration,EnumValue,EnumValue)

COLOR_MUST_BE_VALID

public static final Color COLOR_MUST_BE_VALID

Special default value that ensures a valid Color is parsed (i.e. to be used when no default value is applicable).

See Also:

getColorProperty(String,Color,Color)

UNDEFINED_SOURCE

protected static final String UNDEFINED_SOURCE

A default source description.

See Also:

Constant Field Values

serialVersionUID

protected static final long serialVersionUID

Version of class serialisation.

See Also:

Constant Field Values

_sourceDescription

protected String _sourceDescription

A description of where the properties were defined.

_sourceFile

protected File _sourceFile

The file used to persist these property values.

Constructor Detail

Properties

public Properties()

Set-up an empty table of property values.
Clients are encouraged to use the Properties( String ) constructor instead and specify a description of the properties table, so that messages relating to property values can be put in context
e.g. "The database.url property in the myappn.properties file"

Properties

public Properties(String sourceDescription)

Set-up an empty table of property values, with a description of the source of the property values.
The description will be used to give messages relating to property values some context
e.g. "The database.url property in the myappn.properties file"

Parameters:

sourceDescription - a description of where the property values will be loaded from

Properties

public Properties(File sourceFile)
           throws IOException

Set-up a table of property values loaded from a given source file.
The file will also be taken as the source of the properties - meaning a link will be established between the properties table and the content of the file. If the store or load methods are called it will be assumed the properties are to be stored/loaded from this source file, unless a different file is stated.

Parameters:

sourceFile - the file where the property values are to be loaded from and stored to

Throws:

IOException - an error prevented the values being read from the specified file

See Also:

load(), store(), setSourceFile(java.io.File)

Properties

public Properties(Properties properties)

Set-up a table of property values copying values from another Properties table.
Clients are encouraged to use the Properties( Properties, String ) constructor instead and specify a description of the properties table, so that messages relating to property values can be put in context
e.g. "The database.url property in the myappn.properties file"

Parameters:

properties - initial values to be loaded into this properties table

Properties

public Properties(Properties properties,
                  String sourceDescription)

Set-up a table of property values copying values from another Properties table, with a description of the source of the property values.
The description will be used to give messages relating to property values some context
e.g. "The database.url property in the myappn.properties file"

Parameters:

properties - initial values to be loaded into this properties table

sourceDescription - a description of where the property values will be loaded from

Method Detail

setSourceFile

public void setSourceFile(File sourceFile)

Set the file that is used to persist these properties.
The given file will be implicitly linked to this table of properties table. If the store or load methods are called it will be assumed the properties are to be stored/loaded from this source file, unless a different file is stated.

Parameters:

sourceFile - the file where the property values are to be loaded and stored

See Also:

store(), load()

load

public void load()
          throws FileNotFoundException,
                 IOException

Load property values from the source file.
The properties will be added to those already contained in this Properties table (to remove values already loaded, use the clear method).
If a source file has not been set, either by using the Properties( File ) constructor or by calling the setSourceFile method, then an exception will be thrown.
The contents of the file must meet the specification described by the load method of the java.util.Properties class.

Throws:

FileNotFoundException - no source file has been defined for this Properties table or the specified source file does not exist

IOException - an error prevented the values being read from the specified file

See Also:

Properties.load(java.io.InputStream)

load

public void load(File inFile)
          throws FileNotFoundException,
                 IOException

Load property values from a specified file.
The properties will be added to those already contained in this Properties table (to remove values already loaded, use the clear method).
The contents of the file must meet the specification described by the load method of the java.util.Properties class.

Parameters:

inFile - the file where the property values are defined

Throws:

FileNotFoundException - the specified file does not exist

IOException - an error prevented the values being read from the specified file

See Also:

Properties.load(java.io.InputStream)

load

public void load(URL inUrl)
          throws IOException

Load property values from a specified URL.
The properties will be added to those already contained in this Properties table (to remove values already loaded, use the clear method).
The contents of the file must meet the specification described by the load method of the java.util.Properties class.

Parameters:

inUrl - the location of the resource where the property values are defined

Throws:

IOException - an error prevented the values being read from the specified resource

See Also:

Properties.load(java.io.InputStream)

store

public void store()
           throws IOException

Store the property values into the source file.
Any content in the file will be overwritten.

Throws:

IOException - error writing the property values to the source file

See Also:

setSourceFile(java.io.File)

store

public void store(String header)
           throws IOException

Store the property values into the source file.
Any content in the file will be overwritten.

Parameters:

header - a description of the property list

Throws:

IOException - error writing the property values to the source file

See Also:

setSourceFile(java.io.File)

store

public void store(File outFile,
                  String header)
           throws IOException

Store the property values into a file at the given location.
Any content in the file will be overwritten.

Parameters:

outFile - the file where the property values are to be stored

header - a description of the property list

Throws:

IOException - error writing the property values to the specified file

getStringProperty

public String getStringProperty(String key)
                         throws PropertyException

Retrieve a String value from the property with given key.
If the property with given key does not exist an exception will be thrown.
The return value is guaranteed non-null. Thus, the following line of code will never cause a NullPointerException:
int strLen = myproperties.getStringProperty( key ).length();
Although it may throw a PropertyException if the property does not exist.

Parameters:

key - the name of the property to be read

Returns:

the text value of the given property

Throws:

PropertyException - the property does not exist

getStringProperty

public String getStringProperty(String key,
                                String defaultValue)

Retrieve a String value from the property with given key, returning the default value if the property is missing.
If the property with given key does not exist then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null. Thus, the following line of code will never cause a NullPointerException:
int strLen = myproperties.getStringProperty( key, default ).length();

Parameters:

key - the name of the property to be read

defaultValue - the value to be used if the property is missing

Returns:

the text value of the given property

setStringProperty

public void setStringProperty(String key,
                              String value)

Assign a text value to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property

getBooleanProperty

public Boolean getBooleanProperty(String key)
                           throws PropertyException

Parse a Boolean value from the property with given key.
If the property with given key does not exist an exception will be thrown.
If the value of the property with given key does not represent a valid Boolean value then an exception will be thrown.
The return value is guaranteed non-null. Thus, the following line of code will never cause a NullPointerException:
boolean value = myproperties.getBooleanProperty( key ).booleanValue();
Although it may throw a PropertyException if the property value is invalid.

Parameters:

key - the name of the property to be read

Returns:

the Boolean value of the given property

Throws:

PropertyException - the property does not exist or is invalid

getBooleanProperty

public Boolean getBooleanProperty(String key,
                                  Boolean defaultIfMissing,
                                  Boolean defaultIfInvalid)
                           throws PropertyException

Parse a Boolean value from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.BOOLEAN_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not represent a valid Boolean value and the defaultIfInvalid parameter is set to Properties.BOOLEAN_MUST_BE_VALID then an exception will be thrown. Otherwise the defaultIfInvalid value is returned.
The return value is guaranteed non-null provided neither of the defaultValues are null. Thus, the following line of code will never cause a NullPointerException:
boolean value = myproperties.getBooleanProperty( key, default, default ).booleanValue();
Although it may throw a PropertyException if the property value is invalid.

Parameters:

key - the name of the property to be read

defaultIfMissing - the Boolean value to use if the property is missing (use Properties.BOOLEAN_PARAM_MUST_EXIST to cause an exception in such a situation)

defaultIfInvalid - the Boolean value to use if the property does not specify a valid Boolean value (use Properties.BOOLEAN_MUST_BE_VALID to cause an exception in such a situation)

Returns:

the Boolean value of the given property

Throws:

PropertyException - the property does not exist or is invalid

getBooleanProperty

public Boolean getBooleanProperty(String key,
                                  Boolean defaultValue)

Parse a Boolean value from the property with given key, returning the default value if the property is missing or invalid.
If the property with given key does not exist or does not represent a valid Boolean value then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null. Thus, the following line of code will never cause a NullPointerException:
boolean value = myproperties.getBooleanProperty( key, default ).booleanValue();

Parameters:

key - the name of the property to be read

defaultValue - the value to be used if the property is missing or does not represent a Boolean value

Returns:

the Boolean value of the given property

getBooleanProperty

public boolean getBooleanProperty(String key,
                                  boolean defaultValue)

Parse a Boolean value from the property with given key, returning the default value if the property is missing or invalid.
If the property with given key does not exist or does not represent a valid Boolean value then the default value will be returned.

Parameters:

key - the name of the property to be read

defaultValue - the value to be used if the property is missing or does not represent a Boolean value

Returns:

the Boolean value of the given property

getBooleanProperty

public boolean getBooleanProperty(String key,
                                  boolean defaultIfMissing,
                                  boolean defaultIfInvalid)

Parse a Boolean value from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist, the defaultIfMissing value will be returned.
If the value of the property with given key does not represent a valid Boolean value then the defaultIfInvalid value is returned.

Parameters:

key - the name of the property to be read

defaultIfMissing - the value to be used if the property is missing

defaultIfInvalid - the value to be used if the property does not represent a Boolean value

Returns:

the Boolean value of the given property

setBooleanProperty

public void setBooleanProperty(String key,
                               Boolean value)

Assign a Boolean value to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property

setBooleanProperty

public void setBooleanProperty(String key,
                               boolean value)

Assign a Boolean value to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property

getLongProperty

public Long getLongProperty(String key)
                     throws PropertyException

Parse a numeric, integer value from the property with given key.
If the property with given key does not exist an exception will be thrown.
If the value of the property with given key does not represent a valid integer value then an exception will be thrown.
The return value is guaranteed non-null. Thus, the following lines of code will never cause a NullPointerException:
long value = myproperties.getLongProperty( key ).longValue();
int value = myproperties.getLongProperty( key ).intValue();
Although they may throw a PropertyException if the property value is invalid.

Parameters:

key - the name of the property to be read

Returns:

the numeric, integer value of the given property

Throws:

PropertyException - the property does not exist or is invalid

getLongProperty

public Long getLongProperty(String key,
                            Long defaultIfMissing,
                            Long defaultIfInvalid)
                     throws PropertyException

Parse a numeric, integer value from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.LONG_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not represent a valid numeric, integer value and the defaultIfInvalid parameter is set to Properties.LONG_MUST_BE_VALID then an exception will be thrown. Otherwise the defaultIfInvalid value is returned.
The return value is guaranteed non-null provided neither of the defaultValues are null. Thus, the following lines of code will never cause a NullPointerException:
long value = myproperties.getLongProperty( key, default, default ).longValue();
int value = myproperties.getLongProperty( key, default, default ).intValue();
Although it may throw a PropertyException if the property value is invalid.

Parameters:

key - the name of the property to be read

defaultIfMissing - the number to use if the property is missing (use Properties.LONG_PARAM_MUST_EXIST to cause an exception in such a situation)

defaultIfInvalid - the number to use if the property does not specify a valid integer value (use Properties.LONG_MUST_BE_VALID to cause an exception in such a situation)

Returns:

the numeric, integer value of the given property

Throws:

PropertyException - the property does not exist or is invalid

getLongProperty

public Long getLongProperty(String key,
                            Long defaultValue)

Parse a numeric, integer value from the property with given key, returning the default value if the property is missing or invalid.
If the property with given key does not exist or does not represent a valid numeric, integer value then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null. Thus, the following lines of code will never cause a NullPointerException:
long value = myproperties.getLongProperty( key, default ).longValue();
int value = myproperties.getLongProperty( key, default ).intValue();

Parameters:

key - the name of the property to be read

defaultValue - the value to be used if the property is missing or does not represent a numeric, integer value

Returns:

the numeric, integer value of the given property

getLongProperty

public long getLongProperty(String key,
                            long defaultValue)

Parse a numeric, integer value from the property with given key, returning the default value if the property is missing or invalid.
If the property with given key does not exist or does not represent a valid numeric, integer value then the default value will be returned.

Parameters:

key - the name of the property to be read

defaultValue - the value to be used if the property is missing or does not represent a numeric, integer value

Returns:

the numeric, integer value of the given property

getLongProperty

public long getLongProperty(String key,
                            long defaultIfMissing,
                            long defaultIfInvalid)

Parse a numeric, integer value from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist, the defaultIfMissing value will be returned.
If the value of the property with given key does not represent a valid numeric, integer value then the defaultIfInvalid value is returned.

Parameters:

key - the name of the property to be read

defaultIfMissing - the value to be used if the property is missing

defaultIfInvalid - the value to be used if the property does not represent a numeric, integer value

Returns:

the numeric, integer value of the given property

setLongProperty

public void setLongProperty(String key,
                            Long value)

Assign an integer value to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property

setLongProperty

public void setLongProperty(String key,
                            long value)

Assign an integer value to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property

getDoubleProperty

public Double getDoubleProperty(String key)
                         throws PropertyException

Parse a numeric, floating-point value from the property with given key.
If the property with given key does not exist an exception will be thrown.
If the value of the property with given key does not represent a valid floating-point value then an exception will be thrown.
The return value is guaranteed non-null. Thus, the following lines of code will never cause a NullPointerException:
double value = myproperties.getDoubleProperty( key ).doubleValue();
float value = myproperties.getDoubleProperty( key ).floatValue();
Although they may throw a PropertyException if the property value is invalid.

Parameters:

key - the name of the property to be read

Returns:

the numeric, floating-point value of the given property

Throws:

PropertyException - the property does not exist or is invalid

getDoubleProperty

public Double getDoubleProperty(String key,
                                Double defaultIfMissing,
                                Double defaultIfInvalid)
                         throws PropertyException

Parse a numeric, floating-point value from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.DOUBLE_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not represent a valid numeric, floating-point value and the defaultIfInvalid parameter is set to Properties.DOUBLE_MUST_BE_VALID then an exception will be thrown. Otherwise the defaultIfInvalid value is returned.
The return value is guaranteed non-null provided neither of the defaultValues are null. Thus, the following lines of code will never cause a NullPointerException:
double value = myproperties.getDoubleProperty( key, default, default ).doubleValue();
float value = myproperties.getDoubleProperty( key, default, default ).floatValue();
Although it may throw a PropertyException if the property value is invalid.

Parameters:

key - the name of the property to be read

defaultIfMissing - the number to use if the property is missing (use Properties.DOUBLE_PARAM_MUST_EXIST to cause an exception in such a situation)

defaultIfInvalid - the number to use if the property does not specify a valid floating-point value (use Properties.DOUBLE_MUST_BE_VALID to cause an exception in such a situation)

Returns:

the numeric, floating-point value of the given property

Throws:

PropertyException - the property does not exist or is invalid

getDoubleProperty

public Double getDoubleProperty(String key,
                                Double defaultValue)

Parse a numeric, floating-point value from the property with given key, returning the default value if the property is missing or invalid.
If the property with given key does not exist or does not represent a valid numeric, floating-point value then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null. Thus, the following lines of code will never cause a NullPointerException:
double value = myproperties.getDoubleProperty( key, default ).doubleValue();
float value = myproperties.getDoubleProperty( key, default ).floatValue();

Parameters:

key - the name of the property to be read

defaultValue - the value to be used if the property is missing or does not represent a numeric, floating-point value

Returns:

the numeric, floating-point value of the given property

getDoubleProperty

public double getDoubleProperty(String key,
                                double defaultValue)

Parse a numeric, floating-point value from the property with given key, returning the default value if the property is missing or invalid.
If the property with given key does not exist or does not represent a valid numeric, floating-point value then the default value will be returned.

Parameters:

key - the name of the property to be read

defaultValue - the value to be used if the property is missing or does not represent a numeric, floating-point value

Returns:

the numeric, floating-point value of the given property

getDoubleProperty

public double getDoubleProperty(String key,
                                double defaultIfMissing,
                                double defaultIfInvalid)

Parse a numeric, floating-point value from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist, the defaultIfMissing value will be returned.
If the value of the property with given key does not represent a valid numeric, floating-point value then the defaultIfInvalid value is returned.

Parameters:

key - the name of the property to be read

defaultIfMissing - the value to be used if the property is missing

defaultIfInvalid - the value to be used if the property does not represent a numeric, floating-point value

Returns:

the numeric, floating-point value of the given property

setDoubleProperty

public void setDoubleProperty(String key,
                              Double value)

Assign a (floating-point) numeric value to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property

setDoubleProperty

public void setDoubleProperty(String key,
                              double value)

Assign a (floating-point) numeric value to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property

getFileProperty

public File getFileProperty(String key)
                     throws PropertyException

Parse a file reference from the property with given key.
If the property with given key does not exist an exception will be thrown.
If the value of the property with given key does not specify a valid file path then an exception will be thrown.
The return value is guaranteed non-null.

Parameters:

key - the name of the property to be read

Returns:

file reference of the location specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFileProperty

public File getFileProperty(String key,
                            File defaultIfMissing,
                            File defaultIfInvalid)
                     throws PropertyException

Parse a file reference from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.FILE_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not specify a valid file path and the defaultIfInvalid parameter is set to Properties.FILE_MUST_EXIST, an exception will be thrown.
If the value of the property with given key does not specify a valid file path and the defaultIfInvalid parameter is set to Properties.ENSURE_FILE_EXISTS, a new, empty file will be created and a reference to that new file returned.
If the value of the property with given key specifies a path to a file in a folder that does not exist and the defaultIfInvalid parameter is set to Properties.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key specifies a path to a file in a folder that does not exist and the defaultIfInvalid parameter is set to Properties.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant file (in a existant folder) will be returned.
The return value is guaranteed non-null provided neither of the defaultValues are null.

Parameters:

key - the name of the property to be read

defaultIfMissing - the file to use if the property is missing (use Properties.FILE_PARAM_MUST_EXIST to cause an exception in such a situation)

defaultIfInvalid - the file to use if the property does not specify a valid file (use Properties.FILE_MUST_EXIST to cause an exception in such a situation)

Returns:

file reference of the location specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFileProperty

public File getFileProperty(String key,
                            String defaultIfMissing,
                            File defaultIfInvalid)
                     throws PropertyException

Parse a file reference from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist the path specified by the defaultIfMissing parameter will be used in place of the property value.
If the value of the property with given key does not specify a valid file path and the defaultIfInvalid parameter is set to Properties.FILE_MUST_EXIST, an exception will be thrown.
If the value of the property with given key does not specify a valid file path and the defaultIfInvalid parameter is set to Properties.ENSURE_FILE_EXISTS, a new, empty file will be created and a reference to that new file returned.
If the value of the property with given key specifies a path to a file in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key specifies a path to a file in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant file (in an existant folder) will be returned.
The return value is guaranteed non-null provided neither of the defaultValues are null. If defaultIfInvalid is set to Properties.ENSURE_FILE_EXISTS then the return value is also guaranteed to reference a file that exists.

Parameters:

key - the name of the property to be read

defaultIfMissing - the path of the file to use if the property is missing

defaultIfInvalid - the file to use if the property does not specify a valid file (use Properties.FILE_MUST_EXIST to cause an exception in such a situation)

Returns:

reference to the file specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFileProperty

public File getFileProperty(String key,
                            File defaultValue)

Parse a file reference from the property with given key, returning the default value if the property is missing or invalid.
If the property with given key does not exist or does not specify a valid file then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null.

Parameters:

key - the name of the property to be read

defaultValue - the file to use if the property is missing or invalid

Returns:

file reference of the location specified by the given property

getFileProperty

public File getFileProperty(String key,
                            String defaultPath)

Parse a file reference from the property with given key, using the default file path if the property is missing or invalid.
If the property with given key does not exist or does not specify a valid file then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null.

Parameters:

key - the name of the property to be read

defaultPath - the file path to use if the property is missing or invalid

Returns:

file reference of the location specified by the given property

getFileProperty

public File getFileProperty(File baseFolder,
                            String key)
                     throws PropertyException

Parse a file reference from the property with given key.
The property with given key should specify the path to a file, either absolute or relative to the baseFolder.
If the property with given key does not exist an exception will be thrown.
If the value of the property with given key does not specify a valid file path then an exception will be thrown.
The return value is guaranteed non-null.

Parameters:

baseFolder - the base/parent folder to use if the file path defined by the string is relative, rather than an absolute path

key - the name of the property to be read

Returns:

file reference of the location specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFileProperty

public File getFileProperty(File baseFolder,
                            String key,
                            File defaultIfMissing,
                            File defaultIfInvalid)
                     throws PropertyException

Parse a file reference from the property with given key, returning one of the default values if the property is missing or invalid.
The property with given key should specify the path to a file, either absolute or relative to the baseFolder.
If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.FILE_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not specify a valid file path and the defaultIfInvalid parameter is set to Properties.FILE_MUST_EXIST, an exception will be thrown.
If the value of the property with given key does not specify a valid file path and the defaultIfInvalid parameter is set to Properties.ENSURE_FILE_EXISTS, a new, empty file will be created and a reference to that new file returned.
If the value of the property with given key specifies a path to a file in a folder that does not exist and the defaultIfInvalid parameter is set to Properties.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key specifies a path to a file in a folder that does not exist and the defaultIfInvalid parameter is set to Properties.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant file (in a existant folder) will be returned.
The return value is guaranteed non-null provided neither of the defaultValues are null.

Parameters:

baseFolder - the base/parent folder to use if the file path defined by the string is relative, rather than an absolute path

key - the name of the property to be read

defaultIfMissing - the file to use if the property is missing (use Properties.FILE_PARAM_MUST_EXIST to cause an exception in such a situation)

defaultIfInvalid - the file to use if the property does not specify a valid file (use Properties.FILE_MUST_EXIST to cause an exception in such a situation)

Returns:

file reference of the location specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFileProperty

public File getFileProperty(File baseFolder,
                            String key,
                            String defaultIfMissing,
                            File defaultIfInvalid)
                     throws PropertyException

Parse a file reference from the property with given key, returning one of the default values if the property is missing or invalid.
The property with given key should specify the path to a file, either absolute or relative to the baseFolder.
If the property with given key does not exist the path specified by the defaultIfMissing parameter will be used in place of the property value.
If the value of the property with given key does not specify a valid file path and the defaultIfInvalid parameter is set to Properties.FILE_MUST_EXIST, an exception will be thrown.
If the value of the property with given key does not specify a valid file path and the defaultIfInvalid parameter is set to Properties.ENSURE_FILE_EXISTS, a new, empty file will be created and a reference to that new file returned.
If the value of the property with given key specifies a path to a file in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key specifies a path to a file in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant file (in an existant folder) will be returned.
The return value is guaranteed non-null provided neither of the defaultValues are null. If defaultIfInvalid is set to Properties.ENSURE_FILE_EXISTS then the return value is also guaranteed to reference a file that exists.

Parameters:

baseFolder - the base/parent folder to use if the file path defined by the string is relative, rather than an absolute path

key - the name of the property to be read

defaultIfMissing - the path of the file to use if the property is missing

defaultIfInvalid - the file to use if the property does not specify a valid file (use Properties.FILE_MUST_EXIST to cause an exception in such a situation)

Returns:

reference to the file specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFileProperty

public File getFileProperty(File baseFolder,
                            String key,
                            File defaultValue)

Parse a file reference from the property with given key, returning the default value if the property is missing or invalid.
The property with given key should specify the path to a file, either absolute or relative to the baseFolder.
If the property with given key does not exist or does not specify a valid file then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null.

Parameters:

baseFolder - the base/parent folder to use if the file path defined by the string is relative, rather than an absolute path

key - the name of the property to be read

defaultValue - the file to use if the property is missing or invalid

Returns:

file reference of the location specified by the given property

setFileProperty

public void setFileProperty(String key,
                            File value)

Assign a file path to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property

getFolderProperty

public File getFolderProperty(String key)
                       throws PropertyException

Parse a folder reference from the property with given key.
If the property with given key does not exist an exception will be thrown.
If the value of the property with given key does not specify a valid folder path then an exception will be thrown.
The return value is guaranteed non-null. However, no guarantee is made about the existance of the folder referenced by the defaultValue. Use getFolderProperty( String key, String defaultIfMissing, File defaultIfInvalid ) and set defaultIfInvalid to Properties.ENSURE_FOLDER_EXISTS to be sure the return value references a folder that exists.

Parameters:

key - the name of the property to be read

Returns:

file reference of the location specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFolderProperty

public File getFolderProperty(String key,
                              File defaultIfMissing,
                              File defaultIfInvalid)
                       throws PropertyException

Parse a folder reference from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.FOLDER_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not specify a valid folder path and the defaultIfInvalid parameter is set to Properties.FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key does not specify a valid folder path and the defaultIfInvalid parameter is set to Properties.ENSURE_FOLDER_EXISTS, a new, empty folder will be created and a reference to that new folder returned.
If the value of the property with given key specifies a path to a folder in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key specifies a path to a folder in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant sub-folder (of an existant folder) will be returned.
The return value is guaranteed non-null provided neither of the defaultValues are null. However, no guarantee is made about the existance of the folder referenced by the defaultValue. Use getFolderProperty( String key, String defaultIfMissing, File defaultIfInvalid ) and set defaultIfInvalid to Properties.ENSURE_FOLDER_EXISTS to be sure the return value references a folder that exists.

Parameters:

key - the name of the property to be read

defaultIfMissing - the folder to use if the property is missing (use Properties.FOLDER_PARAM_MUST_EXIST to cause an exception in such a situation)

defaultIfInvalid - the folder to use if the property does not specify a valid folder (use Properties.FOLDER_MUST_EXIST to cause an exception in such a situation)

Returns:

file reference of the folder specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFolderProperty

public File getFolderProperty(String key,
                              String defaultIfMissing,
                              File defaultIfInvalid)
                       throws PropertyException

Parse a folder reference from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist the path specified by the defaultIfMissing parameter will be used in place of the property value.
If the value of the property with given key does not specify a valid folder path and the defaultIfInvalid parameter is set to Properties.FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key does not specify a valid folder path and the defaultIfInvalid parameter is set to Properties.ENSURE_FOLDER_EXISTS, a new, empty folder will be created and a reference to that new folder returned.
If the value of the property with given key specifies a path to a folder in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key specifies a path to a folder in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant sub-folder (of an existant folder) will be returned.
The return value is guaranteed non-null provided neither of the defaultValues are null. If defaultIfInvalid is set to Properties.ENSURE_FOLDER_EXISTS then the return value is also guaranteed to reference a folder that exists.

Parameters:

key - the name of the property to be read

defaultIfMissing - the path of the folder to use if the property is missing

defaultIfInvalid - the folder to use if the property does not specify a valid folder (use Properties.FOLDER_MUST_EXIST to cause an exception in such a situation)

Returns:

file reference of the folder specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFolderProperty

public File getFolderProperty(String key,
                              File defaultValue)

Parse a folder reference from the property with given key, returning the default value if the property is missing or invalid.
If the property with given key does not exist or does not specify a valid folder then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null. However, no guarantee is made about the existance of the folder referenced by the defaultValue. Use getFolderProperty( String key, String defaultIfMissing, File defaultIfInvalid ) and set defaultIfInvalid to Properties.ENSURE_FOLDER_EXISTS to be sure the return value references a folder that exists.

Parameters:

key - the name of the property to be read

defaultValue - the folder to use if the property is missing or invalid

Returns:

file reference of the folder location specified by the given property

getFolderProperty

public File getFolderProperty(File baseFolder,
                              String key)
                       throws PropertyException

Parse a folder reference from the property with given key.
The property with given key should specify the path to a folder, either absolute or relative to the baseFolder.
If the property with given key does not exist an exception will be thrown.
If the value of the property with given key does not specify a valid folder path then an exception will be thrown.
The return value is guaranteed non-null. However, no guarantee is made about the existance of the folder referenced by the defaultValue. Use getFolderProperty( File baseFolder, String key, String defaultIfMissing, File defaultIfInvalid ) and set defaultIfInvalid to Properties.ENSURE_FOLDER_EXISTS to be sure the return value references a folder that exists.

Parameters:

baseFolder - the base/parent folder to use if the folder path defined by the string is relative, rather than an absolute path

key - the name of the property to be read

Returns:

file reference of the folder location specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFolderProperty

public File getFolderProperty(File baseFolder,
                              String key,
                              File defaultIfMissing,
                              File defaultIfInvalid)
                       throws PropertyException

Parse a folder reference from the property with given key, returning one of the default values if the property is missing or invalid.
The property with given key should specify the path to a folder, either absolute or relative to the baseFolder.
If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.FOLDER_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not specify a valid folder path and the defaultIfInvalid parameter is set to Properties.FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key does not specify a valid folder path and the defaultIfInvalid parameter is set to Properties.ENSURE_FOLDER_EXISTS, a new, empty folder will be created and a reference to that new folder returned.
If the value of the property with given key specifies a path to a folder in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key specifies a path to a folder in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant sub-folder (of an existant folder) will be returned.
The return value is guaranteed non-null provided neither of the defaultValues are null. However, no guarantee is made about the existance of the folder referenced by the defaultValue. Use getFolderProperty( File baseFolder, String key, String defaultIfMissing, File defaultIfInvalid ) and set defaultIfInvalid to Properties.ENSURE_FOLDER_EXISTS to be sure the return value references a folder that exists.

Parameters:

baseFolder - the base/parent folder to use if the folder path defined by the string is relative, rather than an absolute path

key - the name of the property to be read

defaultIfMissing - the folder to use if the property is missing (use Properties.FOLDER_PARAM_MUST_EXIST to cause an exception in such a situation)

defaultIfInvalid - the folder to use if the property does not specify a valid folder (use Properties.FOLDER_MUST_EXIST to cause an exception in such a situation)

Returns:

file reference of the folder specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFolderProperty

public File getFolderProperty(File baseFolder,
                              String key,
                              String defaultIfMissing,
                              File defaultIfInvalid)
                       throws PropertyException

Parse a folder reference from the property with given key, returning one of the default values if the property is missing or invalid.
The property with given key should specify the path to a folder, either absolute or relative to the baseFolder.
If the property with given key does not exist, the path specified by the defaultIfMissing parameter will be used in place of the property value.
If the value of the property with given key does not specify a valid folder path and the defaultIfInvalid parameter is set to Properties.FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key does not specify a valid folder path and the defaultIfInvalid parameter is set to Properties.ENSURE_FOLDER_EXISTS, a new, empty folder will be created and a reference to that new folder returned.
If the value of the property with given key specifies a path to a folder in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.PARENT_FOLDER_MUST_EXIST, an exception will be thrown.
If the value of the property with given key specifies a path to a folder in a parent folder that does not exist and the defaultIfInvalid parameter is set to Properties.ENSURE_PARENT_FOLDER_EXISTS, the parent folder will be created and a reference to an inexistant sub-folder (of an existant folder) will be returned.
The return value is guaranteed non-null provided neither of the defaultValues are null. If defaultIfInvalid is set to Properties.ENSURE_FOLDER_EXISTS then the return value is also guaranteed to reference a folder that exists.

Parameters:

baseFolder - the base/parent folder to use if the folder path defined by the string is relative, rather than an absolute path

key - the name of the property to be read

defaultIfMissing - the path of the folder to use if the property is missing

defaultIfInvalid - the folder to use if the property does not specify a valid folder (use Properties.FOLDER_MUST_EXIST to cause an exception in such a situation)

Returns:

file reference of the folder specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getFolderProperty

public File getFolderProperty(File baseFolder,
                              String key,
                              File defaultValue)

Parse a folder reference from the property with given key, returning the default value if the property is missing or invalid.
The property with given key should specify the path to a folder, either absolute or relative to the baseFolder.
If the property with given key does not exist or does not specify a valid folder then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null. However, no guarantee is made about the existance of the folder referenced by the defaultValue. Use getFolderProperty( File baseFolder, String key, String defaultIfMissing, File defaultIfInvalid ) and set defaultIfInvalid to Properties.ENSURE_FOLDER_EXISTS to be sure the return value references a folder that exists.

Parameters:

baseFolder - the base/parent folder to use if the folder path defined by the string is relative, rather than an absolute path

key - the name of the property to be read

defaultValue - the folder to use if the property is missing or invalid

Returns:

file reference of the folder location specified by the given property

setFolderProperty

public void setFolderProperty(String key,
                              File value)

Assign a folder path to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property

getClassProperty

public Class getClassProperty(String key)
                       throws PropertyException

Parse a Java class from the property with given key.
If the property with given key does not exist an exception will be thrown.
If the value of the property with given key does not specify a valid class path then an exception will be thrown.
The return value is guaranteed non-null.

Parameters:

key - the name of the property to be read

Returns:

the Java class specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getClassProperty

public Class getClassProperty(String key,
                              Class defaultIfMissing,
                              Class defaultIfInvalid)
                       throws PropertyException

Parse a Java class from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.CLASS_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not specify a valid class path and the defaultIfInvalid parameter is set to Properties.CLASS_MUST_EXIST, an exception will be thrown.
The return value is guaranteed non-null provided neither of the defaultValues are null.

Parameters:

key - the name of the property to be read

defaultIfMissing - the class to use if the property is missing (use Properties.CLASS_PARAM_MUST_EXIST to cause an exception in such a situation)

defaultIfInvalid - the class to use if the property does not specify a valid Java class (use Properties.CLASS_MUST_BE_VALID to cause an exception in such a situation)

Returns:

the Java class specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getClassProperty

public Class getClassProperty(String key,
                              Class defaultValue)

Parse a Java class from the property with given key, returning the default value if the property is missing or invalid.
If the property with given key does not exist or does not specify a valid folder then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null.

Parameters:

key - the name of the property to be read

defaultValue - the class to use if the property is missing or invalid

Returns:

the Java class specified by the given property

getClassProperty

public Class getClassProperty(String key,
                              String basePackage)
                       throws PropertyException

Parse a Java class from the property with given key.
The property with given key should specify the path of a class, either absolute or relative to the basePackage.
If the property with given key does not exist an exception will be thrown.
If the value of the property with given key does not specify a valid folder path then an exception will be thrown.
The return value is guaranteed non-null.

Parameters:

key - the name of the property to be read

basePackage - the base package path to use if the class name defined by the parameter is not an absolute path

Returns:

the Java class specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getClassProperty

public Class getClassProperty(String key,
                              String basePackage,
                              Class defaultIfMissing,
                              Class defaultIfInvalid)
                       throws PropertyException

Parse a Java class from the property with given key, returning one of the default values if the property is missing or invalid.
The property with given key should specify the path of a class, either absolute or relative to the basePackage.
If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.CLASS_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not specify a valid class path and the defaultIfInvalid parameter is set to Properties.CLASS_MUST_EXIST, an exception will be thrown.
The return value is guaranteed non-null provided neither of the defaultValues are null.

Parameters:

key - the name of the property to be read

basePackage - the base package path to use if the class name defined by the parameter is not an absolute path

defaultIfMissing - the class to use if the property is missing (use Properties.CLASS_PARAM_MUST_EXIST to cause an exception in such a situation)

defaultIfInvalid - the class to use if the property does not specify a valid Java class (use Properties.CLASS_MUST_BE_VALID to cause an exception in such a situation)

Returns:

the Java class specified by the given property

Throws:

PropertyException - the property does not exist or is invalid

getClassProperty

public Class getClassProperty(String key,
                              String basePackage,
                              Class defaultValue)

Parse a Java class from the property with given key, returning the default value if the property is missing or invalid.
The property with given key should specify the path of a class, either absolute or relative to the basePackage.
If the property with given key does not exist or does not specify a valid folder then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null.

Parameters:

key - the name of the property to be read

basePackage - the base package path to use if the class name defined by the parameter is not an absolute path

defaultValue - the folder to use if the property is missing or invalid

Returns:

the Java class specified by the given property

setClassProperty

public void setClassProperty(String key,
                             Class value)

Assign the name of a Java class to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property

getEnumProperty

public EnumValue getEnumProperty(String key,
                                 Enumeration enumeration)
                          throws PropertyException

Parse an enumeration value from the property with given key.
If the property with given key does not exist an exception will be thrown.
If the value of the property with given key does not equate to any of the values in the given enumeration then an exception will be thrown.
The return value is guaranteed non-null.

Parameters:

key - the name of the property to be read

enumeration - the enumeration type

Returns:

the enumeration value, taken from the given enumeration, identified by the value of the given property

Throws:

PropertyException - the property does not exist or is invalid

getEnumProperty

public EnumValue getEnumProperty(String key,
                                 Enumeration enumeration,
                                 EnumValue defaultIfMissing,
                                 EnumValue defaultIfInvalid)
                          throws PropertyException

Parse an enumeration value from the property with given key, returning one of the default values if the property is missing or invalid.
If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.ENUM_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not equate to any of the values in the given enumeration and the defaultIfInvalid parameter is set to Properties.ENUM_VALUE_MUST_BE_VALID, an exception will be thrown.
The return value is guaranteed non-null provided neither of the defaultValues are null.

Parameters:

key - the name of the property to be read

enumeration - the enumeration type

defaultIfMissing - the enumeration value to use if the property is missing (use Properties.ENUM_PARAM_MUST_EXIST to cause an exception in such a situation)

defaultIfInvalid - the enumeration value to use if the property does not equate to one of the enumeration values (use Properties.ENUM_VALUE_MUST_BE_VALID to cause an exception in such a situation)

Returns:

the enumeration value, taken from the given enumeration, identified by the value of the given property

Throws:

PropertyException - the property does not exist or is invalid

getEnumProperty

public EnumValue getEnumProperty(String key,
                                 Enumeration enumeration,
                                 EnumValue defaultValue)

Parse an enumeration value from the property with given key, returning the default value if the property is missing or invalid.
If the value of the property with given key does not equate to any of the values in the given enumeration then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null.

Parameters:

key - the name of the property to be read

enumeration - the enumeration type

defaultValue - the enumeration value to use if the property is missing or invalid

Returns:

the enumeration value, taken from the given enumeration, identified by the value of the given property

setEnumProperty

public void setEnumProperty(String key,
                            EnumValue value)

Assign an enumeration value to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property

getColorProperty

public Color getColorProperty(String key)
                       throws PropertyException

Parse a Color from the property with given key.

The property value should specify a colour in either:
• decimal format: "[AAA] RRR GGG BBB" where AAA, RRR, GGG and BBB are 16-bit decimal values (0-255) for the alpha, red, green and blue components of the colour (alpha optional) each separated by one or more whitespace characters
• hexadecimal format: "#[AA]RRGGBB" where AA, RR, GG and BB are 16-bit hex values for the alpha, red, green and blue components of the colour (alpha optional)
• equivalent decimal value: a single decimal value that equates to a hexadecimal value in "#[AA]RRGGBB" format

If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.COLOR_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not conform to any of the above formats and the defaultIfInvalid parameter is set to Properties.COLOR_VALUE_MUST_BE_VALID, an exception will be thrown.

If the property with given key does not exist an exception will be thrown.
If the value of the property with given key does not equate to any of the values in the given enumeration then an exception will be thrown.
The return value is guaranteed non-null.

Parameters:

key - the name of the property to be read

Returns:

a Color object for the color specified by the property value

Throws:

PropertyException - the property does not exist or is invalid

getColorProperty

public Color getColorProperty(String key,
                              Color defaultIfMissing,
                              Color defaultIfInvalid)
                       throws PropertyException

Parse a Color from the property with given key, returning one of the default values if the property is missing or invalid.

The property value should specify a colour in either:
• decimal format: "[AAA] RRR GGG BBB" where AAA, RRR, GGG and BBB are 16-bit decimal values (0-255) for the alpha, red, green and blue components of the colour (alpha optional) each separated by one or more whitespace characters
• hexadecimal format: "#[AA]RRGGBB" where AA, RR, GG and BB are 16-bit hex values for the alpha, red, green and blue components of the colour (alpha optional)
• equivalent decimal value: a single decimal value that equates to a hexadecimal value in "#[AA]RRGGBB" format

If the property with given key does not exist and the defaultIfMissing parameter is set to Properties.COLOR_PARAM_MUST_EXIST then an exception will be thrown. Otherwise the defaultIfMissing value is returned.
If the value of the property with given key does not conform to any of the above formats and the defaultIfInvalid parameter is set to Properties.COLOR_VALUE_MUST_BE_VALID, an exception will be thrown.
The return value is guaranteed non-null provided neither of the defaultValues are null.

Parameters:

key - the name of the property to be read

defaultIfMissing - the value to use if the property is missing (use Properties.ENUM_PARAM_MUST_EXIST to cause an exception in such a situation)

defaultIfInvalid - the value to use if the property does not equate to one of the enumeration values (use Properties.ENUM_VALUE_MUST_BE_VALID to cause an exception in such a situation)

Returns:

a Color object for the color specified by the property value, or the default value if the property value is invalid

Throws:

PropertyException - the property does not exist or is invalid

getColorProperty

public Color getColorProperty(String key,
                              Color defaultValue)

Parse a Color from the property with given key, returning the default value if the property is missing or invalid.

The property value should specify a colour in either:
• decimal format: "[AAA] RRR GGG BBB" where AAA, RRR, GGG and BBB are 16-bit decimal values (0-255) for the alpha, red, green and blue components of the colour (alpha optional) each separated by one or more whitespace characters
• hexadecimal format: "#[AA]RRGGBB" where AA, RR, GG and BB are 16-bit hex values for the alpha, red, green and blue components of the colour (alpha optional)
• equivalent decimal value: a single decimal value that equates to a hexadecimal value in "#[AA]RRGGBB" format

If the value of the property with given key does not conform to any of the above formats then the default value will be returned.
The return value is guaranteed non-null provided the defaultValue is not null.

Parameters:

key - the name of the property to be read

defaultValue - the value to use if the property is missing or invalid

Returns:

a Color object for the color specified by the property value, or the default value if the property value is invalid

setColorProperty

public void setColorProperty(String key,
                             Color value)

Assign a color value to a given property.

Parameters:

key - the name of the property to be stored

value - the new value of the property