bcds.tools
Class Environ

java.lang.Object
  bcds.tools.Environ

Direct Known Subclasses:

DemandTypesReader.DemandType

public class Environ
extends java.lang.Object

Implements a table of key=value pairs, where key is a string and value a value of arbitrary type which can be retrieved under a number of a specific types (for example int, double and bool), possibly after a type adaptation.

Author:

Juan Segovia S.

Constructor Summary

Environ()
Creates a new, empty instance.

Environ(Environ b)
Copy constructor (shallow).

Environ(java.lang.Object... kv_pairs)
Creates a new instance and inserts the given key-value pairs.

Method Summary

void	adaptTypes(java.lang.Object[] def_kvp) Adapts the types of values already present in the table to that of the default value given in def_kvp.
boolean	containsKey(java.lang.String key) Returns true if key exists in this table.
void	createPrefixedAliases(java.lang.String old_prefix, java.lang.String new_prefix) Creates aliases of existing keys whose name match (from the beginning) a given prefix that ends with a dot (".").
void	fromArgsString(java.lang.String args) Returns the value of fromArgsString(key, true).
void	fromArgsString(java.lang.String args, boolean overwrite) Inserts into this environemnt the keys and values given.
java.lang.Object	get(java.lang.String key) Returns the object associated to key, or null if no such key exists.
boolean	getBool(java.lang.String key) Returns the value of getBool(key, false).
boolean	getBool(java.lang.String key, boolean defval) Returns the value associated to key as a boolean, or defval if the key does not exist.
double	getDouble(java.lang.String key) Returns the value of getDouble(key, 0.0).
double	getDouble(java.lang.String key, double defval) Returns the value associated to key as a double, or defval if the key does not exist.
int	getInt(java.lang.String key) Returns the value of getInt(key, 0).
int	getInt(java.lang.String key, int defval) Returns the value associated to key as an int, or defval if the key does not exist.
java.lang.String	getStr(java.lang.String key) Returns the value of getStr(key, null).
java.lang.String	getStr(java.lang.String key, java.lang.String defval) Returns the string produced by the toString method applied to key, or defval if the key does not exist.
<T> T	getTyped(java.lang.String key) Returns the value associated to key, cast to the "destination" type T.
java.util.Set<java.lang.String>	keySet() Returns the currently list of keys.
void	put(java.lang.String key, java.lang.Object val) Sets val as the value for key.
void	readFromFile(java.lang.String fname) Read the file fname and populates this with keys and values found there.
void	remove(java.lang.String key) Removes key from this table.
java.lang.String	toString() Returns a the list of key and their values, each pair separated by a newline character.

Methods inherited from class java.lang.Object

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

Constructor Detail

Environ

public Environ()

Creates a new, empty instance.

Environ

public Environ(Environ b)

Copy constructor (shallow). The map that holds the key-value pairs is copied, but not the contents.

Environ

public Environ(java.lang.Object... kv_pairs)

Creates a new instance and inserts the given key-value pairs. The length of kv_pairs must be even. In each pair, the first element is the key and the second the value. Example of use:

    Environ env = new Environ("max_iterations", 100,
                              "stop_on_error", true,
                              "timestamp", new MyTimeStamp);
 

Throws:

java.lang.RuntimeException - if kv_pairs does not have an even number of elements.

java.lang.IllegalArgumentException - if there exists null key or a key is not a String.

Method Detail

put

public void put(java.lang.String key,
                java.lang.Object val)

Sets val as the value for key. Overrides any previous association.

get

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

Returns the object associated to key, or null if no such key exists.

keySet

public java.util.Set<java.lang.String> keySet()

Returns the currently list of keys.

getStr

public java.lang.String getStr(java.lang.String key,
                               java.lang.String defval)

Returns the string produced by the toString method applied to key, or defval if the key does not exist.

getStr

public java.lang.String getStr(java.lang.String key)

Returns the value of getStr(key, null).

getInt

public int getInt(java.lang.String key,
                  int defval)

Returns the value associated to key as an int, or defval if the key does not exist. If the associated value is an instance of a class that "fits" into an int, it is promoted to int. If it is a string, an attempt is made to parse it as an integer.

Throws:

