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

## Class BaseConfigurationBuilderProvider

- java.lang.Object
- - org.apache.commons.configuration2.builder.combined.BaseConfigurationBuilderProvider

- All Implemented Interfaces:
    `ConfigurationBuilderProvider`
  Direct Known Subclasses:
    `CombinedConfigurationBuilderProvider`, `FileExtensionConfigurationBuilderProvider`, `MultiFileConfigurationBuilderProvider`

      public class BaseConfigurationBuilderProvider
      extends Object
      implements ConfigurationBuilderProvider

  A fully-functional, reflection-based implementation of the `ConfigurationBuilderProvider` interface which can deal with the default tags defining configuration sources.

  An instance of this class is initialized with the names of the `ConfigurationBuilder` class used by this provider and the concrete `Configuration` class. The `ConfigurationBuilder` class must be derived from `BasicConfigurationBuilder`. When asked for the builder object, an instance of the builder class is created and initialized from the bean declaration associated with the current configuration source.

  `ConfigurationBuilder` objects are configured using parameter objects. When declaring configuration sources in XML it should not be necessary to define the single parameter objects. Rather, simple and complex properties are set in the typical way of a bean declaration (i.e. as attributes of the current XML element or as child elements). This class creates all supported parameter objects (whose names also must be provided at construction time) and takes care that their properties are initialized according to the current bean declaration.

  The use of reflection to create builder instances allows a generic implementation supporting many concrete builder classes. Another reason for this approach is that builder classes are only loaded if actually needed. Some specialized `Configuration` implementations require specific external dependencies which should not be mandatory for the use of `CombinedConfigurationBuilder`. Because such classes are lazily loaded, an application only has to include the dependencies it actually uses.

  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `BaseConfigurationBuilderProvider​(String bldrCls, String reloadBldrCls, String configCls, Collection<String> paramCls)` | Creates a new instance of `BaseConfigurationBuilderProvider` and initializes all its properties.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `configureBuilder​(BasicConfigurationBuilder<? extends Configuration> builder, ConfigurationDeclaration decl, Collection<BuilderParameters> params)` | Configures a newly created builder instance with its initialization parameters.
    `protected BasicConfigurationBuilder<? extends Configuration>` | `createBuilder​(ConfigurationDeclaration decl, Collection<BuilderParameters> params)` | Creates a new, uninitialized instance of the builder class managed by this provider.
    `protected Collection<BuilderParameters>` | `createParameterObjects()` | Creates a collection of parameter objects to be used for configuring the builder.
    `protected String` | `determineBuilderClass​(ConfigurationDeclaration decl)` | Determines the name of the class to be used for a new builder instance.
    `protected String` | `determineConfigurationClass​(ConfigurationDeclaration decl, Collection<BuilderParameters> params)` | Determines the name of the configuration class produced by the builder.
    `String` | `getBuilderClass()` | Gets the name of the class of the builder created by this provider.
    `ConfigurationBuilder<? extends Configuration>` | `getConfigurationBuilder​(ConfigurationDeclaration decl)` | Gets the builder for the configuration source managed by this provider.
    `String` | `getConfigurationClass()` | Gets the name of the configuration class created by the builder produced by this provider.
    `Collection<String>` | `getParameterClasses()` | Gets an unmodifiable collection with the names of parameter classes supported by this provider.
    `String` | `getReloadingBuilderClass()` | Gets the name of the class of the builder created by this provider if the reload flag is set.
    `protected void` | `inheritParentBuilderProperties​(ConfigurationDeclaration decl, Collection<BuilderParameters> params)` | Passes all parameter objects to the parent `CombinedConfigurationBuilder` so that properties already defined for the parent builder can be added.
    `protected void` | `initializeParameterObjects​(ConfigurationDeclaration decl, Collection<BuilderParameters> params)` | Initializes the parameter objects with data stored in the current bean declaration.
    `protected boolean` | `isAllowFailOnInit​(ConfigurationDeclaration decl)` | Determines the allowFailOnInit flag for the newly created builder based on the given `ConfigurationDeclaration`.

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

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

