Note that this documentation is for the old 5.55 release.
For the newest documentation, please see the current release documentation.

Settings

Owned by Colin Samuel Rosenthal
Nov 27, 2018
2 min read

Settings are read using methods in the class dk.netarkivet.common.utils.Settings.The declarations of the settings themselves are to be found in separate classes in each module. Every module except for the Deploy module has its own Settings class and a settings.xml file containing the default values for the module settings.

In addition, every plug-in may declare its own settings inside itself, and be associated with an xml-file containing the default values of these settings placed in the same directory as the plugin itself. For more information, please refer to the Configuration Basics description in the Configuration Manual.

Associated with most of the NetarchiveSuite plug-ins, there are also factory classes that hide the complexity behind selecting the correct plugin according to the chosen settings. The names of these classes all end in Factory, e.g. JMSConnectionFactory, RemoteFileFactory.

Almost all configuration of NetarchiveSuite is done through the main module Settings classes as for example the dk.netarkivet.common.Settings class. It provides a simple interface to the settings.xml file as well as definitions of all current configuration default settings. The settings.xml file itself is an XML file with a hierarchy based on the same structural breakdown as the NetarchiveSuite code modules.

Settings are referred to inside NetarchiveSuite by their path in the XML structure. For instance, the class ArchiveSettings contains the following code:

/**
 * <b>settings.archive.bitarchive.minSpaceRequired</b>: <br>
 * The minimum amount of bytes required left *in all dirs* after we have accepted an upload. If no dir has enough
 * space to store a received file and still have at least this much space left, the operation will result in an
 * error.
 */
public static String BITARCHIVE_MIN_SPACE_REQUIRED = "settings.archive.bitarchive.minSpaceRequired";

This defines a setting settings.archive.bitarchive.minSpaceRequired which can then be specified IN a settings.xml file or overridden as a system property on the command line (using the standard java -D parameter). All such settings must be properly documented in javadoc as shown in the example above.

To add a new setting, the following steps need to be taken:

1) The Settings class (e.g. ArchiveSettings) should get a definition for the path of the setting (see the snippet above). This String, although a constant, must not be declared final since settings are initialised by a static initialiser in the class

2) Javadoc for the definition must including the path name of the setting as well as a description of the setting.

3) All default settings.xml files must be updated (including those in the unit tests).

4) deploy/distribution/src/main/resources/examples/settings_example.xml) must be updated. This file will become examples/settings_example.xml in the distribution.zip file

5) update deploy/deploy-core/src/main/resources/dk/netarkivet/deploy/complete_settings.xml

Note that there is no XML Schema to be updated because i) the settings file has to be open to extension (by plugins) and ii) all settings are optional (for example they may already be set in a default file or on the command line). 

Note also that the Configuration Manual includes a description of how deploy can be used to validate whether the settings in a settings file are valid (not necessarily exhaustive!).