Package org.graphstream.util

Class Environment

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 Details

  • Constructor Details

  • Method Details

    • 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.
      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.