dk.netarkivet.common.utils
Class SettingsStructure

java.lang.Object
  extended by dk.netarkivet.common.utils.SettingsStructure

public class SettingsStructure
extends java.lang.Object

Provides access to general application settings. The settings are retrieved from an xml file.


Field Summary
 int edition
          The edition of the Settings-object.
 
Constructor Summary
SettingsStructure(java.lang.String systemProperty, java.lang.String defaultSettingsFilepath)
          Create new instance, look for settings file in the following order: If the property given is set, data are loaded from this file Otherwise the file path given as default is used.
 
Method Summary
 void conditionalReload()
          Reload the settings if they have changed on disk.
 void create(java.lang.String key, java.lang.String... values)
          Create a new setting.
 java.lang.String get(java.lang.String key)
          Gets a setting.
 java.lang.String[] getAll(java.lang.String key)
          Gets a list of settings.
 int getEdition()
          Return the current edition of this class.
 int getInt(java.lang.String key)
          Gets a setting as an int.
 long getLong(java.lang.String key)
          Gets a setting as a long.
 java.io.File getSettingsFile()
          Return the file these settings are read from.
 void reload()
          Reloads the settings.
 void set(java.lang.String key, java.lang.String... values)
          Sets the key to one or more values.
 void validateStrings(java.lang.Class classToCheck, java.util.List<java.lang.String> excludedFields)
          Validate that the strings defined in the given class are present in the settings xml file.
 void validateWithXSD(java.io.File xsdFile)
          Validate that the settings xml file conforms to the XSD.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

edition

public int edition
The edition of the Settings-object. Each reload increases this edition by 1.

Constructor Detail

SettingsStructure

public SettingsStructure(java.lang.String systemProperty,
                         java.lang.String defaultSettingsFilepath)
Create new instance, look for settings file in the following order: If no settings file could be located all subsequent calls will fail.

Parameters:
systemProperty - The system property specifying the file path
defaultSettingsFilepath - The file path if the system property is not set.
Throws:
ArgumentNotValid - on null or empty parameters
IOFailure - if settings cannot be loaded
Method Detail

getSettingsFile

public java.io.File getSettingsFile()
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 java.lang.String get(java.lang.String key)
                     throws UnknownID,
                            IOFailure,
                            ArgumentNotValid
Gets a setting. First System.property is checked, if the key is registered here the registered value is returned, otherwise the data loaded from the settings xml file are checked.

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 no settings loaded.

getInt

public int getInt(java.lang.String key)
Gets a setting as an int. This method calls get(key) and then parses the value to int.

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 to int
UnknownID - if no setting loaded matches key
IOFailure - if no settings loaded.

getLong

public long getLong(java.lang.String key)
             throws UnknownID,
                    IOFailure,
                    ArgumentNotValid
Gets a setting as a long. This method calls get(key) and then parses the value to 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 to long
UnknownID - if no setting loaded matches key
IOFailure - if no settings loaded.

getAll

public java.lang.String[] getAll(java.lang.String key)
                          throws UnknownID,
                                 IOFailure,
                                 ArgumentNotValid
Gets a list of settings. First System.property is checked, if the key is registered here the registered value is returned in a list of length 1, otherwise the data loaded from the settings xml file are checked.

Parameters:
key - name of the setting to retrieve
Returns:
the retrieved values
Throws:
ArgumentNotValid - if key is null or the empty string
UnknownID - if no setting loaded matches key
IOFailure - if no settings loaded.

create

public void create(java.lang.String key,
                   java.lang.String... values)
            throws ArgumentNotValid
Create a new setting.

Parameters:
key - the name of the setting
values - the values
Throws:
ArgumentNotValid - if key or value is null, or if a corresponding key already exists.

set

public void set(java.lang.String key,
                java.lang.String... values)
Sets the key to one or more values. The key must exist beforehand.

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 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 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...) or create(java.lang.String, java.lang.String...)

Throws:
IOFailure - if settings cannot be loaded
See Also:
conditionalReload()

validateWithXSD

public void validateWithXSD(java.io.File xsdFile)
Validate that the settings xml file conforms to the XSD.

Parameters:
xsdFile - Schema to check settings against.

getEdition

public int getEdition()
Return the current edition of this class. This will increase by one on each reload of settings.

Returns:
the current edition of this class

validateStrings

public void validateStrings(java.lang.Class classToCheck,
                            java.util.List<java.lang.String> excludedFields)
Validate that the strings defined in the given class are present in the settings xml file. Checks all static String fields that are not explicitly excluded above. This asserts the correspondence between the settings we think we have and those defined in the XSD/.xml file.

Parameters:
classToCheck - The class defining the constants to check
excludedFields - Fields not to check, even thoug they are constants in that class.