Package org.opencms.configuration

Class CmsParameterConfiguration

java.lang.Object
java.util.AbstractMap<String,String>
org.opencms.configuration.CmsParameterConfiguration
All Implemented Interfaces:
Serializable, Map<String,String>
public class CmsParameterConfiguration extends AbstractMap<String,String> implements 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:

  • Field Details

  • Constructor Details

    • CmsParameterConfiguration

      public CmsParameterConfiguration()
      Creates an empty parameter configuration.

    • CmsParameterConfiguration

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

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

    • CmsParameterConfiguration

      public CmsParameterConfiguration(Map<String,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(String file) throws IOException
      Creates a parameter wrapper by loading the parameters from the specified property file.

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

  • Method Details

    • unmodifiableVersion

      public static CmsParameterConfiguration unmodifiableVersion(CmsParameterConfiguration original)
      Returns an unmodifiable version of this parameter configuration.

      Parameters:
      original - the configuration to make unmodifiable
      Returns:
      an unmodifiable version of this parameter configuration

    • countPreceding

      protected static int countPreceding(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(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 String unescape(String value)
      Replaces escaped char sequences in the input value.

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

    • add

      public void add(String key, 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, List<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 Map<String,String>
      Overrides:
      clear in class AbstractMap<String,String>
      See Also:

    • containsKey

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

    • containsValue

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

    • entrySet

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

    • get

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

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

    • getBoolean

      public boolean getBoolean(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(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 List<String> getList(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 List<String> getList(String key, List<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 Object getObject(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 Properties getPrefixedProperties(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 String getString(String key, 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 Map<String,String>
      Overrides:
      hashCode in class AbstractMap<String,String>
      See Also:

    • keySet

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

    • load

      public void load(InputStream input) throws 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:
      IOException - in case of IO errors reading from the stream

    • put

      public String put(String key, 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 Map<String,String>
      Overrides:
      put in class AbstractMap<String,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(Map<? extends String,? extends 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 Map<String,String>
      Overrides:
      putAll in class AbstractMap<String,String>
      Parameters:
      other - the other parameter configuration to merge this configuration with

    • remove

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

    • toString

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

    • values

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