org.graphstream.util

Class Environment

java.lang.Object

org.graphstream.util.Environment

All Implemented Interfaces:

java.lang.Cloneable

public class Environment
extends java.lang.Object
implements java.lang.Cloneable

Representation of a set of parameters.

The environment class mimics the environment variables available in any shell using a hash map of keys/values, the key being the variables names, excepted here they are called parameters.

In addition, this class provides facilities to:

• Read a parameter file and set the parameters from this file;
• Write a parameter file from the parameter of this environment;
• Parse the command line and get parameters from it;
• Take a class as argument and set all its fields having the same name as parameters in this class;

As in any shell, most of the time, the environment is global and accessible from any part of the system. Here a singleton instance of this class is created and accessible from anywhere in the JVM using the getGlobalEnvironment() method (indeed the singleton instance is created at its first access). However, it is still possible to create a private instance of this class for use in a specific part of a program.

To read a file of parameters, simply call the readParameterFile(String) method. In the same way, to write a set of parameters to a file, call the writeParameterFile(String) method. The format of the parameter file is given in the description of these methods.

To read parameters from he command line, call the readCommandLine(String[]) or readCommandLine(String[], Collection) methods. These methods expect a format for the command line that is described in there respective documentations.

It is also possible to setup automatically the fields of an arbitrary object, provided these fields have name that match parameters in this environment. To do this call the initializeFieldsOf(Object) method passing the object to initialise as argument. The object to setup must provide methods of the form "setThing(Type)" where "Thing" or "thing" is the name of the field to set and "Type" is one of "int", "long", "float", "double", "String" and "boolean". For the boolean type, the accepted values meaning true are "true", "on", "1", and "yes", all other value are considered as false.

TODO: how (or when) does the default configuration file is read? TODO: how to handle parameters that cannot be setup in the initializeFieldsOf(Object)?

Version:

1.0 (jdk 1.5)

Author:

Fr??d??ric Guinand, Yoann Pign??, Antoine Dutot

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	configFileName Name of the configuration file.
protected boolean	configFileRead Has the configuration file been read yet?.
static Environment	GLOBAL_ENV Global environment for the whole JVM.
protected boolean	locked When locked the environment parameters value still can be changed but it is no more possible to add new parameters.
protected java.util.Hashtable<java.lang.String,java.lang.String>	parameters Set of parameters.

Constructor Summary

Constructors

Constructor and Description
Environment()

Method Summary

Methods

Modifier and Type	Method and Description
Environment	clone() Generate a new Environment object with a deep copy of the elements this object.
boolean	getBooleanParameter(java.lang.String parameter) Check a parameter expected to be of boolean type.
int	getBooleanParameteri(java.lang.String parameter) Check a parameter expected to be of boolean type.
static Environment	getGlobalEnvironment() Access to the global shared environment for the whole JVM.
double	getNumberParameter(java.lang.String parameter) Get the value of a parameter that is expected to be a number.
java.lang.String	getParameter(java.lang.String parameter) Access to a parameter in the environment.
int	getParameterCount() Returns the number of parameters found in the configuration file.
java.util.Set<java.lang.String>	getParametersKeySet() Set of all parameter names.
boolean	hasParameter(java.lang.String parameter) True if the given paramter exist.
void	initializeFieldsOf(java.lang.Object object) Initialize all the fields of the given object whose name correspond to parameters of this environment.
protected void	initializeFieldsOf(java.lang.Object object, java.util.Collection<java.lang.String> fieldList) Initialize all the fields of the given object that both appear in the given field list and whose name correspond to parameters of this environment.
void	initializeFieldsOf(java.lang.Object object, java.lang.String... fieldList) Initialize all the fields of the given object that both appear in the given field list and whose name correspond to parameters of this environment.
protected void	invokeSetMethod(java.lang.Object object, java.lang.reflect.Method method, java.lang.Class<?>[] types, java.lang.String name, java.lang.String value)
boolean	isLocked() Is the environment locked?.
void	lockEnvironment(boolean on) Disallow the addition of new parameters.
void	printParameters() Print all parameters the stdout.
void	printParameters(java.io.PrintStream out) Print all parameters to the given stream.
void	readCommandLine(java.lang.String[] args) Read the parameters from the given command line array.
void	readCommandLine(java.lang.String[] args, java.util.Collection<java.lang.String> trashcan) Read the parameters from the given command line array.
protected void	readConfigFile(java.lang.String filename, java.util.Collection<java.lang.String> trashcan) Internal method that reads a configuration file.
protected void	readConfigurationFile() Read the default configuration file.
void	readParameterFile(java.lang.String fileName) Read a parameter file.
void	setParameter(java.lang.String parameter, java.lang.String value) Set the value of a parameter.
java.lang.String	toString()
void	writeParameterFile(java.lang.String fileName) Save the curent parameters to a file.

