Package ec.util

Class ParameterDatabase

java.lang.Object

ec.util.ParameterDatabase

All Implemented Interfaces:

Serializable

public class ParameterDatabase
extends Object
implements Serializable

This extension of the Properties class allows you to set, get, and delete Parameters in a hierarchical tree-like database. The database consists of a list of Parameters, plus an array of "parent databases" which it falls back on when it can't find the Parameter you're looking for. Parents may also have arrays of parents, and so on..

The parameters are loaded from a Java property-list file, which is basically a collection of parameter=value pairs, one per line. Empty lines and lines beginning with # are ignored. These parameters and their values are case-sensitive , and whitespace is trimmed I believe.

An optional set of parameters, "parent. n ", where n are consecutive integers starting at 0, define the filenames of the database's parents.

An optional set of parameters, "print-params", specifies whether or not parameters should be printed as they are used (through one of the get(...) methods). If print-params is unset, or set to false or FALSE, nothing is printed. If set to non-false, then the parameters are printed prepended with a "P:" when their values are requested, "E:" when their existence is tested. Prior to the "P:" or "E:" you may see a "!" (meaning that the parameter isn't in the database), or a "<" (meaning that the parameter was a default parameter which was never looked up because the primary parameter contained the value).

When you create a ParameterDatabase using new ParameterDatabase(), it is created thus:

DATABASE:	database
FROM:	(empty)

When you create a ParameterDatabase using new ParameterDatabase( file ), it is created by loading the database file, and its parent file tree, thus:

DATABASE:	database	->	parent0	+->	parent0	+->	parent0	+->	....
FROM:	(empty)		(file)	|	(parent.0)	|	(parent.0)		....
				|		+->	parent1	+->	....
				|		|	(parent.1)
				|		....
				|
				+->	parent1	+->	....
				|	(parent.1)
				....

When you create a ParameterDatabase using new ParameterDatabase( file,argv ), the preferred way, it is created thus:

DATABASE:	database	->	parent0	+->	parent0	+->	parent0	+->	parent0	+->	....
FROM:	(empty)		(argv)		(file)	|	(parent.0)	|	(parent.0)		....
						|		+->	parent1	+->	....
						|		|	(parent.1)
						|		....
						|
						+->	parent1	+->	....
						|	(parent.1)
						....

...that is, the actual top database is empty, and stores parameters added programmatically; its parent is a database formed from arguments passed in on the command line; its parent is the parameter database which actually loads from foo. This allows you to programmatically add parameters which override those in foo, then delete them, thus bringing foo's parameters back in view.

Once a parameter database is loaded, you query it with the get methods. The database, then its parents, are searched until a match is found for your parameter. The search rules are thus: (1) the root database is searched first. (2) If a database being searched doesn't contain the data, it searches its parents recursively, starting with parent 0, then moving up, until all searches are exhausted or something was found. (3) No database is searched twice.

The various get methods all take two parameters. The first parameter is fetched and retrieved first. If that fails, the second one (known as the default parameter) is fetched and retrieved. You can pass in null for the default parameter if you don't have one.

You can test a parameter for existence with the exists methods.

You can set a parameter (in the topmost database only with the set command. The remove command removes a parameter from the topmost database only. The removeDeeply command removes that parameter from every database.

The values stored in a parameter database must not contain "#", "=", non-ascii values, or whitespace.

The get... methods can also handle special macro parameters. Macro parameter names will end in default or alias, which means you cannot have any parameter names which end with these two words. The idea behind a macro parameter is that it can substitute one substring for another among your parameter names, making your parameters potentially much simpler. Macros work along period boundaries.

The alias parameter macro works as follows. A parameter entry of the form:

hello.there.alias = foo

Means that parameters which start with hello.there should have the hello.there portion replace with foo. Thus

hello.there.mom.how.are.you

... becomes ...

foo.mom.how.are.you

and

hello.there

... becomes ...

foo

but hello.thereyo is unchanged, and yohello.there.how.are.you is unchanged.

Furthermore if you already have a parameter entered for a given name, it takes precedence over a macro, and more specific macros take precedence over more general ones. Thus imagine you have a.b.alias = quux. Now when you query a.b.c.d this will get converted to quux.c.d and that parameter will get looked up instead. If you also had a.b.c.alias = bar, when when you query a.b.c.d, this takes precedence, so now it'll get converted to bar.d and that'll get looked up. Finally, if you had a.b.c.d = foo, when querying a.b.c.d will simply result in foo. Additionally there is the default macro. This works just like the alias macro except that it allows anything to be in the last parameter position prior to the default. That is:

hello.there.default = foo

Means that parameters which start with hello.* , where "*" can be any single parameter element, will have that portion replaced with foo. Thus

hello.there.mom.how.are.you

... becomes ...

foo.mom.how.are.you

and

hello.yo.whatever

... becomes ...

foo.whatever

and

hello.blah

... becomes ...

foo This second macro is particularly useful for replacing groups of parameters which differ based on some number.

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final String	C_CLASS
static final String	C_HERE
static final String	PRINT_PARAMS
int	printState
static final int	PS_NONE
static final int	PS_PRINT_PARAMS
static final int	PS_UNKNOWN
static final String	UNKNOWN_VALUE
static final String	V_ALIAS
static final String	V_DEFAULT

Constructor Summary

Constructors

Constructor	Description
ParameterDatabase()	Creates an empty parameter database.
ParameterDatabase(File file)	Creates a new parameter database tree from a given database file and its parent files.
ParameterDatabase(File file, String[] args)	Creates a new parameter database from a given database file and argv list.
ParameterDatabase(InputStream stream)	Creates a new parameter database loaded from the given stream.
ParameterDatabase(String pathNameRelativeToClassFile, Class cls)	Creates a new parameter database loaded from a parameter file located relative to a class file, wherever the class file may be (such as in a jar).
ParameterDatabase(String pathNameRelativeToClassFile, Class cls, String[] args)	Creates a new parameter database from a given database file and argv list.
ParameterDatabase(Dictionary map)	Creates a new parameter database from the given Dictionary.

Method Summary

Modifier and Type	Method	Description
void	addParent(ParameterDatabase database)
TreeModel	buildTreeModel()	Builds a TreeModel from the available property keys.
boolean	exists(Parameter parameter)	Returns true if parameter exist in the database
boolean	exists(Parameter parameter, Parameter defaultParameter)	Returns true if either parameter or defaultParameter exists in the database
boolean	getBoolean(Parameter parameter, Parameter defaultParameter, boolean defaultValue)	Searches down through databases to find a given parameter; If the parameter does not exist, defaultValue is returned.
Class	getClassForParameter(Parameter parameter, Parameter defaultParameter, Class mustCastTosuperclass)	Searches down through databases to find a given parameter.
double	getDouble(Parameter parameter, Parameter defaultParameter)
double	getDouble(Parameter parameter, Parameter defaultParameter, double minValue)	Searches down through databases to find a given parameter, whose value must be a double >= minValue.
double	getDouble(Parameter parameter, Parameter defaultParameter, double minValue, double maxValue)	Searches down through databases to find a given parameter, whose value must be a double >= minValue and invalid input: '<'= maxValue.
double[]	getDoubles(Parameter parameter, Parameter defaultParameter, double minValue)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, each of which is >= minValue, and which must be at least 1 number long.
double[]	getDoubles(Parameter parameter, Parameter defaultParameter, double minValue, int expectedLength)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, each of which is >= minValue, and which must be exactly expectedLength (> 0) long.
double[]	getDoublesUnconstrained(Parameter parameter, Parameter defaultParameter)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, and which must be at least 1 number long.
double[]	getDoublesUnconstrained(Parameter parameter, Parameter defaultParameter, int expectedLength)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, and which must be exactly expectedLength (> 0) long.
double[]	getDoublesWithMax(Parameter parameter, Parameter defaultParameter, double minValue, double maxValue)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, each of which is >= minValue and invalid input: '<'= maxValue, and which must be at least 1 number long.
double[]	getDoublesWithMax(Parameter parameter, Parameter defaultParameter, double minValue, double maxValue, int expectedLength)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, each of which is >= minValue and invalid input: '<'= maxValue, and which must be exactly expectedLength (> 0) long.
double	getDoubleWithDefault(Parameter parameter, Parameter defaultParameter, double defaultValue)	Searches down through databases to find a given parameter, which must be a float.
double	getDoubleWithMax(Parameter parameter, Parameter defaultParameter, double minValue, double maxValue)	Searches down through databases to find a given parameter, whose value must be a double >= minValue and invalid input: '<'= maxValue.
File	getFile(Parameter parameter, Parameter defaultParameter)	Searches down through the databases to find a given parameter, whose value must be an absolute or relative path name.
float	getFloat(Parameter parameter, Parameter defaultParameter)
float	getFloat(Parameter parameter, Parameter defaultParameter, double minValue)	Searches down through databases to find a given parameter, whose value must be a float >= minValue.
float	getFloat(Parameter parameter, Parameter defaultParameter, double minValue, double maxValue)	Searches down through databases to find a given parameter, whose value must be a float >= minValue and invalid input: '<'= maxValue.
float	getFloatWithDefault(Parameter parameter, Parameter defaultParameter, double defaultValue)	Searches down through databases to find a given parameter, which must be a float.
float	getFloatWithMax(Parameter parameter, Parameter defaultParameter, double minValue, double maxValue)	Searches down through databases to find a given parameter, whose value must be a float >= minValue and invalid input: '<'= maxValue.
Object	getInstanceForParameter(Parameter parameter, Parameter defaultParameter, Class mustCastTosuperclass)	Searches down through databases to find a given parameter, whose value must be a full Class name, and the class must be a descendent of but not equal to mustCastTosuperclass .
Object	getInstanceForParameterEq(Parameter parameter, Parameter defaultParameter, Class mustCastTosuperclass)	Searches down through databases to find a given parameter, whose value must be a full Class name, and the class must be a descendent, or equal to, mustCastTosuperclass .
int	getInt(Parameter parameter, Parameter defaultParameter)	Searches down through databases to find a given parameter, whose value must be an integer.
int	getInt(Parameter parameter, Parameter defaultParameter, int minValue)	Searches down through databases to find a given parameter, whose value must be an integer >= minValue.
int[]	getInts(Parameter parameter, Parameter defaultParameter, int minValue)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, each of which is >= minValue, and which must be at least 1 number long.
int[]	getInts(Parameter parameter, Parameter defaultParameter, int minValue, int expectedLength)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, each of which is >= minValue, and which must be exactly expectedLength (> 0) long.
int[]	getIntsUnconstrained(Parameter parameter, Parameter defaultParameter)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, and which must be at least 1 number long.
int[]	getIntsUnconstrained(Parameter parameter, Parameter defaultParameter, int expectedLength)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, and which must be exactly expectedLength (> 0) long.
int[]	getIntsWithMax(Parameter parameter, Parameter defaultParameter, int minValue, int maxValue)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, each of which is >= minValue and invalid input: '<'= maxValue, and which must be at least 1 number long.
int[]	getIntsWithMax(Parameter parameter, Parameter defaultParameter, int minValue, int maxValue, int expectedLength)	Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, each of which is >= minValue and invalid input: '<'= maxValue, and which must be exactly expectedLength (> 0) long.
int	getIntWithDefault(Parameter parameter, Parameter defaultParameter, int defaultValue)	Searches down through databases to find a given parameter, which must be an integer.
int	getIntWithMax(Parameter parameter, Parameter defaultParameter, int minValue, int maxValue)	Searches down through databases to find a given parameter, whose value must be an integer >= minValue and invalid input: '<'= maxValue.
String	getLabel()	Returns a String describing the location of the ParameterDatabase holding this parameter, or "" if there is none.
ParameterDatabase	getLocation(Parameter parameter)
ParameterDatabase	getLocation(String parameter)
long	getLong(Parameter parameter, Parameter defaultParameter)	Searches down through databases to find a given parameter, whose value must be a long.
long	getLong(Parameter parameter, Parameter defaultParameter, long minValue)	Searches down through databases to find a given parameter, whose value must be a long >= minValue.
long	getLong(Parameter parameter, Parameter defaultParameter, long minValue, long maxValue)	Use getLongWithMax(...) instead.
long	getLongWithDefault(Parameter parameter, Parameter defaultParameter, long defaultValue)	Searches down through databases to find a given parameter, which must be a long.
long	getLongWithMax(Parameter parameter, Parameter defaultParameter, long minValue, long maxValue)	Searches down through databases to find a given parameter, whose value must be a long >= minValue and = invalid input: '<' maxValue.
InputStream	getResource(Parameter parameter, Parameter defaultParameter)	Searches down through the databases to find a given parameter, whose value must be an absolute or relative path name.
Set	getShadowedValues(Parameter parameter)
String	getString(Parameter parameter, Parameter defaultParameter)	Searches down through databases to find a given parameter.
String	getStringWithDefault(Parameter parameter, Parameter defaultParameter, String defaultValue)	Searches down through databases to find a given parameter.
void	list(PrintWriter p)	Prints out all the parameters in the database, but not shadowed parameters.
void	list(PrintWriter p, boolean listShadowed)	Prints out all the parameters in the database.
void	listAccessed(PrintWriter p)	Prints out all the parameters marked as accessed ("gotten" by some getFoo(...) method), plus their values.
void	listGotten(PrintWriter p)	Prints out all the parameters marked as used, plus their values.
void	listNotAccessed(PrintWriter p)	Prints out all the parameters NOT marked as used, plus their values.
void	listNotGotten(PrintWriter p)	Prints out all the parameters NOT marked as used, plus their values.
static void	main(String[] args)	Test the ParameterDatabase
void	prependParent(ParameterDatabase database)
void	remove(Parameter parameter)	Removes a parameter from the topmost database.
void	removeDeeply(Parameter parameter)
void	set(Parameter parameter, String value)	Sets a parameter in the topmost database to a given value, trimmed of whitespace.
String	toString()

Methods inherited from class java.lang.Object

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

Field Details

C_HERE

public static final String C_HERE

See Also:

• Constant Field Values

C_CLASS

public static final String C_CLASS

See Also:

• Constant Field Values

V_ALIAS

public static final String V_ALIAS

See Also:

• Constant Field Values

V_DEFAULT

public static final String V_DEFAULT

See Also:

• Constant Field Values

UNKNOWN_VALUE

public static final String UNKNOWN_VALUE

See Also:

• Constant Field Values

PRINT_PARAMS

public static final String PRINT_PARAMS

See Also:

• Constant Field Values

PS_UNKNOWN

public static final int PS_UNKNOWN

See Also:

• Constant Field Values

PS_NONE

public static final int PS_NONE

See Also:

• Constant Field Values

PS_PRINT_PARAMS

public static final int PS_PRINT_PARAMS

See Also:

• Constant Field Values

printState

public int printState

Constructor Details

ParameterDatabase

public ParameterDatabase()

Creates an empty parameter database.

ParameterDatabase

public ParameterDatabase(Dictionary map)
                  throws FileNotFoundException,
IOException

Creates a new parameter database from the given Dictionary. Both the keys and values will be run through toString() before adding to the dataase. Keys are parameters. Values are the values of the parameters. Beware that a ParameterDatabase is itself a Dictionary; but if you pass one in here you will only get the lowest-level elements. If parent.n are defined, parents will be attempted to be loaded -- that's the reason for the FileNotFoundException and IOException.

Throws:

FileNotFoundException

IOException

ParameterDatabase

public ParameterDatabase(String pathNameRelativeToClassFile,
 Class cls,
 String[] args)
                  throws FileNotFoundException,
IOException

Creates a new parameter database from a given database file and argv list. The top-level database is completely empty, pointing to a second database which contains the parameter entries stored in args, which points to a tree of databases constructed using ParameterDatabase(filename).

Throws:

FileNotFoundException

IOException

ParameterDatabase

public ParameterDatabase(String pathNameRelativeToClassFile,
 Class cls)
                  throws FileNotFoundException,
IOException

Creates a new parameter database loaded from a parameter file located relative to a class file, wherever the class file may be (such as in a jar). This approach uses resourceLocation.getResourceAsStream() to load the parameter file. If parent.n are defined, parents will be attempted to be loaded -- that's the reason for the FileNotFoundException and IOException.

Throws:

FileNotFoundException

IOException

ParameterDatabase

public ParameterDatabase(InputStream stream)
                  throws FileNotFoundException,
IOException

Creates a new parameter database loaded from the given stream. Non-relative parents are not permitted. If parent.n are defined, parents will be attempted to be loaded -- that's the reason for the FileNotFoundException and IOException.

Throws:

FileNotFoundException

IOException

ParameterDatabase

public ParameterDatabase(File file)
                  throws FileNotFoundException,
IOException

Creates a new parameter database tree from a given database file and its parent files.

Throws:

FileNotFoundException

IOException

ParameterDatabase

public ParameterDatabase(File file,
 String[] args)
                  throws FileNotFoundException,
IOException

Creates a new parameter database from a given database file and argv list. The top-level database is completely empty, pointing to a second database which contains the parameter entries stored in args, which points to a tree of databases constructed using ParameterDatabase(file).

Throws:

FileNotFoundException

IOException

Method Details

getInstanceForParameter

public Object getInstanceForParameter(Parameter parameter,
 Parameter defaultParameter,
 Class mustCastTosuperclass)
                               throws ParamClassLoadException

Searches down through databases to find a given parameter, whose value must be a full Class name, and the class must be a descendent of but not equal to mustCastTosuperclass . Loads the class and returns an instance (constructed with the default constructor), or throws a ParamClassLoadException if there is no such Class. If the parameter is not found, the defaultParameter is used. The parameter chosen is marked "used".

Throws:

ParamClassLoadException

getInstanceForParameterEq

public Object getInstanceForParameterEq(Parameter parameter,
 Parameter defaultParameter,
 Class mustCastTosuperclass)
                                 throws ParamClassLoadException

Searches down through databases to find a given parameter, whose value must be a full Class name, and the class must be a descendent, or equal to, mustCastTosuperclass . Loads the class and returns an instance (constructed with the default constructor), or throws a ParamClassLoadException if there is no such Class. The parameter chosen is marked "used".

Throws:

ParamClassLoadException

getClassForParameter

public Class getClassForParameter(Parameter parameter,
 Parameter defaultParameter,
 Class mustCastTosuperclass)
                           throws ParamClassLoadException

Searches down through databases to find a given parameter. The value associated with this parameter must be a full Class name, and the class must be a descendent of but not equal to mustCastTosuperclass . Loads and returns the associated Class, or throws a ParamClassLoadException if there is no such Class. If the parameter is not found, the defaultParameter is used. The parameter chosen is marked "used".

Throws:

ParamClassLoadException

getBoolean

public boolean getBoolean(Parameter parameter,
 Parameter defaultParameter,
 boolean defaultValue)

Searches down through databases to find a given parameter; If the parameter does not exist, defaultValue is returned. If the parameter exists, and it is set to "false" (case insensitive), false is returned. Else true is returned. The parameter chosen is marked "used" if it exists.

getInt

public int getInt(Parameter parameter,
 Parameter defaultParameter)
           throws NumberFormatException

Searches down through databases to find a given parameter, whose value must be an integer. It returns the value, else throws a NumberFormatException exception if there is an error in parsing the parameter. The parameter chosen is marked "used" if it exists. Integers may be in decimal or (if preceded with an X or x) in hexadecimal.

Throws:

NumberFormatException

getInt

public int getInt(Parameter parameter,
 Parameter defaultParameter,
 int minValue)

Searches down through databases to find a given parameter, whose value must be an integer >= minValue. It returns the value, or minValue-1 if the value is out of range or if there is an error in parsing the parameter. The parameter chosen is marked "used" if it exists. Integers may be in decimal or (if preceded with an X or x) in hexadecimal.

getIntWithDefault

public int getIntWithDefault(Parameter parameter,
 Parameter defaultParameter,
 int defaultValue)

Searches down through databases to find a given parameter, which must be an integer. If there is an error in parsing the parameter, then default is returned. The parameter chosen is marked "used" if it exists. Integers may be in decimal or (if preceded with an X or x) in hexadecimal.

getIntWithMax

public int getIntWithMax(Parameter parameter,
 Parameter defaultParameter,
 int minValue,
 int maxValue)

Searches down through databases to find a given parameter, whose value must be an integer >= minValue and invalid input: '<'= maxValue. It returns the value, or minValue-1 if the value is out of range or if there is an error in parsing the parameter. The parameter chosen is marked "used" if it exists. Integers may be in decimal or (if preceded with an X or x) in hexadecimal.

getFloat

public float getFloat(Parameter parameter,
 Parameter defaultParameter)
               throws NumberFormatException

Throws:

NumberFormatException

getFloat

public float getFloat(Parameter parameter,
 Parameter defaultParameter,
 double minValue)

Searches down through databases to find a given parameter, whose value must be a float >= minValue. If not, this method returns minvalue-1, else it returns the parameter value. The parameter chosen is marked "used" if it exists.

getFloatWithDefault

public float getFloatWithDefault(Parameter parameter,
 Parameter defaultParameter,
 double defaultValue)

Searches down through databases to find a given parameter, which must be a float. If there is an error in parsing the parameter, then default is returned. The parameter chosen is marked "used" if it exists.

getFloatWithMax

public float getFloatWithMax(Parameter parameter,
 Parameter defaultParameter,
 double minValue,
 double maxValue)

Searches down through databases to find a given parameter, whose value must be a float >= minValue and invalid input: '<'= maxValue. If not, this method returns minvalue-1, else it returns the parameter value. The parameter chosen is marked "used" if it exists.

getFloat

public float getFloat(Parameter parameter,
 Parameter defaultParameter,
 double minValue,
 double maxValue)

Searches down through databases to find a given parameter, whose value must be a float >= minValue and invalid input: '<'= maxValue. If not, this method returns minvalue-1, else it returns the parameter value. The parameter chosen is marked "used" if it exists.

getDouble

public double getDouble(Parameter parameter,
 Parameter defaultParameter)
                 throws NumberFormatException

Throws:

NumberFormatException

getDouble

public double getDouble(Parameter parameter,
 Parameter defaultParameter,
 double minValue)

Searches down through databases to find a given parameter, whose value must be a double >= minValue. If not, this method returns minvalue-1, else it returns the parameter value. The parameter chosen is marked "used" if it exists.

getDoubleWithMax

public double getDoubleWithMax(Parameter parameter,
 Parameter defaultParameter,
 double minValue,
 double maxValue)

Searches down through databases to find a given parameter, whose value must be a double >= minValue and invalid input: '<'= maxValue. If not, this method returns minvalue-1, else it returns the parameter value. The parameter chosen is marked "used" if it exists.

getDouble

public double getDouble(Parameter parameter,
 Parameter defaultParameter,
 double minValue,
 double maxValue)

Searches down through databases to find a given parameter, whose value must be a double >= minValue and invalid input: '<'= maxValue. If not, this method returns minvalue-1, else it returns the parameter value. The parameter chosen is marked "used" if it exists.

getDoubleWithDefault

public double getDoubleWithDefault(Parameter parameter,
 Parameter defaultParameter,
 double defaultValue)

Searches down through databases to find a given parameter, which must be a float. If there is an error in parsing the parameter, then default is returned. The parameter chosen is marked "used" if it exists.

getDoublesWithMax

public double[] getDoublesWithMax(Parameter parameter,
 Parameter defaultParameter,
 double minValue,
 double maxValue,
 int expectedLength)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, each of which is >= minValue and invalid input: '<'= maxValue, and which must be exactly expectedLength (> 0) long. If the parameter does not exist, or any of its doubles are out of bounds, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the doubles in question. The doubles may not be NaN. The parameter chosen is marked "used" if it exists.

getDoublesWithMax

public double[] getDoublesWithMax(Parameter parameter,
 Parameter defaultParameter,
 double minValue,
 double maxValue)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, each of which is >= minValue and invalid input: '<'= maxValue, and which must be at least 1 number long. If the parameter does not exist, or any of its doubles are out of bounds, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the doubles in question. The doubles may not be NaN. The parameter chosen is marked "used" if it exists.

getDoubles

public double[] getDoubles(Parameter parameter,
 Parameter defaultParameter,
 double minValue,
 int expectedLength)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, each of which is >= minValue, and which must be exactly expectedLength (> 0) long. If the parameter does not exist, or any of its doubles are out of bounds, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the doubles in question. The doubles may not be NaN. The parameter chosen is marked "used" if it exists.

getDoubles

public double[] getDoubles(Parameter parameter,
 Parameter defaultParameter,
 double minValue)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, each of which is >= minValue, and which must be at least 1 number long. If the parameter does not exist, or any of its doubles are out of bounds, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the doubles in question. The doubles may not be NaN. The parameter chosen is marked "used" if it exists.

getDoublesUnconstrained

public double[] getDoublesUnconstrained(Parameter parameter,
 Parameter defaultParameter,
 int expectedLength)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, and which must be exactly expectedLength (> 0) long. If the parameter does not exist, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the doubles in question. The doubles may not be NaN. The parameter chosen is marked "used" if it exists.

getDoublesUnconstrained

public double[] getDoublesUnconstrained(Parameter parameter,
 Parameter defaultParameter)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of doubles, and which must be at least 1 number long. If the parameter does not exist, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the doubles in question. The doubles may not be NaN. The parameter chosen is marked "used" if it exists.

getIntsWithMax

public int[] getIntsWithMax(Parameter parameter,
 Parameter defaultParameter,
 int minValue,
 int maxValue,
 int expectedLength)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, each of which is >= minValue and invalid input: '<'= maxValue, and which must be exactly expectedLength (> 0) long. If the parameter does not exist, or any of its ints are out of bounds, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the ints in question. The parameter chosen is marked "used" if it exists.

getIntsWithMax

public int[] getIntsWithMax(Parameter parameter,
 Parameter defaultParameter,
 int minValue,
 int maxValue)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, each of which is >= minValue and invalid input: '<'= maxValue, and which must be at least 1 number long. If the parameter does not exist, or any of its ints are out of bounds, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the ints in question. The parameter chosen is marked "used" if it exists.

getInts

public int[] getInts(Parameter parameter,
 Parameter defaultParameter,
 int minValue,
 int expectedLength)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, each of which is >= minValue, and which must be exactly expectedLength (> 0) long. If the parameter does not exist, or any of its ints are out of bounds, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the ints in question. The parameter chosen is marked "used" if it exists.

getInts

public int[] getInts(Parameter parameter,
 Parameter defaultParameter,
 int minValue)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, each of which is >= minValue, and which must be at least 1 number long. If the parameter does not exist, or any of its ints are out of bounds, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the ints in question. The parameter chosen is marked "used" if it exists.

getIntsUnconstrained

public int[] getIntsUnconstrained(Parameter parameter,
 Parameter defaultParameter,
 int expectedLength)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, and which must be exactly expectedLength (> 0) long. If the parameter does not exist, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the ints in question. The parameter chosen is marked "used" if it exists.

getIntsUnconstrained

public int[] getIntsUnconstrained(Parameter parameter,
 Parameter defaultParameter)

Searches down through databases to find a given parameter, whose value must be a space- or tab-delimited list of ints, and which must be at least 1 number long. If the parameter does not exist, or the list is not long enough or is too long or has garbage at the end of it, then this method returns null. Otherwise the method returns the ints in question. The parameter chosen is marked "used" if it exists.

getLong

public long getLong(Parameter parameter,
 Parameter defaultParameter)
             throws NumberFormatException

Searches down through databases to find a given parameter, whose value must be a long. It returns the value, else throws a NumberFormatException exception if there is an error in parsing the parameter. The parameter chosen is marked "used" if it exists. Longs may be in decimal or (if preceded with an X or x) in hexadecimal.

Throws:

NumberFormatException

getLong

public long getLong(Parameter parameter,
 Parameter defaultParameter,
 long minValue)

Searches down through databases to find a given parameter, whose value must be a long >= minValue. If not, this method returns errValue, else it returns the parameter value. The parameter chosen is marked "used" if it exists. Longs may be in decimal or (if preceded with an X or x) in hexadecimal.

getLongWithDefault

public long getLongWithDefault(Parameter parameter,
 Parameter defaultParameter,
 long defaultValue)

Searches down through databases to find a given parameter, which must be a long. If there is an error in parsing the parameter, then default is returned. The parameter chosen is marked "used" if it exists. Longs may be in decimal or (if preceded with an X or x) in hexadecimal.

getLongWithMax

public long getLongWithMax(Parameter parameter,
 Parameter defaultParameter,
 long minValue,
 long maxValue)

Searches down through databases to find a given parameter, whose value must be a long >= minValue and = invalid input: '<' maxValue. If not, this method returns errValue, else it returns the parameter value. The parameter chosen is marked "used" if it exists. Longs may be in decimal or (if preceded with an X or x) in hexadecimal.

getLong

public long getLong(Parameter parameter,
 Parameter defaultParameter,
 long minValue,
 long maxValue)

Use getLongWithMax(...) instead. Searches down through databases to find a given parameter, whose value must be a long >= minValue and = invalid input: '<' maxValue. If not, this method returns errValue, else it returns the parameter value. The parameter chosen is marked "used" if it exists. Longs may be in decimal or (if preceded with an X or x) in hexadecimal.

getFile

public File getFile(Parameter parameter,
 Parameter defaultParameter)

Searches down through the databases to find a given parameter, whose value must be an absolute or relative path name. If it is absolute, a File is made based on the path name. If it is relative, a file is made by resolving the path name with respect to the directory in which the file was which defined this ParameterDatabase in the ParameterDatabase hierarchy. If the parameter is not found, this returns null. The File is not checked for validity. The parameter chosen is marked "used" if it exists.

getResource

public InputStream getResource(Parameter parameter,
 Parameter defaultParameter)

Searches down through the databases to find a given parameter, whose value must be an absolute or relative path name. If it is absolute, a file is made based on the path name, and an InputStream is opened on the file and returned. If the path name begins with "$", then an InputStream is opened on a file relative to the directory where the system was started. Otherwise if the path name is relative, an InputStream is made by resolving the path name with respect to the directory in which the file was which defined this ParameterDatabase in the ParameterDatabase hierarchy, be it in the file system or in a jar file. If the parameter is not found, this returns null. If no such file exists, null is also returned. The parameter chosen is marked "used" if it exists.

getString

public String getString(Parameter parameter,
 Parameter defaultParameter)

Searches down through databases to find a given parameter. Returns the parameter's value (trimmed) or null if not found or if the trimmed result is empty. The parameter chosen is marked "used" if it exists.

getStringWithDefault

public String getStringWithDefault(Parameter parameter,
 Parameter defaultParameter,
 String defaultValue)

Searches down through databases to find a given parameter. Returns the parameter's value trimmed of whitespace, or defaultValue.trim() if the result is not found or the trimmed result is empty.

set

public void set(Parameter parameter,
 String value)

Sets a parameter in the topmost database to a given value, trimmed of whitespace.

listGotten

public void listGotten(PrintWriter p)

Prints out all the parameters marked as used, plus their values. If a parameter was listed as "used" but not's actually in the database, the value printed is UNKNOWN_VALUE (set to "?????")

listNotGotten

public void listNotGotten(PrintWriter p)

Prints out all the parameters NOT marked as used, plus their values.

listNotAccessed

public void listNotAccessed(PrintWriter p)

Prints out all the parameters NOT marked as used, plus their values.

listAccessed

public void listAccessed(PrintWriter p)

Prints out all the parameters marked as accessed ("gotten" by some getFoo(...) method), plus their values. If this method ever prints UNKNOWN_VALUE ("?????"), that's a bug.

exists

public boolean exists(Parameter parameter)

Returns true if parameter exist in the database

exists

public boolean exists(Parameter parameter,
 Parameter defaultParameter)

Returns true if either parameter or defaultParameter exists in the database

getLocation

public ParameterDatabase getLocation(Parameter parameter)

getLocation

public ParameterDatabase getLocation(String parameter)

getShadowedValues

public Set getShadowedValues(Parameter parameter)

getLabel

public String getLabel()

Returns a String describing the location of the ParameterDatabase holding this parameter, or "" if there is none.

remove

public void remove(Parameter parameter)

Removes a parameter from the topmost database.

removeDeeply

public void removeDeeply(Parameter parameter)

prependParent

public void prependParent(ParameterDatabase database)

addParent

public void addParent(ParameterDatabase database)

list

public void list(PrintWriter p)

Prints out all the parameters in the database, but not shadowed parameters.

list

public void list(PrintWriter p,
 boolean listShadowed)

Prints out all the parameters in the database. Useful for debugging. If listShadowed is true, each parameter is printed with the parameter database it's located in. If listShadowed is false, only active parameters are listed, and they're all given in one big chunk.

toString

public String toString()

Overrides:

toString in class Object

buildTreeModel

public TreeModel buildTreeModel()

Builds a TreeModel from the available property keys.

main

public static void main(String[] args)
                 throws FileNotFoundException,
IOException

Test the ParameterDatabase

Throws:

FileNotFoundException

IOException