Package org.apache.commons.configuration2.builder.combined

# Class CombinedBuilderParametersImpl

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

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

public class CombinedBuilderParametersImpl extends BasicBuilderParameters implements CombinedBuilderProperties<CombinedBuilderParametersImpl>

A specialized parameters object for a `CombinedConfigurationBuilder`.

This class defines methods for setting properties for customizing a builder for combined configurations. Note that some of these properties can also be set in the configuration definition file. If this is the case, the settings in the definition file override the content of this object.

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
  `CombinedBuilderParametersImpl()`
  Creates a new instance of `CombinedBuilderParametersImpl`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `CombinedBuilderParametersImpl`
  `clone()`
  Clones this object.
  `static CombinedBuilderParametersImpl`
  `fromParameters(Map<String,?> params)`
  Looks up an instance of this class in the specified parameters map.
  `static CombinedBuilderParametersImpl`
  `fromParameters(Map<String,?> params, boolean createIfMissing)`
  Looks up an instance of this class in the specified parameters map and optionally creates a new one if none is found.
  `String`
  `getBasePath()`
  Gets the base path for relative names of configuration sources.
  `DefaultParametersManager`
  `getChildDefaultParametersManager()`
  Gets the `DefaultParametersManager` object for initializing parameter objects for child configuration sources.
  `Collection<? extends BuilderParameters>`
  `getDefaultChildParameters()`
  Gets a collection with default parameter objects for child configuration sources.
  `ConfigurationBuilder<? extends HierarchicalConfiguration<?>>`
  `getDefinitionBuilder()`
  Gets the `ConfigurationBuilder` object for obtaining the definition configuration.
  `BuilderParameters`
  `getDefinitionBuilderParameters()`
  Gets the parameters object for the definition configuration builder if present.
  `Map<String,Object>`
  `getParameters()`
  Gets a map with all parameters defined by this objects.
  `Map<String,ConfigurationBuilderProvider>`
  `getProviders()`
  Gets an (unmodifiable) map with the currently registered `ConfigurationBuilderProvider` objects.
  `void`
  `inheritFrom(Map<String,?> source)`
  Inherits properties from the specified map.
  `boolean`
  `isInheritSettings()`
  Returns the current value of the flag that controls whether the settings of the parent combined configuration builder should be inherited by its child configurations.
  `ConfigurationBuilderProvider`
  `providerForTag(String tagName)`
  Returns the `ConfigurationBuilderProvider` which is registered for the specified tag name or null if there is no registration for this tag.
  `<D> CombinedBuilderParametersImpl`
  `registerChildDefaultsHandler(Class<D> paramClass, DefaultParametersHandler<? super D> handler)`
  Registers a `DefaultParametersHandler` for child configuration sources.
  `<D> CombinedBuilderParametersImpl`
  `registerChildDefaultsHandler(Class<D> paramClass, DefaultParametersHandler<? super D> handler, Class<?> startClass)`
  Registers a `DefaultParametersHandler` for child configuration sources derived from the given start class.
  `CombinedBuilderParametersImpl`
  `registerMissingProviders(Map<String,ConfigurationBuilderProvider> providers)`
  Registers all `ConfigurationBuilderProvider`s in the given map to this object which have not yet been registered.
  `CombinedBuilderParametersImpl`
  `registerMissingProviders(CombinedBuilderParametersImpl params)`
  Registers all `ConfigurationBuilderProvider`s in the given parameters object which have not yet been registered.
  `CombinedBuilderParametersImpl`
  `registerProvider(String tagName, ConfigurationBuilderProvider provider)`
  Registers the given `ConfigurationBuilderProvider` for the specified tag name.
  `CombinedBuilderParametersImpl`
  `setBasePath(String path)`
  Sets the base path for this combined configuration builder.
  `CombinedBuilderParametersImpl`
  `setChildDefaultParametersManager(DefaultParametersManager manager)`
  Sets a `DefaultParametersManager` object responsible for managing the default parameter handlers to be applied on child configuration sources.
  `CombinedBuilderParametersImpl`
  `setDefinitionBuilder(ConfigurationBuilder<? extends HierarchicalConfiguration<?>> builder)`
  Sets the `ConfigurationBuilder` for the definition configuration.
  `CombinedBuilderParametersImpl`
  `setDefinitionBuilderParameters(BuilderParameters params)`
  Sets the parameters object for the definition configuration builder.
  `CombinedBuilderParametersImpl`
  `setInheritSettings(boolean inheritSettings)`
  Sets a flag whether the child configurations created by a `CombinedConfigurationBuilder` should inherit the settings defined for the builder.

  ### Methods inherited from class org.apache.commons.configuration2.builder.BasicBuilderParameters

  `copyPropertiesFrom, fetchBeanHelper, fetchInterpolatorSpecification, fetchProperty, merge, setBeanHelper, setConfigurationDecoder, setConversionHandler, setDefaultLookups, setInterpolator, setListDelimiterHandler, setLogger, setParentInterpolator, setPrefixLookups, setSynchronizer, setThrowExceptionOnMissing, storeProperty`

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

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

