org.norther.tammi.core.config
Class Configuration

java.lang.Object
  java.util.AbstractMap
      org.norther.tammi.acorn.util.ConcurrentAbstractMap
          org.norther.tammi.acorn.util.ConcurrentReadMap
              org.norther.tammi.acorn.util.OrderedHashMap
                  org.norther.tammi.core.config.Configuration

All Implemented Interfaces:

Serializable, Cloneable, ConcurrentMap, Map, Traceable, OrderedMap

public class Configuration
extends OrderedHashMap
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.

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.Entry

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(int index, Object key, Object value) Associates the specified value with the specified key to the specified index in this map if not already mapped.
boolean	add(Object key, Object value) Associates the specified value with the specified key in this map if not already mapped.
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(int index, String key, String[] values) Adds multivalued property values 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	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	getLastInitialized() Gets the timestamp of the last initialization of the traced object.
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.
String	getNull() Gets the null value.
static String	getNullKey() Gets the property key for a 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	loadFromXML(InputStream input) Loads the properties represented by the XML document on the specified input stream into this configuration.
void	merge(Map map) Merges the specified map to this configuration.
Enumeration	propertyNames() Returns an enumeration of all property names including the defaults.
Object	put(int index, Object key, Object value) Associates the specified value with the specified key to the specified index in this map.
Object	put(Object key, Object value)
Object	putIfAbsent(int index, Object key, Object value) Associates the specified value with the specified key to the specified index in this map if not already mapped.
Object	putIfAbsent(Object key, Object value)
Object	remove(int index) Removes the indexed element in this map.
Object	remove(Object key)
boolean	remove(Object key, Object value)
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(Object key, Object value)
boolean	replace(Object 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 separ) Sets the item separator(s).
void	setKeyDelimiter(String delim) Sets the key delimiter(s).
void	setLastModified(Object key, long timestamp) Sets the timestamp of the last modification of the specified resource.
void	setNull(String nl) Sets the null value.
static void	setNullKey(String key) Sets the property key for a 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	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.
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.
static Configuration	toConfiguration(Properties p) Converts a standard properties class into a configuration class.
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

entryList, entrySet, get, getEntryAt, getKeyAt, indexOfKey, isModifiable, keyList, keySet, putAll, putInternal, putInternal, removeInternal, valueList, values

Methods inherited from class org.norther.tammi.acorn.util.ConcurrentReadMap

capacity, containsKey, containsValue, getEntry, getInternal, getReadTable, getWriteTable, isEmpty, recordWrite, rehash, replaceInternal, setWriteTable, size

Methods inherited from class org.norther.tammi.acorn.util.ConcurrentAbstractMap

capacity, contains, elements, get, hash, keys

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, 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.

toConfiguration

public static Configuration toConfiguration(Properties p)

Converts a standard properties class into a configuration class.

Parameters:

p - properties object to convert into a Configuration object.

Returns:

the configuration created from the properties object.

clone

public Object clone()

Overrides:

clone in class OrderedHashMap

clear

public void clear()

Specified by:

clear in interface Map

Overrides:

clear in class OrderedHashMap

put

public Object put(Object key,
                  Object value)

Specified by:

put in interface Map

Overrides:

put in class ConcurrentAbstractMap

remove

public Object remove(Object key)

Specified by:

remove in interface Map

Overrides:

remove in class ConcurrentAbstractMap

putIfAbsent

public Object putIfAbsent(Object key,
                          Object value)

Specified by:

putIfAbsent in interface ConcurrentMap

Overrides:

putIfAbsent in class ConcurrentAbstractMap

add

