Class 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.
    • Constructor Summary

      Constructors 
      Constructor Description
      Settings()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void addDefaultClasspathSettings​(java.lang.String defaultClasspathSettingsPath)
      Add the settings file represented by this path to the list of default classpath settings.
      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.
      static boolean verifyClass​(java.lang.String classname)
      Verify, if the given class exists in the classpath.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • 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
      • 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.
      • verifyClass

        public static boolean verifyClass​(java.lang.String classname)
        Verify, if the given class exists in the classpath.
        Parameters:
        classname - A given class to check for
        Returns:
        true, if the given class exists in the classpath, else false