Environment (The GraphStream 1.3 API)

java.lang.Object
- 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:
- 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

static Environment GLOBAL_ENV
Global environment for the whole JVM.

Fields
Modifier and Type	Field and Description
`static Environment`	`GLOBAL_ENV` Global environment for the whole JVM.

Constructor Summary

Constructors
Constructor and Description

Environment()

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(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:
    - 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).
  - 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:
    - 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:
    
    IOException - For any error with the given parameter file name.

Class Environment

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

GLOBAL_ENV

Constructor Detail

Environment

Method Detail

getGlobalEnvironment

isLocked

getParameter

hasParameter

getBooleanParameter

getBooleanParameteri

getNumberParameter

getParameterCount

getParametersKeySet

clone

setParameter

lockEnvironment

initializeFieldsOf

initializeFieldsOf

printParameters

printParameters

toString

readCommandLine

readCommandLine

writeParameterFile

readParameterFile