de.fu_berlin.ties
Class TiesConfiguration

java.lang.Object
  extended by org.apache.commons.configuration.AbstractConfiguration
      extended by org.apache.commons.configuration.CompositeConfiguration
          extended by de.fu_berlin.ties.TiesConfiguration
All Implemented Interfaces:
Configuration

public class TiesConfiguration
extends CompositeConfiguration

A composite configuration that allows to localize of keys and to querying types and descriptions of entries.

Version:
$Revision: 1.24 $, $Date: 2004/10/30 17:25:28 $, $Author: siefkes $
Author:
Christian Siefkes

Nested Class Summary
 class TiesConfiguration.EntryDescriptor
          An inner class wrapping descriptor information on an entry: type of the entry, whether it is optional or a list, a description of the entry.
 
Field Summary
static TiesConfiguration CONF
          The main configuration object for TIES, loaded via TiesConfiguration(String) using "ties" as base name.
static String CONF_DIR
          The subdirectory in the class path containing config files.
static String CONF_EXTENSION
          The extension of config files in PropertiesConfiguration format.
static String CONFIG_GOAL_PREFIX
          Configuration key prefix mapping goals to fully qualified class names.
static String CONFIG_LANG
          Special configuration key: the language of documents, using the ISO 639 language codes (2-letter codes where available, e.g.
static String DESC_EXTENSION
          The extension of descriptor configuration files (in PropertiesConfiguration format).
static String XML_EXTENSION
          The extension of config files in XML format.
 
Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
END_TOKEN, START_TOKEN
 
Constructor Summary
TiesConfiguration()
          Creates a new empty instance.
TiesConfiguration(Configuration config, Configuration desc)
          Creates a new instance, delegating to addConfiguration(Configuration, Configuration).
TiesConfiguration(String baseName)
          Creates a new instance, delegating to load(String).
 
Method Summary
 String adaptKey(String baseKey, String suffix)
          Creates a adapted (caller-specific) key by joining a base name with a suffix.
 void addConfiguration(Configuration config, Configuration desc)
          Adds a configuration and a corresponding descriptor config.
 void addDescriptorConfig(Configuration desc)
          Adds a descriptor configuration that can be consulted to query the type and use of a entries.
static boolean arrayIsEmpty(String[] array)
          Utility method that thorougly checks whether a string array is empty.
 List configureFromArgs(String[] args)
          Modifies configuration properties from [+|-]key[=value] pairs in a string array.
 void flatten(Configuration appender)
          Copies all properties contained in this instance to a given configuration.
 TiesConfiguration.EntryDescriptor getDescriptor(String key)
          Returns the descriptor for a given key, if any is given in the descriptor configuration.
protected  Object getPropertyDirect(String key)
          Read a property from this configuration.
 String[] getStringArray(String key)
          Get an array of strings associated with the given configuration key.
static String joinKey(String prefix, String suffix)
          Creates a full key by joining a prefix and a suffix string, separated by the property delimiter.
static boolean listIsEmpty(List list)
          Utility method that thorougly checks whether a list is empty.
 void load(String baseName)
          Loads configuration in PropertiesConfiguration or XML format.
 String localizeKey(String baseKey)
          Creates a localized (language-specific) key by joining a base name with the configured language suffix (value mapped to the CONFIG_LANG} key (if this key doesn't exist, the language of default locale used by the Java Virtual Machine is used).
 void modifyProperty(String keyValue, boolean overwrite)
          Modifies a configuration property, parsing a key[=value] pair.
static boolean propertyIsEmpty(Object object)
          Utility method that thorougly checks whether a property (as returned by Configuration.getProperty(String) is empty.
 void save(File file)
          Saves the contents of this configuration in a file, storing them in PropertiesConfiguration format.
 void save(String filename)
          Saves the contents of this configuration in a file, storing them in PropertiesConfiguration format.
 SortedSet sortedKeys()
          Returns the list of keys contained in this configuration, sorted in alphabetic order.
 SortedSet<Object> sortedKeys(boolean inclNotSet)
          Returns the list of keys contained in this configuration, sorted in alphabetic order.
 Configuration subset(String prefix)
          Create an Configuration object that is a subset of this one.
 
Methods inherited from class org.apache.commons.configuration.CompositeConfiguration
addConfiguration, addPropertyDirect, clear, clearProperty, containsKey, getConfiguration, getInMemoryConfiguration, getKeys, getKeys, getList, getNumberOfConfigurations, getProperty, getVector, isEmpty, removeConfiguration, setProperty
 
Methods inherited from class org.apache.commons.configuration.AbstractConfiguration
addProperty, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getList, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getVector, interpolate, interpolateHelper, isThrowExceptionOnMissing, setDelimiter, setThrowExceptionOnMissing, split
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CONF

public static final TiesConfiguration CONF
The main configuration object for TIES, loaded via TiesConfiguration(String) using "ties" as base name. You should NOT modify the configuration properties stored in this object, especially since it is not fully thread-safe (unless you know what you're doing and are sure there are no other objects around that might try to access the configuration, e.g. at the begin of a program's main method).


CONF_DIR

public static final String CONF_DIR
The subdirectory in the class path containing config files.

See Also:
Constant Field Values

CONF_EXTENSION

public static final String CONF_EXTENSION
The extension of config files in PropertiesConfiguration format.

See Also:
Constant Field Values

XML_EXTENSION

public static final String XML_EXTENSION
The extension of config files in XML format.

See Also:
Constant Field Values

DESC_EXTENSION

public static final String DESC_EXTENSION
The extension of descriptor configuration files (in PropertiesConfiguration format).

See Also:
Constant Field Values

CONFIG_GOAL_PREFIX

public static final String CONFIG_GOAL_PREFIX
Configuration key prefix mapping goals to fully qualified class names.

See Also:
Constant Field Values

CONFIG_LANG

public static final String CONFIG_LANG
Special configuration key: the language of documents, using the ISO 639 language codes (2-letter codes where available, e.g. "en" (English) or "de" (German).

See Also:
Constant Field Values
Constructor Detail

TiesConfiguration

public TiesConfiguration()
Creates a new empty instance.


TiesConfiguration

public TiesConfiguration(Configuration config,
                         Configuration desc)
Creates a new instance, delegating to addConfiguration(Configuration, Configuration).

Parameters:
config - the initial configuration to wrap
desc - the initial descriptor config to wrap (cf. addDescriptorConfig(Configuration) for the required contents)

TiesConfiguration

public TiesConfiguration(String baseName)
Creates a new instance, delegating to load(String).

Parameters:
baseName - the base name of the configuration
Method Detail

adaptKey

public String adaptKey(String baseKey,
                       String suffix)
Creates a adapted (caller-specific) key by joining a base name with a suffix. If the adapted form of the key doesn't exist in this configuration, the base form is returned instead.

Parameters:
baseKey - the basic key
suffix - the suffix of the key; if null the baseKey is returned
Returns:
the full key, adapted by joining with the CONFIG_LANG key; resp. the base form if the full key doesn't exist or suffix is null
See Also:
joinKey(String, String)

arrayIsEmpty

public static boolean arrayIsEmpty(String[] array)
Utility method that thorougly checks whether a string array is empty. It returns true in three cases:
  1. the specified array is null;
  2. the specified array is empty (0 elements);
  3. the specified array contains a single element which is null or an empty or blank (only whitespace) string.
This method is useful because some reconfigurations can cause a TiesConfiguration to return a single-element list containing only an empty string. Usually such a list should be treated as empty.

Parameters:
array - the array to check
Returns:
true iff the list is empty as described above

listIsEmpty

public static boolean listIsEmpty(List list)
Utility method that thorougly checks whether a list is empty. It returns true in three cases:
  1. the specified list is null;
  2. the specified list is empty (0 elements);
  3. the specified list contains a single element which is null or an empty or blank (only whitespace) string.
This method is useful because some reconfigurations can cause a TiesConfiguration to return a single-element list containing only an empty string. Usually such a list should be treated as empty.

Parameters:
list - the list to check
Returns:
true iff the list is empty as described above

propertyIsEmpty

public static boolean propertyIsEmpty(Object object)
Utility method that thorougly checks whether a property (as returned by Configuration.getProperty(String) is empty. It returns true in two cases:
  1. the specified object is null;
  2. the specified object is an empty or blank (only whitespace) string.
This method is useful because some reconfigurations can cause a TiesConfiguration to return a empty strings.

Parameters:
object - the object to check
Returns:
true iff the object is empty as described above

joinKey

public static String joinKey(String prefix,
                             String suffix)
Creates a full key by joining a prefix and a suffix string, separated by the property delimiter.

Parameters:
prefix - the prefix of the key
suffix - the suffix of the key
Returns:
the full key (prefix + delimiter + suffix)

addConfiguration

public void addConfiguration(Configuration config,
                             Configuration desc)
Adds a configuration and a corresponding descriptor config.

Parameters:
config - the configuration to add
desc - the descriptor config to add (cf. addDescriptorConfig(Configuration) for the required contents)

addDescriptorConfig

public void addDescriptorConfig(Configuration desc)
Adds a descriptor configuration that can be consulted to query the type and use of a entries. Each value must be a two-array specifying the type (first element) and a description (second element) of the key as used in the main configuration. Append '?' to the type if it is optional (zero or one values), '*' if it is an optional list (zero or more values), or '+' if it is a required list (one or more values).

Parameters:
desc - the descriptor configuration to add

configureFromArgs

public List configureFromArgs(String[] args)
                       throws IllegalArgumentException
Modifies configuration properties from [+|-]key[=value] pairs in a string array. Delegates to modifyProperty(String, boolean) for each array element starting with "-" (using overwrite mode) or "+" (using append mode). Other array elements are collected and returned.

Parameters:
args - the array of strings to parse
Returns:
a list of all arguments that do not start with "+" or "-"
Throws:
IllegalArgumentException - if one of the [+|-]key[=value] pairs doesn't contain a key ("=" is second character)

getDescriptor

public TiesConfiguration.EntryDescriptor getDescriptor(String key)
Returns the descriptor for a given key, if any is given in the descriptor configuration.

Parameters:
key - the key to describe
Returns:
a descriptor object for this key, or null is none is given

getPropertyDirect

protected Object getPropertyDirect(String key)
Read a property from this configuration. If the given key does not exist in this configuration, it is looked up as a Java system property.

Overrides:
getPropertyDirect in class CompositeConfiguration
Parameters:
key - key to use for mapping
Returns:
object associated with the given configuration key

getStringArray

public String[] getStringArray(String key)
Get an array of strings associated with the given configuration key.

Specified by:
getStringArray in interface Configuration
Overrides:
getStringArray in class CompositeConfiguration
Parameters:
key - The configuration key
Returns:
The associated string array if key is found.

flatten

public void flatten(Configuration appender)
Copies all properties contained in this instance to a given configuration. This method can be used for storing this configuration in any format desired, by creating an empty configuration of the requested type and passing it to this method. Keys are sorted in alphabetic order.

Parameters:
appender - the configuration to append all properties to

load

public void load(String baseName)
Loads configuration in PropertiesConfiguration or XML format. Combines configuration properties from several resources if they exist:
  1. The files baseName.xml resp. baseName.cfg in the current working directory, if they exist and are readable files
  2. The file baseName.xml resp. baseName.cfg in the user's home directory, if they exist and are readable files
  3. The file baseName.cfg in the conf subdirectory in the classpath (e.g. from a jar file) -- this classpath resource should always exist (otherwise an warning will be logged and later errors are likely)

For shared keys, the first match will be returned. If corresponding baseName.desc exists, they are assumed to contain descriptors.

*.cfg and *.desc files must must use the PropertiesConfiguration format, *.xml files must use the XML format.

The last resource loaded form the classpath must use UTF-8 character set (otherwise it could not be shared between systems). The other *.cfg and *.desc (local files) are assumed to use the platform's default character set. The character set of XML files is determined in the standard way.

Parameters:
baseName - the base name of the configuration

localizeKey

public String localizeKey(String baseKey)
Creates a localized (language-specific) key by joining a base name with the configured language suffix (value mapped to the CONFIG_LANG} key (if this key doesn't exist, the language of default locale used by the Java Virtual Machine is used). If the localized form of the key doesn't exist in the specified configuration, the base form is returned instead. Implemented by delegating to adaptKey(String, String).

Parameters:
baseKey - the basic key
Returns:
the full key, localized by joining with the CONFIG_LANG key

modifyProperty

public void modifyProperty(String keyValue,
                           boolean overwrite)
                    throws IllegalArgumentException
Modifies a configuration property, parsing a key[=value] pair. Both key and value are trimmed. Boolean.TRUE is used as default value if the =value part is omitted. If "=" is the last character (empty value) and overwrite is true, the property is removed from the configuration (Configuration.clearProperty(java.lang.String)).

Parameters:
keyValue - the key=value pair to parse
overwrite - whether to overwrite (replacing old value: Configuration.setProperty(java.lang.String, java.lang.Object)) or add (append to list, Configuration.addProperty(java.lang.String, java.lang.Object)) the value
Throws:
IllegalArgumentException - if keyValue doesn't contain a key ("=" is first character)

save

public void save(File file)
          throws ConfigurationException
Saves the contents of this configuration in a file, storing them in PropertiesConfiguration format. The platform's default character set is used.

Parameters:
file - the file to use
Throws:
ConfigurationException - if an I/O error occurs during saving

save

public void save(String filename)
          throws ConfigurationException
Saves the contents of this configuration in a file, storing them in PropertiesConfiguration format. The platform's default character set is used.

Parameters:
filename - the name of the file
Throws:
ConfigurationException - if an I/O error occurs during saving

sortedKeys

public SortedSet sortedKeys()
Returns the list of keys contained in this configuration, sorted in alphabetic order. Delegates to sortedKeys(boolean), setting inclNotSet to false.

Returns:
an immutable set containing the sorted list of keys

sortedKeys

public SortedSet<Object> sortedKeys(boolean inclNotSet)
Returns the list of keys contained in this configuration, sorted in alphabetic order.

Parameters:
inclNotSet - if true, keys that are not contained in this configuration but that described in the descriptor configuration are also included
Returns:
an immutable set containing the sorted list of keys

subset

public Configuration subset(String prefix)
Create an Configuration object that is a subset of this one. The new Configuration object contains every key from the current Configuration that starts with prefix. The prefix is removed from the keys in the subset.

Specified by:
subset in interface Configuration
Overrides:
subset in class AbstractConfiguration
Parameters:
prefix - The prefix used to select the properties
Returns:
a subset of this configuration; the returned object will be a TiesConfiguration instance


Copyright © 2003-2004 Christian Siefkes. All Rights Reserved.