org.opencms.configuration
Class CmsParameterConfiguration

java.lang.Object
  java.util.AbstractMap<String,String>
      org.opencms.configuration.CmsParameterConfiguration

All Implemented Interfaces:

Map<String,String>

public class CmsParameterConfiguration
extends AbstractMap<String,String>

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?
 

Nested Class Summary

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

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

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

Map.Entry<K,V>

Field Summary

static CmsParameterConfiguration

EMPTY_PARAMETERS An empty, immutable parameter configuration.

Constructor Summary

CmsParameterConfiguration()
Creates an empty parameter configuration.

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

CmsParameterConfiguration(Map<String,String> configuration)
Creates a parameter configuration from a Map of Strings.

CmsParameterConfiguration(String file)
Creates a parameter wrapper by loading the parameters from the specified property file.

Method Summary

void	add(String key, String value) Add a parameter to this configuration.
Element	appendToXml(Element parentNode) Serializes this parameter configuration for the OpenCms XML configuration.
Element	appendToXml(Element parentNode, List<String> parametersToIgnore) Serializes this parameter configuration for the OpenCms XML configuration.
void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
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'.
protected static boolean	endsWithSlash(String line) Checks if the line ends with odd number of backslashes.
Set<Map.Entry<String,String>>	entrySet()
String	get(Object key) Returns the String associated with the given parameter.
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.
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.
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.
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.
Object	getObject(String key) Returns the raw Object associated with the given parameter, or null in case there is no Object for this parameter.
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.
int	hashCode()
Set<String>	keySet()
void	load(InputStream input) Load the parameters from the given input stream, which must be in property file format.
String	put(String key, String value) Set a parameter for this configuration.
void	putAll(Map<? extends String,? extends String> other) Merges this parameter configuration with the provided other parameter configuration.
String	remove(Object key) Removes a parameter from this configuration.
String	toString()
protected static String	unescape(String value) Replaces escaped char sequences in the input value.
static CmsParameterConfiguration	unmodifiableVersion(CmsParameterConfiguration original) Returns an unmodifiable version of this parameter configuration.
Collection<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

Field Detail

EMPTY_PARAMETERS

public static final CmsParameterConfiguration EMPTY_PARAMETERS

An empty, immutable parameter configuration.

Constructor Detail

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 Detail

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 Element appendToXml(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 Element appendToXml(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:

Map.clear()

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<String,String>

Overrides:

containsKey in class AbstractMap<String,String>

See Also:

Map.containsKey(java.lang.Object)

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<String,String>

Overrides:

containsValue in class AbstractMap<String,String>

See Also:

Map.containsValue(java.lang.Object)

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:

Map.entrySet()

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.

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:

Map.hashCode()

keySet

public Set<String> keySet()

Specified by:

keySet in interface Map<String,String>

Overrides:

keySet in class AbstractMap<String,String>

See Also:

Map.keySet()

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:

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:

Map.values()