CombinedBuilderProperties (Apache Commons Configuration 2.15.1 API)
Description: declaration: package: org.apache.commons.configuration2.builder.combined, interface: CombinedBuilderProperties

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

# Interface CombinedBuilderProperties<T>

Type Parameters:
  `T` - the return type of all methods for allowing method chaining

All Known Subinterfaces:
  `CombinedBuilderParameters`

All Known Implementing Classes:
  `CombinedBuilderParametersImpl`

public interface CombinedBuilderProperties<T>

Definition of a properties interface for the parameters of a combined configuration builder.

This interface defines a number of properties for adapting the construction of a combined configuration based on a definition configuration. Properties can be set in a fluent style.

Important note: This interface is not intended to be implemented by client code! It defines a set of available properties and may be extended even in minor releases.

Since:
  2.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<D> T`
  `registerChildDefaultsHandler(Class<D> paramClass, DefaultParametersHandler<? super D> handler)`
  Registers a `DefaultParametersHandler` for child configuration sources.
  `<D> T`
  `registerChildDefaultsHandler(Class<D> paramClass, DefaultParametersHandler<? super D> handler, Class<?> startClass)`
  Registers a `DefaultParametersHandler` for child configuration sources derived from the given start class.
  `T`
  `registerProvider(String tagName, ConfigurationBuilderProvider provider)`
  Registers the given `ConfigurationBuilderProvider` for the specified tag name.
  `T`
  `setBasePath(String path)`
  Sets the base path for this combined configuration builder.
  `T`
  `setChildDefaultParametersManager(DefaultParametersManager manager)`
  Sets a `DefaultParametersManager` object responsible for managing the default parameter handlers to be applied on child configuration sources.
  `T`
  `setDefinitionBuilder(ConfigurationBuilder<? extends HierarchicalConfiguration<?>> builder)`
  Sets the `ConfigurationBuilder` for the definition configuration.
  `T`
  `setDefinitionBuilderParameters(BuilderParameters params)`
  Sets the parameters object for the definition configuration builder.
  `T`
  `setInheritSettings(boolean f)`
  Sets a flag whether the child configurations created by a `CombinedConfigurationBuilder` should inherit the settings defined for the builder.

- ## Method Details

  - ### registerChildDefaultsHandler

    <D> T 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.
    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

    <D> T 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.
    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)`

  - ### registerProvider

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

  - ### setBasePath

    T 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.
    Parameters:
      `path` - the base path for resolving relative file names
    Returns:
      a reference to this object for method chaining

  - ### setChildDefaultParametersManager

    T 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).
    Parameters:
      `manager` - the `DefaultParametersManager`
    Returns:
      a reference to this object for method chaining

  - ### setDefinitionBuilder

    T 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.
    Parameters:
      `builder` - the definition `ConfigurationBuilder`
    Returns:
      a reference to this object for method chaining

  - ### setDefinitionBuilderParameters

    T 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.
    Parameters:
      `params` - the parameters object for the definition configuration builder
    Returns:
      a reference to this object for method chaining

  - ### setInheritSettings

    T setInheritSettings(boolean f)
    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.
    Parameters:
      `f` - the flag whether settings should be inherited by child configurations
    Returns:
      a reference to this object for method chaining