org.graphstream.util
Class Environment

java.lang.Object
  extended by org.graphstream.util.Environment
All Implemented Interfaces:
Cloneable

public class Environment
extends Object
implements 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:

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
static Environment GLOBAL_ENV
          Global environment for the whole JVM.
 
Constructor Summary
Environment()
           
 
Method Summary
 Environment clone()
          Generate a new Environment object with a deep copy of the elements this object.
 boolean getBooleanParameter(String parameter)
          Check a parameter expected to be of boolean type.
 int getBooleanParameteri(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(String parameter)
          Get the value of a parameter that is expected to be a number.
 String getParameter(String parameter)
          Access to a parameter in the environment.
 int getParameterCount()
          Returns the number of parameters found in the configuration file.
 Set<String> getParametersKeySet()
          Set of all parameter names.
 boolean hasParameter(String parameter)
          True if the given paramter exist.
 void initializeFieldsOf(Object object)
          Initialize all the fields of the given object whose name correspond to parameters of this environment.
 void initializeFieldsOf(Object object, 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.
 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(PrintStream out)
          Print all parameters to the given stream.
 void readCommandLine(String[] args)
          Read the parameters from the given command line array.
 void readCommandLine(String[] args, Collection<String> trashcan)
          Read the parameters from the given command line array.
 void readParameterFile(String fileName)
          Read a parameter file.
 void setParameter(String parameter, String value)
          Set the value of a parameter.
 String toString()
           
 void writeParameterFile(String fileName)
          Save the curent parameters to a file.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

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 String getParameter(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(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(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(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(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 Set<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 Object
Returns:
An Environment object identical to this one

setParameter

public void setParameter(String parameter,
                         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(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(Object object,
                               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)

printParameters

public void printParameters(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 String toString()
Overrides:
toString in class Object

readCommandLine

public void readCommandLine(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(String[] args,
                            Collection<String> trashcan)
Read the parameters from the given command line array. The expected format of this array is the following:

Parameters:
args - The command line.
trashcan - Will be filled by the set of unparsed strings (can be null if these strings can be ignored).

writeParameterFile

public void writeParameterFile(String fileName)
                        throws IOException
Save the curent parameters to a file.

Parameters:
fileName - Name of the file to save the config in.
Throws:
IOException - For any output error on the given file name.

readParameterFile

public void readParameterFile(String fileName)
                       throws IOException
Read a parameter file. The format of this file is as follows:

Parameters:
fileName - Name of the parameter file to read.
Throws:
IOException - For any error with the given parameter file name.


Copyright © 2013. All Rights Reserved.