dk.netarkivet.common.utils
Class Settings

java.lang.Object
  dk.netarkivet.common.utils.Settings

public class Settings
extends java.lang.Object

Provides access to general application settings. The settings are retrieved from xml files. XML files may be specified one of two places: 1) Default settings in XML files, specified by class path. These are intended to be packaged in the jar files, to provide a fallback for settings. 2) Overriding settings in XML files in file systems. These are intended to override the necessary values with minimal XML files. The location of these files are either specified by the system property SETTINGS_FILE_PROPERTY, multiple files can be separated by File.pathSeparator, that is ':' on linux and ';' on windows; or if that property is not set, the default location is DEFAULT_SETTINGS_FILEPATH.

Field Summary

static java.lang.String	DEFAULT_SETTINGS_FILEPATH The file path to look for settings in, if the system property SETTINGS_FILE_PROPERTY is not set.
static java.lang.String	SETTINGS_FILE_PROPERTY This system property specifies alternative position(s) to look for settings files.

Constructor Summary

Settings()

Method Summary

static void	addDefaultClasspathSettings(java.lang.String defaultClasspathSettingsPath) Add the settings file represented by this path to the list of default classpath settings.
static void	conditionalReload() Reload the settings if they have changed on disk.
static java.lang.String	get(java.lang.String key) Gets a setting.
static java.lang.String[]	getAll(java.lang.String key) Gets a list of settings.
static boolean	getBoolean(java.lang.String key) Gets a setting as a boolean.
static double	getDouble(java.lang.String key) Gets a setting as a double.
static java.io.File	getFile(java.lang.String key) Gets a setting as a file.
static int	getInt(java.lang.String key) Gets a setting as an int.
static long	getLong(java.lang.String key) Gets a setting as a long.
static java.util.List<java.io.File>	getSettingsFiles() Return the file these settings are read from.
static StringTree<java.lang.String>	getTree(java.lang.String path) Get a tree view of a part of the settings.
static void	reload() Reloads the settings.
static void	set(java.lang.String key, java.lang.String... values) Sets the key to one or more values.

Methods inherited from class java.lang.Object

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

Field Detail

SETTINGS_FILE_PROPERTY

public static final java.lang.String SETTINGS_FILE_PROPERTY

This system property specifies alternative position(s) to look for settings files. If more files are specified, they should be separated by File.pathSeparatorChar

See Also:

Constant Field Values

DEFAULT_SETTINGS_FILEPATH

public static final java.lang.String DEFAULT_SETTINGS_FILEPATH

The file path to look for settings in, if the system property SETTINGS_FILE_PROPERTY is not set.

See Also:

Constant Field Values

Constructor Detail

Settings

public Settings()

Method Detail

getSettingsFiles

public static java.util.List<java.io.File> getSettingsFiles()

Return the file these settings are read from. If the property given in the constructor is set, that will be used to determine the file. If it is not set, the default settings file path given in the constructor will be used.

Returns:

The settings file.

get

public static java.lang.String get(java.lang.String key)
                            throws UnknownID,
                                   IOFailure,
                                   ArgumentNotValid

Gets a setting. The search order for a given setting is as follows: First it is checked, if the argument key is set as a System property. If yes, return this value. If no, we continue the search. Secondly, we check, if the setting is in one of the loaded settings xml files. If the value is there, it is returned. If no, we continue the search. Finally, we check if the setting is in one of default settings files from classpath. If the value is there, it is returned. Otherwise an UnknownId exception is thrown. Note: The retrieved value can be the empty string

Parameters:

key - name of the setting to retrieve

Returns:

the retrieved value

Throws:

ArgumentNotValid - if key is null or the empty string

UnknownID - if no setting loaded matches key

IOFailure - if IO Failure

getInt

public static int getInt(java.lang.String key)
                  throws UnknownID,
                         ArgumentNotValid

Gets a setting as an int. This method calls get(key) and then parses the value as integer.

Parameters:

