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.
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. @author Sean Luke @version 1.0
| |