cds.util
Class Parameters

java.lang.Object
  extended bycds.util.Parameters
All Implemented Interfaces:
java.io.Serializable

public class Parameters
extends java.lang.Object
implements java.io.Serializable

Parameter objects.
Parameters are contained in files. Their syntax is described below. The files may have any extension. If there is no extension, the default extension '.prm' is used.

The data model is made of:
- sections gathering several parameters
- parameters made of a name and a value (syntax: name = value)

A section entry can also contain a pathname whose parameters will be loaded under this section (include). The section can afterwards be completed by regular local parameters. An anonymous include (without section name) requires that the called file contains its own section names.

The syntax will primarily be the one of windows .ini files.

 [section]
param1=value
param2 = value
[section = pathname]
otherparam=value
[section=pathname2]
[= pathname]
...
A special section is [system] . It can contain currently the following entries:
    1. 'name = Parameters_object-name' to give a name to this object and allow its retrieval through a static method
      'parameters = pathname' to create, independantly from the current object other Parameters objects. If they contain a name entry in the [system] section, they can be retrieved easily.
      'varvalsep = x' to define another character for seperating a parameter namefrom its value (default '='). This definition is applicable immediatly for the next parameter
      'sectiondelimitors = XY' to define another pair of characters to delimit section names. By default, they are []. They can be identical, but both characters (beginning ending) must be written without any separation. This definition is applicable immediately after the current section
  • [macro] and [gmacro] are special setions containing variable definitions. macros are local to one parameter file, gmacro are global macros available for all parameter files loaded after the macro definitions.
    A macro is written:

     [macro]
     ROOT=/usr/local
     VERSION=1.3
     ...
     
    and is used in any parameter definition like a variable in a shell:
     myfile = $ROOT/xfile
     number = ${VERSION}a
     

    It is also possible to define macros in a external file, using the regular syntax:
     [macro = /home/macros/mymacro]
     
    mymacro being a parameter file (default extension .prm)


    Comments are lines beginning with a # char
    Long lines can be split in several lines, provided that each non final line is ended by a '\'. The convention is to keep any space before the '\', and suppress any space beginning the line. So the following:

     param = first part + \
             second part
     
    will be read like :
     param = first part + second part
     

    if no section is defined in the file (flat list of parameters), then the default section name is ""

    The parameter objects are made of two levels of HashMaps: a first HashMap manages the sections, each section being one HashMap containing the parameters.

    Parameters pathnames can be either regular filenames or URLs. The default extension of these files is '.prm'. But any extension name is accepted if it exists.

    Version:
    1.0 Apr 2002
    2.0 Jun 2002 extend filenames to 'pathnames' including URLs
    2.1 Jun 2002 add a static (pname, section, name) method
    2.2 Jun 2002 add returns the previous value
    3.0 Oct 2002 (SJ) Utilisation de SortedHashMap + ajout methode paramExists + modif meth get(...) pour param sans val
    3.1 Jan 2003 (SJ) ajout methode sectionExists
    4.0 May 2003 (MW): use TreeHashMaps, add variables 4.1 Jul 2003 (SJ): ajout du test if(params != null) dans methode delete() 4.2 Jan 2004 (BB) modification : UNKNOWN_PARAM est passe de protected a public
    Author:
    Marc Wenger/CDS, Benoit Baranne (Stagiaire UTBM)
    See Also:
    Serialized Form

    Field Summary
    protected static java.lang.String BACKUP_EXTENSION
               
    protected static java.lang.String CONTINUATION_CHAR
               
    protected static java.lang.String CREATION_NAME
               
    protected static java.lang.String DEFAULT_EXTENSION
               
    protected static java.lang.String GLOBAL_MACRO_NAME
               
    private static Macro globalMacroDic
               
    protected static java.lang.String MACRO_NAME
               
    private  Macro macroDic
               
    protected  java.lang.String name
               
    protected static java.lang.String NAME_NAME
               
    protected static SortedHashMap paramList
               
    protected  SortedHashMap params
               
    protected  java.lang.String pathname
               
    protected static char SECTION_BEGIN_CHAR
               
    protected static java.lang.String SECTION_DELIM_NAME
               
    protected static char SECTION_END_CHAR
               
    private  char sectionBeginChar
               
    private  char sectionEndChar
               
    protected  java.lang.String sectionName
               
    protected  SortedHashMap sections
               
    protected static java.lang.String SYSTEM_SECTION_NAME
               
    static java.lang.String UNKNOWN_PARAM
               
    protected static char VAR_VAL_SEP
               
    private  char varValSep
               
    protected static java.lang.String VARVALSEP_NAME
               
     
    Constructor Summary
    Parameters()
              Empty constructor : creates a Parameters object for memory only usage.
    Parameters(java.lang.String pathname)
              Constructor.
    Parameters(java.lang.String pathname, java.lang.String name)
              Constructor.
     
    Method Summary
     java.lang.String add(java.lang.String sectionName, boolean create, java.lang.String name, java.lang.String value)
              adds a parameter to a particular section If the section does not yet exist, it will be created if the create variable is true.
     void add(java.lang.String name, java.lang.String value)
              adds a parameter to the unnamed section.
    private  java.lang.String completeName(java.lang.String pathname)
              Computes the full pathname, including an eventual extension
     void delete()
              Deletes the whole Parameters object
     java.lang.String get(java.lang.String name)
              returns the value of a parameter, without specifying the section.
     java.lang.String get(java.lang.String section, java.lang.String name)
              returns the value for a particular parameter
    static java.lang.String get(java.lang.String pname, java.lang.String section, java.lang.String name)
              returns the value for a particular parameter
     java.lang.String getName()
              returns the name of a parameters object.
    static Parameters getParameters(java.lang.String name)
              Returns the Parameters object corresponding to its name
    static java.util.Iterator getParametersIterator()
              Returns an iterator to browse the Parameters object list
    private  java.lang.String getPath(java.lang.String sname, java.lang.String name)
              Returns the full path of a parameter in the current object
    private static java.lang.String getPath(java.lang.String pname, java.lang.String sname, java.lang.String name)
              Returns the full path of a parameter
     java.util.HashMap getTopic(java.lang.String name)
              returns the HashMap corresponding to a section
    private  void init(java.lang.String pathname, java.lang.String name)
              Initializes and loads a Parameters file
     java.util.Iterator iterator()
              Returns an Iterator object for the list of sections usage is: while(iter.hasNext()) { String sectionname = (String) iter.next()); ... }
     java.util.Iterator iterator(java.lang.String sectionName)
              Returns an Iterator object for the parameters of the given section
     java.util.Iterator iteratorCreate(java.lang.String sectionName)
              Retourne un iterateur sur les parametres d'une section donnee
    Les parametres concernes sont ceux sans valeur, avec valeur differente de listes ou composees et les parametres presents dans les listes ou composees
     java.util.Iterator iteratorGet(java.lang.String sectionName)
              Retourne un iterateur sur les parametres d'une section donnee
    Les parametres concernes sont ceux sans valeur et ceux ayant pour valeur des listes ou composees
     java.util.Iterator iteratorInsert(java.lang.String sectionName)
              Retourne un iterateur sur les parametres d'une section donnee
    Les parametres concernes sont ceux sans valeur et les parametres presents dans les listes ou composees
    protected  boolean load(java.lang.String pathname)
              load the parameters from the designated file or URL
    static void main(java.lang.String[] args)
               
     boolean paramExists(java.lang.String section, java.lang.String param)
              Methode qui permet de savoir si un parametre est contenu dans une section
     boolean sectionExists(java.lang.String section)
              Methode qui permet de savoir si une section existe dans le fichier de parametre
     void setName(java.lang.String name)
              Sets a name to the Parameters object.
     void setPathName(java.lang.String path)
              Sets the pathname for a created parameters set
     java.lang.String toString()
              Edition of a parameter set in a String.
     void update(java.lang.String sectionName, java.lang.String name, java.lang.String value)
              updates a Parameters object: the parameter is written (whether it exists or not) in the given section and the Parameters object is written down
     void write(boolean backup)
              write the parameter file
     
    Methods inherited from class java.lang.Object
    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
     

    Field Detail

    UNKNOWN_PARAM

    public static final java.lang.String UNKNOWN_PARAM
    See Also:
    Constant Field Values

    DEFAULT_EXTENSION

    protected static final java.lang.String DEFAULT_EXTENSION
    See Also:
    Constant Field Values

    BACKUP_EXTENSION

    protected static final java.lang.String BACKUP_EXTENSION
    See Also:
    Constant Field Values

    CONTINUATION_CHAR

    protected static final java.lang.String CONTINUATION_CHAR
    See Also:
    Constant Field Values

    VAR_VAL_SEP

    protected static final char VAR_VAL_SEP
    See Also:
    Constant Field Values

    SECTION_BEGIN_CHAR

    protected static final char SECTION_BEGIN_CHAR
    See Also:
    Constant Field Values

    SECTION_END_CHAR

    protected static final char SECTION_END_CHAR
    See Also:
    Constant Field Values

    varValSep

    private char varValSep

    sectionBeginChar

    private char sectionBeginChar

    sectionEndChar

    private char sectionEndChar

    SYSTEM_SECTION_NAME

    protected static final java.lang.String SYSTEM_SECTION_NAME
    See Also:
    Constant Field Values

    CREATION_NAME

    protected static final java.lang.String CREATION_NAME
    See Also:
    Constant Field Values

    NAME_NAME

    protected static final java.lang.String NAME_NAME
    See Also:
    Constant Field Values

    VARVALSEP_NAME

    protected static final java.lang.String VARVALSEP_NAME
    See Also:
    Constant Field Values

    SECTION_DELIM_NAME

    protected static final java.lang.String SECTION_DELIM_NAME
    See Also:
    Constant Field Values

    MACRO_NAME

    protected static final java.lang.String MACRO_NAME
    See Also:
    Constant Field Values

    GLOBAL_MACRO_NAME

    protected static final java.lang.String GLOBAL_MACRO_NAME
    See Also:
    Constant Field Values

    globalMacroDic

    private static Macro globalMacroDic

    macroDic

    private Macro macroDic

    paramList

    protected static SortedHashMap paramList

    pathname

    protected java.lang.String pathname

    name

    protected java.lang.String name

    sections

    protected SortedHashMap sections

    sectionName

    protected java.lang.String sectionName

    params

    protected SortedHashMap params
    Constructor Detail

    Parameters

    public Parameters()
    Empty constructor : creates a Parameters object for memory only usage. Its name will have to be given through the setName() method.


    Parameters

    public Parameters(java.lang.String pathname)
    Constructor. The name for the Parameters object should be defined in the [system] section

    Parameters:
    pathname - filename or URL of the file containing the parameters to load

    Parameters

    public Parameters(java.lang.String pathname,
                      java.lang.String name)
    Constructor.

    Parameters:
    pathname - filename or URL of the file containing the parameters to load
    name - name of the Parameters object. Needed to retrieve it easily through a static method.
    Method Detail

    init

    private void init(java.lang.String pathname,
                      java.lang.String name)
    Initializes and loads a Parameters file

    Parameters:
    pathname - filepath for the parameter file. If it ends with an extension, it is kept. If it is without extension, the default extension '.prm' is appended.
    name - forcing a name for the parameter set. This name may be overriden by the 'name' parameter in the [system] section.

    completeName

    private java.lang.String completeName(java.lang.String pathname)
    Computes the full pathname, including an eventual extension

    Parameters:
    pathname - original name
    Returns:
    final name

    load

    protected boolean load(java.lang.String pathname)
                    throws java.io.IOException
    load the parameters from the designated file or URL

    Parameters:
    pathname - name of the file or URL containing the parameters to load The file should have 'prm' as extension. If the string pathname has not this extension, it will be added
    Returns:
    true if the parameter file is loaded
    Throws:
    java.io.IOException

    setName

    public void setName(java.lang.String name)
    Sets a name to the Parameters object. This may also be used to change the name of the Parameters object. If the object is read from a file, the name can also be contained in the 'name' parameter of the 'system' section

    Parameters:
    name - name to give to the Parameters object

    setPathName

    public void setPathName(java.lang.String path)
    Sets the pathname for a created parameters set

    Parameters:
    path - pathname (without the final filename)

    getName

    public java.lang.String getName()
    returns the name of a parameters object. This name is by default the pathname, but can be specified as a 'name' parameter in the 'system' section.

    Returns:
    then name of the Parameters object

    getParameters

    public static Parameters getParameters(java.lang.String name)
    Returns the Parameters object corresponding to its name

    Parameters:
    name - name of the Parameters object to retrieve
    Returns:
    the Parameters object (or null)

    getParametersIterator

    public static java.util.Iterator getParametersIterator()
    Returns an iterator to browse the Parameters object list

    Returns:
    an iterator on the Parameters object

    getTopic

    public java.util.HashMap getTopic(java.lang.String name)
    returns the HashMap corresponding to a section

    Parameters:
    name - name of the section
    Returns:
    the parameter HashMap for this section or null

    get

    public static java.lang.String get(java.lang.String pname,
                                       java.lang.String section,
                                       java.lang.String name)
    returns the value for a particular parameter

    Parameters:
    pname - parameter object name
    section - name of the section
    name - name of the parameter
    Returns:
    the parameter value or null

    get

    public java.lang.String get(java.lang.String section,
                                java.lang.String name)
    returns the value for a particular parameter

    Parameters:
    section - name of the section
    name - name of the parameter
    Returns:
    the parameter value or null

    get

    public java.lang.String get(java.lang.String name)
    returns the value of a parameter, without specifying the section.
    The algorithm consists first in looking in the last used table, if already available. If the parameter is not found, then all the sections are browsed. The first parameter found with the right name stops the process. The used section becomes the current one.

    Parameters:
    name - name of the parameter to find
    Returns:
    the parameter value or UNKNOWN_PARAM_STRING and an error message.

    add

    public java.lang.String add(java.lang.String sectionName,
                                boolean create,
                                java.lang.String name,
                                java.lang.String value)
    adds a parameter to a particular section If the section does not yet exist, it will be created if the create variable is true.

    Parameters:
    sectionName - name of the section to which the parameter should be added
    create - if true, create a not yet existing section
    name - parameter name
    value - parameter value
    Returns:
    the previous value of the parameter (if any). null is returned if the parameter does not yet exist, or if the section is not created (new section and create=false).

    update

    public void update(java.lang.String sectionName,
                       java.lang.String name,
                       java.lang.String value)
    updates a Parameters object: the parameter is written (whether it exists or not) in the given section and the Parameters object is written down

    Parameters:
    sectionName - name of the section to which the parameter should be added
    name - parameter name
    value - parameter value

    add

    public void add(java.lang.String name,
                    java.lang.String value)
    adds a parameter to the unnamed section. This is just a shortcut for Parameters object containing only one section (generally build in memory)

    Parameters:
    name - parameter name
    value - parameter value

    getPath

    private static java.lang.String getPath(java.lang.String pname,
                                            java.lang.String sname,
                                            java.lang.String name)
    Returns the full path of a parameter

    Parameters:
    pname - Parameters object name
    sname - Section name
    name - parameter name. It can be replaced by null to display a section path.
    Returns:
    the full path "parameters-object/section/parameter-name"

    getPath

    private java.lang.String getPath(java.lang.String sname,
                                     java.lang.String name)
    Returns the full path of a parameter in the current object

    Parameters:
    sname - Section name
    name - parameter name. It can be replaced by null to display a section path.
    Returns:
    the full path "parameters-object/section/parameter-name"

    iterator

    public java.util.Iterator iterator()
    Returns an Iterator object for the list of sections usage is:
     while(iter.hasNext()) {
        String sectionname = (String) iter.next());
            ...
     }
     

    Returns:
    an Iterator object browsing the section names

    iterator

    public java.util.Iterator iterator(java.lang.String sectionName)
    Returns an Iterator object for the parameters of the given section

    Parameters:
    sectionName - name of the section whose elements will be accessed by the iterator. Browsing through all parameters is done with the following sequence:
     Iterator itop = params.iterator();
     		while (itop.hasNext()) {
     			String topname = (String) itop.next();
     			System.out.println("== "+topname+":");
     			Enumeration iparm = params.itarator(topname);
     			while (iparm.hasNext()) {
     				String parmname = (String) iparm.next();
     				System.out.println("\t"+parmname+" = "+params.get(topname,parmname));
     			}
     		}
     
    Returns:
    an Iterator object browsing the parameter names of the given section. or null if the sectionName doesn't exist

    iteratorCreate

    public java.util.Iterator iteratorCreate(java.lang.String sectionName)
    Retourne un iterateur sur les parametres d'une section donnee
    Les parametres concernes sont ceux sans valeur, avec valeur differente de listes ou composees et les parametres presents dans les listes ou composees

    Parameters:
    sectionName - nom de la section
    Returns:
    un iterateur sur les parametres d'une section donnee ou null si la section n'existe pas

    iteratorInsert

    public java.util.Iterator iteratorInsert(java.lang.String sectionName)
    Retourne un iterateur sur les parametres d'une section donnee
    Les parametres concernes sont ceux sans valeur et les parametres presents dans les listes ou composees

    Parameters:
    sectionName - nom de la section
    Returns:
    un iterateur sur les parametres d'une section donnee ou null si la section n'existe pas

    iteratorGet

    public java.util.Iterator iteratorGet(java.lang.String sectionName)
    Retourne un iterateur sur les parametres d'une section donnee
    Les parametres concernes sont ceux sans valeur et ceux ayant pour valeur des listes ou composees

    Parameters:
    sectionName - nom de la section
    Returns:
    un iterateur sur les parametres d'une section donnee ou null si la section n'existe pas

    write

    public void write(boolean backup)
    write the parameter file

    Parameters:
    backup - if true

    toString

    public java.lang.String toString()
    Edition of a parameter set in a String. A parameter without value has just its name displayed.

    Returns:
    the resulting string, which can be directly printed

    delete

    public void delete()
    Deletes the whole Parameters object


    paramExists

    public boolean paramExists(java.lang.String section,
                               java.lang.String param)
    Methode qui permet de savoir si un parametre est contenu dans une section

    Parameters:
    section - nom de la section
    param - nom du parametre
    Returns:
    vrai si le parametre est contenu dans la section, faux sinon

    sectionExists

    public boolean sectionExists(java.lang.String section)
    Methode qui permet de savoir si une section existe dans le fichier de parametre

    Parameters:
    section - nom de la section
    Returns:
    vrai si la section existe, faux sinon

    main

    public static void main(java.lang.String[] args)