org.apache.commons.configuration

Class AbstractConfiguration

public abstract class AbstractConfiguration extends EventSource implements Configuration

Abstract configuration class. Provides basic functionality but does not store any data.

If you want to write your own Configuration class then you should implement only abstract methods from this class. A lot of functionality needed by typical implementations of the Configuration interface is already provided by this base class. Following is a list of feauters implemented here:

Version: $Id: AbstractConfiguration.java,v 1.29 2004/12/02 22:05:52 ebourg Exp $

Author: Konstantin Shaposhnikov Oliver Heger Henning P. Schmiedehausen

Field Summary
static chardefaultListDelimiter
The default value for listDelimiter
booleandelimiterParsingDisabled
When set to true the given configuration delimiter will not be used while parsing for this configuration.
protected static StringEND_TOKEN
end token
static intEVENT_ADD_PROPERTY
Constant for the add property event type.
static intEVENT_CLEAR
Constant for the clear configuration event type.
static intEVENT_CLEAR_PROPERTY
Constant for the clear property event type.
static intEVENT_READ_PROPERTY
Constant for the get property event type.
static intEVENT_SET_PROPERTY
Constant for the set property event type.
charlistDelimiter
Delimiter used to convert single values to lists
Loglog
Stores the logger.
StrSubstitutorsubstitutor
Stores a reference to the object that handles variable interpolation.
protected static StringSTART_TOKEN
start token
booleanthrowExceptionOnMissing
Whether the configuration should throw NoSuchElementExceptions or simply return null when a property does not exist.
Constructor Summary
AbstractConfiguration()
Creates a new instance of AbstractConfiguration.
Method Summary
voidaddErrorLogListener()
Adds a special ConfigurationErrorListener object to this configuration that will log all internal errors.
voidaddProperty(String key, Object value)
protected abstract voidaddPropertyDirect(String key, Object value)
Adds a key/value pair to the Configuration.
voidclear()
voidclearProperty(String key)
Removes the specified property from this configuration.
protected voidclearPropertyDirect(String key)
Removes the specified property from this configuration.
abstract booleancontainsKey(String key)
protected ConfigurationInterpolatorcreateInterpolator()
Creates the interpolator object that is responsible for variable interpolation.
BigDecimalgetBigDecimal(String key)
BigDecimalgetBigDecimal(String key, BigDecimal defaultValue)
BigIntegergetBigInteger(String key)
BigIntegergetBigInteger(String key, BigInteger defaultValue)
booleangetBoolean(String key)
booleangetBoolean(String key, boolean defaultValue)
BooleangetBoolean(String key, Boolean defaultValue)
Obtains the value of the specified key and tries to convert it into a Boolean object.
bytegetByte(String key)
bytegetByte(String key, byte defaultValue)
BytegetByte(String key, Byte defaultValue)
static chargetDefaultListDelimiter()
Retrieve the current delimiter.
static chargetDelimiter()
Returns the default list delimiter.
doublegetDouble(String key)
doublegetDouble(String key, double defaultValue)
DoublegetDouble(String key, Double defaultValue)
floatgetFloat(String key)
floatgetFloat(String key, float defaultValue)
FloatgetFloat(String key, Float defaultValue)
intgetInt(String key)
intgetInt(String key, int defaultValue)
IntegergetInteger(String key, Integer defaultValue)
ConfigurationInterpolatorgetInterpolator()
Returns the ConfigurationInterpolator object that manages the lookup objects for resolving variables.
abstract IteratorgetKeys()
IteratorgetKeys(String prefix)
ListgetList(String key)
ListgetList(String key, List defaultValue)
chargetListDelimiter()
Retrieve the delimiter for this configuration.
LoggetLogger()
Returns the logger used by this configuration object.
longgetLong(String key)
longgetLong(String key, long defaultValue)
LonggetLong(String key, Long defaultValue)
PropertiesgetProperties(String key)
PropertiesgetProperties(String key, Properties defaults)
Get a list of properties associated with the given configuration key.
shortgetShort(String key)
shortgetShort(String key, short defaultValue)
ShortgetShort(String key, Short defaultValue)
StringgetString(String key)
StringgetString(String key, String defaultValue)
String[]getStringArray(String key)
Get an array of strings associated with the given configuration key.
StrSubstitutorgetSubstitutor()
Returns the object that is responsible for variable interpolation.
protected Stringinterpolate(String base)
interpolate key names to handle ${key} stuff
protected Objectinterpolate(Object value)
Returns the interpolated value.
protected StringinterpolateHelper(String base, List priorVariables)
Recursive handler for multple levels of interpolation.
booleanisDelimiterParsingDisabled()
Determine if this configuration is using delimiters when parsing property values to convert them to lists of values.
abstract booleanisEmpty()
booleanisThrowExceptionOnMissing()
Returns true if missing values throw Exceptions.
protected ObjectresolveContainerStore(String key)
Returns an object from the store described by the key.
static voidsetDefaultListDelimiter(char delimiter)
For configurations extending AbstractConfiguration, allow them to change the listDelimiter from the default comma (",").
static voidsetDelimiter(char delimiter)
Sets the default list delimiter.
voidsetDelimiterParsingDisabled(boolean delimiterParsingDisabled)
Set whether this configuration should use delimiters when parsing property values to convert them to lists of values.
voidsetListDelimiter(char listDelimiter)
Change the list delimiter for this configuration.
voidsetLogger(Log log)
Allows to set the logger to be used by this configuration object.
voidsetProperty(String key, Object value)
voidsetThrowExceptionOnMissing(boolean throwExceptionOnMissing)
Allows to set the throwExceptionOnMissing flag.
Configurationsubset(String prefix)