Methods inherited from class java.lang.Object

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

Field Detail

configFileName

protected java.lang.String configFileName

Name of the configuration file. Default is "config"

configFileRead

protected boolean configFileRead

Has the configuration file been read yet?.

parameters

protected java.util.Hashtable<java.lang.String,java.lang.String> parameters

Set of parameters. This is a hash table and not a hashmap since several thread may access this class at once.

locked

protected boolean locked

When locked the environment parameters value still can be changed but it is no more possible to add new parameters.

GLOBAL_ENV

public static Environment GLOBAL_ENV

Global environment for the whole JVM. This global environment is available and editable from everywhere. It is create as soon as the getGlobalEnvironment() static method is called if this field was not yet initialized by any other mean.

See Also:

getGlobalEnvironment()

Constructor Detail

Environment

public Environment()

Method Detail

getGlobalEnvironment

public static Environment getGlobalEnvironment()

Access to the global shared environment for the whole JVM. This method allows to access a shared environment, that can be read and written from anywhere.

Returns:

A singleton instance of the global environment.

isLocked

public boolean isLocked()

Is the environment locked?.

Returns:

True if the environment is locked.

See Also:

lockEnvironment(boolean)

getParameter

public java.lang.String getParameter(java.lang.String parameter)

Access to a parameter in the environment.

Parameters:

parameter - The parameter name.

Returns:

The parameter value (empty string if not set).

hasParameter

public boolean hasParameter(java.lang.String parameter)

True if the given paramter exist.

Parameters:

parameter - The parameter name.

Returns:

True if the given paramter name points to a value.

getBooleanParameter

public boolean getBooleanParameter(java.lang.String parameter)

Check a parameter expected to be of boolean type. This method returns "true" if the parameter exists and has a value that is "1", "true", "on" or "yes" (with any possible combination of upper or lower-case letters). For any other values of the parameter or if the parameter does not exist in the environment, "false" is returned.

Parameters:

parameter - The parameter name.

Returns:

True if the parameter value means "true", false for any other value or if the parameter does not exist.

See Also:

getBooleanParameteri(String)

getBooleanParameteri

public int getBooleanParameteri(java.lang.String parameter)

Check a parameter expected to be of boolean type. This method returns the value 1 if the parameter has value "1", "true", "on", "yes" (the case does not matter). Else it returns 0. To account the case of non-existing parameters, this method returns -1 if the given parameter does not exist.

Parameters:

parameter - The parameter name.

Returns:

1 if the parameter value means "true", 0 if it has any other value, or -1 if it does not exist.

See Also:

getBooleanParameter(String)

getNumberParameter

public double getNumberParameter(java.lang.String parameter)

Get the value of a parameter that is expected to be a number. If the parameter does not exist or is not a number, 0 is returned.

Parameters:

parameter - The parameter name.

Returns:

The numeric value of the parameter. 0 if the parameter does not exist or is not a number.

getParameterCount

public int getParameterCount()

Returns the number of parameters found in the configuration file.

Returns:

The number of parameters found in the configuration file.

getParametersKeySet

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

Set of all parameter names.

Returns:

A set of all the names identifying parameters in this environment.

clone

public Environment clone()

Generate a new Environment object with a deep copy of the elements this object.

Overrides:

clone in class java.lang.Object

Returns:

An Environment object identical to this one

setParameter

public void setParameter(java.lang.String parameter,
                java.lang.String value)

Set the value of a parameter. If the parameter already exists its old value is overwritten. This works only if the environment is not locked.

Parameters:

parameter - The parameter name.

value - The new parameter value.

See Also:

isLocked(), lockEnvironment(boolean)

lockEnvironment

public void lockEnvironment(boolean on)

