javatools.administrative
Class NonsharedParameters

java.lang.Object
  javatools.administrative.NonsharedParameters

All Implemented Interfaces:

java.lang.Cloneable

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

This class is part of the Java Tools (see http://mpii.de/yago-naga/javatools). It is licensed under the Creative Commons Attribution License (see http://creativecommons.org/licenses/by/3.0) by the YAGO-NAGA team (see http://mpii.de/yago-naga). This is a nonshared, i.e. instantiable variation of the Parameters class. It allows to have different parameter settings handled simultaneously, i.e. each component (or each component instance) using NonsharedParameters can maintain its own parameters. This allows, for instance, that two components running at the same time work on different databases, both obtained through their own NonsharedParameters instance. While the old 'Parameters' class is more convenient to use (less objects passed around), this version makes it easier to integrate your components with other components that also use the Parameters/NonsharedParameters to load (and maintain) their settings. Therefore please consider using the NonsharedParameters instead of the Parameters, if your code may ever be used in parallel with another project that might use one of the Parameters classes. Provides an interface for an ini-File. The ini-File may contain parameters of the form

  parameterName = value
  ...
  

It may also contain comments or section headers (i.e. anything that does not match the above pattern). Parameter names are not case sensitive. Initial and terminal spaces are trimmed for both parameter names and values. Boolean parameters accept multiple ways of expressing "true" (namely "on", "true", "yes" and "active"). You may also use ${param} constructs to refer to parameters set earlier, these references are replaced at the time the file is read by the current value of 'param' (null if it does not have a value!) Alternatively you can use $[param] references, they will be replaced by the current value of 'param' at runtime. Thus, param could be set/overriden after the actual reference appears, i.e. always reflects current settings. This class does function as an object. Example:

    // Read data from my.ini
    NonsharedParameters params = new NonsharedParameters("my.ini");
    // Abort with error message if the following parameters are not specified
    params.ensureParameters(
       "firstPar - some help text for the first parameter",
       "secondPar - some help text for the secondparameter"
    );
    // Retrieve the value of a parameter
    String p=params.get("firstPar");
  

You can load parameters from multiple files. These will overlay. You can reference a .ini file in another .ini file using the 'include' parameter, included files will be loaded at the point of the 'include' statements, parameter settings following the include statement can overwrite parameter settings of this included ini file. Example: Content of main.ini:

     //load database configuration
     include = db_myserver.ini
     // overwrite or add parameters
     databasePort = 5555
     myOtherParameter = 4
   

Content of db_myserver.ini:

     databaseSystem = postgres
     databaseDatabase = example
     databaseUser = albert
     databaseHost = localhost
     databasePort = 5432
   

If main.ini is loaded, the 'databasePort' parameter will have value '5555' in the resulting NonsharedParameters instance. Include is recursive, make sure you do not generate a cycle!

Nested Class Summary

static class	NonsharedParameters.ParameterFileException Reading or writing the parameters ini file failed for some reason In some cases the enclosing program might resolve the issue by providing another file
static class	NonsharedParameters.UndefinedParameterException Thrown for an undefined Parameter

Field Summary

java.lang.String	basePath Holds the path that should be assumed to be the base path to the current directory for all local path values
java.io.File	iniFile Holds the filename of the ini-file
static java.util.regex.Pattern	INIPATTERN Holds the pattern used for ini-file-entries
static FinalSet<java.lang.String>	no Holds words that count as "no" for boolean parameters
static java.util.regex.Pattern	READTIMEVARIABLEPATTERN
static java.util.regex.Pattern	RUNTIMVARIABLEPATTERN
java.util.Map<java.lang.String,java.lang.String>	values Contains the values for the parameters

Constructor Summary

NonsharedParameters()
Constructors

NonsharedParameters(java.io.File iniFile)

NonsharedParameters(java.io.File iniFile, java.lang.String localPath)

NonsharedParameters(NonsharedParameters other)

NonsharedParameters(java.lang.String iniFile)

NonsharedParameters(java.lang.String iniFile, java.lang.String localPath)

Method Summary

void	add(java.lang.String key, java.lang.String value) Adds a value to the map and to the ini file, if not yet there
NonsharedParameters	clone() Cloning implementation
void	ensureParameters(java.lang.String... p) Reports an error message and aborts if the parameters are undefined.
java.lang.String	get(java.lang.String s) Returns a value for a parameter
java.lang.String	get(java.lang.String s, java.lang.String defaultValue) Returns a value for a parameter, returning a default value by default
boolean	getBoolean(java.lang.String s) Returns a value for a boolean parameter
boolean	getBoolean(java.lang.String s, boolean defaultValue) Returns a value for a boolean parameter, returning a default value by default
boolean	getBooleanArgument(java.lang.String[] args, java.lang.String... argnames) Parses the arguments of the main method and tells whether a parameter is on or off
java.lang.Boolean	getBooleanObject(java.lang.String s) Returns a value for a boolean parameter
java.lang.Boolean	getBooleanObject(java.lang.String s, java.lang.Boolean defaultValue) Returns a value for a boolean parameter, returning a default value by default
Database	getDatabase() Returns the database defined in this ini-file
double	getDouble(java.lang.String s) Returns a value for an integer parameter
java.lang.Double	getDouble(java.lang.String s, java.lang.Double defaultValue) Returns a value for an integer parameter returning the default value if undefined
java.io.File	getFile(java.lang.String s) Returns a value for a file or folder parameter; same as getPath but returns an actual File instance
java.io.File	getFile(java.lang.String s, java.io.File defaultValue) Returns a value for a file or folder parameter, returning the default value if undefined; same as getPath but returns an actual File instance
float	getFloat(java.lang.String s) Returns a value for an integer parameter
float	getFloat(java.lang.String s, float defaultValue) Returns a value for an integer parameter returning the default value if undefined
java.lang.Float	getFloatObject(java.lang.String s) Returns a value for an integer parameter
java.lang.Float	getFloatObject(java.lang.String s, java.lang.Float defaultValue) Returns a value for an integer parameter returning the default value if undefined
int	getInt(java.lang.String s) Returns a value for an integer parameter
int	getInt(java.lang.String s, int defaultValue) Returns a value for an integer parameter returning the default value if undefined
java.lang.Integer	getInteger(java.lang.String s) Returns a value for an integer parameter as Integer object
java.lang.Integer	getInteger(java.lang.String s, java.lang.Integer defaultValue) Returns a value for an integer parameter returning the default value if undefined
java.util.List<java.lang.String>	getList(java.lang.String s) Returns a value for a list parameter
java.util.Map<java.lang.String,java.lang.String>	getMap(java.lang.String s) Returns a value for a map parameter
java.lang.String	getMapEntry(java.lang.String s, java.lang.String key) Returns a value for a map parameter
java.lang.String	getOrRequest(java.lang.String s, java.lang.String description) Returns a value for a parameter.
java.lang.String	getOrRequestAndAdd(java.lang.String s, java.lang.String description) Returns a value for a parameter.
boolean	getOrRequestAndAddBoolean(java.lang.String s, java.lang.String description) Returns a value for a parameter.
boolean	getOrRequestBoolean(java.lang.String s, java.lang.String description) Returns a value for a parameter.
java.io.File	getOrRequestFileParameter(java.lang.String s, java.lang.String description) Returns a value for a parameter.
int	getOrRequestInteger(java.lang.String s, java.lang.String description) Returns a value for a parameter.
java.lang.String	getPath(java.lang.String s) Returns a value for a file or folder parameter; same as getFile but returns the path as String also adjusts local paths such that a global path is returned (if a base path is set)
java.lang.String	getPath(java.lang.String s, java.lang.String defaultValue) Returns a value for a file or folder parameter, returning the default value if undefined; same as getFile but returns the path as String
java.sql.Timestamp	getTimestamp(java.lang.String s) Returns a value for a date parameter;
java.sql.Timestamp	getTimestamp(java.lang.String s, java.sql.Timestamp defaultValue) Returns a value for a date parameter, returning the default value if undefined;
java.net.URI	getURI(java.lang.String s) Returns a URI built from a given parameter's value
java.net.URI	getURI(java.lang.String s, java.net.URI defaultValue) Returns a URI built from a given parameter's value, but returns a given default value if the parameter is undefined
java.net.URL	getURL(java.lang.String s) Returns a URL built from a given parameter's value
java.net.URL	getURL(java.lang.String s, java.net.URL defaultValue) Returns a URL built from a given parameter's value, but returns a given default value if the parameter is undefined
void	init(java.io.File f) Initializes the parameters from a file
void	init(java.io.File f, boolean mainIni)
void	init(java.lang.String filename) Initializes the parameters from a file
void	init(java.lang.String file, boolean mainIni)
void	init(java.lang.String filename, java.io.File... folders) Seeks the file in all given folders
void	initiateAllClassAttributes(java.lang.Object object) Checks for all full-upper-case class attributes whether there is a matching parameter and sets its value to the parameter value.
void	initiateClassAttributes(java.lang.Object object) Checks for all full-upper-case class attributes whether there is a matching parameter and sets its value to the parameter value.
void	initiateClassAttributes(java.lang.String className, java.lang.Object object) Checks for all full-upper-case class attributes whether there is a matching parameter and sets its value to the parameter value.
boolean	isDefined(java.lang.String s) Tells whether a parameter is defined
static void	main(java.lang.String[] args) Test routine
java.lang.Object	matchObjectAttribut(java.lang.reflect.Field field) Deprecated.
java.util.Set<java.lang.String>	parameters() Returns all defined parameters
java.lang.String	remove(java.lang.String parameter) Removes a value from the mapping (NOT: from the file)
void	reset() Deletes all current values
void	saveAs(java.lang.String file) Stores the parameters in a given file
void	set(java.lang.String param, java.lang.String value) sets a value for a parameter

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

iniFile

public java.io.File iniFile

Holds the filename of the ini-file

basePath

public java.lang.String basePath

Holds the path that should be assumed to be the base path to the current directory for all local path values

values

public java.util.Map<java.lang.String,java.lang.String> values

Contains the values for the parameters

INIPATTERN

public static java.util.regex.Pattern INIPATTERN

Holds the pattern used for ini-file-entries

READTIMEVARIABLEPATTERN

public static java.util.regex.Pattern READTIMEVARIABLEPATTERN

RUNTIMVARIABLEPATTERN

public static java.util.regex.Pattern RUNTIMVARIABLEPATTERN

no

public static FinalSet<java.lang.String> no

Holds words that count as "no" for boolean parameters

Constructor Detail

NonsharedParameters

public NonsharedParameters()

Constructors

NonsharedParameters

public NonsharedParameters(java.io.File iniFile)
                    throws NonsharedParameters.ParameterFileException

Throws:

NonsharedParameters.ParameterFileException

NonsharedParameters

public NonsharedParameters(java.lang.String iniFile)
                    throws NonsharedParameters.ParameterFileException

Throws:

NonsharedParameters.ParameterFileException

NonsharedParameters

public NonsharedParameters(java.io.File iniFile,
                           java.lang.String localPath)
                    throws NonsharedParameters.ParameterFileException

Throws:

NonsharedParameters.ParameterFileException

NonsharedParameters

public NonsharedParameters(java.lang.String iniFile,
                           java.lang.String localPath)
                    throws NonsharedParameters.ParameterFileException

Throws:

NonsharedParameters.ParameterFileException

NonsharedParameters

public NonsharedParameters(NonsharedParameters other)

Method Detail

clone

public NonsharedParameters clone()

Cloning implementation

Overrides:

clone in class java.lang.Object

getTimestamp

public java.sql.Timestamp getTimestamp(java.lang.String s)
                                throws NonsharedParameters.UndefinedParameterException

Returns a value for a date parameter;

Throws:

NonsharedParameters.UndefinedParameterException

getTimestamp

public java.sql.Timestamp getTimestamp(java.lang.String s,
                                       java.sql.Timestamp defaultValue)
                                throws NonsharedParameters.UndefinedParameterException

Returns a value for a date parameter, returning the default value if undefined;

Throws:

NonsharedParameters.UndefinedParameterException

getPath

public java.lang.String getPath(java.lang.String s)
                         throws NonsharedParameters.UndefinedParameterException

Returns a value for a file or folder parameter; same as getFile but returns the path as String also adjusts local paths such that a global path is returned (if a base path is set)

Throws:

NonsharedParameters.UndefinedParameterException

getPath

public java.lang.String getPath(java.lang.String s,
                                java.lang.String defaultValue)
                         throws NonsharedParameters.UndefinedParameterException

Returns a value for a file or folder parameter, returning the default value if undefined; same as getFile but returns the path as String

Throws:

NonsharedParameters.UndefinedParameterException

getFile

public java.io.File getFile(java.lang.String s)
                     throws NonsharedParameters.UndefinedParameterException

Returns a value for a file or folder parameter; same as getPath but returns an actual File instance

Throws:

NonsharedParameters.UndefinedParameterException

getFile

public java.io.File getFile(java.lang.String s,
                            java.io.File defaultValue)
                     throws NonsharedParameters.UndefinedParameterException

Returns a value for a file or folder parameter, returning the default value if undefined; same as getPath but returns an actual File instance

Throws:

NonsharedParameters.UndefinedParameterException

getURI

public java.net.URI getURI(java.lang.String s)
                    throws NonsharedParameters.UndefinedParameterException,
                           java.net.URISyntaxException

Returns a URI built from a given parameter's value

Throws:

java.net.URISyntaxException

NonsharedParameters.UndefinedParameterException

getURI

public java.net.URI getURI(java.lang.String s,
                           java.net.URI defaultValue)
                    throws NonsharedParameters.UndefinedParameterException,
                           java.net.URISyntaxException

Returns a URI built from a given parameter's value, but returns a given default value if the parameter is undefined

Throws:

java.net.URISyntaxException

NonsharedParameters.UndefinedParameterException

getURL

public java.net.URL getURL(java.lang.String s)
                    throws NonsharedParameters.UndefinedParameterException,
                           java.net.MalformedURLException

Returns a URL built from a given parameter's value

Throws:

java.net.MalformedURLException

NonsharedParameters.UndefinedParameterException

getURL

public java.net.URL getURL(java.lang.String s,
                           java.net.URL defaultValue)
                    throws NonsharedParameters.UndefinedParameterException,
                           java.net.MalformedURLException

Returns a URL built from a given parameter's value, but returns a given default value if the parameter is undefined

Throws:

java.net.MalformedURLException

java.net.URISyntaxException

NonsharedParameters.UndefinedParameterException

getInteger

public java.lang.Integer getInteger(java.lang.String s)
                             throws NonsharedParameters.UndefinedParameterException

Returns a value for an integer parameter as Integer object

Throws:

NonsharedParameters.UndefinedParameterException

getInteger

public java.lang.Integer getInteger(java.lang.String s,
                                    java.lang.Integer defaultValue)
                             throws NonsharedParameters.UndefinedParameterException

Returns a value for an integer parameter returning the default value if undefined

Throws:

NonsharedParameters.UndefinedParameterException

getInt

public int getInt(java.lang.String s)
           throws NonsharedParameters.UndefinedParameterException

Returns a value for an integer parameter

Throws:

NonsharedParameters.UndefinedParameterException

getInt

public int getInt(java.lang.String s,
                  int defaultValue)
           throws NonsharedParameters.UndefinedParameterException

Returns a value for an integer parameter returning the default value if undefined

Throws:

NonsharedParameters.UndefinedParameterException

getFloatObject

public java.lang.Float getFloatObject(java.lang.String s)
                               throws NonsharedParameters.UndefinedParameterException

Returns a value for an integer parameter

Throws:

NonsharedParameters.UndefinedParameterException

getFloatObject

public java.lang.Float getFloatObject(java.lang.String s,
                                      java.lang.Float defaultValue)
                               throws NonsharedParameters.UndefinedParameterException

Returns a value for an integer parameter returning the default value if undefined

Throws:

NonsharedParameters.UndefinedParameterException

getFloat

public float getFloat(java.lang.String s)
               throws NonsharedParameters.UndefinedParameterException

Returns a value for an integer parameter

Throws:

NonsharedParameters.UndefinedParameterException

getFloat

public float getFloat(java.lang.String s,
                      float defaultValue)
               throws NonsharedParameters.UndefinedParameterException

Returns a value for an integer parameter returning the default value if undefined

Throws:

NonsharedParameters.UndefinedParameterException

getDouble

public double getDouble(java.lang.String s)
                 throws NonsharedParameters.UndefinedParameterException

Returns a value for an integer parameter

Throws:

NonsharedParameters.UndefinedParameterException

getDouble

public java.lang.Double getDouble(java.lang.String s,
                                  java.lang.Double defaultValue)
                           throws NonsharedParameters.UndefinedParameterException

Returns a value for an integer parameter returning the default value if undefined

Throws:

NonsharedParameters.UndefinedParameterException

getBooleanObject

public java.lang.Boolean getBooleanObject(java.lang.String s)
                                   throws NonsharedParameters.UndefinedParameterException

Returns a value for a boolean parameter

Throws:

NonsharedParameters.UndefinedParameterException

getBooleanObject

public java.lang.Boolean getBooleanObject(java.lang.String s,
                                          java.lang.Boolean defaultValue)

Returns a value for a boolean parameter, returning a default value by default

getBoolean

public boolean getBoolean(java.lang.String s)
                   throws NonsharedParameters.UndefinedParameterException

Returns a value for a boolean parameter

Throws:

NonsharedParameters.UndefinedParameterException

getBoolean

public boolean getBoolean(java.lang.String s,
                          boolean defaultValue)

Returns a value for a boolean parameter, returning a default value by default

getList

public java.util.List<java.lang.String> getList(java.lang.String s)
                                         throws NonsharedParameters.UndefinedParameterException

Returns a value for a list parameter

Throws:

NonsharedParameters.UndefinedParameterException

getMap

public java.util.Map<java.lang.String,java.lang.String> getMap(java.lang.String s)
                                                        throws NonsharedParameters.UndefinedParameterException

Returns a value for a map parameter

Throws:

NonsharedParameters.UndefinedParameterException

getMapEntry

public java.lang.String getMapEntry(java.lang.String s,
                                    java.lang.String key)
                             throws NonsharedParameters.UndefinedParameterException

Returns a value for a map parameter

Throws:

NonsharedParameters.UndefinedParameterException

get

public java.lang.String get(java.lang.String s)
                     throws NonsharedParameters.UndefinedParameterException

Returns a value for a parameter

Throws:

NonsharedParameters.UndefinedParameterException

get

public java.lang.String get(java.lang.String s,
                            java.lang.String defaultValue)

Returns a value for a parameter, returning a default value by default

getOrRequest

public java.lang.String getOrRequest(java.lang.String s,
                                     java.lang.String description)

Returns a value for a parameter. If not present, asks the user for it

getOrRequestAndAdd

public java.lang.String getOrRequestAndAdd(java.lang.String s,
                                           java.lang.String description)
                                    throws java.io.IOException

Returns a value for a parameter. If not present, asks the user for it and adds it

Throws:

java.io.IOException

getOrRequestAndAddBoolean

public boolean getOrRequestAndAddBoolean(java.lang.String s,
                                         java.lang.String description)
                                  throws java.io.IOException

Returns a value for a parameter. If not present, asks the user for it and adds it

Throws:

java.io.IOException

getOrRequestFileParameter

public java.io.File getOrRequestFileParameter(java.lang.String s,
                                              java.lang.String description)

Returns a value for a parameter. If not present, asks the user for it

getOrRequestBoolean

public boolean getOrRequestBoolean(java.lang.String s,
                                   java.lang.String description)

Returns a value for a parameter. If not present, asks the user for it

getOrRequestInteger

public int getOrRequestInteger(java.lang.String s,
                               java.lang.String description)

Returns a value for a parameter. If not present, asks the user for it

add

public void add(java.lang.String key,
                java.lang.String value)
         throws java.io.IOException

Adds a value to the map and to the ini file, if not yet there

Throws:

java.io.IOException

remove

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

Removes a value from the mapping (NOT: from the file)

set

public void set(java.lang.String param,
                java.lang.String value)

sets a value for a parameter

init

public void init(java.io.File f)
          throws NonsharedParameters.ParameterFileException

Initializes the parameters from a file

Throws:

NonsharedParameters.ParameterFileException

init

public void init(java.io.File f,
                 boolean mainIni)
          throws NonsharedParameters.ParameterFileException

Throws:

NonsharedParameters.ParameterFileException

init

public void init(java.lang.String filename,
                 java.io.File... folders)
          throws NonsharedParameters.ParameterFileException

Seeks the file in all given folders

Throws:

NonsharedParameters.ParameterFileException

init

public void init(java.lang.String filename)
          throws NonsharedParameters.ParameterFileException

Initializes the parameters from a file

Throws:

NonsharedParameters.ParameterFileException

init

public void init(java.lang.String file,
                 boolean mainIni)
          throws NonsharedParameters.ParameterFileException

Throws:

NonsharedParameters.ParameterFileException

isDefined

public boolean isDefined(java.lang.String s)

Tells whether a parameter is defined

ensureParameters

public void ensureParameters(java.lang.String... p)

Reports an error message and aborts if the parameters are undefined. p may contain strings of the form "parametername explanation"

getBooleanArgument

public boolean getBooleanArgument(java.lang.String[] args,
                                  java.lang.String... argnames)

Parses the arguments of the main method and tells whether a parameter is on or off

reset

public void reset()

Deletes all current values

getDatabase

public Database getDatabase()
                     throws java.sql.SQLException,
                            java.lang.InstantiationException,
                            java.lang.IllegalAccessException,
                            java.lang.ClassNotFoundException

Returns the database defined in this ini-file

Throws:

java.sql.SQLException

java.lang.InstantiationException

java.lang.IllegalAccessException

java.lang.ClassNotFoundException

matchObjectAttribut

@Deprecated
public java.lang.Object matchObjectAttribut(java.lang.reflect.Field field)
                                     throws java.lang.IllegalAccessException

Deprecated.

Checks whether a parameter matching the field name is available. There are two ways to declare attributes to configurable parameters, either write them all upper case of use the prefix "cp_"; in the latter case the prefix is ignored when matching parameters to the field. Returns the parameter value in the format corresponding the field.

Parameters:

field - the attribute against which to match the parameters

Returns:

an object representing the value of a parameter that matches the given attribute iff there is a match, otherwise null

Throws:

java.lang.IllegalAccessException

initiateClassAttributes

public void initiateClassAttributes(java.lang.String className,
                                    java.lang.Object object)

Checks for all full-upper-case class attributes whether there is a matching parameter and sets its value to the parameter value.

Parameters:

classname - name of the class for which to check

object - object, which needs to be an instance of the given class

initiateAllClassAttributes

public void initiateAllClassAttributes(java.lang.Object object)

Checks for all full-upper-case class attributes whether there is a matching parameter and sets its value to the parameter value. Does this also for parameters inherited from super-classes.

Parameters:

classname - name of the class for which to check

object - object, which needs to be an instance of the given class

initiateClassAttributes

public void initiateClassAttributes(java.lang.Object object)

Checks for all full-upper-case class attributes whether there is a matching parameter and sets its value to the parameter value.

Parameters:

classname - name of the class for which to check

object - object, which needs to be an instance of the given class

parameters

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

Returns all defined parameters

saveAs

public void saveAs(java.lang.String file)
            throws NonsharedParameters.ParameterFileException

Stores the parameters in a given file

Throws:

NonsharedParameters.ParameterFileException

main

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

Test routine

Throws:

java.lang.Exception