Field Detail

defaultListDelimiter

private static char defaultListDelimiter
The default value for listDelimiter

delimiterParsingDisabled

private boolean delimiterParsingDisabled
When set to true the given configuration delimiter will not be used while parsing for this configuration.

END_TOKEN

protected static final String END_TOKEN
end token

EVENT_ADD_PROPERTY

public static final int EVENT_ADD_PROPERTY
Constant for the add property event type.

Since: 1.3

EVENT_CLEAR

public static final int EVENT_CLEAR
Constant for the clear configuration event type.

Since: 1.3

EVENT_CLEAR_PROPERTY

public static final int EVENT_CLEAR_PROPERTY
Constant for the clear property event type.

Since: 1.3

EVENT_READ_PROPERTY

public static final int EVENT_READ_PROPERTY
Constant for the get property event type. This event type is used for error events.

Since: 1.4

EVENT_SET_PROPERTY

public static final int EVENT_SET_PROPERTY
Constant for the set property event type.

Since: 1.3

listDelimiter

private char listDelimiter
Delimiter used to convert single values to lists

log

private Log log
Stores the logger.

substitutor

private StrSubstitutor substitutor
Stores a reference to the object that handles variable interpolation.

START_TOKEN

protected static final String START_TOKEN
start token

throwExceptionOnMissing

private boolean throwExceptionOnMissing
Whether the configuration should throw NoSuchElementExceptions or simply return null when a property does not exist. Defaults to return null.

Constructor Detail

AbstractConfiguration

public AbstractConfiguration()
Creates a new instance of AbstractConfiguration.

Method Detail

addErrorLogListener

public void addErrorLogListener()
Adds a special ConfigurationErrorListener object to this configuration that will log all internal errors. This method is intended to be used by certain derived classes, for which it is known that they can fail on property access (e.g. DatabaseConfiguration).

Since: 1.4

addProperty

public void addProperty(String key, Object value)
{@inheritDoc }

addPropertyDirect

protected abstract void addPropertyDirect(String key, Object value)
Adds a key/value pair to the Configuration. Override this method to provide write acces to underlying Configuration store.

Parameters: key key to use for mapping value object to store

clear

public void clear()
{@inheritDoc }

clearProperty

public void clearProperty(String key)
Removes the specified property from this configuration. This implementation performs some preparations and then delegates to clearPropertyDirect(), which will do the real work.

Parameters: key the key to be removed

clearPropertyDirect

protected void clearPropertyDirect(String key)
Removes the specified property from this configuration. This method is called by clearProperty() after it has done some preparations. It should be overriden in sub classes. This base implementation is just left empty.

Parameters: key the key to be removed

containsKey

public abstract boolean containsKey(String key)
{@inheritDoc }

createInterpolator

protected ConfigurationInterpolator createInterpolator()
Creates the interpolator object that is responsible for variable interpolation. This method is invoked on first access of the interpolation features. It creates a new instance of ConfigurationInterpolator and sets the default lookup object to an implementation that queries this configuration.

Returns: the newly created interpolator object

Since: 1.4

getBigDecimal

public BigDecimal getBigDecimal(String key)
{@inheritDoc }

See Also: AbstractConfiguration

