ec.util
Class ParameterDatabase

java.lang.Object
  |
  +--java.util.Dictionary
        |
        +--java.util.Hashtable
              |
              +--java.util.Properties
                    |
                    +--ec.util.ParameterDatabase

public final class ParameterDatabase
extends java.util.Properties
implements java.io.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.

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.

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.

Note for JDK 1.1. Finally recovering from stupendous idiocy, JDK 1.2 included parseDouble() and parseFloat() commands; now you can READ A FLOAT FROM A STRING without having to create a Float object first! Anyway, you will need to modify the getFloat() method below if you're running on JDK 1.1, but understand that large numbers of calls to the method may be inefficient. Sample JDK 1.1 code is given with those methods, but is commented out.

See Also:
Serialized Form

Field Summary
static java.lang.String C_HERE
           
static java.lang.String UNKNOWN_VALUE
           
 
Fields inherited from class java.util.Properties
defaults
 
Constructor Summary
ParameterDatabase()
          Creates an empty parameter database.
ParameterDatabase(java.io.File filename)
          Creates a new parameter database tree from a given database file and its parent files.
ParameterDatabase(java.io.File filename, java.lang.String[] args)
          Creates a new parameter database from a given database file and argv list.
 
Method Summary
 java.io.File directoryFor(Parameter parameter)
          Searches down through databases to find the directory for the database which holds a given parameter.
 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
protected  java.lang.String get(Parameter parameter)
           
 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.
 java.lang.Object getClassForParameter(Parameter parameter, Parameter defaultParameter, java.lang.Class mustCastTosuperclass)
          Searches down through databases to find a given parameter.
 java.io.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, 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 <= maxValue.
 java.lang.Object getInstanceForParameter(Parameter parameter, Parameter defaultParameter, java.lang.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.
 java.lang.Object getInstanceForParameterEq(Parameter parameter, Parameter defaultParameter, java.lang.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, int minValue)
          Searches down through databases to find a given parameter, whose value must be an integer >= minValue.
 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 <= maxValue.
 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)
          Searches down through databases to find a given parameter, whose value must be a long >= minValue and =< maxValue.
 java.lang.String getString(Parameter parameter, Parameter defaultParameter)
          Searches down through databases to find a given parameter.
 java.lang.String getStringWithDefault(Parameter parameter, Parameter defaultParameter, java.lang.String defaultValue)
          Searches down through databases to find a given parameter.
 java.lang.String getStringWithDefault(Parameter parameter, java.lang.String defaultValue)
          Searches down through databases to find a given parameter.
 void list(java.io.PrintWriter p, boolean listShadowed)
          Prints out all the parameters in the database.
 void listAccessed(java.io.PrintWriter p)
          Prints out all the parameters marked as accessed ("gotten" by some getFoo(...) method), plus their values.
 void listGotten(java.io.PrintWriter p)
          Prints out all the parameters marked as used, plus their values.
static void main(java.lang.String[] args)
          Test the ParameterDatabase
 void remove(Parameter parameter)
          Removes a parameter from the topmost database.
 void removeDeeply(Parameter parameter)
          Removes a parameter from the database and all its parent databases.
 void set(Parameter parameter, java.lang.String value)
          Sets a parameter in the topmost database to a given value, trimmed of whitespace.
 void uncheck()
          Clears the checked flag
 
Methods inherited from class java.util.Properties
getProperty, getProperty, list, list, load, propertyNames, save, setProperty, store
 
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

C_HERE

public static final java.lang.String C_HERE

UNKNOWN_VALUE

public static final java.lang.String UNKNOWN_VALUE
Constructor Detail

ParameterDatabase

public ParameterDatabase()
Creates an empty parameter database.

ParameterDatabase

public ParameterDatabase(java.io.File filename)
                  throws java.io.FileNotFoundException,
                         java.io.IOException
Creates a new parameter database tree from a given database file and its parent files.

ParameterDatabase

public ParameterDatabase(java.io.File filename,
                         java.lang.String[] args)
                  throws java.io.FileNotFoundException,
                         java.io.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).
Method Detail

getInstanceForParameter

public final java.lang.Object getInstanceForParameter(Parameter parameter,
                                                      Parameter defaultParameter,
                                                      java.lang.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".

getInstanceForParameterEq

public final java.lang.Object getInstanceForParameterEq(Parameter parameter,
                                                        Parameter defaultParameter,
                                                        java.lang.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".

getClassForParameter

public final java.lang.Object getClassForParameter(Parameter parameter,
                                                   Parameter defaultParameter,
                                                   java.lang.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".

getBoolean

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

getIntWithDefault

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

getInt

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

getIntWithMax

public final 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 <= 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.

getFloat

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

getFloat

public final 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 <= maxValue. If not, this method returns minvalue-1, else it returns the parameter value. The parameter chosen is marked "used" if it exists.

getLong

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

getLong

public final long getLong(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 =< maxValue. If not, this method returns errValue, else it returns the parameter value. The parameter chosen is marked "used" if it exists.

getFile

public final java.io.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.

getString

public final java.lang.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 final java.lang.String getStringWithDefault(Parameter parameter,
                                                   Parameter defaultParameter,
                                                   java.lang.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.

getStringWithDefault

public final java.lang.String getStringWithDefault(Parameter parameter,
                                                   java.lang.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.

uncheck

public final void uncheck()
Clears the checked flag

set

public final void set(Parameter parameter,
                      java.lang.String value)
Sets a parameter in the topmost database to a given value, trimmed of whitespace.

listGotten

public final void listGotten(java.io.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 "?????")

listAccessed

public final void listAccessed(java.io.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 final boolean exists(Parameter parameter)
Returns true if parameter exist in the database

exists

public final boolean exists(Parameter parameter,
                            Parameter defaultParameter)
Returns true if either parameter or defaultParameter exists in the database

get

protected final java.lang.String get(Parameter parameter)

directoryFor

public final java.io.File directoryFor(Parameter parameter)
Searches down through databases to find the directory for the database which holds a given parameter. Returns the directory name or null if not found.

remove

public final void remove(Parameter parameter)
Removes a parameter from the topmost database.

removeDeeply

public final void removeDeeply(Parameter parameter)
Removes a parameter from the database and all its parent databases.

list

public final void list(java.io.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.

main

public static void main(java.lang.String[] args)
                 throws java.io.FileNotFoundException,
                        java.io.IOException
Test the ParameterDatabase