org.apache.commons.configuration2

Class SubsetConfiguration

java.lang.Object

org.apache.commons.configuration2.event.BaseEventSource

org.apache.commons.configuration2.AbstractConfiguration

org.apache.commons.configuration2.SubsetConfiguration

All Implemented Interfaces:

Configuration, EventSource, ImmutableConfiguration, SynchronizerSupport

public class SubsetConfiguration
extends AbstractConfiguration

A subset of another configuration. The new Configuration object contains every key from the parent Configuration that starts with prefix. The prefix is removed from the keys in the subset.

It is usually not necessary to use this class directly. Instead the Configuration.subset(String) method should be used, which will return a correctly initialized instance.

Field Summary

Fields

Modifier and Type	Field and Description
protected String	delimiter The prefix delimiter
protected Configuration	parent The parent configuration.
protected String	prefix The prefix used to select the properties.

Constructor Summary

Constructors

Constructor and Description
SubsetConfiguration(Configuration parent, String prefix) Create a subset of the specified configuration
SubsetConfiguration(Configuration parent, String prefix, String delimiter) Create a subset of the specified configuration

Method Summary

Modifier and Type	Method and Description
void	addPropertyDirect(String key, Object value) Adds a key/value pair to the Configuration.
protected void	clearPropertyDirect(String key) Removes the specified property from this configuration.
protected boolean	containsKeyInternal(String key) Actually checks whether the specified key is contained in this configuration.
protected String	getChildKey(String key) Return the key in the subset configuration associated to the specified key in the parent configuration.
protected Iterator<String>	getKeysInternal() Actually creates an iterator for iterating over the keys in this configuration.
protected Iterator<String>	getKeysInternal(String prefix) Returns an Iterator with all property keys starting with the specified prefix.
ListDelimiterHandler	getListDelimiterHandler() Returns the ListDelimiterHandler used by this instance.
Configuration	getParent() Return the parent configuration for this subset.
protected String	getParentKey(String key) Return the key in the parent configuration associated to the specified key in this subset.
String	getPrefix() Return the prefix used to select the properties in the parent configuration.
protected Object	getPropertyInternal(String key) Actually obtains the value of the specified property.
protected boolean	isEmptyInternal() Actually checks whether this configuration contains data.
boolean	isThrowExceptionOnMissing() Returns true if missing values throw Exceptions.
void	setListDelimiterHandler(ListDelimiterHandler listDelimiterHandler) Sets the ListDelimiterHandler to be used by this instance.
void	setPrefix(String prefix) Set the prefix used to select the properties in the parent configuration.
void	setThrowExceptionOnMissing(boolean throwExceptionOnMissing) Allows to set the throwExceptionOnMissing flag.
Configuration	subset(String prefix) Return a decorator Configuration containing every key from the current Configuration that starts with the specified prefix.

Methods inherited from class org.apache.commons.configuration2.AbstractConfiguration

addErrorLogListener, addProperty, addPropertyInternal, append, beginRead, beginWrite, clear, clearInternal, clearProperty, cloneInterpolator, containsKey, copy, endRead, endWrite, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getConfigurationDecoder, getConversionHandler, getDouble, getDouble, getDouble, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getKeys, getList, getList, getList, getList, getLogger, getLong, getLong, getLong, getProperties, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, getSynchronizer, immutableSubset, initLogger, installInterpolator, interpolate, interpolate, interpolatedConfiguration, isEmpty, isScalarValue, lock, setConfigurationDecoder, setConversionHandler, setDefaultLookups, setInterpolator, setLogger, setParentInterpolator, setPrefixLookups, setProperty, setPropertyInternal, setSynchronizer, size, sizeInternal, unlock

Methods inherited from class org.apache.commons.configuration2.event.BaseEventSource

addEventListener, clearErrorListeners, clearEventListeners, clone, copyEventListeners, createErrorEvent, createEvent, fireError, fireEvent, getEventListenerRegistrations, getEventListeners, isDetailEvents, removeEventListener, setDetailEvents

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

parent

protected Configuration parent

The parent configuration.

prefix

protected String prefix

The prefix used to select the properties.

delimiter

protected String delimiter

The prefix delimiter

Constructor Detail

SubsetConfiguration

public SubsetConfiguration(Configuration parent,
                           String prefix)

Create a subset of the specified configuration

Parameters:

parent - The parent configuration (must not be null)

prefix - The prefix used to select the properties

Throws:

IllegalArgumentException - if the parent configuration is null

SubsetConfiguration

public SubsetConfiguration(Configuration parent,
                           String prefix,
                           String delimiter)

Create a subset of the specified configuration

Parameters:

parent - The parent configuration (must not be null)

prefix - The prefix used to select the properties

delimiter - The prefix delimiter

Throws:

IllegalArgumentException - if the parent configuration is null

Method Detail

getParentKey

protected String getParentKey(String key)

Return the key in the parent configuration associated to the specified key in this subset.

Parameters:

key - The key in the subset.

Returns:

the key as to be used by the parent

getChildKey

protected String getChildKey(String key)

Return the key in the subset configuration associated to the specified key in the parent configuration.

Parameters:

key - The key in the parent configuration.

Returns:

the key in the context of this subset configuration

getParent

public Configuration getParent()

Return the parent configuration for this subset.

Returns:

the parent configuration

getPrefix

public String getPrefix()

Return the prefix used to select the properties in the parent configuration.

Returns:

the prefix used by this subset

setPrefix

public void setPrefix(String prefix)

Set the prefix used to select the properties in the parent configuration.

Parameters:

prefix - the prefix

subset

public Configuration subset(String prefix)

Description copied from interface: Configuration

Return a decorator Configuration containing every key from the current Configuration that starts with the specified prefix. The prefix is removed from the keys in the subset. For example, if the configuration contains the following properties:

    prefix.number = 1
    prefix.string = Apache
    prefixed.foo = bar
    prefix = Jakarta

the Configuration returned by subset("prefix") will contain the properties:

    number = 1
    string = Apache
    = Jakarta

(The key for the value "Jakarta" is an empty string)

Since the subset is a decorator and not a modified copy of the initial Configuration, any change made to the subset is available to the Configuration, and reciprocally.

Specified by:

subset in interface Configuration

Overrides:

subset in class AbstractConfiguration

Parameters:

prefix - The prefix used to select the properties.

Returns:

a subset configuration

See Also:

SubsetConfiguration

isEmptyInternal

protected boolean isEmptyInternal()

Description copied from class: AbstractConfiguration

Actually checks whether this configuration contains data. This method is called by isEmpty(). It has to be defined by concrete subclasses.

Specified by:

isEmptyInternal in class AbstractConfiguration

Returns:

true if this configuration contains no data, false otherwise

containsKeyInternal

protected boolean containsKeyInternal(String key)

Description copied from class: AbstractConfiguration

Actually checks whether the specified key is contained in this configuration. This method is called by containsKey(). It has to be defined by concrete subclasses.

Specified by:

containsKeyInternal in class AbstractConfiguration

Parameters:

key - the key in question

Returns:

true if this key is contained in this configuration, false otherwise

addPropertyDirect

public void addPropertyDirect(String key,
                              Object value)

Description copied from class: AbstractConfiguration

Adds a key/value pair to the Configuration. Override this method to provide write access to underlying Configuration store.

Specified by:

addPropertyDirect in class AbstractConfiguration

Parameters:

key - key to use for mapping

value - object to store

clearPropertyDirect

protected void clearPropertyDirect(String key)

Description copied from class: AbstractConfiguration

Removes the specified property from this configuration. This method is called by clearProperty() after it has done some preparations. It must be overridden in sub classes.

Specified by:

clearPropertyDirect in class AbstractConfiguration

Parameters:

key - the key to be removed

getPropertyInternal

protected Object getPropertyInternal(String key)

Description copied from class: AbstractConfiguration

Actually obtains the value of the specified property. This method is called by getProperty(). Concrete subclasses must define it to fetch the value of the desired property.

Specified by:

getPropertyInternal in class AbstractConfiguration

Parameters:

key - the key of the property in question

Returns:

the (raw) value of this property

getKeysInternal

protected Iterator<String> getKeysInternal(String prefix)

Description copied from class: AbstractConfiguration

Returns an Iterator with all property keys starting with the specified prefix. This method is called by AbstractConfiguration.getKeys(String). It is fully implemented by delegating to getKeysInternal() and returning a special iterator which filters for the passed in prefix. Subclasses can override it if they can provide a more efficient way to iterate over specific keys only.

Overrides:

getKeysInternal in class AbstractConfiguration

Parameters:

prefix - the prefix for the keys to be taken into account

Returns:

an Iterator returning the filtered keys

getKeysInternal

protected Iterator<String> getKeysInternal()

Description copied from class: AbstractConfiguration

Actually creates an iterator for iterating over the keys in this configuration. This method is called by getKeys(), it has to be defined by concrete subclasses.

Specified by:

getKeysInternal in class AbstractConfiguration

Returns:

an Iterator with all property keys in this configuration

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. Change the behavior of the parent configuration if it supports this feature.

Overrides:

setThrowExceptionOnMissing in class AbstractConfiguration

Parameters:

throwExceptionOnMissing - The new value for the property

isThrowExceptionOnMissing

public boolean isThrowExceptionOnMissing()

Returns true if missing values throw Exceptions. The subset inherits this feature from its parent if it supports this feature.

Overrides:

isThrowExceptionOnMissing in class AbstractConfiguration

Returns:

true if missing values throw Exceptions

getListDelimiterHandler

public ListDelimiterHandler getListDelimiterHandler()

Returns the ListDelimiterHandler used by this instance. If the parent configuration extends AbstractConfiguration, the list delimiter handler is obtained from there.

Overrides:

getListDelimiterHandler in class AbstractConfiguration

Returns:

the ListDelimiterHandler

setListDelimiterHandler

public void setListDelimiterHandler(ListDelimiterHandler listDelimiterHandler)

Sets the ListDelimiterHandler to be used by this instance. This object is invoked every time when dealing with string properties that may contain a list delimiter and thus have to be split to multiple values. Per default, a ListDelimiterHandler implementation is set which does not support list splitting. This can be changed for instance by setting a DefaultListDelimiterHandler object.

Warning: Be careful when changing the list delimiter handler when the configuration has already been loaded/populated. List handling is typically applied already when properties are added to the configuration. If later another handler is set which processes lists differently, results may be unexpected; some operations may even cause exceptions.

If the parent configuration extends AbstractConfiguration, the list delimiter handler is passed to the parent.

Overrides:

setListDelimiterHandler in class AbstractConfiguration

Parameters:

listDelimiterHandler - the ListDelimiterHandler to be used (must not be null)