getBigDecimal

public BigDecimal getBigDecimal(String key, BigDecimal defaultValue)
{@inheritDoc }

getBigInteger

public BigInteger getBigInteger(String key)
{@inheritDoc }

See Also: AbstractConfiguration

getBigInteger

public BigInteger getBigInteger(String key, BigInteger defaultValue)
{@inheritDoc }

getBoolean

public boolean getBoolean(String key)
{@inheritDoc }

See Also: toBoolean

getBoolean

public boolean getBoolean(String key, boolean defaultValue)
{@inheritDoc }

See Also: toBoolean

getBoolean

public Boolean getBoolean(String key, Boolean defaultValue)
Obtains the value of the specified key and tries to convert it into a Boolean object. If the property has no value, the passed in default value will be used.

Parameters: key the key of the property defaultValue the default value

Returns: the value of this key converted to a Boolean

Throws: ConversionException if the value cannot be converted to a Boolean

See Also: toBoolean

getByte

public byte getByte(String key)
{@inheritDoc }

getByte

public byte getByte(String key, byte defaultValue)
{@inheritDoc }

getByte

public Byte getByte(String key, Byte defaultValue)
{@inheritDoc }

getDefaultListDelimiter

public static char getDefaultListDelimiter()
Retrieve the current delimiter. By default this is a comma (",").

Returns: The delimiter in use

getDelimiter

public static char getDelimiter()

Deprecated: Use AbstractConfiguration.getDefaultListDelimiter() instead

Returns the default list delimiter.

Returns: the default list delimiter

getDouble

public double getDouble(String key)
{@inheritDoc }

getDouble

public double getDouble(String key, double defaultValue)
{@inheritDoc }

getDouble

public Double getDouble(String key, Double defaultValue)
{@inheritDoc }

getFloat

public float getFloat(String key)
{@inheritDoc }

getFloat

public float getFloat(String key, float defaultValue)
{@inheritDoc }

getFloat

public Float getFloat(String key, Float defaultValue)
{@inheritDoc }

getInt

public int getInt(String key)
{@inheritDoc }

getInt

public int getInt(String key, int defaultValue)
{@inheritDoc }

getInteger

public Integer getInteger(String key, Integer defaultValue)
{@inheritDoc }

getInterpolator

public ConfigurationInterpolator getInterpolator()
Returns the ConfigurationInterpolator object that manages the lookup objects for resolving variables. Note: If this object is manipulated (e.g. new lookup objects added), synchronisation has to be manually ensured. Because ConfigurationInterpolator is not thread-safe concurrent access to properties of this configuration instance (which causes the interpolator to be invoked) may cause race conditions.

Returns: the ConfigurationInterpolator associated with this configuration

Since: 1.4

getKeys

public abstract Iterator getKeys()
{@inheritDoc }

getKeys

public Iterator getKeys(String prefix)
{@inheritDoc }

getList

public List getList(String key)
{@inheritDoc }

See Also: getStringArray

getList

public List getList(String key, List defaultValue)
{@inheritDoc }

getListDelimiter

public char getListDelimiter()
Retrieve the delimiter for this configuration. The default is the value of defaultListDelimiter.

Returns: The listDelimiter in use

getLogger

public Log getLogger()
Returns the logger used by this configuration object.

Returns: the logger

Since: 1.4

getLong

public long getLong(String key)
{@inheritDoc }

getLong

public long getLong(String key, long defaultValue)
{@inheritDoc }

getLong

public Long getLong(String key, Long defaultValue)
{@inheritDoc }

getProperties

public Properties getProperties(String key)
{@inheritDoc }

getProperties

public Properties getProperties(String key, Properties defaults)
Get a list of properties associated with the given configuration key.

Parameters: key The configuration key. defaults Any default values for the returned Properties object. Ignored if null.

Returns: The associated properties if key is found.

Throws: ConversionException is thrown if the key maps to an object that is not a String/List of Strings. IllegalArgumentException if one of the tokens is malformed (does not contain an equals sign).

getShort

public short getShort(String key)
{@inheritDoc }

getShort

public short getShort(String key, short defaultValue)
{@inheritDoc }

getShort

public Short getShort(String key, Short defaultValue)
{@inheritDoc }

getString

public String getString(String key)
{@inheritDoc }

See Also: AbstractConfiguration

getString

public String getString(String key, String defaultValue)
{@inheritDoc }

getStringArray

