core

Class Settings

java.lang.Object

core.Settings

public class Settings
extends java.lang.Object

Interface for simulation settings stored in setting file(s). Settings class should be initialized before using (with init(String)). If Settings isn't initialized, only settings in DEF_SETTINGS_FILE are read. Normally, after initialization, settings in the given file can override any settings defined in the default settings file and/or define new settings.

All settings are key-value pairs. For parsing details see Properties.getProperty(String). Value can be a single value or comma separated list of values. With CSV values, CSV methods must be used (e.g. getCsvInts(String, int)). Setting value should not start and end with a bracket since those are reserved for run-specific values (see setRunIndex(int)). In file paths directory separator should always be forward slash ("/").

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEF_SETTINGS_FILE file name of the default settings file ("default_settings.txt")
static java.lang.String	FILL_DELIMITER delimiter for requested values in strings ("%%")
protected static java.util.Properties	props properties object where the setting files are read into
static java.lang.String	SETTING_OUTPUT_S Setting to define the file name where all read settings are written ("Settings.output".

Constructor Summary

Constructors

Constructor and Description
Settings() Create a setting object without namespace.
Settings(java.lang.String namespace) Creates a setting object with a namespace.

Method Summary

Methods

Modifier and Type	Method and Description
static void	addSettings(java.lang.String propFile) Reads another settings file and adds the key-value pairs to the current settings overriding any values that already existed with the same keys.
void	assertValidRange(int[] range, java.lang.String sname) Checks that the given integer array contains a valid range.
boolean	contains(java.lang.String name) Returns true if a setting with defined name (in the current namespace or secondary namespace if such is set) exists and has some value (not just white space)
java.lang.Object	createIntializedObject(java.lang.String className) Creates (and dynamically loads the class of) an object that initializes itself using the settings in this Settings object (given as the only parameter to the constructor).
java.lang.Object	createObject(java.lang.String className) Creates (and dynamically loads the class of) an object using the constructor without any parameters.
void	ensurePositiveValue(double value, java.lang.String settingName) Makes sure that the given settings value is positive
boolean	getBoolean(java.lang.String name) Returns a boolean-valued setting
boolean	getBoolean(java.lang.String name, boolean defaultValue) Returns the given boolean setting if it exists, or defaultValue if the setting does not exist
ArithmeticCondition	getCondition(java.lang.String name) Returns an ArithmeticCondition setting.
double[]	getCsvDoubles(java.lang.String name) Returns an array of CSV setting double values.
double[]	getCsvDoubles(java.lang.String name, int expectedCount) Returns an array of CSV setting double values containing expected amount of values.
int[]	getCsvInts(java.lang.String name) Returns an array of CSV setting integer values
int[]	getCsvInts(java.lang.String name, int expectedCount) Returns an array of CSV setting integer values
util.Range[]	getCsvRanges(java.lang.String name) Returns comma-separated ranges (e.g., "3-5, 17-20, 15")
java.lang.String[]	getCsvSetting(java.lang.String name) Returns a CSV setting.
java.lang.String[]	getCsvSetting(java.lang.String name, int expectedCount) Returns a CSV setting containing expected amount of values.
double	getDouble(java.lang.String name) Returns a double-valued setting
double	getDouble(java.lang.String name, double defaultValue) Returns a double-valued setting, or the default value if the given setting does not exist
java.lang.String	getFullPropertyName(java.lang.String setting) Returns full (namespace prefixed) property name for a setting.
int	getInt(java.lang.String name) Returns an integer-valued setting
int	getInt(java.lang.String name, int defaultValue) Returns an integer-valued setting, or the default value if the setting does not exist
java.lang.String	getNameSpace() Returns the namespace of the settings object
java.lang.String	getSecondaryNameSpace() Returns the secondary namespace of the settings object
java.lang.String	getSetting(java.lang.String name) Returns a String-valued setting.
java.lang.String	getSetting(java.lang.String name, java.lang.String defaultValue) Returns the given setting if it exists, or defaultValue if the setting does not exist
static void	init(java.lang.String propFile) Initializes the settings all Settings objects will use.
void	restoreNameSpace() Restores the namespace that was in use before a call to setNameSpace
void	restoreSecondaryNamespace() Restores the secondary namespace that was in use before a call to setSecondaryNameSpace
void	restoreSubNameSpace() Reverts the change made with setSubNameSpace(String), i.e., restores both the primary and secondary namespace.
void	setNameSpace(java.lang.String namespace) Sets the namespace to something else than the current namespace.
static void	setRunIndex(int index) Sets the run index for the settings (only has effect on settings with run array).
void	setSecondaryNamespace(java.lang.String namespace) Sets a secondary namespace where a setting is searched from if it isn't found from the primary namespace.
void	setSubNameSpace(java.lang.String namespace) Appends the given namespace to the the current namespace, for both the primary and secondary namespace .
java.lang.String	toString() Returns a String representation of the stored settings
java.lang.String	valueFillString(java.lang.String input) Fills a String formatted in a special way with values from Settings.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

props

protected static java.util.Properties props

properties object where the setting files are read into

DEF_SETTINGS_FILE

public static final java.lang.String DEF_SETTINGS_FILE

file name of the default settings file ("default_settings.txt")

See Also:

Constant Field Values

SETTING_OUTPUT_S

public static final java.lang.String SETTING_OUTPUT_S

Setting to define the file name where all read settings are written ("Settings.output". If set to an empty string, standard output is used. By default setting are not written anywhere.

See Also:

Constant Field Values

FILL_DELIMITER

public static final java.lang.String FILL_DELIMITER

delimiter for requested values in strings ("%%")

See Also:

valueFillString(String), Constant Field Values

Constructor Detail

Settings

public Settings(java.lang.String namespace)

Creates a setting object with a namespace. Namespace is the prefix of the all subsequent setting requests.

Parameters:

namespace - Namespace to use

Settings

public Settings()

Create a setting object without namespace. All setting requests must be prefixed with a valid namespace (e.g. "Report.nrofReports").

Method Detail

setRunIndex

public static void setRunIndex(int index)

Sets the run index for the settings (only has effect on settings with run array). A run array can be defined with syntax
[settingFor1stRun ; settingFor2ndRun ; SettingFor3rdRun]
I.e. settings are put in brackets and delimited with semicolon. First run's setting is returned when index is 0, second when index is 1 etc. If run index is bigger than run array's length, indexing wraps around in run array (i.e. return value is the value at index runIndex % arrayLength). To disable whole run-index-thing, set index to value smaller than zero (e.g. -1). When disabled, run-arrays are returned as normal values, including the brackets.

Parameters:

index - The run index to use for subsequent settings calls, or -1 to disable run indexing

assertValidRange

public void assertValidRange(int[] range,
                    java.lang.String sname)
                      throws SettingsError

Checks that the given integer array contains a valid range. I.e., the length of the array must be two and first_value <= second_value.

Parameters:

range - The range array

sname - Name of the setting (for error messages)

Throws:

SettingsError - If the given array didn't qualify as a range

ensurePositiveValue

public void ensurePositiveValue(double value,
                       java.lang.String settingName)

Makes sure that the given settings value is positive

Parameters:

value - Value to check

settingName - Name of the setting (for error's message)

Throws:

SettingsError - if the value was not positive

setNameSpace

public void setNameSpace(java.lang.String namespace)

Sets the namespace to something else than the current namespace. This change can be reverted using restoreNameSpace()

Parameters:

namespace - The new namespace

setSubNameSpace

public void setSubNameSpace(java.lang.String namespace)

Appends the given namespace to the the current namespace, for both the primary and secondary namespace . This change can be reverted using restoreNameSpace() and restoreSecondaryNamespace().

Parameters:

namespace - The new namespace to append

getFullPropertyName

public java.lang.String getFullPropertyName(java.lang.String setting)

Returns full (namespace prefixed) property name for a setting.

Parameters:

setting - The name of the setting

Returns:

The setting name prefixed with fully qualified name of the namespace where the requested setting would be retrieved from or null if that setting is not found from any of the current namespace(s)

getNameSpace

public java.lang.String getNameSpace()

Returns the namespace of the settings object

Returns:

the namespace of the settings object

getSecondaryNameSpace

public java.lang.String getSecondaryNameSpace()

Returns the secondary namespace of the settings object

Returns:

the secondary namespace of the settings object

setSecondaryNamespace

public void setSecondaryNamespace(java.lang.String namespace)

Sets a secondary namespace where a setting is searched from if it isn't found from the primary namespace. Secondary namespace can be used e.g. as a "default" space where the settings are looked from if no specific setting is set. This change can be reverted using restoreSecondaryNamespace()

Parameters:

namespace - The new secondary namespace or null if secondary namespace is not used (default behavior)

restoreNameSpace

public void restoreNameSpace()

Restores the namespace that was in use before a call to setNameSpace

See Also:

setNameSpace(String)

restoreSecondaryNamespace

public void restoreSecondaryNamespace()

Restores the secondary namespace that was in use before a call to setSecondaryNameSpace

See Also:

setSecondaryNamespace(String)

restoreSubNameSpace

public void restoreSubNameSpace()

Reverts the change made with setSubNameSpace(String), i.e., restores both the primary and secondary namespace.

init

public static void init(java.lang.String propFile)
                 throws SettingsError

Initializes the settings all Settings objects will use. This should be called before any setting requests. Subsequent calls replace all old settings and then Settings contains only the new settings. The file DEF_SETTINGS_FILE, if exists, is always read.

Parameters:

propFile - Path to the property file where additional settings are read from or null if no additional settings files are needed.

Throws:

SettingsError - If loading the settings file(s) didn't succeed

addSettings

public static void addSettings(java.lang.String propFile)
                        throws SettingsError

Reads another settings file and adds the key-value pairs to the current settings overriding any values that already existed with the same keys.

Parameters:

propFile - Path to the property file

Throws:

SettingsError - If loading the settings file didn't succeed

See Also:

init(String)

contains

public boolean contains(java.lang.String name)

Returns true if a setting with defined name (in the current namespace or secondary namespace if such is set) exists and has some value (not just white space)

Parameters:

name - Name of the setting to check

Returns:

True if the setting exists, false if not

getSetting

public java.lang.String getSetting(java.lang.String name)

Returns a String-valued setting. Setting is first looked from the namespace that is set (if any) and then from the secondary namespace (if any). All other getters use this method as their first step too (so all getters may throw SettingsError and look from both namespaces).

Parameters:

name - Name of the setting to get

Returns:

The contents of the setting in a String

Throws:

SettingsError - if the setting is not found from either one of the namespaces

getSetting

public java.lang.String getSetting(java.lang.String name,
                          java.lang.String defaultValue)

Returns the given setting if it exists, or defaultValue if the setting does not exist

Parameters:

name - The name of the setting

defaultValue - The value to return if the given setting didn't exist

Returns:

The setting value or the default value if the setting didn't exist

getDouble

public double getDouble(java.lang.String name)

Returns a double-valued setting

Parameters:

name - Name of the setting to get

Returns:

Value of the setting as a double

getDouble

public double getDouble(java.lang.String name,
               double defaultValue)

Returns a double-valued setting, or the default value if the given setting does not exist

Parameters:

name - Name of the setting to get

defaultValue - The value to return if the setting doesn't exist

Returns:

Value of the setting as a double (or the default value)

getCsvSetting

public java.lang.String[] getCsvSetting(java.lang.String name)

Returns a CSV setting. Value part of the setting must be a list of comma separated values. Whitespace between values is trimmed away.

Parameters:

name - Name of the setting

Returns:

Array of values that were comma-separated

Throws:

SettingsError - if something went wrong with reading

getCsvSetting

public java.lang.String[] getCsvSetting(java.lang.String name,
                               int expectedCount)

Returns a CSV setting containing expected amount of values. Value part of the setting must be a list of comma separated values. Whitespace between values is trimmed away.

Parameters:

name - Name of the setting

expectedCount - how many values are expected

Returns:

Array of values that were comma-separated

Throws:

SettingsError - if something went wrong with reading or didn't read the expected amount of values.

getCsvDoubles

public double[] getCsvDoubles(java.lang.String name,
                     int expectedCount)

Returns an array of CSV setting double values containing expected amount of values.

Parameters:

name - Name of the setting

expectedCount - how many values are expected

Returns:

Array of values that were comma-separated

See Also:

getCsvSetting(String, int)

getCsvDoubles

public double[] getCsvDoubles(java.lang.String name)

Returns an array of CSV setting double values.

Parameters:

name - Name of the setting

Returns:

Array of values that were comma-separated

See Also:

getCsvSetting(String)

getCsvInts

public int[] getCsvInts(java.lang.String name,
               int expectedCount)

Returns an array of CSV setting integer values

Parameters:

name - Name of the setting

expectedCount - how many values are expected

Returns:

Array of values that were comma-separated

See Also:

getCsvSetting(String, int)

getCsvInts

public int[] getCsvInts(java.lang.String name)

Returns an array of CSV setting integer values

Parameters:

name - Name of the setting

Returns:

Array of values that were comma-separated

See Also:

getCsvSetting(String, int)

getCsvRanges

public util.Range[] getCsvRanges(java.lang.String name)

Returns comma-separated ranges (e.g., "3-5, 17-20, 15")

Parameters:

name - Name of the setting

Returns:

Array of ranges that were comma-separated in the setting

Throws:

SettingsError - if something went wrong with reading

getInt

public int getInt(java.lang.String name)

Returns an integer-valued setting

Parameters:

name - Name of the setting to get

Returns:

Value of the setting as an integer

getInt

public int getInt(java.lang.String name,
         int defaultValue)

Returns an integer-valued setting, or the default value if the setting does not exist

Parameters:

name - Name of the setting to get

defaultValue - The value to return if the setting didn't exist

Returns:

Value of the setting as an integer

getBoolean

public boolean getBoolean(java.lang.String name)

Returns a boolean-valued setting

Parameters:

name - Name of the setting to get

Returns:

True if the settings value was either "true" (case ignored) or "1", false is the settings value was either "false" (case ignored) or "0".

Throws:

SettingsError - if the value wasn't any recognized value

See Also:

getSetting(String)

getBoolean

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

Returns the given boolean setting if it exists, or defaultValue if the setting does not exist

Parameters:

name - The name of the setting

defaultValue - The value to return if the given setting didn't exist

Returns:

The setting value or the default value if the setting didn't exist

getCondition

public ArithmeticCondition getCondition(java.lang.String name)

Returns an ArithmeticCondition setting. See ArithmeticCondition

Parameters:

name - Name of the setting to get

Returns:

ArithmeticCondition from the setting

Throws:

SettingsError - if the value wasn't a valid arithmetic expression

createIntializedObject

public java.lang.Object createIntializedObject(java.lang.String className)

Creates (and dynamically loads the class of) an object that initializes itself using the settings in this Settings object (given as the only parameter to the constructor).

Parameters:

className - Name of the class of the object

Returns:

Initialized object

Throws:

SettingsError - if object couldn't be created

createObject

public java.lang.Object createObject(java.lang.String className)

Creates (and dynamically loads the class of) an object using the constructor without any parameters.

Parameters:

className - Name of the class of the object

Returns:

Initialized object

Throws:

SettingsError - if object couldn't be created

valueFillString

public java.lang.String valueFillString(java.lang.String input)

Fills a String formatted in a special way with values from Settings. String can contain (fully qualified) setting names surrounded by delimiters (see FILL_DELIMITER). Values for those settings are retrieved and filled in the place of place holders.

Parameters:

input - The input string that may contain value requests

Returns:

A string filled with requested values (or the original string if no requests were found)

Throws:

SettingsError - if such settings were not found

toString

public java.lang.String toString()

Returns a String representation of the stored settings

Overrides:

toString in class java.lang.Object

Returns:

a String representation of the stored settings