org.apache.tamaya.builder

## Class ConfigurationBuilder

- java.lang.Object
- - org.apache.tamaya.builder.ConfigurationBuilder

-     public class ConfigurationBuilder
      extends Object

  Builder class used for building a configuration manually without relying only on the Service Provider Interface API.

  Features of the builder

  1. Adding of property converters manually
  2. Adding of property sources directly
  3. Adding of property sources via URL
  4. Adding of property source providers directly
  5. Enabling and disabling of via SPI mechanism provided resources as converters, property sources, etc.

  Example

       ConfigurationBuilder builder = new ConfigurationBuilder();
       builder.disableProvidedPropertySources()           // Do not load provided property
              .disableProvidedPropertySourceProviders()   // sources and providers automatically
              .addPropertySource("file:/etc/conf.properties"); // Load properties from conf.properties

       Configuration config = builder.build();

  Support for configuration formats

  The configuration builder allows you to put property resources via a URL, as shown in the code example above, without implementing a `PropertySource` or providing an instance of a `PropertySource`. If a property resource in a specific format can be added to configuration builder or not depends on the available implementations of `ConfigurationFormat` in the classpath. Which formats are available can be checked via `ConfigurationFormats.getFormats()`.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ConfigurationBuilder()` Creates a new builder instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `<T> ConfigurationBuilder` | `addPropertyConverter(Class<T> type, PropertyConverter<T> converter)` Adds a property converter for the a given type to the configuration to be build.
    `<T> ConfigurationBuilder` | `addPropertyConverter(TypeLiteral<T> type, PropertyConverter<T> propertyConverter)`
    `ConfigurationBuilder` | `addPropertyFilters(PropertyFilter... filters)` Adds one or more property filter instances to the configuration to be build.
    `ConfigurationBuilder` | `addPropertySource(URL url)` Adds one resources with properties in an arbitrary format to the configuration to be build.
    `ConfigurationBuilder` | `addPropertySourceProviders(PropertySourceProvider... providers)` Adds one or more property source provider instances to the configuration to be build.
    `ConfigurationBuilder` | `addPropertySources(Collection<URL> urls)` Adds one or more resources with properties in an arbitrary format to the configuration to be build.
    `ConfigurationBuilder` | `addPropertySources(PropertySource... sources)` Adds one or more property source instances to the configuration to be build.
    `ConfigurationBuilder` | `addPropertySources(String... urls)` Adds one or more resources with properties in an arbitrary format to the configuration to be build.
    `ConfigurationBuilder` | `addPropertySources(URL... urls)` Adds one or more resources with properties in an arbitrary format to the configuration to be build.
    `Configuration` | `build()` Builds a new configuration based on the configuration of this builder instance.
    `ConfigurationBuilder` | `disableProvidedPropertyConverters()` Disables the automatic loading of all `PropertyConverter` service providers.
    `ConfigurationBuilder` | `disableProvidedPropertyFilters()` Disables the automatic loading of all `PropertyFilter` service providers.
    `ConfigurationBuilder` | `disableProvidedPropertySourceProviders()` Disables the automatic loading of `property source providers` provided via the SPI API.
    `ConfigurationBuilder` | `disableProvidedPropertySources()` Disables the automatic loading of all `PropertySource` service providers.
    `ConfigurationBuilder` | `enabledProvidedPropertyFilters()` Enables the automatic loading of all `PropertyFilter` service providers.
    `ConfigurationBuilder` | `enableProvidedPropertyConverters()` Enables the loading of all `PropertyConverter` service providers.
    `ConfigurationBuilder` | `enableProvidedPropertySourceProviders()` Enables the automatic loading of `property source providers` provided via the SPI API.
    `ConfigurationBuilder` | `enableProvidedPropertySources()` Enables the automatic loading of all `PropertySource` service providers.
    `protected ConfigurationData` | `getConfigurationDataFromURL(URL url)`
    `boolean` | `isPropertyConverterLoadingEnabled()` Checks if the automatic loading of all `PropertyConverter` service providers is enabled or disabled.
    `boolean` | `isPropertyFilterLoadingEnabled()` Checks if the automatic loading of all `PropertyFilter` service providers is enabled or disabled.
    `boolean` | `isPropertySourceProvidersLoadingEnabled()` Checks if the automatic loading of `PropertySourceProviders` is enabled or disabled.
    `boolean` | `isPropertySourcesLoadingEnabled()` Checks if the automatic loading of all `PropertySource` service providers is enabled or disabled.
    `ConfigurationBuilder` | `setPropertyValueCombinationPolicy(PropertyValueCombinationPolicy propertyValueCombinationPolicy)`

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

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

- - ### Constructor Detail

    - #### ConfigurationBuilder

          public ConfigurationBuilder()

      Creates a new builder instance.

  - ### Method Detail

    - #### addPropertySource

          public ConfigurationBuilder addPropertySource(URL url)

      Adds one resources with properties in an arbitrary format to the configuration to be build.

      If a specific format is supported depends on the available `ConfigurationFormat` implementations.

           URL resource = new URL("file:/etc/service/config.json");

           builder.addPropertySources(resource);

      Parameters:
        `url` - resource with properties for the the configuration to be build.
      Returns:
        the builder instance currently used
      See Also:
        `ConfigurationFormat`, `ConfigurationFormats.getFormats()`

    - #### getConfigurationDataFromURL

          protected ConfigurationData getConfigurationDataFromURL(URL url)
                                                           throws IOException

      Throws:
        `IOException`

    - #### addPropertySources

          public ConfigurationBuilder addPropertySources(URL... urls)

      Adds one or more resources with properties in an arbitrary format to the configuration to be build.

      If a specific format is supported depends on the available `ConfigurationFormat` implementations.

           URL first = new URL("file:/etc/service/config.json");
           URL second = new URL("file:/etc/defaults/values.properties");

           builder.addPropertySources(first, second);

      Parameters:
        `urls` - list of resources with properties for the configuration to be build.
      Returns:
        the builder instance currently used
      See Also:
        `ConfigurationFormat`, `ConfigurationFormats.getFormats()`

    - #### addPropertySources

          public ConfigurationBuilder addPropertySources(Collection<URL> urls)

      Adds one or more resources with properties in an arbitrary format to the configuration to be build.

      If a specific format is supported depends on the available `ConfigurationFormat` implementations.

           URL first = new URL("file:/etc/service/config.json");
           URL second = new URL("file:/etc/defaults/values.properties");

           builder.addPropertySources(first, second);

      Parameters:
        `urls` - list of resources with properties for the configuration to be build.
      Returns:
        the builder instance currently used
      See Also:
        `ConfigurationFormat`, `ConfigurationFormats.getFormats()`

    - #### addPropertySources

          public ConfigurationBuilder addPropertySources(String... urls)

      Adds one or more resources with properties in an arbitrary format to the configuration to be build.

      If a specific format is supported depends on the available `ConfigurationFormat` implementations.

           builder.addPropertySources("file:/etc/service/config.json",
                                      "file:/etc/defaults/values.properties");

      Parameters:
        `urls` - list of resources with properties for the configuration to be build.
      Returns:
        the builder instance currently used
      See Also:
        `ConfigurationFormat`, `ConfigurationFormats.getFormats()`

    - #### addPropertySources

          public ConfigurationBuilder addPropertySources(PropertySource... sources)

      Adds one or more property source instances to the configuration to be build.

           PropertySource first = new CustomPropertySource();
           PropertySource second = new YetAnotherPropertySource();

           builder.addPropertySources(first, second);

      Parameters:
        `sources` - list of property source instances with properties for the configuration to be build.
      Returns:
        the builder instance currently used
      See Also:
        `PropertySource`

    - #### addPropertySourceProviders

          public ConfigurationBuilder addPropertySourceProviders(PropertySourceProvider... providers)

      Adds one or more property source provider instances to the configuration to be build.

           PropertySourceProvider jc = new JavaConfigurationProvider();

           builder.addPropertySources(jc);

      Parameters:
        `providers` - list of property source provider instances each providing a set of property source instances for the configuration to be build.
      Returns:
        the builder instance currently used
      See Also:
        `PropertySourceProvider`

    - #### addPropertyFilters

          public ConfigurationBuilder addPropertyFilters(PropertyFilter... filters)

      Adds one or more property filter instances to the configuration to be build.

           PropertyFilter quoteReplacingFilter = new QuoteFilter();
           PropertyFilter commaRemovingFilter = new CommaFilter();

           builder.addPropertyFilters(commaRemovingFilter, quoteReplacingFilter);

      Parameters:
        `filters` - list of property filter instances which should be applied to the properties of the configuration to be build.
      Returns:
        the builder instance currently used
      See Also:
        `PropertyFilter`, `disableProvidedPropertyFilters()`, `enabledProvidedPropertyFilters()`

    - #### setPropertyValueCombinationPolicy

          public ConfigurationBuilder setPropertyValueCombinationPolicy(PropertyValueCombinationPolicy propertyValueCombinationPolicy)

      Returns:
        the builder instance currently used

    - #### addPropertyConverter

          public <T> ConfigurationBuilder addPropertyConverter(Class<T> type,
                                                               PropertyConverter<T> converter)

      Adds a property converter for the a given type to the configuration to be build.

           PropertyConverter<MyType> converter = value -> new MyType(value, 42);

           builder.addPropertyConverter(MyType.class, converter

      Parameters:
        `type` - the required target type the converter should be applied to
        `converter` - the converter to be used to convert the string property to the given target type.
      Returns:
        the builder instance currently used
      See Also:
        `PropertyConverter`, `enableProvidedPropertyConverters()`, `disableProvidedPropertyConverters()`

    - #### addPropertyConverter

          public <T> ConfigurationBuilder addPropertyConverter(TypeLiteral<T> type,
                                                               PropertyConverter<T> propertyConverter)

      Returns:
        the builder instance currently used

    - #### isPropertyConverterLoadingEnabled

          public boolean isPropertyConverterLoadingEnabled()

      Checks if the automatic loading of all `PropertyConverter` service providers is enabled or disabled.
      Returns:
        `true` if the automatic loading is enabled, otherwise `false`.
      See Also:
        `enableProvidedPropertyConverters()`, `disableProvidedPropertyConverters()`, `addPropertyConverter(Class, org.apache.tamaya.spi.PropertyConverter)`, `addPropertyConverter(org.apache.tamaya.TypeLiteral, org.apache.tamaya.spi.PropertyConverter)`

    - #### enableProvidedPropertyConverters

          public ConfigurationBuilder enableProvidedPropertyConverters()

      Enables the loading of all `PropertyConverter` service providers.
      Returns:
        the builder instance currently used
      See Also:
        `PropertyConverter`, `disableProvidedPropertyConverters()`, `enableProvidedPropertyConverters()`

    - #### disableProvidedPropertyConverters

          public ConfigurationBuilder disableProvidedPropertyConverters()

      Disables the automatic loading of all `PropertyConverter` service providers.
      Returns:
        the builder instance currently used
      See Also:
        `PropertyConverter`, `enableProvidedPropertyConverters()`, `addPropertyConverter(Class, org.apache.tamaya.spi.PropertyConverter)`

    - #### enableProvidedPropertySources

          public ConfigurationBuilder enableProvidedPropertySources()

      Enables the automatic loading of all `PropertySource` service providers.
      Returns:
        the builder instance currently used
      See Also:
        `PropertySource`, `disableProvidedPropertySources()`

    - #### isPropertySourcesLoadingEnabled

          public boolean isPropertySourcesLoadingEnabled()

      Checks if the automatic loading of all `PropertySource` service providers is enabled or disabled.
      Returns:
        `true` if the automatic loading is enabled, otherwise `false`.

    - #### isPropertyFilterLoadingEnabled

          public boolean isPropertyFilterLoadingEnabled()

      Checks if the automatic loading of all `PropertyFilter` service providers is enabled or disabled.
      Returns:
        `true` if the automatic loading is enabled, otherwise `false`.

    - #### enabledProvidedPropertyFilters

          public ConfigurationBuilder enabledProvidedPropertyFilters()

      Enables the automatic loading of all `PropertyFilter` service providers.
      Returns:
        the builder instance currently used
      See Also:
        `PropertyFilter`, `disableProvidedPropertyFilters()`, `addPropertyFilters(org.apache.tamaya.spi.PropertyFilter...)`

    - #### disableProvidedPropertyFilters

          public ConfigurationBuilder disableProvidedPropertyFilters()

      Disables the automatic loading of all `PropertyFilter` service providers.
      Returns:
        the builder instance currently used
      See Also:
        `PropertyFilter`, `enabledProvidedPropertyFilters()`, `addPropertyFilters(org.apache.tamaya.spi.PropertyFilter...)`

    - #### disableProvidedPropertySources

          public ConfigurationBuilder disableProvidedPropertySources()

      Disables the automatic loading of all `PropertySource` service providers.
      Returns:
        the builder instance currently used
      See Also:
        `PropertySource`, `enableProvidedPropertySources()`

    - #### enableProvidedPropertySourceProviders

          public ConfigurationBuilder enableProvidedPropertySourceProviders()

      Enables the automatic loading of `property source providers` provided via the SPI API.
      Returns:
        the builder instance currently used
      See Also:
        `PropertySourceProvider`,

    - #### disableProvidedPropertySourceProviders

          public ConfigurationBuilder disableProvidedPropertySourceProviders()

      Disables the automatic loading of `property source providers` provided via the SPI API.
      Returns:
        the builder instance currently used

    - #### isPropertySourceProvidersLoadingEnabled

          public boolean isPropertySourceProvidersLoadingEnabled()

      Checks if the automatic loading of `PropertySourceProviders` is enabled or disabled.
      Returns:
        `true` if the automatic loading is enabled, otherwise `false`.

    - #### build

          public Configuration build()

      Builds a new configuration based on the configuration of this builder instance.
      Returns:
        a new `configuration instance`, never `null`.

Copyright © 2015 Apache Software Foundation. All rights reserved.