Package 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 | 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 | 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()` | Gets 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​(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.
    `FileBasedConfigurationBuilder<PropertiesConfiguration>` | `propertiesBuilder​(PropertiesBuilderParameters parameters)` | Creates a builder for a `PropertiesConfiguration` and initializes it with the given parameters 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()

      Gets 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