public String[] getStringArray(String key)
Get an array of strings associated with the given configuration key. If the key doesn't map to an existing object, an empty array is returned. If a property is added to a configuration, it is checked whether it contains multiple values. This is obvious if the added object is a list or an array. For strings it is checked whether the string contains the list delimiter character that can be specified using the setListDelimiter() method. If this is the case, the string is splitted at these positions resulting in a property with multiple values.

Parameters: key The configuration key.

Returns: The associated string array if key is found.

Throws: ConversionException is thrown if the key maps to an object that is not a String/List of Strings.

See Also: AbstractConfiguration AbstractConfiguration

getSubstitutor

public StrSubstitutor getSubstitutor()
Returns the object that is responsible for variable interpolation.

Returns: the object responsible for variable interpolation

Since: 1.4

interpolate

protected String interpolate(String base)
interpolate key names to handle ${key} stuff

Parameters: base string to interpolate

Returns: returns the key name with the ${key} substituted

interpolate

protected Object interpolate(Object value)
Returns the interpolated value. Non String values are returned without change.

Parameters: value the value to interpolate

Returns: returns the value with variables substituted

interpolateHelper

protected String interpolateHelper(String base, List priorVariables)

Deprecated: Interpolation is now handled by PropertyConverter; this method will no longer be called

Recursive handler for multple levels of interpolation. When called the first time, priorVariables should be null.

Parameters: base string with the ${key} variables priorVariables serves two purposes: to allow checking for loops, and creating a meaningful exception message should a loop occur. It's 0'th element will be set to the value of base from the first call. All subsequent interpolated variables are added afterward.

Returns: the string with the interpolation taken care of

isDelimiterParsingDisabled

public boolean isDelimiterParsingDisabled()
Determine if this configuration is using delimiters when parsing property values to convert them to lists of values. Defaults to false

Returns: true if delimiters are not being used

isEmpty

public abstract boolean isEmpty()
{@inheritDoc }

isThrowExceptionOnMissing

public boolean isThrowExceptionOnMissing()
Returns true if missing values throw Exceptions.

Returns: true if missing values throw Exceptions

resolveContainerStore

protected Object resolveContainerStore(String key)
Returns an object from the store described by the key. If the value is a List object, replace it with the first object in the list.

Parameters: key The property key.

Returns: value Value, transparently resolving a possible List dependency.

setDefaultListDelimiter

public static void setDefaultListDelimiter(char delimiter)
For configurations extending AbstractConfiguration, allow them to change the listDelimiter from the default comma (","). This value will be used only when creating new configurations. Those already created will not be affected by this change

Parameters: delimiter The new listDelimiter

setDelimiter

public static void setDelimiter(char delimiter)

Deprecated: Use AbstractConfiguration.setDefaultListDelimiter(char) instead

Sets the default list delimiter.

Parameters: delimiter the delimiter character

setDelimiterParsingDisabled

public void setDelimiterParsingDisabled(boolean delimiterParsingDisabled)
Set whether this configuration should use delimiters when parsing property values to convert them to lists of values. By default delimiter parsing is enabled Note: this change will only be effective for new parsings. If you want it to take effect for all loaded properties use the no arg constructor and call this method before setting source.

Parameters: delimiterParsingDisabled a flag whether delimiter parsing should be disabled

setListDelimiter

public void setListDelimiter(char listDelimiter)
Change the list delimiter for this configuration. Note: this change will only be effective for new parsings. If you want it to take effect for all loaded properties use the no arg constructor and call this method before setting the source.

Parameters: listDelimiter The new listDelimiter

setLogger

public void setLogger(Log log)
Allows to set the logger to be used by this configuration object. This method makes it possible for clients to exactly control logging behavior. Per default a logger is set that will ignore all log messages. Derived classes that want to enable logging should call this method during their initialization with the logger to be used.

Parameters: log the new logger

Since: 1.4

setProperty

public void setProperty(String key, Object value)
{@inheritDoc }

setThrowExceptionOnMissing

public void setThrowExceptionOnMissing(boolean throwExceptionOnMissing)
Allows to set the throwExceptionOnMissing flag. This flag controls the behavior of property getter methods that return objects if the requested property is missing. If the flag is set to false (which is the default value), these methods will return null. If set to true, they will throw a NoSuchElementException exception. Note that getter methods for primitive data types are not affected by this flag.

Parameters: throwExceptionOnMissing The new value for the property

subset

public Configuration subset(String prefix)
{@inheritDoc }