org.apache.commons.configuration2.builder.fluent

## Class Configurations

- java.lang.Object
- - org.apache.commons.configuration2.builder.fluent.Configurations

-     public class Configurations
      extends Object

  A convenience class which simplifies the creation of standard configurations and their builders.

  Complex initializations of configuration builders can be done in a pretty straight-forward way by making use of the provided fluent API. However, if only default settings are used (and maybe a configuration file to be loaded has to be specified), this approach tends to become a bit verbose. This class was introduced to simplify the creation of configuration objects in such cases. It offers a bunch of methods which allow the creation of some standard configuration classes with default settings passing in only a minimum required parameters.

  An an example consider the creation of a `PropertiesConfiguration` object from a file. Using a builder, code like the following one would have to be written:

       Parameters params = new Parameters();
       FileBasedConfigurationBuilder<PropertiesConfiguration> builder =
         new FileBasedConfigurationBuilder<PropertiesConfiguration>(PropertiesConfiguration.class)
           .configure(params.fileBased().setFile(new File("config.properties")));
       PropertiesConfiguration config = builder.getConfiguration();

  With a convenience method of `Configurations` the same can be achieved with the following:

       Configurations configurations = new Configurations();
       PropertiesConfiguration config = configurations.properties(new File("config.properties"));

  There are similar methods for constructing builder objects from which configurations can then be obtained.

  This class is thread-safe. A single instance can be created by an application and used in a central way to create configuration objects. When an instance is created a `Parameters` instance can be passed in. Otherwise, a default instance is created. In any case, the `Parameters` instance associated with a `Configurations` object can be used to define default settings for the configurations to be created.

  Since:
    2.0
  See Also:
    `DefaultParametersManager`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Configurations()` Creates a new `Configurations` instance with default settings.
    `Configurations(Parameters params)` Creates a new instance of `Configurations` and initializes it with the specified `Parameters` object.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `CombinedConfiguration` | `combined(File file)` Creates a `CombinedConfiguration` instance from the content of the given file.
    `CombinedConfiguration` | `combined(String path)` Creates a `CombinedConfiguration` instance from the content of the file identified by the given path.
    `CombinedConfiguration` | `combined(URL url)` Creates a `CombinedConfiguration` instance from the content of the given URL.
    `CombinedConfigurationBuilder` | `combinedBuilder(File file)` Creates a builder for a `CombinedConfiguration` and initializes it with the given file to be loaded.
    `CombinedConfigurationBuilder` | `combinedBuilder(String path)` Creates a builder for a `CombinedConfiguration` and initializes it with the given path to the file to be loaded.
    `CombinedConfigurationBuilder` | `combinedBuilder(URL url)` Creates a builder for a `CombinedConfiguration` and initializes it with the given URL to be loaded.
    `<T extends FileBasedConfiguration> T` | `fileBased(Class<T> configClass, File file)` Creates an instance of the specified file-based configuration class from the content of the given file.
    `<T extends FileBasedConfiguration> T` | `fileBased(Class<T> configClass, String path)` Creates an instance of the specified file-based configuration class from the content of the file identified by the given path.
    `<T extends FileBasedConfiguration> T` | `fileBased(Class<T> configClass, URL url)` Creates an instance of the specified file-based configuration class from the content of the given URL.
    `<T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T>` | `fileBasedBuilder(Class<T> configClass, File file)` Creates a `FileBasedConfigurationBuilder` for the specified configuration class and initializes it with the file to be loaded.
    `<T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T>` | `fileBasedBuilder(Class<T> configClass, String path)` Creates a `FileBasedConfigurationBuilder` for the specified configuration class and initializes it with the path to the file to be loaded.
    `<T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T>` | `fileBasedBuilder(Class<T> configClass, URL url)` Creates a `FileBasedConfigurationBuilder` for the specified configuration class and initializes it with the URL to the file to be loaded.
    `Parameters` | `getParameters()` Returns the `Parameters` instance associated with this object.
    `INIConfiguration` | `ini(File file)` Creates a `INIConfiguration` instance from the content of the given file.
    `INIConfiguration` | `ini(String path)` Creates a `INIConfiguration` instance from the content of the file identified by the given path.
    `INIConfiguration` | `ini(URL url)` Creates a `INIConfiguration` instance from the content of the given URL.
    `FileBasedConfigurationBuilder<INIConfiguration>` | `iniBuilder(File file)` Creates a builder for a `INIConfiguration` and initializes it with the given file to be loaded.
    `FileBasedConfigurationBuilder<INIConfiguration>` | `iniBuilder(String path)` Creates a builder for a `INIConfiguration` and initializes it with the file file identified by the given path.
    `FileBasedConfigurationBuilder<INIConfiguration>` | `iniBuilder(URL url)` Creates a builder for a `INIConfiguration` and initializes it with the given URL to be loaded.
    `PropertiesConfiguration` | `properties(File file)` Creates a `PropertiesConfiguration` instance from the content of the given file.
    `PropertiesConfiguration` | `properties(String path)` Creates a `PropertiesConfiguration` instance from the content of the file identified by the given path.
    `PropertiesConfiguration` | `properties(URL url)` Creates a `PropertiesConfiguration` instance from the content of the given URL.
    `FileBasedConfigurationBuilder<PropertiesConfiguration>` | `propertiesBuilder()` Creates a builder for a `PropertiesConfiguration`.
    `FileBasedConfigurationBuilder<PropertiesConfiguration>` | `propertiesBuilder(File file)` Creates a builder for a `PropertiesConfiguration` and initializes it with the given file to be loaded.
    `FileBasedConfigurationBuilder<PropertiesConfiguration>` | `propertiesBuilder(PropertiesBuilderParameters parameters)` Creates a builder for a `PropertiesConfiguration` and initializes it with the given parameters to be loaded.
    `FileBasedConfigurationBuilder<PropertiesConfiguration>` | `propertiesBuilder(String path)` Creates a builder for a `PropertiesConfiguration` and initializes it with the given path to the file to be loaded.
    `FileBasedConfigurationBuilder<PropertiesConfiguration>` | `propertiesBuilder(URL url)` Creates a builder for a `PropertiesConfiguration` and initializes it with the given URL to be loaded.
    `XMLConfiguration` | `xml(File file)` Creates a `XMLConfiguration` instance from the content of the given file.
    `XMLConfiguration` | `xml(String path)` Creates a `XMLConfiguration` instance from the content of the file identified by the given path.
    `XMLConfiguration` | `xml(URL url)` Creates a `XMLConfiguration` instance from the content of the given URL.
    `FileBasedConfigurationBuilder<XMLConfiguration>` | `xmlBuilder(File file)` Creates a builder for a `XMLConfiguration` and initializes it with the given file to be loaded.
    `FileBasedConfigurationBuilder<XMLConfiguration>` | `xmlBuilder(String path)` Creates a builder for a `XMLConfiguration` and initializes it with the given path to the file to be loaded.
    `FileBasedConfigurationBuilder<XMLConfiguration>` | `xmlBuilder(URL url)` Creates a builder for a `XMLConfiguration` and initializes it with the given URL to be loaded.

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

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

- - ### Constructor Detail

    - #### Configurations

          public Configurations()

      Creates a new `Configurations` instance with default settings.

    - #### Configurations

          public Configurations(Parameters params)

      Creates a new instance of `Configurations` and initializes it with the specified `Parameters` object.
      Parameters:
        `params` - the `Parameters` (may be null, then a default instance is created)

  - ### Method Detail

    - #### getParameters

          public Parameters getParameters()

      Returns the `Parameters` instance associated with this object.
      Returns:
        the associated `Parameters` object

    - #### fileBasedBuilder

          public <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> fileBasedBuilder(Class<T> configClass,
                                                                                                      File file)

      Creates a `FileBasedConfigurationBuilder` for the specified configuration class and initializes it with the file to be loaded.
      Type Parameters:
        `T` - the type of the configuration to be constructed
      Parameters:
        `configClass` - the configuration class
        `file` - the file to be loaded
      Returns:
        the new `FileBasedConfigurationBuilder`

    - #### fileBasedBuilder

          public <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> fileBasedBuilder(Class<T> configClass,
                                                                                                      URL url)

      Creates a `FileBasedConfigurationBuilder` for the specified configuration class and initializes it with the URL to the file to be loaded.
      Type Parameters:
        `T` - the type of the configuration to be constructed
      Parameters:
        `configClass` - the configuration class
        `url` - the URL to be loaded
      Returns:
        the new `FileBasedConfigurationBuilder`

    - #### fileBasedBuilder

          public <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> fileBasedBuilder(Class<T> configClass,
                                                                                                      String path)

      Creates a `FileBasedConfigurationBuilder` for the specified configuration class and initializes it with the path to the file to be loaded.
      Type Parameters:
        `T` - the type of the configuration to be constructed
      Parameters:
        `configClass` - the configuration class
        `path` - the path to the file to be loaded
      Returns:
        the new `FileBasedConfigurationBuilder`

    - #### fileBased

          public <T extends FileBasedConfiguration> T fileBased(Class<T> configClass,
                                                                File file)
                                                         throws ConfigurationException

      Creates an instance of the specified file-based configuration class from the content of the given file. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Type Parameters:
        `T` - the type of the configuration to be constructed
      Parameters:
        `configClass` - the configuration class
        `file` - the file to be loaded
      Returns:
        a `FileBasedConfiguration` object initialized from this file
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### fileBased

          public <T extends FileBasedConfiguration> T fileBased(Class<T> configClass,
                                                                URL url)
                                                         throws ConfigurationException

      Creates an instance of the specified file-based configuration class from the content of the given URL. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Type Parameters:
        `T` - the type of the configuration to be constructed
      Parameters:
        `configClass` - the configuration class
        `url` - the URL to be loaded
      Returns:
        a `FileBasedConfiguration` object initialized from this file
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### fileBased

          public <T extends FileBasedConfiguration> T fileBased(Class<T> configClass,
                                                                String path)
                                                         throws ConfigurationException

      Creates an instance of the specified file-based configuration class from the content of the file identified by the given path. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Type Parameters:
        `T` - the type of the configuration to be constructed
      Parameters:
        `configClass` - the configuration class
        `path` - the path to the file to be loaded
      Returns:
        a `FileBasedConfiguration` object initialized from this file
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### propertiesBuilder

          public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder()

      Creates a builder for a `PropertiesConfiguration`.
      Returns:
        the newly created `FileBasedConfigurationBuilder`
      Since:
        2.6

    - #### propertiesBuilder

          public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(File file)

      Creates a builder for a `PropertiesConfiguration` and initializes it with the given file to be loaded.
      Parameters:
        `file` - the file to be loaded
      Returns:
        the newly created `FileBasedConfigurationBuilder`

    - #### propertiesBuilder

          public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(PropertiesBuilderParameters parameters)

      Creates a builder for a `PropertiesConfiguration` and initializes it with the given parameters to be loaded.
      Parameters:
        `parameters` - the parameters to be loaded
      Returns:
        the newly created `FileBasedConfigurationBuilder`
      Since:
        2.6

    - #### propertiesBuilder

          public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(URL url)

      Creates a builder for a `PropertiesConfiguration` and initializes it with the given URL to be loaded.
      Parameters:
        `url` - the URL to be loaded
      Returns:
        the newly created `FileBasedConfigurationBuilder`

    - #### propertiesBuilder

          public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(String path)

      Creates a builder for a `PropertiesConfiguration` and initializes it with the given path to the file to be loaded.
      Parameters:
        `path` - the path to the file to be loaded
      Returns:
        the newly created `FileBasedConfigurationBuilder`

    - #### properties

          public PropertiesConfiguration properties(File file)
                                             throws ConfigurationException

      Creates a `PropertiesConfiguration` instance from the content of the given file. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `file` - the file to be loaded
      Returns:
        a `PropertiesConfiguration` object initialized from this file
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### properties

          public PropertiesConfiguration properties(URL url)
                                             throws ConfigurationException

      Creates a `PropertiesConfiguration` instance from the content of the given URL. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `url` - the URL to be loaded
      Returns:
        a `PropertiesConfiguration` object initialized from this URL
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### properties

          public PropertiesConfiguration properties(String path)
                                             throws ConfigurationException

      Creates a `PropertiesConfiguration` instance from the content of the file identified by the given path. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `path` - the path to the file to be loaded
      Returns:
        a `PropertiesConfiguration` object initialized from this path
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### xmlBuilder

          public FileBasedConfigurationBuilder<XMLConfiguration> xmlBuilder(File file)

      Creates a builder for a `XMLConfiguration` and initializes it with the given file to be loaded.
      Parameters:
        `file` - the file to be loaded
      Returns:
        the newly created `FileBasedConfigurationBuilder`

    - #### xmlBuilder

          public FileBasedConfigurationBuilder<XMLConfiguration> xmlBuilder(URL url)

      Creates a builder for a `XMLConfiguration` and initializes it with the given URL to be loaded.
      Parameters:
        `url` - the URL to be loaded
      Returns:
        the newly created `FileBasedConfigurationBuilder`

    - #### xmlBuilder

          public FileBasedConfigurationBuilder<XMLConfiguration> xmlBuilder(String path)

      Creates a builder for a `XMLConfiguration` and initializes it with the given path to the file to be loaded.
      Parameters:
        `path` - the path to the file to be loaded
      Returns:
        the newly created `FileBasedConfigurationBuilder`

    - #### xml

          public XMLConfiguration xml(File file)
                               throws ConfigurationException

      Creates a `XMLConfiguration` instance from the content of the given file. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `file` - the file to be loaded
      Returns:
        a `XMLConfiguration` object initialized from this file
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### xml

          public XMLConfiguration xml(URL url)
                               throws ConfigurationException

      Creates a `XMLConfiguration` instance from the content of the given URL. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `url` - the URL to be loaded
      Returns:
        a `XMLConfiguration` object initialized from this file
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### xml

          public XMLConfiguration xml(String path)
                               throws ConfigurationException

      Creates a `XMLConfiguration` instance from the content of the file identified by the given path. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `path` - the path to the file to be loaded
      Returns:
        a `XMLConfiguration` object initialized from this file
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### iniBuilder

          public FileBasedConfigurationBuilder<INIConfiguration> iniBuilder(File file)

      Creates a builder for a `INIConfiguration` and initializes it with the given file to be loaded.
      Parameters:
        `file` - the file to be loaded
      Returns:
        the newly created `FileBasedConfigurationBuilder`

    - #### iniBuilder

          public FileBasedConfigurationBuilder<INIConfiguration> iniBuilder(URL url)

      Creates a builder for a `INIConfiguration` and initializes it with the given URL to be loaded.
      Parameters:
        `url` - the URL to be loaded
      Returns:
        the newly created `FileBasedConfigurationBuilder`

    - #### iniBuilder

          public FileBasedConfigurationBuilder<INIConfiguration> iniBuilder(String path)

      Creates a builder for a `INIConfiguration` and initializes it with the file file identified by the given path.
      Parameters:
        `path` - the path to the file to be loaded
      Returns:
        the newly created `FileBasedConfigurationBuilder`

    - #### ini

          public INIConfiguration ini(File file)
                               throws ConfigurationException

      Creates a `INIConfiguration` instance from the content of the given file. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `file` - the file to be loaded
      Returns:
        a `INIConfiguration` object initialized from this file
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### ini

          public INIConfiguration ini(URL url)
                               throws ConfigurationException

      Creates a `INIConfiguration` instance from the content of the given URL. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `url` - the URL to be loaded
      Returns:
        a `INIConfiguration` object initialized from this file
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### ini

          public INIConfiguration ini(String path)
                               throws ConfigurationException

      Creates a `INIConfiguration` instance from the content of the file identified by the given path. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `path` - the path to the file to be loaded
      Returns:
        a `INIConfiguration` object initialized from this file
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### combinedBuilder

          public CombinedConfigurationBuilder combinedBuilder(File file)

      Creates a builder for a `CombinedConfiguration` and initializes it with the given file to be loaded.
      Parameters:
        `file` - the file to be loaded
      Returns:
        the newly created `CombinedConfigurationBuilder`

    - #### combinedBuilder

          public CombinedConfigurationBuilder combinedBuilder(URL url)

      Creates a builder for a `CombinedConfiguration` and initializes it with the given URL to be loaded.
      Parameters:
        `url` - the URL to be loaded
      Returns:
        the newly created `CombinedConfigurationBuilder`

    - #### combinedBuilder

          public CombinedConfigurationBuilder combinedBuilder(String path)

      Creates a builder for a `CombinedConfiguration` and initializes it with the given path to the file to be loaded.
      Parameters:
        `path` - the path to the file to be loaded
      Returns:
        the newly created `CombinedConfigurationBuilder`

    - #### combined

          public CombinedConfiguration combined(File file)
                                         throws ConfigurationException

      Creates a `CombinedConfiguration` instance from the content of the given file. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `file` - the file to be loaded
      Returns:
        a `CombinedConfiguration` object initialized from this file
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### combined

          public CombinedConfiguration combined(URL url)
                                         throws ConfigurationException

      Creates a `CombinedConfiguration` instance from the content of the given URL. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `url` - the URL to be loaded
      Returns:
        a `CombinedConfiguration` object initialized from this URL
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

    - #### combined

          public CombinedConfiguration combined(String path)
                                         throws ConfigurationException

      Creates a `CombinedConfiguration` instance from the content of the file identified by the given path. This is a convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is created).
      Parameters:
        `path` - the path to the file to be loaded
      Returns:
        a `CombinedConfiguration` object initialized from this URL
      Throws:
        `ConfigurationException` - if an error occurred when loading the configuration

Copyright © 2001–2022 The Apache Software Foundation. All rights reserved.