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

  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 Details

  - ### 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 Details

  - ### 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(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

  - ### 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

  - ### 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(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`

  - ### 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`

  - ### 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, 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

  - ### 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

  - ### 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, 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`

  - ### 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`

  - ### getParameters

    public Parameters getParameters()
    Gets the `Parameters` instance associated with this object.
    Returns:
      the associated `Parameters` object

  - ### 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(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

  - ### 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

  - ### 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(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`

  - ### 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`

  - ### 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(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

  - ### 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

  - ### 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(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`

  - ### 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`

  - ### 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(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

  - ### 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

  - ### 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(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`

  - ### 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`