Package org.apache.commons.configuration2.builder

# Class BasicBuilderParameters

java.lang.Object
org.apache.commons.configuration2.builder.BasicBuilderParameters

All Implemented Interfaces:
  `Cloneable`, `BasicBuilderProperties<BasicBuilderParameters>`, `BuilderParameters`

Direct Known Subclasses:
  `CombinedBuilderParametersImpl`, `DatabaseBuilderParametersImpl`, `FileBasedBuilderParametersImpl`, `JndiBuilderParametersImpl`, `MultiFileBuilderParametersImpl`

public class BasicBuilderParameters extends Object implements Cloneable, BuilderParameters, BasicBuilderProperties<BasicBuilderParameters>

An implementation of `BuilderParameters` which handles the parameters of a `ConfigurationBuilder` common to all concrete `Configuration` implementations.

This class provides methods for setting standard properties supported by the `AbstractConfiguration` base class. A fluent interface can be used to set property values.

This class is not thread-safe. It is intended that an instance is constructed and initialized by a single thread during configuration of a `ConfigurationBuilder`.

Since:
  2.0

- ## Field Summary

  ### Fields inherited from interface org.apache.commons.configuration2.builder.BuilderParameters

  `RESERVED_PARAMETER_PREFIX`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BasicBuilderParameters()`
  Creates a new instance of `BasicBuilderParameters`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `BasicBuilderParameters`
  `clone()`
  Clones this object.
  `protected void`
  `copyPropertiesFrom(Map<String,?> source, String... keys)`
  Copies a number of properties from the given map into this object.
  `static BeanHelper`
  `fetchBeanHelper(Map<String,Object> params)`
  Obtains the `BeanHelper` object from the specified map with parameters.
  `static InterpolatorSpecification`
  `fetchInterpolatorSpecification(Map<String,Object> params)`
  Obtains a specification for a `ConfigurationInterpolator` from the specified map with parameters.
  `protected Object`
  `fetchProperty(String key)`
  Obtains the value of the specified property from the internal map.
  `Map<String,Object>`
  `getParameters()`
  Gets a map with all parameters defined by this objects.
  `void`
  `inheritFrom(Map<String,?> source)`
  Inherits properties from the specified map.
  `void`
  `merge(BuilderParameters p)`
  Merges this object with the given parameters object.
  `BasicBuilderParameters`
  `setBeanHelper(BeanHelper beanHelper)`
  Sets a `BeanHelper` object to be used by the configuration builder.
  `BasicBuilderParameters`
  `setConfigurationDecoder(ConfigurationDecoder decoder)`
  Sets the `ConfigurationDecoder` object for this configuration.
  `BasicBuilderParameters`
  `setConversionHandler(ConversionHandler handler)`
  Sets the `ConversionHandler` object for this configuration.
  `BasicBuilderParameters`
  `setDefaultLookups(Collection<? extends Lookup> lookups)`
  Adds additional default `Lookup` objects (i.e. lookups which are not associated with a specific prefix) to this configuration object.
  `BasicBuilderParameters`
  `setInterpolator(ConfigurationInterpolator ci)`
  Sets the `ConfigurationInterpolator` to be used for this configuration.
  `BasicBuilderParameters`
  `setListDelimiterHandler(ListDelimiterHandler handler)`
  Sets the value of the listDelimiterHandler property.
  `BasicBuilderParameters`
  `setLogger(ConfigurationLogger log)`
  Sets the logger property.
  `BasicBuilderParameters`
  `setParentInterpolator(ConfigurationInterpolator parent)`
  Sets the parent `ConfigurationInterpolator` for this configuration's `ConfigurationInterpolator`.
  `BasicBuilderParameters`
  `setPrefixLookups(Map<String,? extends Lookup> lookups)`
  Sets additional `Lookup` objects for specific prefixes for this configuration object.
  `BasicBuilderParameters`
  `setSynchronizer(Synchronizer sync)`
  Sets the `Synchronizer` object for this configuration.
  `BasicBuilderParameters`
  `setThrowExceptionOnMissing(boolean b)`
  Sets the value of the throwExceptionOnMissing property.
  `protected void`
  `storeProperty(String key, Object value)`
  Sets a property for this parameters object.

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

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

- ## Constructor Details

  - ### BasicBuilderParameters

    public BasicBuilderParameters()
    Creates a new instance of `BasicBuilderParameters`.

- ## Method Details

  - ### fetchBeanHelper

    public static BeanHelper fetchBeanHelper(Map<String,Object> params)
    Obtains the `BeanHelper` object from the specified map with parameters. This method can be used to obtain an instance from a parameters map that has been set via the `setBeanHelper()` method. If no such instance is found, result is null.
    Parameters:
      `params` - the map with parameters (must not be null)
    Returns:
      the `BeanHelper` stored in this map or null
    Throws:
      `IllegalArgumentException` - if the map is null

  - ### fetchInterpolatorSpecification

    public static InterpolatorSpecification fetchInterpolatorSpecification(Map<String,Object> params)
    Obtains a specification for a `ConfigurationInterpolator` from the specified map with parameters. All properties related to interpolation are evaluated and added to the specification object.
    Parameters:
      `params` - the map with parameters (must not be null)
    Returns:
      an `InterpolatorSpecification` object constructed with data from the map
    Throws:
      `IllegalArgumentException` - if the map is null or contains invalid data

  - ### clone

    public BasicBuilderParameters clone()
    Clones this object. This is useful because multiple builder instances may use a similar set of parameters. However, single instances of parameter objects must not assigned to multiple builders. Therefore, cloning a parameters object provides a solution for this use case. This method creates a new parameters object with the same content as this one. The internal map storing the parameter values is cloned, too, also collection structures contained in this map. However, no a full deep clone operation is performed. Objects like a `ConfigurationInterpolator` or `Lookup`s are shared between this and the newly created instance.
    Overrides:
      `clone` in class `Object`
    Returns:
      a clone of this object

  - ### copyPropertiesFrom

    protected void copyPropertiesFrom(Map<String,?> source, String... keys)
    Copies a number of properties from the given map into this object. Properties are only copied if they are defined in the source map.
    Parameters:
      `source` - the source map
      `keys` - the keys to be copied

  - ### fetchProperty

    protected Object fetchProperty(String key)
    Obtains the value of the specified property from the internal map. This method can be used by derived classes if a specific property is to be accessed. If the given key is not found, result is null.
    Parameters:
      `key` - the key of the property in question
    Returns:
      the value of the property with this key or null

  - ### getParameters

    public Map<String,Object> getParameters()
    Gets a map with all parameters defined by this objects. The keys of the map correspond to concrete properties supported by the `Configuration` implementation class the builder produces. The values are the corresponding property values. The return value must not be null. This implementation returns a copy of the internal parameters map with the values set so far. Collection structures (for example for lookup objects) are stored as defensive copies, so the original data cannot be modified.
    Specified by:
      `getParameters` in interface `BuilderParameters`
    Returns:
      a map with builder parameters

  - ### inheritFrom

    public void inheritFrom(Map<String,?> source)
    Inherits properties from the specified map. This can be used for instance to reuse parameters from one builder in another builder - also in parent-child relations in which a parent builder creates child builders. The purpose of this method is to let a concrete implementation decide which properties can be inherited. Because parameters are basically organized as a map it would be possible to simply copy over all properties from the source object. However, this is not appropriate in all cases. For instance, some properties - like a `ConfigurationInterpolator` - are tightly connected to a configuration and cannot be reused in a different context. For other properties, for example a file name, it does not make sense to copy it. Therefore, an implementation has to be explicit in the properties it wants to take over.
    Parameters:
      `source` - the source properties to inherit from
    Throws:
      `IllegalArgumentException` - if the source map is null

  - ### merge

    public void merge(BuilderParameters p)
    Merges this object with the given parameters object. This method adds all property values defined by the passed in parameters object to the internal storage which are not already in. So properties already defined in this object take precedence. Property names starting with the reserved parameter prefix are ignored.
    Parameters:
      `p` - the object whose properties should be merged (must not be null)
    Throws:
      `IllegalArgumentException` - if the passed in object is null

  - ### setBeanHelper

    public BasicBuilderParameters setBeanHelper(BeanHelper beanHelper)
    Sets a `BeanHelper` object to be used by the configuration builder. The `BeanHelper` is used to create the managed configuration instance dynamically. It is not a property of the configuration as most other properties defined by this interface. By setting an alternative `BeanHelper` the process of creating configuration instances via reflection can be adapted. (Some specialized configuration builder implementations also use a `BeanHelper` to create complex helper objects during construction of their result object. `CombinedConfigurationBuilder` for instance supports a complex configuration definition format which may contain several specialized bean declarations.) If no specific `BeanHelper` is set, the builder uses the default instance. This implementation stores the passed in `BeanHelper` object in the internal parameters map, but uses a reserved key, so that it is not used for the initialization of properties of the managed configuration object. The `fetchBeanHelper()` method can be used to obtain the `BeanHelper` instance from a parameters map.
    Specified by:
      `setBeanHelper` in interface `BasicBuilderProperties<BasicBuilderParameters>`
    Parameters:
      `beanHelper` - the `BeanHelper` to be used by the builder
    Returns:
      a reference to this object for method chaining

  - ### setConfigurationDecoder

    public BasicBuilderParameters setConfigurationDecoder(ConfigurationDecoder decoder)
    Sets the `ConfigurationDecoder` object for this configuration. This object is called when encoded properties are queried using the `getEncodedString()` method. This implementation stores the passed in `ConfigurationDecoder` object in the internal parameters map.
    Specified by:
      `setConfigurationDecoder` in interface `BasicBuilderProperties<BasicBuilderParameters>`
    Parameters:
      `decoder` - the `ConfigurationDecoder` to be used
    Returns:
      a reference to this object for method chaining

  - ### setConversionHandler

    public BasicBuilderParameters setConversionHandler(ConversionHandler handler)
    Sets the `ConversionHandler` object for this configuration. This object is responsible for all data type conversions required for accessing configuration properties in a specific target type. If this property is not set, a default `ConversionHandler` is used. This implementation stores the passed in `ConversionHandler` object in the internal parameters map.
    Specified by:
      `setConversionHandler` in interface `BasicBuilderProperties<BasicBuilderParameters>`
    Parameters:
      `handler` - the `ConversionHandler` to be used
    Returns:
      a reference to this object for method chaining

  - ### setDefaultLookups

    public BasicBuilderParameters setDefaultLookups(Collection<? extends Lookup> lookups)
    Adds additional default `Lookup` objects (i.e. lookups which are not associated with a specific prefix) to this configuration object. Note: This method only takes effect if no `ConfigurationInterpolator` is set using the `BasicBuilderProperties.setInterpolator(ConfigurationInterpolator)` method. A defensive copy of the passed in collection is created. A null argument causes all default lookups to be removed from the internal parameters map.
    Specified by:
      `setDefaultLookups` in interface `BasicBuilderProperties<BasicBuilderParameters>`
    Parameters:
      `lookups` - a collection with `Lookup` objects to be added as default lookups at the configuration's `ConfigurationInterpolator`
    Returns:
      a reference to this object for method chaining
    See Also:
      - `ConfigurationInterpolator.addDefaultLookups(Collection)`

  - ### setInterpolator

    public BasicBuilderParameters setInterpolator(ConfigurationInterpolator ci)
    Sets the `ConfigurationInterpolator` to be used for this configuration. Using this method a custom `ConfigurationInterpolator` can be set which can be freely configured. Alternatively, it is possible to add custom `Lookup` objects using other methods provided by this interface. The passed in `ConfigurationInterpolator` is set without modifications.
    Specified by:
      `setInterpolator` in interface `BasicBuilderProperties<BasicBuilderParameters>`
    Parameters:
      `ci` - the `ConfigurationInterpolator` for this configuration
    Returns:
      a reference to this object for method chaining

  - ### setListDelimiterHandler

    public BasicBuilderParameters setListDelimiterHandler(ListDelimiterHandler handler)
    Sets the value of the listDelimiterHandler property. This property defines the object responsible for dealing with list delimiter and escaping characters. Note: `AbstractConfiguration` does not allow setting this property to null. If the default `ListDelimiterHandler` is to be used, do not call this method.
    Specified by:
      `setListDelimiterHandler` in interface `BasicBuilderProperties<BasicBuilderParameters>`
    Parameters:
      `handler` - the `ListDelimiterHandler`
    Returns:
      a reference to this object for method chaining

  - ### setLogger

    public BasicBuilderParameters setLogger(ConfigurationLogger log)
    Sets the logger property. With this property a concrete `Log` object can be set for the configuration. Thus logging behavior can be controlled.
    Specified by:
      `setLogger` in interface `BasicBuilderProperties<BasicBuilderParameters>`
    Parameters:
      `log` - the `Log` for the configuration produced by this builder
    Returns:
      a reference to this object for method chaining

  - ### setParentInterpolator

    public BasicBuilderParameters setParentInterpolator(ConfigurationInterpolator parent)
    Sets the parent `ConfigurationInterpolator` for this configuration's `ConfigurationInterpolator`. Setting a parent `ConfigurationInterpolator` can be used for defining a default behavior for variables which cannot be resolved. This implementation stores the passed in `ConfigurationInterpolator` object in the internal parameters map.
    Specified by:
      `setParentInterpolator` in interface `BasicBuilderProperties<BasicBuilderParameters>`
    Parameters:
      `parent` - the new parent `ConfigurationInterpolator`
    Returns:
      a reference to this object for method chaining
    See Also:
      - `ConfigurationInterpolator.setParentInterpolator(ConfigurationInterpolator)`

  - ### setPrefixLookups

    public BasicBuilderParameters setPrefixLookups(Map<String,? extends Lookup> lookups)
    Sets additional `Lookup` objects for specific prefixes for this configuration object. All `Lookup` objects contained in the given map are added to the configuration's `ConfigurationInterpolator`. Note: This method only takes effect if no `ConfigurationInterpolator` is set using the `BasicBuilderProperties.setInterpolator(ConfigurationInterpolator)` method. A defensive copy of the passed in map is created. A null argument causes all prefix lookups to be removed from the internal parameters map.
    Specified by:
      `setPrefixLookups` in interface `BasicBuilderProperties<BasicBuilderParameters>`
    Parameters:
      `lookups` - a map with `Lookup` objects and their associated prefixes
    Returns:
      a reference to this object for method chaining
    See Also:
      - `ConfigurationInterpolator.registerLookups(Map)`

  - ### setSynchronizer

    public BasicBuilderParameters setSynchronizer(Synchronizer sync)
    Sets the `Synchronizer` object for this configuration. This object is used to protect this configuration instance against concurrent access. The concrete `Synchronizer` implementation used determines whether a configuration instance is thread-safe or not. This implementation stores the passed in `Synchronizer` object in the internal parameters map.
    Specified by:
      `setSynchronizer` in interface `BasicBuilderProperties<BasicBuilderParameters>`
    Parameters:
      `sync` - the `Synchronizer` to be used (a value of null means that a default `Synchronizer` is used)
    Returns:
      a reference to this object for method chaining

  - ### setThrowExceptionOnMissing

    public BasicBuilderParameters setThrowExceptionOnMissing(boolean b)
    Sets the value of the throwExceptionOnMissing property. This property controls the configuration's behavior if missing properties are queried: a value of true causes the configuration to throw an exception, for a value of false it will return null values. (Note: Methods returning a primitive data type will always throw an exception if the property is not defined.)
    Specified by:
      `setThrowExceptionOnMissing` in interface `BasicBuilderProperties<BasicBuilderParameters>`
    Parameters:
      `b` - the value of the property
    Returns:
      a reference to this object for method chaining

  - ### storeProperty

    protected void storeProperty(String key, Object value)
    Sets a property for this parameters object. Properties are stored in an internal map. With this method a new entry can be added to this map. If the value is null, the key is removed from the internal map. This method can be used by sub classes which also store properties in a map.
    Parameters:
      `key` - the key of the property
      `value` - the value of the property