public boolean add(Object 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

Overrides:

add in class ConcurrentAbstractMap

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(Object key,
                      Object value)

Specified by:

replace in interface ConcurrentMap

Overrides:

replace in class ConcurrentAbstractMap

replace

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

Specified by:

replace in interface ConcurrentMap

Overrides:

replace in class ConcurrentAbstractMap

remove

public boolean remove(Object key,
                      Object value)

Specified by:

remove in interface ConcurrentMap

Overrides:

remove in class ConcurrentAbstractMap

put

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

Description copied from interface: OrderedMap

Associates the specified value with the specified key to the specified index in this map. Note that an existing key is not moved.

Specified by:

put in interface OrderedMap

Overrides:

put in class OrderedHashMap

Parameters:

index - the index.

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with the specified key.

putIfAbsent

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

Description copied from interface: OrderedMap

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

Specified by:

putIfAbsent in interface OrderedMap

Overrides:

putIfAbsent in class OrderedHashMap

Parameters:

index - the index.

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with the specified key.

add

public boolean add(int index,
                   Object key,
                   Object value)

Description copied from interface: OrderedMap

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

Specified by:

add in interface OrderedMap

Overrides:

add in class OrderedHashMap

Parameters:

index - the index.

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(int index,
                      Object value)

Description copied from interface: OrderedMap

Replaces the indexed element in this map.

Specified by:

replace in interface OrderedMap

Overrides:

replace in class OrderedHashMap

Parameters:

index - the index.

value - the new value.

Returns:

the replaced value.

remove

public Object remove(int index)

Description copied from interface: OrderedMap

Removes the indexed element in this map.

Specified by:

remove in interface OrderedMap

Overrides:

remove in class OrderedHashMap

Parameters:

index - the index.

Returns:

the removed value.

getLastInitialized

public long getLastInitialized()

Description copied from interface: Traceable

Gets the timestamp of the last initialization of the traced object.

Specified by:

getLastInitialized in interface Traceable

Returns:

the initialization timestamp.

getLastModified

public long getLastModified()

Description copied from interface: Traceable

Gets the timestamp of the last modification of the traced object.

Specified by:

getLastModified in interface Traceable

Returns:

the modification timestamp.

getLastModified

public long getLastModified(Object key)

Description copied from interface: Traceable

Gets the timestamp of the last modification of the specified resource.

Specified by:

getLastModified in interface Traceable

Parameters:

key - the key of the resource.

Returns:

the modification timestamp.

setLastModified

public void setLastModified(Object key,
                            long timestamp)

Description copied from interface: Traceable

Sets the timestamp of the last modification of the specified resource. This is a clumsy way to maintain original timestamps of resources copied between objects, so implementors are encouraged to provide timestamped setters to be applied instead of this method.

Specified by:

setLastModified in interface Traceable

Parameters:

key - the key of the resource.

timestamp - the modification timestamp.

addTraceListener

public void addTraceListener(TraceListener listener)

Description copied from interface: Traceable

Adds a listener if not already present.

Specified by:

addTraceListener in interface Traceable

Parameters:

listener - a listener to add.

removeTraceListener

public void removeTraceListener(TraceListener listener)

Description copied from interface: Traceable

Removes a listener.

Specified by:

removeTraceListener in interface Traceable

Parameters:

listener - the listener to remove.

clearTraceListeners

public void clearTraceListeners()

Description copied from interface: Traceable

Clears all listeners from this traceable.

Specified by:

clearTraceListeners in interface Traceable

getNull

public String getNull()

Gets the null value.

Returns:

the null value.

setNull

public void setNull(String nl)

Sets the null value.

Parameters:

nl - the null.

getKeyDelimiter

public String getKeyDelimiter()

Gets the key delimiters(s).

Returns:

the separators(s).

setKeyDelimiter

public void setKeyDelimiter(String delim)

Sets the key delimiter(s). Null enables default delimiter(s).

Parameters:

delim - the delimiters(s).

getItemSeparator

public String getItemSeparator()

Gets the item separator(s).

Returns:

the separator(s).

setItemSeparator

public void setItemSeparator(String separ)

Sets the item separator(s). Null disables value arrays. An empty string enables value arrays given as separate properties.

Parameters:

separ - the separator(s).

loadFromXML

public void loadFromXML(InputStream input)
                 throws IOException,
                        InvalidPropertiesFormatException

Loads the properties represented by the XML document on the specified input stream into this configuration.

The XML document must be compatible with the following DTD:

 <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
 

Parameters:

input - the input stream.

Throws:

IOException - on I/O errors.

InvalidPropertiesFormatException - for invalid data.

storeToXML

public void storeToXML(OutputStream output,
                       String header)
                throws IOException

Stores an XML document representing the properties contained in this configuration by applying the UTF-8 encoding.

The defaults are not included in the document by this method.

Parameters:

output - the output stream.

header - an optional header.

Throws:

IOException - on I/O errors.

storeToXML

public void storeToXML(OutputStream output,
                       String header,
                       String encoding)
                throws IOException

Stores an XML document representing the properties contained in this configuration by applying the specified encoding.

The defaults are not included in the document by this method.

Parameters:

output - the output stream.

header - an optional header.

encoding - the encoding.

Throws:

IOException - on I/O errors.

load

public void load(InputStream input)
          throws IOException

Loads the properties from an input stream by applying the ISO-8859-1 encoding to be compatible with java.util.Properties.

Parameters:

input - the input stream.

Throws:

IOException - on I/O errors.

load

public void load(InputStream input,
                 String encoding)
          throws IOException

Loads the proper