- ## Constructor Details

  - ### CombinedBuilderParametersImpl

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

- ## Method Details

  - ### fromParameters

    public static CombinedBuilderParametersImpl fromParameters(Map<String,?> params)
    Looks up an instance of this class in the specified parameters map. This is equivalent to `fromParameters(params, false);`
    Parameters:
      `params` - the map with parameters (must not be null
    Returns:
      the instance obtained from the map or null
    Throws:
      `NullPointerException` - if the map is null

  - ### fromParameters

    public static CombinedBuilderParametersImpl fromParameters(Map<String,?> params, boolean createIfMissing)
    Looks up an instance of this class in the specified parameters map and optionally creates a new one if none is found. This method can be used to obtain an instance of this class which has been stored in a parameters map. It is compatible with the `getParameters()` method.
    Parameters:
      `params` - the map with parameters (must not be null
      `createIfMissing` - determines the behavior if no instance is found in the map; if true, a new instance with default settings is created; if false, null is returned
    Returns:
      the instance obtained from the map or null
    Throws:
      `NullPointerException` - if the map is null

  - ### 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, e.g. 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. This implementation additionally copies some properties defined by this class.
    Overrides:
      `inheritFrom` in class `BasicBuilderParameters`
    Parameters:
      `source` - the source properties to inherit from

  - ### isInheritSettings

    public boolean isInheritSettings()
    Returns the current value of the flag that controls whether the settings of the parent combined configuration builder should be inherited by its child configurations.
    Returns:
      the flag whether settings should be inherited by child configurations

  - ### setInheritSettings

    public CombinedBuilderParametersImpl setInheritSettings(boolean inheritSettings)
    Description copied from interface: `CombinedBuilderProperties`
    Sets a flag whether the child configurations created by a `CombinedConfigurationBuilder` should inherit the settings defined for the builder. This is typically useful because for configurations coming from homogeneous sources often similar conventions are used. Therefore, this flag is true per default.
    Specified by:
      `setInheritSettings` in interface `CombinedBuilderProperties<CombinedBuilderParametersImpl>`
    Parameters:
      `inheritSettings` - the flag whether settings should be inherited by child configurations
    Returns:
      a reference to this object for method chaining

  - ### getDefinitionBuilder

    public ConfigurationBuilder<? extends HierarchicalConfiguration<?>> getDefinitionBuilder()
    Gets the `ConfigurationBuilder` object for obtaining the definition configuration.
    Returns:
      the definition `ConfigurationBuilder`

  - ### setDefinitionBuilder

    public CombinedBuilderParametersImpl setDefinitionBuilder(ConfigurationBuilder<? extends HierarchicalConfiguration<?>> builder)
    Sets the `ConfigurationBuilder` for the definition configuration. This is the configuration which contains the configuration sources that form the combined configuration.
    Specified by:
      `setDefinitionBuilder` in interface `CombinedBuilderProperties<CombinedBuilderParametersImpl>`
    Parameters:
      `builder` - the definition `ConfigurationBuilder`
    Returns:
      a reference to this object for method chaining

  - ### registerProvider

    public CombinedBuilderParametersImpl registerProvider(String tagName, ConfigurationBuilderProvider provider)
    Registers the given `ConfigurationBuilderProvider` for the specified tag name. This means that whenever this tag is encountered in a configuration definition file, the corresponding builder provider is invoked.
    Specified by:
      `registerProvider` in interface `CombinedBuilderProperties<CombinedBuilderParametersImpl>`
    Parameters:
      `tagName` - the name of the tag (must not be null)
      `provider` - the `ConfigurationBuilderProvider` (must not be null)
    Returns:
      a reference to this object for method chaining
    Throws:
      `IllegalArgumentException` - if a required parameter is missing

  - ### registerMissingProviders

    public CombinedBuilderParametersImpl registerMissingProviders(Map<String,ConfigurationBuilderProvider> providers)
    Registers all `ConfigurationBuilderProvider`s in the given map to this object which have not yet been registered. This method is mainly used for internal purposes: a `CombinedConfigurationBuilder` takes the providers contained in a parameters object and adds all standard providers. This way it is possible to override a standard provider by registering a provider object for the same tag name at the parameters object.
    Parameters:
      `providers` - a map with tag names and corresponding providers (must not be null or contain null entries)
    Returns:
      a reference to this object for method chaining
    Throws:
      `IllegalArgumentException` - if the map with providers is null or contains null entries

  - ### registerMissingProviders

    public CombinedBuilderParametersImpl registerMissingProviders(CombinedBuilderParametersImpl params)
    Registers all `ConfigurationBuilderProvider`s in the given parameters object which have not yet been registered. This method works like the method with the same name, but the map with providers is obtained from the passed in parameters object.
    Parameters:
      `params` - the parameters object from which to copy providers(must not be null)
    Returns:
      a reference to this object for method chaining
    Throws:
      `IllegalArgumentException` - if the source parameters object is null

  - ### getProviders

    public Map<String,ConfigurationBuilderProvider> getProviders()
    Gets an (unmodifiable) map with the currently registered `ConfigurationBuilderProvider` objects.
    Returns:
      the map with `ConfigurationBuilderProvider` objects (the keys are the tag names)

  - ### providerForTag

    public ConfigurationBuilderProvider providerForTag(String tagName)
    Returns the `ConfigurationBuilderProvider` which is registered for the specified tag name or null if there is no registration for this tag.
    Parameters:
      `tagName` - the tag name
    Returns:
      the provider registered for this tag or null

  - ### getBasePath

    public String getBasePath()
    Gets the base path for relative names of configuration sources. Result may be null if no base path has been set.
    Returns:
      the base path for resolving relative file names

  - ### setBasePath

    public CombinedBuilderParametersImpl setBasePath(String path)
    Sets the base path for this combined configuration builder. Normally it it not necessary to set the base path explicitly. Per default, relative file names of configuration sources are resolved based on the location of the definition file. If this is not desired or if the definition configuration is loaded by a different means, the base path for relative file names can be specified using this method.
    Specified by:
      `setBasePath` in interface `CombinedBuilderProperties<CombinedBuilderParametersImpl>`
    Parameters:
      `path` - the base path for resolving relative file names
    Returns:
      a reference to this object for method chaining

  - ### getDefinitionBuilderParameters

    public BuilderParameters getDefinitionBuilderParameters()
    Gets the parameters object for the definition configuration builder if present.
    Returns:
      the parameters object for the definition configuration builder or null

  - ### setDefinitionBuilderParameters

    public CombinedBuilderParametersImpl setDefinitionBuilderParameters(BuilderParameters params)
    Sets the parameters object for the definition configuration builder. This property is evaluated only if the definition configuration builder is not set explicitly (using the `setDefinitionBuilder(ConfigurationBuilder)` method). In this case, a builder for an XML configuration is created and configured with this parameters object.
    Specified by:
      `setDefinitionBuilderParameters` in interface `CombinedBuilderProperties<CombinedBuilderParametersImpl>`
    Parameters:
      `params` - the parameters object for the definition configuration builder
    Returns:
      a reference to this object for method chaining

  - ### getDefaultChildParameters

    public Collection<? extends BuilderParameters> getDefaultChildParameters()
    Gets a collection with default parameter objects for child configuration sources. This collection contains the same objects (in the same order) that were passed to `addChildParameters()`. The returned collection is a defensive copy; it can be modified, but this has no effect on the parameters stored in this object.
    Returns:
      a map with default parameters for child sources

  - ### getChildDefaultParametersManager

    public DefaultParametersManager getChildDefaultParametersManager()
    Gets the `DefaultParametersManager` object for initializing parameter objects for child configuration sources. This method never returns null. If no manager was set, a new instance is created right now.
    Returns:
      the `DefaultParametersManager` for child configuration sources

  - ### setChildDefaultParametersManager

    public CombinedBuilderParametersImpl setChildDefaultParametersManager(DefaultParametersManager manager)
    Sets a `DefaultParametersManager` object responsible for managing the default parameter handlers to be applied on child configuration sources. When creating builders for child configuration sources their parameters are initialized using this `DefaultParametersManager` instance. This way, meaningful defaults can be set. Note that calling this method overrides all `DefaultParametersHandler` objects previously set by one of the `registerChildDefaultsHandler()` methods! So either use this method if a pre-configured manager object is to be set or call the `registerChildDefaultHandler()` methods with the handlers to be registered (in the latter case, it is not necessary to set a `DefaultParametersManager` explicitly; a default one is created behind the scenes). This implementation stores the passed in manager object. An already existing manager object (either explicitly set or created on demand) is overridden. This also removes all default handlers registered before!
    Specified by:
      `setChildDefaultParametersManager` in interface `CombinedBuilderProperties<CombinedBuilderParametersImpl>`
    Parameters:
      `manager` - the `DefaultParametersManager`
    Returns:
      a reference to this object for method chaining

  - ### registerChildDefaultsHandler

    public <D> CombinedBuilderParametersImpl registerChildDefaultsHandler(Class<D> paramClass, DefaultParametersHandler<? super D> handler)
    Registers a `DefaultParametersHandler` for child configuration sources. With this method an arbitrary number of handler objects can be set. When creating builders for child configuration sources their parameters are initialized by invoking all matching `DefaultParametersHandler`s on them. So, basically the same mechanism is used for the initialization of parameters for child configuration sources as for normal parameter objects. This implementation registers the passed in handler at an internal `DefaultParametersManager` instance. If none was set, a new instance is created now.
    Specified by:
      `registerChildDefaultsHandler` in interface `CombinedBuilderProperties<CombinedBuilderParametersImpl>`
    Type Parameters:
      `D` - the type of the handler to be registered
    Parameters:
      `paramClass` - the parameter class supported by the handler
      `handler` - the `DefaultParametersHandler` to be registered
    Returns:
      a reference to this object for method chaining
    See Also:
      - `DefaultParametersManager.registerDefaultsHandler(Class, DefaultParametersHandler)`

  - ### registerChildDefaultsHandler

    public <D> CombinedBuilderParametersImpl registerChildDefaultsHandler(Class<D> paramClass, DefaultParametersHandler<? super D> handler, Class<?> startClass)
    Registers a `DefaultParametersHandler` for child configuration sources derived from the given start class. This method works like the overloaded variant, but limits the application of the defaults handler to specific child configuration sources. This implementation registers the passed in handler at an internal `DefaultParametersManager` instance. If none was set, a new instance is created now.
    Specified by:
      `registerChildDefaultsHandler` in interface `CombinedBuilderProperties<CombinedBuilderParametersImpl>`
    Type Parameters:
      `D` - the type of the handler to be registered
    Parameters:
      `paramClass` - the parameter class supported by the handler
      `handler` - the `DefaultParametersHandler` to be registered
      `startClass` - an optional start class in the hierarchy of parameter objects for which this handler should be applied
    Returns:
      a reference to this object for method chaining
    See Also:
      - `DefaultParametersManager.registerDefaultsHandler(Class, DefaultParametersHandler, Class)`

  - ### 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 (e.g. for lookup objects) are stored as defensive copies, so the original data cannot be modified. This implementation returns a map which contains this object itself under a specific key. The static `fromParameters()` method can be used to extract an instance from a parameters map.
    Specified by:
      `getParameters` in interface `BuilderParameters`
    Overrides:
      `getParameters` in class `BasicBuilderParameters`
    Returns:
      a map with builder parameters

  - ### clone

    public CombinedBuilderParametersImpl 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. This implementation also clones the parameters object for the definition builder if possible.
    Overrides:
      `clone` in class `BasicBuilderParameters`
    Returns:
      a clone of this object