Disallow the addition of new parameters. The already declared parameters are still modifiable, but no new parameter can be added.

Parameters:

on - If true the environment is locked.

initializeFieldsOf

public void initializeFieldsOf(java.lang.Object object)

Initialize all the fields of the given object whose name correspond to parameters of this environment. This works only if the object to initialize provides methods that begins by "set". For example if the object provides a method named "setThing(int value)", and if there is a parameter named "thing" in this environment and its value is convertible to an integer, then the method "setThing()" will be invoked on the object with the correct value.

Parameters:

object - The object to initialize.

See Also:

initializeFieldsOf(Object, String[]), initializeFieldsOf(Object, Collection)

initializeFieldsOf

public void initializeFieldsOf(java.lang.Object object,
                      java.lang.String... fieldList)

Initialize all the fields of the given object that both appear in the given field list and whose name correspond to parameters of this environment. See the initializeFieldsOf(Object) method description.

Parameters:

object - The object to initialize.

fieldList - The name of the fields to initialize in the object.

See Also:

initializeFieldsOf(Object), initializeFieldsOf(Object, Collection)

initializeFieldsOf

protected void initializeFieldsOf(java.lang.Object object,
                      java.util.Collection<java.lang.String> fieldList)

Initialize all the fields of the given object that both appear in the given field list and whose name correspond to parameters of this environment. See the initializeFieldsOf(Object) method description.

Parameters:

object - The object to initialize.

fieldList - The name of the fields to initialize in the object.

See Also:

initializeFieldsOf(Object), initializeFieldsOf(Object, String[])

invokeSetMethod

protected void invokeSetMethod(java.lang.Object object,
                   java.lang.reflect.Method method,
                   java.lang.Class<?>[] types,
                   java.lang.String name,
                   java.lang.String value)

printParameters

public void printParameters(java.io.PrintStream out)

Print all parameters to the given stream.

Parameters:

out - The output stream to use.

printParameters

public void printParameters()

Print all parameters the stdout.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

readCommandLine

public void readCommandLine(java.lang.String[] args)

Read the parameters from the given command line array. See the more complete readCommandLine(String[], Collection) method.

Parameters:

args - The command line.

readCommandLine

public void readCommandLine(java.lang.String[] args,
                   java.util.Collection<java.lang.String> trashcan)

Read the parameters from the given command line array. The expected format of this array is the following:

• a word beginning by a "-" is the parameter name (for example "-param");
• if this word is immediately followed by a "=" and another word, this word is considered as its string value (for example "-param=aValue");
• If the parameter name is not followed by "=", it is considered a boolean option and its value is set to the string "true" (to set this to false simply give the string "-param=false");
• If a word is found on the command line without any preceding "-" but is followed by a "=" and by another word, then it is considered as a key,value brace
• If a word is found on the command line without any preceding "-" and is not followed by any "=", the it is considered to be a filename for a configuration file. The method will try to open this file for reading. A configuration file is composed of lines. Each line is composed of a brace key/value separated by a "=". If a line starts with a "#", then it is considered as a comment. Finally if no format is recognized the line is inserted to the trashcan.

Parameters:

args - The command line.

trashcan - Will be filled by the set of unparsed strings (can be null if these strings can be ignored).

readConfigFile

protected void readConfigFile(java.lang.String filename,
                  java.util.Collection<java.lang.String> trashcan)

Internal method that reads a configuration file.

writeParameterFile

public void writeParameterFile(java.lang.String fileName)
                        throws java.io.IOException

Save the curent parameters to a file.

Parameters:

fileName - Name of the file to save the config in.

Throws:

java.io.IOException - For any output error on the given file name.

readConfigurationFile

protected void readConfigurationFile()

Read the default configuration file. Once this file has been correctly parsed, the configFileRead boolean is set to true.

See Also:

configFileName

readParameterFile

public void readParameterFile(java.lang.String fileName)
                       throws java.io.IOException

Read a parameter file. The format of this file is as follows:

• Each line contains a parameter setting or a comment;
• Lines beginning by a "#" are considered comments (be careful, a "#" in the middle of a line is not a comment);
• parameters settings are of the form "name=value", spaces are allowed, but space before and after the parameter name of value will be stripped.

Parameters:

fileName - Name of the parameter file to read.

Throws:

java.io.IOException - For any error with the given parameter file name.