java.lang.NumberFormatException - if the current value cannot be treated as an integer.

getInt

public int getInt(java.lang.String key)

Returns the value of getInt(key, 0).

getBool

public boolean getBool(java.lang.String key,
                       boolean defval)

Returns the value associated to key as a boolean, or defval if the key does not exist.

Throws:

java.lang.IllegalArgumentException - if a boolean cannot be determined from the value associated to key.

getBool

public boolean getBool(java.lang.String key)

Returns the value of getBool(key, false).

getDouble

public double getDouble(java.lang.String key,
                        double defval)

Returns the value associated to key as a double, or defval if the key does not exist. If the associated value is an instance of Number, the corresponding Number.doubleValue() is returned. If it is a string, parsing to double is attempted.

Throws:

java.lang.NumberFormatException - if a double cannot be obtained from the value currently associated to key.

getTyped

public <T> T getTyped(java.lang.String key)

Returns the value associated to key, cast to the "destination" type T. Example:

    // No explicit cast needed. The compiler "fills in" the right
    // parametric type T.
    DateTime tm = env.getTyped("timestamp");
 

getDouble

public double getDouble(java.lang.String key)

Returns the value of getDouble(key, 0.0).

remove

public void remove(java.lang.String key)

Removes key from this table. It does nothing if key does not exist.

containsKey

public boolean containsKey(java.lang.String key)

Returns true if key exists in this table.

fromArgsString

public void fromArgsString(java.lang.String args,
                           boolean overwrite)

Inserts into this environemnt the keys and values given. The parameter args is a string of comma-separated key=value pairs such as the following:

  "debugLevel=9,dumpState,someparam="some value",xyz"

If overwrite is false, a key is inserted only if it does not already exist in the table. A "boolean" key (such as dumpState above, which has no explicit value) is inserted with true as value.

fromArgsString

public void fromArgsString(java.lang.String args)

Returns the value of fromArgsString(key, true).

toString

public java.lang.String toString()

Returns a the list of key and their values, each pair separated by a newline character. The Java type of each value appended in parenthesis.

Overrides:

toString in class java.lang.Object

adaptTypes

public void adaptTypes(java.lang.Object[] def_kvp)

Adapts the types of values already present in the table to that of the default value given in def_kvp. If a given key is not present in this table, it is inserted with its default value. If it is present but there is a mismatch between the class of the current value and that of the default value, a type adaptation of the former is carried out.

There is a type mismatch if the class references are not the same. That is, the comparison is performed with the class references, not with the instanceof operator.

Type adaptation happens only if the type of the current value is one of: Byte, Short, Integer, Long, Float, Double, Boolean, String, all of which are known to have a constructor from String. It is also skipped if the default value is null.

This method is mostly useful with primitive types (and its boxed equivalents). It is typically used to validate that user-provided data (which is usually of type string) conform are convertible and usable under some other (generally primitive) type.

Parameters:

def_kvp - is an array of consecutive key, value pairs. It can be null or of length 0.

Throws:

java.lang.RuntimeException - if the length of def_kvp is not even.

java.lang.IllegalArgumentException - if type conversion fails (this includes overflows from long to int, for example).

readFromFile

public void readFromFile(java.lang.String fname)

Read the file fname and populates this with keys and values found there. The expected format is:
key = value A value may be put into double quotes. The quotes themselves are discarded (note that only the double quote character is accepted).

Unquoted leading and trailing spaces are removed before insertion. The reading is performed through an instance of DataFileReader. If fname is "-", System.in is used. In that case, if data is not immediately available, a warning is sent to both System.out and System.err alerting the user that input is expected from his/her.

Throws:

AnyException - wrapping an IOException if reading the input file fails.

AnyException - wrappin a java.io.IOException if the input does not conform to the expected format.

createPrefixedAliases

public void createPrefixedAliases(java.lang.String old_prefix,
                                  java.lang.String new_prefix)

Creates aliases of existing keys whose name match (from the beginning) a given prefix that ends with a dot ("."). The aliases are with a new prefix.

Parameters:

old_prefix - The prefix of the keys to be aliased. It must not end with a dot (one is automatically added to it by this method).

new_prefix - The prefix to be used instead of old_prefix.