key - name of the setting to retrieve

Returns:

the retrieved int

Throws:

ArgumentNotValid - if key is null, the empty string or key is not parseable as an integer

UnknownID - if no setting loaded matches key

getLong

public static long getLong(java.lang.String key)
                    throws UnknownID,
                           ArgumentNotValid

Gets a setting as a long. This method calls get(key) and then parses the value as a long.

Parameters:

key - name of the setting to retrieve

Returns:

the retrieved long

Throws:

ArgumentNotValid - if key is null, the empty string or key is not parseable as a long

UnknownID - if no setting loaded matches key

getDouble

public static double getDouble(java.lang.String key)
                        throws UnknownID,
                               ArgumentNotValid

Gets a setting as a double. This method calls get(key) and then parses the value as a double.

Parameters:

key - name of the setting to retrieve

Returns:

the retrieved double

Throws:

ArgumentNotValid - if key is null, the empty string or key is not parseable as a double

UnknownID - if no setting loaded matches key

getFile

public static java.io.File getFile(java.lang.String key)

Gets a setting as a file. This method calls get(key) and then returns the value as a file.

Parameters:

key - name of the setting to retrieve

Returns:

the retrieved file

Throws:

ArgumentNotValid - if key is null, the empty string

UnknownID - if no setting loaded matches ke

getBoolean

public static boolean getBoolean(java.lang.String key)
                          throws UnknownID,
                                 ArgumentNotValid

Gets a setting as a boolean. This method calls get(key) and then parses the value as a boolean.

Parameters:

key - name of the setting to retrieve

Returns:

the retrieved boolean

Throws:

ArgumentNotValid - if key is null or the empty string

UnknownID - if no setting loaded matches key

getAll

public static java.lang.String[] getAll(java.lang.String key)
                                 throws UnknownID,
                                        ArgumentNotValid

Gets a list of settings. First it is checked, if the key is registered as a System property. If yes, registered value is returned in a list of length 1. If no, the data loaded from the settings xml files are examined. If value is there, it is returned in a list. If not, the default settings from classpath are examined. If values for this setting are found here, they are returned. Otherwise, an UnknownId exception is thrown. Note that the values will not be concatenated, the first place with a match will define the entire list. Furthemore the list cannot be empty.

Parameters:

key - name of the setting to retrieve

Returns:

the retrieved values (as a non-empty String array)

Throws:

ArgumentNotValid - if key is null or the empty string

UnknownID - if no setting loaded matches key

set

public static void set(java.lang.String key,
                       java.lang.String... values)

Sets the key to one or more values. Calls to this method are forgotten whenever the reload() is executed. TODO write these values to its own simpleXml structure, that are not reset during reload.

Parameters:

key - The settings key to add this under, legal keys are fields in this class.

values - The (ordered) list of values to put under this key.

Throws:

ArgumentNotValid - if key or values are null

UnknownID - if the key does not already exist

conditionalReload

public static void conditionalReload()

Reload the settings if they have changed on disk. This behaves exactly as forceReload, except it only reloads if the data of the file is different than last time it was loaded.

Throws:

IOFailure - if settings cannot be loaded

reload

public static void reload()

Reloads the settings. This will reload the settings from disk, and forget all settings that were set with set(java.lang.String, java.lang.String...) The field lastModified is updated to timestamp of the settings file that has been changed most recently.

Throws:

IOFailure - if settings cannot be loaded

See Also:

conditionalReload()

addDefaultClasspathSettings

public static void addDefaultClasspathSettings(java.lang.String defaultClasspathSettingsPath)

Add the settings file represented by this path to the list of default classpath settings.

Parameters:

defaultClasspathSettingsPath - the given default classpath setting.

getTree

public static StringTree<java.lang.String> getTree(java.lang.String path)

Get a tree view of a part of the settings. Note: settings read with this mechanism do not support overriding with system properties!

Parameters:

path - Dotted path to a unique element in the tree.

Returns:

The part of the setting structure below the element given.