Configuration (Tammi Framework API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.norther.tammi.core.config
Class Configuration

java.lang.Object
  java.util.AbstractMap<K,V>
      org.norther.tammi.acorn.util.ConcurrentAbstractMap<K,V>
          org.norther.tammi.acorn.util.ConcurrentReadMap<K,V>
              org.norther.tammi.acorn.util.OrderedHashMap<String,Object>
                  org.norther.tammi.core.config.Configuration

All Implemented Interfaces:: Serializable, Cloneable, ConcurrentMap<String,Object>, Map<String,Object>, Traceable, OrderedMap<String,Object>

public class Configuration
extends OrderedHashMap<String,Object>
implements Traceable, Serializable, Cloneable
extends OrderedHashMap<String,Object>
implements Traceable, Serializable, Cloneable

An extension to java.util.Properties adding the possibility to use the same key many times concatenating the value strings instead of overwriting them.

The extended properties syntax is explained below:

Each property has the syntax key = value, or alternatively key: value.
Also, any whitespace character is considered a delimiter between the key and the value.
Alternative key delimiters can be specified by setKeyDelimiter() and getKeyDelimiter().
Within a property file, if a property is named "delimiter" (or whatever is defined by setDelimiterKey() and getDelimiterKey()), delimiters are temporarily changed to the value of that property.
The key may contain any characters but the delimiters without escaping. Delimiters can be espcaped with a backslash.
The value may be divided into separate lines, if a backslash is placed at the end of the line which continues below.
If the value is an array of strings, each token is separated by an item separator specified by setItemSeparator() and getItemSeparator(). By default, arrays are disabled and the separator is null.
Within a property file, if a property is named "separator" (or whatever is defined by setSeparatorKey() and getSeparatorKey()), separators are temporarily changed to the value of that property. Separators cannot be changed if they are originally disabled.
Separators in each token are escaped by placing a backslash right before the separator.
If the key is used more than once and arrays are not disabled, the values are appended like if they were on the same line separated with separators.
Blank lines and lines starting with characters '#' or '!' are skipped.
If a property is named "include" (or whatever is defined by setIncludeKey() and getIncludeKey()) and the value of that property is a path to a file on disk, that file will be included into the Configuration. The path is resolved using the path finder. For example:
```
 include = additional.properties
 
```
will include the additional.properties file as if it was part of the original property file. The suffix of the include property, e.g. "include.resource", is used as a key for the path finder. The root folder is applied if the key is not specified.

Here is an example of a valid extended 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
 ##
 # Separators may be escaped in tokens.
 commas.excaped = Hi\, what'up?

NOTE : this class has not been written for performance nor low memory usage. In fact, it's way slower than it could be and generates too much memory garbage. But since performance is not an issue during intialization (and there is not much time to improve it), I wrote it this way. If you don't like it, go ahead and tune it up!

Based on ExtendedProperties in the Apache Jakarta Commons project.

Version:: $Id: Configuration.java,v 1.43 2009/09/28 15:08:44 cvsimp Exp $
Author:: Stefano Mazzocchi, Jon S. Stevens, Dave Bryson, Jason van Zyl, Geir Magnusson Jr., Leon Messerschmidt, Kent Johnson, Daniel Rall, Ilkka Priha
See Also:: Serialized Form

Nested Class Summary
`protected static class`	`Configuration.PropertiesReader` This class is used to read properties lines.

Nested classes/interfaces inherited from class org.norther.tammi.acorn.util.ConcurrentAbstractMap
`ConcurrentAbstractMap.ConcurrentEntry<K,V>, ConcurrentAbstractMap.Modification`

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

Fields inherited from class org.norther.tammi.acorn.util.ConcurrentReadMap
`DEFAULT_CAPACITY, MAXIMUM_CAPACITY, MINIMUM_CAPACITY`

Fields inherited from class org.norther.tammi.acorn.util.ConcurrentAbstractMap
`DEFAULT_LOAD_FACTOR`

Constructor Summary
`Configuration()` Creates an empty extended properties instance.
`Configuration(Configuration defs)` Creates an empty extended properties instance with defaults.
`Configuration(MBeanReference<?> reference)` Creates an empty extended properties instance for the specified MBean.
`Configuration(MBeanReference<?> reference, Configuration defs)` Creates an empty extended properties instance for the specified MBean with defaults.
`Configuration(MBeanReference<?> reference, String path)` Creates and loads extended properties from the specified file for the specified MBean.
`Configuration(MBeanReference<?> reference, String path, String defaultPath)` Creates and loads extended properties from the specified file with default values from another file for the specified MBean.
`Configuration(String path)` Creates and loads extended properties from the specified file.
`Configuration(String path, String defaultPath)` Creates and loads extended properties from the specified file with default values from another file.

Method Summary
`boolean`	`add(String key, Object value)` Associates the specified value with the specified key in this map if not already mapped.
`boolean`	`addAt(int index, String key, Object value)` Associates the specified value with the specified key at the specified index in this map if not already mapped.
`void`	`addProperties(int index, String key, String[] values)` Adds multivalued property values at the specified index.
`void`	`addProperties(int index, String key, String[] values, String separator)` Adds multivalued property values at the specified index with the specified separator.
`void`	`addProperties(String key, String[] values)` Adds multivalued property values.
`void`	`addProperty(int index, String key, String value)` Adds a multivalued property value at the specified index.
`void`	`addProperty(String key, String value)` Adds a multivalued property value.
`void`	`addTraceListener(TraceListener listener)` Adds a listener if not already present.
`void`	`clear()`
`void`	`clearLastModified()` Clears the timestamp of the last modification of the traced object.
`void`	`clearTraceListeners()` Clears all listeners from this traceable.
`Object`	`clone()`
`boolean`	`containsProperty(String key)` Checks whether a property is available.
`boolean`	`getBoolean(String key)` Gets a boolean property value.
`boolean`	`getBoolean(String key, boolean defaultValue)` Gets a boolean property value with a default.
`Boolean`	`getBoolean(String key, Boolean defaultValue)` Gets a Boolean property value with a default.
`byte`	`getByte(String key)` Gets a byte property value.
`byte`	`getByte(String key, byte defaultValue)` Gets a byte property value with a default.
`Byte`	`getByte(String key, Byte defaultValue)` Gets a Byte property value with a default.
`static String`	`getDelimiterKey()` Gets the property key for a key delimiter.
`double`	`getDouble(String key)` Gets a double property value.
`double`	`getDouble(String key, double defaultValue)` Gets a double property value with a default.
`Double`	`getDouble(String key, Double defaultValue)` Gets a Double property value with a default.
`float`	`getFloat(String key)` Gets a float property value.
`float`	`getFloat(String key, float defaultValue)` Gets a float property value with a default.
`Float`	`getFloat(String key, Float defaultValue)` Gets a Float property value with a default.
`static String`	`getIncludeKey()` Gets the property key for including other properties files.
`int`	`getInt(String key)` Gets an int property value.
`int`	`getInt(String key, int defaultValue)` Gets an int property value with a default.
`Integer`	`getInteger(String key, Integer defaultValue)` Gets an Integer property value with a default.
`String`	`getItemSeparator()` Gets the item separator(s).
`String`	`getKeyDelimiter()` Gets the key delimiters(s).
`long`	`getLastModified()` Gets the timestamp of the last modification of the traced object.
`long`	`getLastModified(Object key)` Gets the timestamp of the last modification of the specified resource.
`long`	`getLong(String key)` Gets a long property value.
`long`	`getLong(String key, long defaultValue)` Gets a long property value with a default.
`Long`	`getLong(String key, Long defaultValue)` Gets a Long property value with a default.
`static String`	`getNullKey()` Gets the property key for a null value.
`String`	`getNullValue()` Gets the null value.
`String[]`	`getProperties(String key)` Gets a multivalued property value.
`String[]`	`getProperties(String key, String[] defaultValues)` Gets multivalued property values with defaults.
`String`	`getProperty(String key)` Gets a property value.
`String`	`getProperty(String key, String defaultValue)` Gets a property value with a default.
`static String`	`getSeparatorKey()` Gets the property key for a list separator.
`short`	`getShort(String key)` Gets a short property value.
`short`	`getShort(String key, short defaultValue)` Gets a short property value with a default.
`Short`	`getShort(String key, Short defaultValue)` Gets a Short property value with a default.
`int`	`indexOfProperty(String key, String value)` Returns the index of a multivalued property value.
`void`	`load(InputStream input)` Loads the properties from an input stream by applying the ISO-8859-1 encoding to be compatible with `java.util.Properties`.
`void`	`load(InputStream input, String encoding)` Loads the properties from an input stream using the specified encoding.
`void`	`load(Properties props)` Loads the properties from properties.
`void`	`load(Reader reader)` Loads the properties from a reader.
`void`	`loadFromXML(InputStream input)` Loads the properties represented by the XML document on the specified input stream into this configuration.
`void`	`loadProperty(String key, String value)` Loads a property by applying the same escaping rules as other load methods.
`void`	`merge(Map<String,Object> map)` Merges the specified map to this configuration.
`Enumeration<String>`	`propertyNames()` Returns an enumeration of all property names including the defaults.
`Object`	`put(int index, String key, Object value)` Associates the specified value with the specified key at the specified index in this map.
`Object`	`put(String key, Object value)`
`Object`	`putIfAbsent(int index, String key, Object value)` Associates the specified value with the specified key at the specified index in this map if not already mapped.
`Object`	`putIfAbsent(String key, Object value)`
`Object`	`remove(Object key)`
`boolean`	`remove(Object key, Object value)`
`Map.Entry<String,Object>`	`removeAt(int index)` Removes the indexed element in this map.
`boolean`	`removeProperties(String key, String[] values)` Removes multivalued property values.
`Object`	`removeProperty(String key)` Removes a property.
`boolean`	`removeProperty(String key, String value)` Removes a multivalued property value.
`void`	`removeTraceListener(TraceListener listener)` Removes a listener.
`Object`	`replace(int index, Object value)` Replaces the indexed element in this map.
`Object`	`replace(String key, Object value)`
`boolean`	`replace(String key, Object oldValue, Object newValue)`
`static void`	`setDelimiterKey(String key)` Sets the property key for a key delimiter.
`static void`	`setIncludeKey(String key)` Sets the property key for including other properties files.
`void`	`setItemSeparator(String separator)` Sets the item separator(s).
`void`	`setKeyDelimiter(String delimiter)` Sets the key delimiter(s).
`void`	`setLastModified(Object key, long timestamp)` Sets the timestamp of the last modification of the specified resource.
`static void`	`setNullKey(String key)` Sets the property key for a null value.
`void`	`setNullValue(String nul)` Sets the null value.
`Object`	`setProperties(String key, String[] values)` Sets a multivalued property value.
`Object`	`setProperty(String key, String value)` Sets a property value.
`static void`	`setSeparatorKey(String key)` Sets the property key for a list separator.
`void`	`store(OutputStream output, String header)` Stores the properties to the given output stream using uencoding.
`void`	`store(OutputStream output, String header, String encoding)` Stores the properties to the given output stream using the specified encoding.
`void`	`store(Writer writer, String header)` Stores the properties to the given writer.
`void`	`storeToXML(OutputStream output, String header)` Stores an XML document representing the properties contained in this configuration by applying the UTF-8 encoding.
`void`	`storeToXML(OutputStream output, String header, String encoding)` Stores an XML document representing the properties contained in this configuration by applying the specified encoding.
`Set<String>`	`stringPropertyNames()` Returns a set of all property names including the defaults.
`Configuration`	`subset(String prefix)` Returns a configuration that is a subset of this one.
`Configuration`	`subset(String prefix, String suffix)` Returns a configuration that is a subset of this one.
`Properties`	`toProperties()` Converts this configuration to properties.
`Properties`	`toProperties(String prefix)` Converts a subset of this configuration to properties.

Methods inherited from class org.norther.tammi.acorn.util.OrderedHashMap
`elements, entryList, entrySet, get, getEntryAt, getKeyAt, indexOfKey, isModifiable, keyList, keys, keySet, putAll, putEntry, removeEntry, set, shift, valueList, values`

Methods inherited from class org.norther.tammi.acorn.util.ConcurrentReadMap
`capacity, containsValue, getEntry, getEntryTable, isEmpty, putAll, rehash, replaceEntry, setEntryTable, size`

Methods inherited from class org.norther.tammi.acorn.util.ConcurrentAbstractMap
`capacity, contains, containsKey, get`

Methods inherited from class java.util.AbstractMap
`equals, hashCode, toString`

Methods inherited from class java.lang.Object
`finalize, getClass, notify, notifyAll, wait, wait, wait`

Methods inherited from interface java.util.Map
`containsKey, containsValue, equals, get, hashCode, isEmpty, putAll, size`

Constructor Detail

Configuration

public Configuration()

Creates an empty extended properties instance.

Configuration

public Configuration(Configuration defs)

Creates an empty extended properties instance with defaults.

Parameters:: defs - the default configuration.

Configuration

public Configuration(String path)
              throws IOException

Creates and loads extended properties from the specified file.

Parameters:: path - the pathname of the properties file.
Throws:: IOException - on I/O errors.

Configuration

public Configuration(String path,
                     String defaultPath)
              throws IOException

Creates and loads extended properties from the specified file with default values from another file.

Parameters:: path - the pathname of the properties file.; defaultPath - the pathname of the defaults file.
Throws:: IOException - on I/O errors.

Configuration

public Configuration(MBeanReference<?> reference)

Creates an empty extended properties instance for the specified MBean.

Parameters:: reference - the MBean reference.

Configuration

public Configuration(MBeanReference<?> reference,
                     Configuration defs)

Creates an empty extended properties instance for the specified MBean with defaults.

Parameters:: reference - the MBean reference.; defs - the default configuration.

Configuration

public Configuration(MBeanReference<?> reference,
                     String path)
              throws IOException

Creates and loads extended properties from the specified file for the specified MBean. The file is searched for from root folder of the path finder.

Parameters:: reference - the MBean reference.; path - the pathname of the properties file.
Throws:: IOException - on I/O errors.

Configuration

public Configuration(MBeanReference<?> reference,
                     String path,
                     String defaultPath)
              throws IOException

Creates and loads extended properties from the specified file with default values from another file for the specified MBean. The files are searched for from the root folder of the path finder.

Parameters:: reference - the MBean reference.; path - the pathname of the properties file.; defaultPath - the pathname of the defaults file.
Throws:: IOException - on I/O errors.

Method Detail

getNullKey

public static String getNullKey()

Gets the property key for a null value. By default it is "null".

Returns:: the null value property key.

setNullKey

public static void setNullKey(String key)

Sets the property key for a null value. By default it is "null".

Parameters:: key - the null value property key.

getDelimiterKey

public static String getDelimiterKey()

Gets the property key for a key delimiter. By default it is "delimiter".

Returns:: the key delimiter property key.

setDelimiterKey

public static void setDelimiterKey(String key)

Sets the property key for a key delimiter. By default it is "delimiter".

Parameters:: key - the key delimiter property key.

getSeparatorKey

public static String getSeparatorKey()

Gets the property key for a list separator. By default it is "separator".

Returns:: the list separator property key.

setSeparatorKey

public static void setSeparatorKey(String key)

Sets the property key for a list separator. By default it is "separator".

Parameters:: key - the list separator property key.

getIncludeKey

public static String getIncludeKey()

Gets the property key for including other properties files. By default it is "include".

Returns:: the include property key.

setIncludeKey

public static void setIncludeKey(String key)

Sets the property key for including other properties files. By default it is "include".

Parameters:: key - the include property key.

clone

public Object clone()

Overrides:: clone in class OrderedHashMap<String,Object>

clear

public void clear()

Specified by:: clear in interface Map<String,Object>
Overrides:: clear in class OrderedHashMap<String,Object>

put

public Object put(String key,
                  Object value)

Specified by:: put in interface Map<String,Object>
Overrides:: put in class ConcurrentAbstractMap<String,Object>

remove

public Object remove(Object key)

Specified by:: remove in interface Map<String,Object>
Overrides:: remove in class ConcurrentAbstractMap<String,Object>

putIfAbsent

public Object putIfAbsent(String key,
                          Object value)

Specified by:: putIfAbsent in interface ConcurrentMap<String,Object>
Overrides:: putIfAbsent in class ConcurrentAbstractMap<String,Object>

add

public boolean add(String key,
                   Object value)

Description copied from class: ConcurrentAbstractMap

Associates the specified value with the specified key in this map if not already mapped. This method may be applied in maps supporting nulls instead of the putIfAbsent method.

Specified by:: add in interface OrderedMap<String,Object>
Overrides:: add in class ConcurrentAbstractMap<String,Object>

Parameters:: key - key with which the specified value is to be associated.; value - value to be associated with the specified key.
Returns:: true if added, false otherwise.

replace

public Object replace(String key,
                      Object value)

Specified by:: replace in interface ConcurrentMap<String,Object>
Overrides:: replace in class ConcurrentAbstractMap<String,Object>

replace

public boolean replace(String key,
                       Object oldValue,
                       Object newValue)

Specified by:: replace in interface ConcurrentMap<String,Object>
Overrides:: replace in class ConcurrentAbstractMap<String,Object>

remove

public boolean remove(Object key,
                      Object value)

Specified by:: remove in interface ConcurrentMap<String,Object>
Overrides:: remove in class ConcurrentAbstractMap<String,Object>

put

public Object put(int index,
                  String key,
                  Object value)

Description copied from interface: OrderedMap

Associates the specified value with the specified key at the specified index in this map. An existing key is not moved.

Specified by:: put in interface OrderedMap<String,Object>
Overrides:: put in class OrderedHashMap<String,Object>

Parameters:: index - the index.; key - the key with which the specified value is to be associated.; value - the value to be associated with the specified key.
Returns:: the previous value associated with the specified key.

putIfAbsent

public Object putIfAbsent(int index,
                          String key,
                          Object value)

Description copied from interface: OrderedMap

Associates the specified value with the specified key at the specified index in this map if not already mapped.

Specified by:: putIfAbsent in interface OrderedMap<String,Object>
Overrides:: putIfAbsent in class OrderedHashMap<String,Object>

Parameters:: index - the index.; key - the key with which the specified value is to be associated.; value - the value to be associated with the specified key.
Returns:: the previous value associated with the specified key.

addAt

public boolean addAt(int index,
                     String key,
                     Object value)

Description copied from interface: OrderedMap

Associates the specified value with the specified key at the specified index in this map if not already mapped.

Specified by:: addAt in interface OrderedMap<String,Object>
Overrides:: addAt in class OrderedHashMap<String,Object>

Parameters:: index - the index.; key - the key with which the specified value is to be associated.; value - the value to be associated with the specified key.
Returns:: true if added, false otherwise.

replace

public Object replace(int index,
                      Object value)

Description copied from interface: OrderedMap

Replaces the indexed element in this map.

Specified by:: replace in interface OrderedMap<String,Object>
Overrides:: replace in class OrderedHashMap<String,Object>

Parameters:: index - the index.; value - the new value.
Returns:: the replaced value.

removeAt

public Map.Entry<String,Object> removeAt(int index)

Description copied from interface: OrderedMap

Removes the indexed element in this map.

Specified by:: removeAt in interface OrderedMap<String,Object>
Overrides:: removeAt in class OrderedHashMap<String,Object>

Parameters:: index - the index.
Returns:: the removed entry.