Package 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
  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
  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
  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 boolean`
  `containsValueInternal(Object value)`
  Tests whether this configuration contains one or more matches to this value.
  `protected String`
  `getChildKey(String key)`
  Gets 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)`
  Gets an `Iterator` with all property keys starting with the specified prefix.
  `ListDelimiterHandler`
  `getListDelimiterHandler()`
  Gets the `ListDelimiterHandler` used by this instance.
  `Configuration`
  `getParent()`
  Gets the parent configuration for this subset.
  `protected String`
  `getParentKey(String key)`
  Gets the key in the parent configuration associated to the specified key in this subset.
  `String`
  `getPrefix()`
  Gets 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)`
  Sets 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, contains, containsKey, containsValue, copy, endRead, endWrite, get, get, getArray, getArray, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getCollection, getCollection, getConfigurationDecoder, getConversionHandler, getDouble, getDouble, getDouble, getDuration, getDuration, getEncodedString, getEncodedString, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getKeys, getKeys, getKeys, getKeysInternal, 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`

  ### Methods inherited from interface org.apache.commons.configuration2.ImmutableConfiguration

  `entrySet, forEach, getEnum, getEnum`

- ## Field Details

  - ### 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 Details

  - ### 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:
      `NullPointerException` - if the parent configuration is null

- ## Method Details

  - ### 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

  - ### 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

  - ### containsValueInternal

    protected boolean containsValueInternal(Object value)
    Tests whether this configuration contains one or more matches to this value. This operation stops at first match but may be more expensive than the containsKey method.
    Specified by:
      `containsValueInternal` in class `AbstractConfiguration`
    Parameters:
      `value` - the value in question
    Returns:
      `true` if and only if some key maps to the `value` argument in this configuration as determined by the `equals` method; `false` otherwise.
    Since:
      2.11.0

  - ### getChildKey

    protected String getChildKey(String key)
    Gets 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

  - ### 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

  - ### getKeysInternal

    protected Iterator<String> getKeysInternal(String prefix)
    Description copied from class: `AbstractConfiguration`
    Gets 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

  - ### getListDelimiterHandler

    public ListDelimiterHandler getListDelimiterHandler()
    Gets 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`

  - ### getParent

    public Configuration getParent()
    Gets the parent configuration for this subset.
    Returns:
      the parent configuration

  - ### getParentKey

    protected String getParentKey(String key)
    Gets 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

  - ### getPrefix

    public String getPrefix()
    Gets the prefix used to select the properties in the parent configuration.
    Returns:
      the prefix used by this subset

  - ### 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

  - ### 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

  - ### 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

  - ### 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)

  - ### setPrefix

    public void setPrefix(String prefix)
    Sets the prefix used to select the properties in the parent configuration.
    Parameters:
      `prefix` - the prefix

  - ### 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

  - ### 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`