Configurations.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.configuration2.builder.fluent;

  18. import java.io.File;
  19. import java.net.URL;

  20. import org.apache.commons.configuration2.CombinedConfiguration;
  21. import org.apache.commons.configuration2.FileBasedConfiguration;
  22. import org.apache.commons.configuration2.INIConfiguration;
  23. import org.apache.commons.configuration2.PropertiesConfiguration;
  24. import org.apache.commons.configuration2.XMLConfiguration;
  25. import org.apache.commons.configuration2.builder.FileBasedConfigurationBuilder;
  26. import org.apache.commons.configuration2.builder.combined.CombinedConfigurationBuilder;
  27. import org.apache.commons.configuration2.ex.ConfigurationException;

  28. //@formatter:off
  29. /**
  30.  * A convenience class which simplifies the creation of standard configurations and their builders.
  31.  * <p>
  32.  * Complex initializations of configuration builders can be done in a pretty straight-forward way by making use of the
  33.  * provided fluent API. However, if only default settings are used (and maybe a configuration file to be loaded has to
  34.  * be specified), this approach tends to become a bit verbose. This class was introduced to simplify the creation of
  35.  * configuration objects in such cases. It offers a bunch of methods which allow the creation of some standard
  36.  * configuration classes with default settings passing in only a minimum required parameters.
  37.  * </p>
  38.  * <p>
  39.  * An an example consider the creation of a {@code PropertiesConfiguration} object from a file. Using a builder, code
  40.  * like the following one would have to be written:
  41.  * </p>
  42.  * <pre>
  43.  * Parameters params = new Parameters();
  44.  * FileBasedConfigurationBuilder&lt;PropertiesConfiguration&gt; builder =
  45.  *   new FileBasedConfigurationBuilder&lt;PropertiesConfiguration&gt;(PropertiesConfiguration.class)
  46.  *     .configure(params.fileBased().setFile(new File(&quot;config.properties&quot;)));
  47.  * PropertiesConfiguration config = builder.getConfiguration();
  48.  * </pre>
  49.  * <p>
  50.  * With a convenience method of {@code Configurations} the same can be achieved with the following:
  51.  * </p>
  52.  * <pre>
  53.  * Configurations configurations = new Configurations();
  54.  * PropertiesConfiguration config = configurations.properties(new File(&quot;config.properties&quot;));
  55.  * </pre>
  56.  * <p>
  57.  * There are similar methods for constructing builder objects from which configurations can then be obtained.
  58.  * </p>
  59.  * <p>
  60.  * This class is thread-safe. A single instance can be created by an application and used in a central way to create
  61.  * configuration objects. When an instance is created a {@link Parameters} instance can be passed in. Otherwise, a
  62.  * default instance is created. In any case, the {@code Parameters} instance associated with a {@code Configurations}
  63.  * object can be used to define default settings for the configurations to be created.
  64.  * </p>
  65.  *
  66.  * @since 2.0
  67.  * @see org.apache.commons.configuration2.builder.DefaultParametersManager
  68.  */
  69. //@formatter:off
  70. public class Configurations {
  71.     /** The parameters object associated with this instance. */
  72.     private final Parameters parameters;

  73.     /**
  74.      * Creates a new {@code Configurations} instance with default settings.
  75.      */
  76.     public Configurations() {
  77.         this(null);
  78.     }

  79.     /**
  80.      * Creates a new instance of {@code Configurations} and initializes it with the specified {@code Parameters} object.
  81.      *
  82.      * @param params the {@code Parameters} (may be <strong>null</strong>, then a default instance is created)
  83.      */
  84.     public Configurations(final Parameters params) {
  85.         parameters = params != null ? params : new Parameters();
  86.     }

  87.     /**
  88.      * Creates a {@code CombinedConfiguration} instance from the content of the given file. This is a convenience method
  89.      * which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a
  90.      * builder is created).
  91.      *
  92.      * @param file the file to be loaded
  93.      * @return a {@code CombinedConfiguration} object initialized from this file
  94.      * @throws ConfigurationException if an error occurred when loading the configuration
  95.      */
  96.     public CombinedConfiguration combined(final File file) throws ConfigurationException {
  97.         return combinedBuilder(file).getConfiguration();
  98.     }

  99.     /**
  100.      * Creates a {@code CombinedConfiguration} instance from the content of the file identified by the given path. This is a
  101.      * convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind
  102.      * the scenes a builder is created).
  103.      *
  104.      * @param path the path to the file to be loaded
  105.      * @return a {@code CombinedConfiguration} object initialized from this URL
  106.      * @throws ConfigurationException if an error occurred when loading the configuration
  107.      */
  108.     public CombinedConfiguration combined(final String path) throws ConfigurationException {
  109.         return combinedBuilder(path).getConfiguration();
  110.     }

  111.     /**
  112.      * Creates a {@code CombinedConfiguration} instance from the content of the given URL. This is a convenience method
  113.      * which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a
  114.      * builder is created).
  115.      *
  116.      * @param url the URL to be loaded
  117.      * @return a {@code CombinedConfiguration} object initialized from this URL
  118.      * @throws ConfigurationException if an error occurred when loading the configuration
  119.      */
  120.     public CombinedConfiguration combined(final URL url) throws ConfigurationException {
  121.         return combinedBuilder(url).getConfiguration();
  122.     }

  123.     /**
  124.      * Creates a builder for a {@code CombinedConfiguration} and initializes it with the given file to be loaded.
  125.      *
  126.      * @param file the file to be loaded
  127.      * @return the newly created {@code CombinedConfigurationBuilder}
  128.      */
  129.     public CombinedConfigurationBuilder combinedBuilder(final File file) {
  130.         return new CombinedConfigurationBuilder().configure(fileParams(file));
  131.     }

  132.     /**
  133.      * Creates a builder for a {@code CombinedConfiguration} and initializes it with the given path to the file to be
  134.      * loaded.
  135.      *
  136.      * @param path the path to the file to be loaded
  137.      * @return the newly created {@code CombinedConfigurationBuilder}
  138.      */
  139.     public CombinedConfigurationBuilder combinedBuilder(final String path) {
  140.         return new CombinedConfigurationBuilder().configure(fileParams(path));
  141.     }

  142.     /**
  143.      * Creates a builder for a {@code CombinedConfiguration} and initializes it with the given URL to be loaded.
  144.      *
  145.      * @param url the URL to be loaded
  146.      * @return the newly created {@code CombinedConfigurationBuilder}
  147.      */
  148.     public CombinedConfigurationBuilder combinedBuilder(final URL url) {
  149.         return new CombinedConfigurationBuilder().configure(fileParams(url));
  150.     }

  151.     /**
  152.      * Creates a configured builder for a file-based configuration of the specified type.
  153.      *
  154.      * @param configClass the configuration class
  155.      * @param <T> the type of the configuration to be constructed
  156.      * @return the newly created builder
  157.      * @since 2.6
  158.      */
  159.     private <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> createFileBasedBuilder(final Class<T> configClass) {
  160.         return new FileBasedConfigurationBuilder<>(configClass);
  161.     }

  162.     /**
  163.      * Creates a configured builder for a file-based configuration of the specified type.
  164.      *
  165.      * @param configClass the configuration class
  166.      * @param params the parameters object for configuring the builder
  167.      * @param <T> the type of the configuration to be constructed
  168.      * @return the newly created builder
  169.      */
  170.     private <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> createFileBasedBuilder(final Class<T> configClass,
  171.         final FileBasedBuilderParameters params) {
  172.         return createFileBasedBuilder(configClass).configure(params);
  173.     }

  174.     /**
  175.      * Creates an instance of the specified file-based configuration class from the content of the given file. This is a
  176.      * convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind
  177.      * the scenes a builder is created).
  178.      *
  179.      * @param configClass the configuration class
  180.      * @param file the file to be loaded
  181.      * @param <T> the type of the configuration to be constructed
  182.      * @return a {@code FileBasedConfiguration} object initialized from this file
  183.      * @throws ConfigurationException if an error occurred when loading the configuration
  184.      */
  185.     public <T extends FileBasedConfiguration> T fileBased(final Class<T> configClass, final File file) throws ConfigurationException {
  186.         return fileBasedBuilder(configClass, file).getConfiguration();
  187.     }

  188.     /**
  189.      * Creates an instance of the specified file-based configuration class from the content of the file identified by the
  190.      * given path. This is a convenience method which can be used if no builder is needed for managing the configuration
  191.      * object. (Although, behind the scenes a builder is created).
  192.      *
  193.      * @param configClass the configuration class
  194.      * @param path the path to the file to be loaded
  195.      * @param <T> the type of the configuration to be constructed
  196.      * @return a {@code FileBasedConfiguration} object initialized from this file
  197.      * @throws ConfigurationException if an error occurred when loading the configuration
  198.      */
  199.     public <T extends FileBasedConfiguration> T fileBased(final Class<T> configClass, final String path) throws ConfigurationException {
  200.         return fileBasedBuilder(configClass, path).getConfiguration();
  201.     }

  202.     /**
  203.      * Creates an instance of the specified file-based configuration class from the content of the given URL. This is a
  204.      * convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind
  205.      * the scenes a builder is created).
  206.      *
  207.      * @param configClass the configuration class
  208.      * @param url the URL to be loaded
  209.      * @param <T> the type of the configuration to be constructed
  210.      * @return a {@code FileBasedConfiguration} object initialized from this file
  211.      * @throws ConfigurationException if an error occurred when loading the configuration
  212.      */
  213.     public <T extends FileBasedConfiguration> T fileBased(final Class<T> configClass, final URL url) throws ConfigurationException {
  214.         return fileBasedBuilder(configClass, url).getConfiguration();
  215.     }

  216.     /**
  217.      * Creates a {@code FileBasedConfigurationBuilder} for the specified configuration class and initializes it with the
  218.      * file to be loaded.
  219.      *
  220.      * @param configClass the configuration class
  221.      * @param file the file to be loaded
  222.      * @param <T> the type of the configuration to be constructed
  223.      * @return the new {@code FileBasedConfigurationBuilder}
  224.      */
  225.     public <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> fileBasedBuilder(final Class<T> configClass, final File file) {
  226.         return createFileBasedBuilder(configClass, fileParams(file));
  227.     }

  228.     /**
  229.      * Creates a {@code FileBasedConfigurationBuilder} for the specified configuration class and initializes it with the
  230.      * path to the file to be loaded.
  231.      *
  232.      * @param configClass the configuration class
  233.      * @param path the path to the file to be loaded
  234.      * @param <T> the type of the configuration to be constructed
  235.      * @return the new {@code FileBasedConfigurationBuilder}
  236.      */
  237.     public <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> fileBasedBuilder(final Class<T> configClass, final String path) {
  238.         return createFileBasedBuilder(configClass, fileParams(path));
  239.     }

  240.     /**
  241.      * Creates a {@code FileBasedConfigurationBuilder} for the specified configuration class and initializes it with the URL
  242.      * to the file to be loaded.
  243.      *
  244.      * @param configClass the configuration class
  245.      * @param url the URL to be loaded
  246.      * @param <T> the type of the configuration to be constructed
  247.      * @return the new {@code FileBasedConfigurationBuilder}
  248.      */
  249.     public <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> fileBasedBuilder(final Class<T> configClass, final URL url) {
  250.         return createFileBasedBuilder(configClass, fileParams(url));
  251.     }

  252.     /**
  253.      * Convenience method for creating a parameters object for a file-based configuration.
  254.      *
  255.      * @return the newly created parameters object
  256.      */
  257.     private FileBasedBuilderParameters fileParams() {
  258.         return getParameters().fileBased();
  259.     }

  260.     /**
  261.      * Convenience method for creating a file-based parameters object initialized with the given file.
  262.      *
  263.      * @param file the file to be loaded
  264.      * @return the initialized parameters object
  265.      */
  266.     private FileBasedBuilderParameters fileParams(final File file) {
  267.         return fileParams().setFile(file);
  268.     }

  269.     /**
  270.      * Convenience method for creating a file-based parameters object initialized with the given file path.
  271.      *
  272.      * @param path the path to the file to be loaded
  273.      * @return the initialized parameters object
  274.      */
  275.     private FileBasedBuilderParameters fileParams(final String path) {
  276.         return fileParams().setFileName(path);
  277.     }

  278.     /**
  279.      * Convenience method for creating a file-based parameters object initialized with the given file.
  280.      *
  281.      * @param url the URL to be loaded
  282.      * @return the initialized parameters object
  283.      */
  284.     private FileBasedBuilderParameters fileParams(final URL url) {
  285.         return fileParams().setURL(url);
  286.     }

  287.     /**
  288.      * Gets the {@code Parameters} instance associated with this object.
  289.      *
  290.      * @return the associated {@code Parameters} object
  291.      */
  292.     public Parameters getParameters() {
  293.         return parameters;
  294.     }

  295.     /**
  296.      * Creates a {@code INIConfiguration} instance from the content of the given file. This is a convenience method which
  297.      * can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is
  298.      * created).
  299.      *
  300.      * @param file the file to be loaded
  301.      * @return a {@code INIConfiguration} object initialized from this file
  302.      * @throws ConfigurationException if an error occurred when loading the configuration
  303.      */
  304.     public INIConfiguration ini(final File file) throws ConfigurationException {
  305.         return iniBuilder(file).getConfiguration();
  306.     }

  307.     /**
  308.      * Creates a {@code INIConfiguration} instance from the content of the file identified by the given path. This is a
  309.      * convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind
  310.      * the scenes a builder is created).
  311.      *
  312.      * @param path the path to the file to be loaded
  313.      * @return a {@code INIConfiguration} object initialized from this file
  314.      * @throws ConfigurationException if an error occurred when loading the configuration
  315.      */
  316.     public INIConfiguration ini(final String path) throws ConfigurationException {
  317.         return iniBuilder(path).getConfiguration();
  318.     }

  319.     /**
  320.      * Creates a {@code INIConfiguration} instance from the content of the given URL. This is a convenience method which can
  321.      * be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is
  322.      * created).
  323.      *
  324.      * @param url the URL to be loaded
  325.      * @return a {@code INIConfiguration} object initialized from this file
  326.      * @throws ConfigurationException if an error occurred when loading the configuration
  327.      */
  328.     public INIConfiguration ini(final URL url) throws ConfigurationException {
  329.         return iniBuilder(url).getConfiguration();
  330.     }

  331.     /**
  332.      * Creates a builder for a {@code INIConfiguration} and initializes it with the given file to be loaded.
  333.      *
  334.      * @param file the file to be loaded
  335.      * @return the newly created {@code FileBasedConfigurationBuilder}
  336.      */
  337.     public FileBasedConfigurationBuilder<INIConfiguration> iniBuilder(final File file) {
  338.         return fileBasedBuilder(INIConfiguration.class, file);
  339.     }

  340.     /**
  341.      * Creates a builder for a {@code INIConfiguration} and initializes it with the file file identified by the given path.
  342.      *
  343.      * @param path the path to the file to be loaded
  344.      * @return the newly created {@code FileBasedConfigurationBuilder}
  345.      */
  346.     public FileBasedConfigurationBuilder<INIConfiguration> iniBuilder(final String path) {
  347.         return fileBasedBuilder(INIConfiguration.class, path);
  348.     }

  349.     /**
  350.      * Creates a builder for a {@code INIConfiguration} and initializes it with the given URL to be loaded.
  351.      *
  352.      * @param url the URL to be loaded
  353.      * @return the newly created {@code FileBasedConfigurationBuilder}
  354.      */
  355.     public FileBasedConfigurationBuilder<INIConfiguration> iniBuilder(final URL url) {
  356.         return fileBasedBuilder(INIConfiguration.class, url);
  357.     }

  358.     /**
  359.      * Creates a {@code PropertiesConfiguration} instance from the content of the given file. This is a convenience method
  360.      * which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a
  361.      * builder is created).
  362.      *
  363.      * @param file the file to be loaded
  364.      * @return a {@code PropertiesConfiguration} object initialized from this file
  365.      * @throws ConfigurationException if an error occurred when loading the configuration
  366.      */
  367.     public PropertiesConfiguration properties(final File file) throws ConfigurationException {
  368.         return propertiesBuilder(file).getConfiguration();
  369.     }

  370.     /**
  371.      * Creates a {@code PropertiesConfiguration} instance from the content of the file identified by the given path. This is
  372.      * a convenience method which can be used if no builder is needed for managing the configuration object. (Although,
  373.      * behind the scenes a builder is created).
  374.      *
  375.      * @param path the path to the file to be loaded
  376.      * @return a {@code PropertiesConfiguration} object initialized from this path
  377.      * @throws ConfigurationException if an error occurred when loading the configuration
  378.      */
  379.     public PropertiesConfiguration properties(final String path) throws ConfigurationException {
  380.         return propertiesBuilder(path).getConfiguration();
  381.     }

  382.     /**
  383.      * Creates a {@code PropertiesConfiguration} instance from the content of the given URL. This is a convenience method
  384.      * which can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a
  385.      * builder is created).
  386.      *
  387.      * @param url the URL to be loaded
  388.      * @return a {@code PropertiesConfiguration} object initialized from this URL
  389.      * @throws ConfigurationException if an error occurred when loading the configuration
  390.      */
  391.     public PropertiesConfiguration properties(final URL url) throws ConfigurationException {
  392.         return propertiesBuilder(url).getConfiguration();
  393.     }

  394.     /**
  395.      * Creates a builder for a {@code PropertiesConfiguration}.
  396.      *
  397.      * @return the newly created {@code FileBasedConfigurationBuilder}
  398.      * @since 2.6
  399.      */
  400.     public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder() {
  401.         return createFileBasedBuilder(PropertiesConfiguration.class);
  402.     }

  403.     /**
  404.      * Creates a builder for a {@code PropertiesConfiguration} and initializes it with the given file to be loaded.
  405.      *
  406.      * @param file the file to be loaded
  407.      * @return the newly created {@code FileBasedConfigurationBuilder}
  408.      */
  409.     public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(final File file) {
  410.         return fileBasedBuilder(PropertiesConfiguration.class, file);
  411.     }

  412.     /**
  413.      * Creates a builder for a {@code PropertiesConfiguration} and initializes it with the given parameters to be loaded.
  414.      *
  415.      * @param parameters the parameters to be loaded
  416.      * @return the newly created {@code FileBasedConfigurationBuilder}
  417.      * @since 2.6
  418.      */
  419.     public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(final PropertiesBuilderParameters parameters) {
  420.         return propertiesBuilder().configure(parameters);
  421.     }

  422.     /**
  423.      * Creates a builder for a {@code PropertiesConfiguration} and initializes it with the given path to the file to be
  424.      * loaded.
  425.      *
  426.      * @param path the path to the file to be loaded
  427.      * @return the newly created {@code FileBasedConfigurationBuilder}
  428.      */
  429.     public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(final String path) {
  430.         return fileBasedBuilder(PropertiesConfiguration.class, path);
  431.     }

  432.     /**
  433.      * Creates a builder for a {@code PropertiesConfiguration} and initializes it with the given URL to be loaded.
  434.      *
  435.      * @param url the URL to be loaded
  436.      * @return the newly created {@code FileBasedConfigurationBuilder}
  437.      */
  438.     public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(final URL url) {
  439.         return fileBasedBuilder(PropertiesConfiguration.class, url);
  440.     }

  441.     /**
  442.      * Creates a {@code XMLConfiguration} instance from the content of the given file. This is a convenience method which
  443.      * can be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is
  444.      * created).
  445.      *
  446.      * @param file the file to be loaded
  447.      * @return a {@code XMLConfiguration} object initialized from this file
  448.      * @throws ConfigurationException if an error occurred when loading the configuration
  449.      */
  450.     public XMLConfiguration xml(final File file) throws ConfigurationException {
  451.         return xmlBuilder(file).getConfiguration();
  452.     }

  453.     /**
  454.      * Creates a {@code XMLConfiguration} instance from the content of the file identified by the given path. This is a
  455.      * convenience method which can be used if no builder is needed for managing the configuration object. (Although, behind
  456.      * the scenes a builder is created).
  457.      *
  458.      * @param path the path to the file to be loaded
  459.      * @return a {@code XMLConfiguration} object initialized from this file
  460.      * @throws ConfigurationException if an error occurred when loading the configuration
  461.      */
  462.     public XMLConfiguration xml(final String path) throws ConfigurationException {
  463.         return xmlBuilder(path).getConfiguration();
  464.     }

  465.     /**
  466.      * Creates a {@code XMLConfiguration} instance from the content of the given URL. This is a convenience method which can
  467.      * be used if no builder is needed for managing the configuration object. (Although, behind the scenes a builder is
  468.      * created).
  469.      *
  470.      * @param url the URL to be loaded
  471.      * @return a {@code XMLConfiguration} object initialized from this file
  472.      * @throws ConfigurationException if an error occurred when loading the configuration
  473.      */
  474.     public XMLConfiguration xml(final URL url) throws ConfigurationException {
  475.         return xmlBuilder(url).getConfiguration();
  476.     }

  477.     /**
  478.      * Creates a builder for a {@code XMLConfiguration} and initializes it with the given file to be loaded.
  479.      *
  480.      * @param file the file to be loaded
  481.      * @return the newly created {@code FileBasedConfigurationBuilder}
  482.      */
  483.     public FileBasedConfigurationBuilder<XMLConfiguration> xmlBuilder(final File file) {
  484.         return fileBasedBuilder(XMLConfiguration.class, file);
  485.     }

  486.     /**
  487.      * Creates a builder for a {@code XMLConfiguration} and initializes it with the given path to the file to be loaded.
  488.      *
  489.      * @param path the path to the file to be loaded
  490.      * @return the newly created {@code FileBasedConfigurationBuilder}
  491.      */
  492.     public FileBasedConfigurationBuilder<XMLConfiguration> xmlBuilder(final String path) {
  493.         return fileBasedBuilder(XMLConfiguration.class, path);
  494.     }

  495.     /**
  496.      * Creates a builder for a {@code XMLConfiguration} and initializes it with the given URL to be loaded.
  497.      *
  498.      * @param url the URL to be loaded
  499.      * @return the newly created {@code FileBasedConfigurationBuilder}
  500.      */
  501.     public FileBasedConfigurationBuilder<XMLConfiguration> xmlBuilder(final URL url) {
  502.         return fileBasedBuilder(XMLConfiguration.class, url);
  503.     }

  504. }