MapConfiguration (Apache Commons Configuration 2.15.1 API)
Description: declaration: package: org.apache.commons.configuration2, class: MapConfiguration

Package org.apache.commons.configuration2

# Class MapConfiguration

java.lang.Object
org.apache.commons.configuration2.event.BaseEventSource
org.apache.commons.configuration2.AbstractConfiguration
org.apache.commons.configuration2.MapConfiguration

All Implemented Interfaces:
  `Cloneable`, `Configuration`, `EventSource`, `ImmutableConfiguration`, `SynchronizerSupport`

Direct Known Subclasses:
  `EnvironmentConfiguration`, `SystemConfiguration`

public class MapConfiguration extends AbstractConfiguration implements Cloneable

A Map based Configuration.

This implementation of the `Configuration` interface is initialized with a `Map`. The methods of the `Configuration` interface are implemented on top of the content of this map. The following storage scheme is used:

Property keys are directly mapped to map keys, i.e. the `getProperty()` method directly performs a `get()` on the map. Analogously, `setProperty()` or `addProperty()` operations write new data into the map. If a value is added to an existing property, a `List` is created, which stores the values of this property.

An important use case of this class is to treat a map as a `Configuration` allowing access to its data through the richer interface. This can be a bit problematic in some cases because the map may contain values that need not adhere to the default storage scheme used by typical configuration implementations, for example regarding lists. In such cases care must be taken when manipulating the data through the `Configuration` interface, for example by calling `addProperty()`; results may be different than expected.

The handling of list delimiters is a bit different for this configuration implementation: When a property of type String is queried, it is passed to the current `ListDelimiterHandler` which may generate multiple values. Note that per default a list delimiter handler is set which does not do any list splitting, so this feature is disabled. It can be enabled by setting a properly configured `ListDelimiterHandler` implementation, for example a `DefaultListDelimiterHandler` object.

Notice that list splitting is only performed for single string values. If a property has multiple values, the single values are not split even if they contain the list delimiter character.

As the underlying `Map` is directly used as store of the property values, the thread-safety of this `Configuration` implementation depends on the map passed to the constructor.

Notes about type safety: For properties with multiple values this implementation creates lists of type `Object` and stores them. If a property is assigned another value, the value is added to the list. This can cause problems if the map passed to the constructor already contains lists of other types. This should be avoided, otherwise it cannot be guaranteed that the application might throw `ClassCastException` exceptions later.

Since:
  1.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Map<String,Object>`
  `map`
  The Map decorated by this configuration.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MapConfiguration(Map<String,?> map)`
  Create a Configuration decorator around the specified Map.
  `MapConfiguration(Properties props)`
  Creates a new instance of `MapConfiguration` which uses the specified `Properties` object as its data store.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected 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.
  `Object`
  `clone()`
  Returns a copy of this object.
  `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 Iterator<String>`
  `getKeysInternal()`
  Creates an iterator for iterating over the keys in this configuration.
  `Map<String,Object>`
  `getMap()`
  Gets the Map decorated by this 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`
  `isTrimmingDisabled()`
  Tests whether the flag whether trimming of property values is disabled.
  `void`
  `setTrimmingDisabled(boolean trimmingDisabled)`
  Sets a flag whether trimming of property values is disabled.
  `protected int`
  `sizeInternal()`
  Actually calculates the size of this configuration.
  `String`
  `toString()`
  Converts this object to a String suitable for debugging and logging.

  ### 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, getKeysInternal, getList, getList, getList, getList, getListDelimiterHandler, getLogger, getLong, getLong, getLong, getProperties, getProperties, getProperty, getShort, getShort, getShort, getString, getString, getStringArray, getSynchronizer, immutableSubset, initLogger, installInterpolator, interpolate, interpolate, interpolatedConfiguration, isEmpty, isScalarValue, isThrowExceptionOnMissing, lock, setConfigurationDecoder, setConversionHandler, setDefaultLookups, setInterpolator, setListDelimiterHandler, setLogger, setParentInterpolator, setPrefixLookups, setProperty, setPropertyInternal, setSynchronizer, setThrowExceptionOnMissing, size, subset, unlock`

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

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

  ### Methods inherited from class java.lang.Object

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

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

  `entrySet, forEach, getEnum, getEnum`

- ## Field Details

  - ### map

    protected Map<String,Object> map
    The Map decorated by this configuration.

- ## Constructor Details

  - ### MapConfiguration

    public MapConfiguration(Map<String,?> map)
    Create a Configuration decorator around the specified Map. The map is used to store the configuration properties, any change will also affect the Map.
    Parameters:
      `map` - the map.

  - ### MapConfiguration

    public MapConfiguration(Properties props)
    Creates a new instance of `MapConfiguration` which uses the specified `Properties` object as its data store. All changes of this configuration affect the given `Properties` object and vice versa. Note that while `Properties` actually implements `Map<Object, Object>`, we expect it to contain only string keys. Other key types will lead to `ClassCastException` exceptions on certain methods.
    Parameters:
      `props` - the `Properties` object defining the content of this configuration.
    Since:
      1.8

- ## Method Details

  - ### addPropertyDirect

    protected 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

  - ### clone

    public Object clone()
    Returns a copy of this object. The returned configuration will contain the same properties as the original. Event listeners are not cloned.
    Overrides:
      `clone` in class `BaseEventSource`
    Returns:
      the copy.
    Since:
      1.3

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

  - ### getKeysInternal

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

  - ### getMap

    public Map<String,Object> getMap()
    Gets the Map decorated by this configuration.
    Returns:
      the map this configuration is based onto.

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

  - ### isTrimmingDisabled

    public boolean isTrimmingDisabled()
    Tests whether the flag whether trimming of property values is disabled.
    Returns:
      true if trimming of property values is disabled; false otherwise.
    Since:
      1.7

  - ### setTrimmingDisabled

    public void setTrimmingDisabled(boolean trimmingDisabled)
    Sets a flag whether trimming of property values is disabled. This flag is only evaluated if list splitting is enabled. Refer to the header comment for more information about list splitting and trimming.
    Parameters:
      `trimmingDisabled` - a flag whether trimming of property values should be disabled.
    Since:
      1.7

  - ### sizeInternal

    protected int sizeInternal()
    Description copied from class: `AbstractConfiguration`
    Actually calculates the size of this configuration. This method is called by `size()` with a read lock held. The base implementation provided here calculates the size based on the iterator returned by `getKeys()`. Sub classes which can determine the size in a more efficient way should override this method.
    Overrides:
      `sizeInternal` in class `AbstractConfiguration`
    Returns:
      the size of this configuration (i.e. the number of keys).

  - ### toString

    public String toString()
    Converts this object to a String suitable for debugging and logging.
    Overrides:
      `toString` in class `Object`
    Since:
      2.3