- - ### Constructor Detail

    - #### BaseConfigurationBuilderProvider

          public BaseConfigurationBuilderProvider​(String bldrCls,
                                                  String reloadBldrCls,
                                                  String configCls,
                                                  Collection<String> paramCls)

      Creates a new instance of `BaseConfigurationBuilderProvider` and initializes all its properties.
      Parameters:
        `bldrCls` - the name of the builder class (must not be null)
        `reloadBldrCls` - the name of a builder class to be used if reloading support is required (null if reloading is not supported)
        `configCls` - the name of the configuration class (must not be null)
        `paramCls` - a collection with the names of parameters classes
      Throws:
        `IllegalArgumentException` - if a required parameter is missing

  - ### Method Detail

    - #### getBuilderClass

          public String getBuilderClass()

      Gets the name of the class of the builder created by this provider.
      Returns:
        the builder class

    - #### getReloadingBuilderClass

          public String getReloadingBuilderClass()

      Gets the name of the class of the builder created by this provider if the reload flag is set. If this method returns null, reloading builders are not supported by this provider.
      Returns:
        the reloading builder class

    - #### getConfigurationClass

          public String getConfigurationClass()

      Gets the name of the configuration class created by the builder produced by this provider.
      Returns:
        the configuration class

    - #### getParameterClasses

          public Collection<String> getParameterClasses()

      Gets an unmodifiable collection with the names of parameter classes supported by this provider.
      Returns:
        the parameter classes

    - #### getConfigurationBuilder

          public ConfigurationBuilder<? extends Configuration> getConfigurationBuilder​(ConfigurationDeclaration decl)
                                                                                throws ConfigurationException

      Gets the builder for the configuration source managed by this provider. This method is called during processing of the combined configuration definition file. This implementation delegates to some protected methods to create a new builder instance using reflection and to configure it with parameter values defined by the passed in `BeanDeclaration`.
      Specified by:
        `getConfigurationBuilder` in interface `ConfigurationBuilderProvider`
      Parameters:
        `decl` - the bean declaration with initialization parameters for the configuration builder
      Returns:
        the `ConfigurationBuilder` object created by this provider
      Throws:
        `ConfigurationException` - if an error occurs

    - #### isAllowFailOnInit

          protected boolean isAllowFailOnInit​(ConfigurationDeclaration decl)

      Determines the allowFailOnInit flag for the newly created builder based on the given `ConfigurationDeclaration`. Some combinations of flags in the declaration say that a configuration source is optional, but an empty instance should be created if its creation fail.
      Parameters:
        `decl` - the current `ConfigurationDeclaration`
      Returns:
        the value of the allowFailOnInit flag

    - #### createParameterObjects

          protected Collection<BuilderParameters> createParameterObjects()
                                                                  throws Exception

      Creates a collection of parameter objects to be used for configuring the builder. This method creates instances of the parameter classes passed to the constructor.
      Returns:
        a collection with parameter objects for the builder
      Throws:
        `Exception` - if an error occurs while creating parameter objects via reflection

    - #### initializeParameterObjects

          protected void initializeParameterObjects​(ConfigurationDeclaration decl,
                                                    Collection<BuilderParameters> params)
                                             throws Exception

      Initializes the parameter objects with data stored in the current bean declaration. This method is called before the newly created builder instance is configured with the parameter objects. It maps attributes of the bean declaration to properties of parameter objects. In addition, it invokes the parent `CombinedConfigurationBuilder` so that the parameters object can inherit properties already defined for this builder.
      Parameters:
        `decl` - the current `ConfigurationDeclaration`
        `params` - the collection with (uninitialized) parameter objects
      Throws:
        `Exception` - if an error occurs

    - #### inheritParentBuilderProperties

          protected void inheritParentBuilderProperties​(ConfigurationDeclaration decl,
                                                        Collection<BuilderParameters> params)

      Passes all parameter objects to the parent `CombinedConfigurationBuilder` so that properties already defined for the parent builder can be added. This method is called before the parameter objects are initialized from the definition configuration. This way properties from the parent builder are inherited, but can be overridden for child configurations.
      Parameters:
        `decl` - the current `ConfigurationDeclaration`
        `params` - the collection with (uninitialized) parameter objects

    - #### createBuilder

          protected BasicConfigurationBuilder<? extends Configuration> createBuilder​(ConfigurationDeclaration decl,
                                                                                     Collection<BuilderParameters> params)
                                                                              throws Exception

      Creates a new, uninitialized instance of the builder class managed by this provider. This implementation determines the builder class to be used by delegating to `determineBuilderClass()`. It then calls the constructor expecting the configuration class, the map with properties, and theallowFailOnInit flag.
      Parameters:
        `decl` - the current `ConfigurationDeclaration`
        `params` - initialization parameters for the new builder object
      Returns:
        the newly created builder instance
      Throws:
        `Exception` - if an error occurs

    - #### configureBuilder

          protected void configureBuilder​(BasicConfigurationBuilder<? extends Configuration> builder,
                                          ConfigurationDeclaration decl,
                                          Collection<BuilderParameters> params)
                                   throws Exception

      Configures a newly created builder instance with its initialization parameters. This method is called after a new instance was created using reflection. This implementation passes the parameter objects to the builder's `configure()` method.
      Parameters:
        `builder` - the builder to be initialized
        `decl` - the current `ConfigurationDeclaration`
        `params` - the collection with initialization parameter objects
      Throws:
        `Exception` - if an error occurs

    - #### determineBuilderClass

          protected String determineBuilderClass​(ConfigurationDeclaration decl)
                                          throws ConfigurationException

      Determines the name of the class to be used for a new builder instance. This implementation selects between the normal and the reloading builder class, based on the passed in `ConfigurationDeclaration`. If a reloading builder is desired, but this provider has no reloading support, an exception is thrown.
      Parameters:
        `decl` - the current `ConfigurationDeclaration`
      Returns:
        the name of the builder class
      Throws:
        `ConfigurationException` - if the builder class cannot be determined

    - #### determineConfigurationClass

          protected String determineConfigurationClass​(ConfigurationDeclaration decl,
                                                       Collection<BuilderParameters> params)
                                                throws ConfigurationException

      Determines the name of the configuration class produced by the builder. This method is called when obtaining the arguments for invoking the constructor of the builder class. This implementation just returns the pre-configured configuration class name. Derived classes may determine this class name dynamically based on the passed in parameters.
      Parameters:
        `decl` - the current `ConfigurationDeclaration`
        `params` - the collection with parameter objects
      Returns:
        the name of the builder's result configuration class
      Throws:
        `ConfigurationException` - if an error occurs