Package org.opencms.configuration

Class CmsParameterConfiguration

  • All Implemented Interfaces:
    java.io.Serializable, java.util.Map<java.lang.String,​java.lang.String>
    public class CmsParameterConfiguration
extends java.util.AbstractMap<java.lang.String,​java.lang.String>
implements java.io.Serializable
    Provides convenient access to configuration parameters.

    Usually the parameters are configured in some sort of String based file, either in an XML configuration, or in a .property file. This wrapper allows accessing such String values directly as int, boolean or other data types, without worrying about the type conversion.

    It can also read a configuration from a special property file format, which is explained here:

    • Each parameter in the file has the syntax key = value
    • The key may use any character but the equal sign '='.
    • value may be separated on different lines if a backslash is placed at the end of the line that continues below.
    • If value is a list of strings, each token is separated by a comma ','.
    • Commas in each token are escaped placing a backslash right before the comma.
    • Backslashes are escaped by using two consecutive backslashes i.e. \\. Note: Unlike in regular Java properties files, you don't need to escape Backslashes.
    • If a key is used more than once, the values are appended as if they were on the same line separated with commas.
    • Blank lines and lines starting with character '#' are skipped.
    Here is an example of a valid parameter properties file:

          # lines starting with # are comments

      # This is the simplest property
      key = value

      # A long property may be separated on multiple lines
      longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
                  aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

      # This is a property with many tokens
      tokens_on_a_line = first token, second token

      # This sequence generates exactly the same result
      tokens_on_multiple_lines = first token
      tokens_on_multiple_lines = second token

      # commas may be escaped in tokens
      commas.escaped = Hi\, what'up?
    See Also:
    Serialized Form

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected static class  CmsParameterConfiguration.ParameterReader
      Used to read parameter lines from a property file.
      protected static class  CmsParameterConfiguration.ParameterTokenizer
      This class divides property value into tokens separated by ",".

      • Nested classes/interfaces inherited from class java.util.AbstractMap

        java.util.AbstractMap.SimpleEntry<K extends java.lang.Object,​V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,​V extends java.lang.Object>

      • Nested classes/interfaces inherited from interface java.util.Map

        java.util.Map.Entry<K extends java.lang.Object,​V extends java.lang.Object>

    • Constructor Summary

      Constructors 
      Constructor Description
      CmsParameterConfiguration()
      Creates an empty parameter configuration.
      CmsParameterConfiguration​(java.io.InputStream in)
      Creates a parameter configuration from an input stream.
      CmsParameterConfiguration​(java.lang.String file)
      Creates a parameter wrapper by loading the parameters from the specified property file.
      CmsParameterConfiguration​(java.util.Map<java.lang.String,​java.lang.String> configuration)
      Creates a parameter configuration from a Map of Strings.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(java.lang.String key, java.lang.String value)
      Add a parameter to this configuration.
      org.dom4j.Element appendToXml​(org.dom4j.Element parentNode)
      Serializes this parameter configuration for the OpenCms XML configuration.
      org.dom4j.Element appendToXml​(org.dom4j.Element parentNode, java.util.List<java.lang.String> parametersToIgnore)
      Serializes this parameter configuration for the OpenCms XML configuration.
      void clear()  
      boolean containsKey​(java.lang.Object key)  
      boolean containsValue​(java.lang.Object value)  
      protected static int countPreceding​(java.lang.String line, int index, char ch)
      Counts the number of successive times 'ch' appears in the 'line' before the position indicated by the 'index'.
      protected static boolean endsWithSlash​(java.lang.String line)
      Checks if the line ends with odd number of backslashes.
      java.util.Set<java.util.Map.Entry<java.lang.String,​java.lang.String>> entrySet()  
      java.lang.String get​(java.lang.Object key)
      Returns the String associated with the given parameter.
      boolean getBoolean​(java.lang.String key, boolean defaultValue)
      Returns the boolean associated with the given parameter, or the default value in case there is no boolean value for this parameter.
      int getInteger​(java.lang.String key, int defaultValue)
      Returns the integer associated with the given parameter, or the default value in case there is no integer value for this parameter.
      java.util.List<java.lang.String> getList​(java.lang.String key)
      Returns the List of Strings associated with the given parameter, or an empty List in case there is no List of Strings for this parameter.
      java.util.List<java.lang.String> getList​(java.lang.String key, java.util.List<java.lang.String> defaultValue)
      Returns the List of Strings associated with the given parameter, or the default value in case there is no List of Strings for this parameter.
      java.lang.Object getObject​(java.lang.String key)
      Returns the raw Object associated with the given parameter, or null in case there is no Object for this parameter.
      java.util.Properties getPrefixedProperties​(java.lang.String keyPrefix)
      Creates a new Properties object from the existing configuration extracting all key-value pars whose key are prefixed with keyPrefix.
      java.lang.String getString​(java.lang.String key, java.lang.String defaultValue)
      Returns the String associated with the given parameter, or the given default value in case there is no value for this parameter.
      int hashCode()  
      java.util.Set<java.lang.String> keySet()  
      void load​(java.io.InputStream input)
      Load the parameters from the given input stream, which must be in property file format.
      java.lang.String put​(java.lang.String key, java.lang.String value)
      Set a parameter for this configuration.
      void putAll​(java.util.Map<? extends java.lang.String,​? extends java.lang.String> other)
      Merges this parameter configuration with the provided other parameter configuration.
      java.lang.String remove​(java.lang.Object key)
      Removes a parameter from this configuration.
      java.lang.String toString()  
      protected static java.lang.String unescape​(java.lang.String value)
      Replaces escaped char sequences in the input value.
      static CmsParameterConfiguration unmodifiableVersion​(CmsParameterConfiguration original)
      Returns an unmodifiable version of this parameter configuration.
      java.util.Collection<java.lang.String> values()  

      • Methods inherited from class java.util.AbstractMap

        clone, equals, isEmpty, size

      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.util.Map

        compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll

    • Constructor Detail

      • CmsParameterConfiguration

        public CmsParameterConfiguration​(java.io.InputStream in)
                          throws java.io.IOException
        Creates a parameter configuration from an input stream.

        Parameters:
        in - the input stream to create the parameter configuration from
        Throws:
        java.io.IOException - in case of errors loading the parameters from the input stream

      • CmsParameterConfiguration

        public CmsParameterConfiguration​(java.util.Map<java.lang.String,​java.lang.String> configuration)
        Creates a parameter configuration from a Map of Strings.

        Parameters:
        configuration - the map of Strings to create the parameter configuration from

      • CmsParameterConfiguration

        public CmsParameterConfiguration​(java.lang.String file)
                          throws java.io.IOException
        Creates a parameter wrapper by loading the parameters from the specified property file.

        Parameters:
        file - the path of the file to load
        Throws:
        java.io.IOException - in case of errors loading the parameters from the specified property file

    • Method Detail

      • countPreceding

        protected static int countPreceding​(java.lang.String line,
                                    int index,
                                    char ch)
        Counts the number of successive times 'ch' appears in the 'line' before the position indicated by the 'index'.

        Parameters:
        line - the line to count
        index - the index position to start
        ch - the character to count
        Returns:
        the number of successive times 'ch' appears in the 'line' before the position indicated by the 'index'

      • endsWithSlash

        protected static boolean endsWithSlash​(java.lang.String line)
        Checks if the line ends with odd number of backslashes.

        Parameters:
        line - the line to check
        Returns:
        true if the line ends with odd number of backslashes

      • unescape

        protected static java.lang.String unescape​(java.lang.String value)
        Replaces escaped char sequences in the input value.

        Parameters:
        value - the value to unescape
        Returns:
        the unescaped String

      • add

        public void add​(java.lang.String key,
                java.lang.String value)
        Add a parameter to this configuration.

        If the parameter already exists then the value will be added to the existing configuration entry and a List will be created for the values.

        String values separated by a comma "," will NOT be tokenized when this method is used. To create a List of String values for a parameter, call this method multiple times with the same parameter name.

        Parameters:
        key - the parameter to add
        value - the value to add

      • appendToXml

        public org.dom4j.Element appendToXml​(org.dom4j.Element parentNode)
        Serializes this parameter configuration for the OpenCms XML configuration.

        For each parameter, a XML node like this
        <param name="theName">theValue</param>
        is generated and appended to the provided parent node.

        Parameters:
        parentNode - the parent node where the parameter nodes are appended to
        Returns:
        the parent node

      • appendToXml

        public org.dom4j.Element appendToXml​(org.dom4j.Element parentNode,
                                     java.util.List<java.lang.String> parametersToIgnore)
        Serializes this parameter configuration for the OpenCms XML configuration.

        For each parameter, a XML node like this
        <param name="theName">theValue</param>
        is generated and appended to the provided parent node.

        Parameters:
        parentNode - the parent node where the parameter nodes are appended to
        parametersToIgnore - if not null, all parameters in this list are not written to the XML
        Returns:
        the parent node

      • clear

        public void clear()
        Specified by:
        clear in interface java.util.Map<java.lang.String,​java.lang.String>
        Overrides:
        clear in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        See Also:
        Map.clear()

      • containsKey

        public boolean containsKey​(java.lang.Object key)
        Specified by:
        containsKey in interface java.util.Map<java.lang.String,​java.lang.String>
        Overrides:
        containsKey in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        See Also:
        Map.containsKey(java.lang.Object)

      • containsValue

        public boolean containsValue​(java.lang.Object value)
        Specified by:
        containsValue in interface java.util.Map<java.lang.String,​java.lang.String>
        Overrides:
        containsValue in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        See Also:
        Map.containsValue(java.lang.Object)

      • entrySet

        public java.util.Set<java.util.Map.Entry<java.lang.String,​java.lang.String>> entrySet()
        Specified by:
        entrySet in interface java.util.Map<java.lang.String,​java.lang.String>
        Specified by:
        entrySet in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        See Also:
        Map.entrySet()

      • get

        public java.lang.String get​(java.lang.Object key)
        Returns the String associated with the given parameter.

        Specified by:
        get in interface java.util.Map<java.lang.String,​java.lang.String>
        Overrides:
        get in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        Parameters:
        key - the parameter to look up the value for
        Returns:
        the String associated with the given parameter

      • getBoolean

        public boolean getBoolean​(java.lang.String key,
                          boolean defaultValue)
        Returns the boolean associated with the given parameter, or the default value in case there is no boolean value for this parameter.

        Parameters:
        key - the parameter to look up the value for
        defaultValue - the default value
        Returns:
        the boolean associated with the given parameter, or the default value in case there is no boolean value for this parameter

      • getInteger

        public int getInteger​(java.lang.String key,
                      int defaultValue)
        Returns the integer associated with the given parameter, or the default value in case there is no integer value for this parameter.

        Parameters:
        key - the parameter to look up the value for
        defaultValue - the default value
        Returns:
        the integer associated with the given parameter, or the default value in case there is no integer value for this parameter

      • getList

        public java.util.List<java.lang.String> getList​(java.lang.String key)
        Returns the List of Strings associated with the given parameter, or an empty List in case there is no List of Strings for this parameter.

        The list returned is a copy of the internal data of this object, and as such you may alter it freely.

        Parameters:
        key - the parameter to look up the value for
        Returns:
        the List of Strings associated with the given parameter, or an empty List in case there is no List of Strings for this parameter

      • getList

        public java.util.List<java.lang.String> getList​(java.lang.String key,
                                                java.util.List<java.lang.String> defaultValue)
        Returns the List of Strings associated with the given parameter, or the default value in case there is no List of Strings for this parameter.

        The list returned is a copy of the internal data of this object, and as such you may alter it freely.

        Parameters:
        key - the parameter to look up the value for
        defaultValue - the default value
        Returns:
        the List of Strings associated with the given parameter, or the default value in case there is no List of Strings for this parameter

      • getObject

        public java.lang.Object getObject​(java.lang.String key)
        Returns the raw Object associated with the given parameter, or null in case there is no Object for this parameter.

        Parameters:
        key - the parameter to look up the value for
        Returns:
        the raw Object associated with the given parameter, or null in case there is no Object for this parameter.

      • getPrefixedProperties

        public java.util.Properties getPrefixedProperties​(java.lang.String keyPrefix)
        Creates a new Properties object from the existing configuration extracting all key-value pars whose key are prefixed with keyPrefix.

        For this example config: 

              # lines starting with # are comments
      db.pool.default.jdbcDriver=net.bull.javamelody.JdbcDriver
      db.pool.default.connectionProperties.driver=com.mysql.cj.jdbc.Driver
        getPrefixedProperties("db.pool.default.connectionProperties") will return a Properties object with one single entry: 
              key:"driver", value:"com.mysql.cj.jdbc.Driver"
        Parameters:
        keyPrefix - prefix to match. If it isn't already, it will be terminated with a dot. If null, it will return an empty Properties instance
        Returns:
        a new Properties object with all the entries from this configuration whose keys math the prefix

      • getString

        public java.lang.String getString​(java.lang.String key,
                                  java.lang.String defaultValue)
        Returns the String associated with the given parameter, or the given default value in case there is no value for this parameter.

        Parameters:
        key - the parameter to look up the value for
        defaultValue - the default value
        Returns:
        the String associated with the given parameter, or the given default value in case there is no value for this parameter.

      • hashCode

        public int hashCode()
        Specified by:
        hashCode in interface java.util.Map<java.lang.String,​java.lang.String>
        Overrides:
        hashCode in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        See Also:
        Map.hashCode()

      • keySet

        public java.util.Set<java.lang.String> keySet()
        Specified by:
        keySet in interface java.util.Map<java.lang.String,​java.lang.String>
        Overrides:
        keySet in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        See Also:
        Map.keySet()

      • load

        public void load​(java.io.InputStream input)
          throws java.io.IOException
        Load the parameters from the given input stream, which must be in property file format.

        Parameters:
        input - the stream to load the input from
        Throws:
        java.io.IOException - in case of IO errors reading from the stream

      • put

        public java.lang.String put​(java.lang.String key,
                            java.lang.String value)
        Set a parameter for this configuration.

        If the parameter already exists then the existing value will be replaced.

        Specified by:
        put in interface java.util.Map<java.lang.String,​java.lang.String>
        Overrides:
        put in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        Parameters:
        key - the parameter to set
        value - the value to set
        Returns:
        the previous String value from the parameter map

      • putAll

        public void putAll​(java.util.Map<? extends java.lang.String,​? extends java.lang.String> other)
        Merges this parameter configuration with the provided other parameter configuration.

        The difference form a simple Map<String, String> is that for the parameter configuration, the values of the keys in both maps are merged and kept in the Object store as a List.

        As result, this configuration will be altered, the other configuration will stay unchanged.

        Specified by:
        putAll in interface java.util.Map<java.lang.String,​java.lang.String>
        Overrides:
        putAll in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        Parameters:
        other - the other parameter configuration to merge this configuration with

      • remove

        public java.lang.String remove​(java.lang.Object key)
        Removes a parameter from this configuration.
        Specified by:
        remove in interface java.util.Map<java.lang.String,​java.lang.String>
        Overrides:
        remove in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        Parameters:
        key - the parameter to remove

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        See Also:
        java.util.Map#toString()

      • values

        public java.util.Collection<java.lang.String> values()
        Specified by:
        values in interface java.util.Map<java.lang.String,​java.lang.String>
        Overrides:
        values in class java.util.AbstractMap<java.lang.String,​java.lang.String>
        See Also:
        Map.values()