Configurations.java
- /*
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
- package org.apache.commons.configuration2.builder.fluent;
- import java.io.File;
- import java.net.URL;
- import org.apache.commons.configuration2.CombinedConfiguration;
- import org.apache.commons.configuration2.FileBasedConfiguration;
- import org.apache.commons.configuration2.INIConfiguration;
- import org.apache.commons.configuration2.PropertiesConfiguration;
- import org.apache.commons.configuration2.XMLConfiguration;
- import org.apache.commons.configuration2.builder.FileBasedConfigurationBuilder;
- import org.apache.commons.configuration2.builder.combined.CombinedConfigurationBuilder;
- import org.apache.commons.configuration2.ex.ConfigurationException;
- //@formatter:off
- /**
- * A convenience class which simplifies the creation of standard configurations and their builders.
- * <p>
- * 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.
- * </p>
- * <p>
- * An an example consider the creation of a {@code PropertiesConfiguration} object from a file. Using a builder, code
- * like the following one would have to be written:
- * </p>
- * <pre>
- * Parameters params = new Parameters();
- * FileBasedConfigurationBuilder<PropertiesConfiguration> builder =
- * new FileBasedConfigurationBuilder<PropertiesConfiguration>(PropertiesConfiguration.class)
- * .configure(params.fileBased().setFile(new File("config.properties")));
- * PropertiesConfiguration config = builder.getConfiguration();
- * </pre>
- * <p>
- * With a convenience method of {@code Configurations} the same can be achieved with the following:
- * </p>
- * <pre>
- * Configurations configurations = new Configurations();
- * PropertiesConfiguration config = configurations.properties(new File("config.properties"));
- * </pre>
- * <p>
- * There are similar methods for constructing builder objects from which configurations can then be obtained.
- * </p>
- * <p>
- * 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 {@link Parameters} instance can be passed in. Otherwise, a
- * default instance is created. In any case, the {@code Parameters} instance associated with a {@code Configurations}
- * object can be used to define default settings for the configurations to be created.
- * </p>
- *
- * @since 2.0
- * @see org.apache.commons.configuration2.builder.DefaultParametersManager
- */
- //@formatter:off
- public class Configurations {
- /** The parameters object associated with this instance. */
- private final Parameters parameters;
- /**
- * Creates a new {@code Configurations} instance with default settings.
- */
- public Configurations() {
- this(null);
- }
- /**
- * Creates a new instance of {@code Configurations} and initializes it with the specified {@code Parameters} object.
- *
- * @param params the {@code Parameters} (may be <strong>null</strong>, then a default instance is created)
- */
- public Configurations(final Parameters params) {
- parameters = params != null ? params : new Parameters();
- }
- /**
- * Creates a {@code 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).
- *
- * @param file the file to be loaded
- * @return a {@code CombinedConfiguration} object initialized from this file
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public CombinedConfiguration combined(final File file) throws ConfigurationException {
- return combinedBuilder(file).getConfiguration();
- }
- /**
- * Creates a {@code 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).
- *
- * @param path the path to the file to be loaded
- * @return a {@code CombinedConfiguration} object initialized from this URL
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public CombinedConfiguration combined(final String path) throws ConfigurationException {
- return combinedBuilder(path).getConfiguration();
- }
- /**
- * Creates a {@code 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).
- *
- * @param url the URL to be loaded
- * @return a {@code CombinedConfiguration} object initialized from this URL
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public CombinedConfiguration combined(final URL url) throws ConfigurationException {
- return combinedBuilder(url).getConfiguration();
- }
- /**
- * Creates a builder for a {@code CombinedConfiguration} and initializes it with the given file to be loaded.
- *
- * @param file the file to be loaded
- * @return the newly created {@code CombinedConfigurationBuilder}
- */
- public CombinedConfigurationBuilder combinedBuilder(final File file) {
- return new CombinedConfigurationBuilder().configure(fileParams(file));
- }
- /**
- * Creates a builder for a {@code CombinedConfiguration} and initializes it with the given path to the file to be
- * loaded.
- *
- * @param path the path to the file to be loaded
- * @return the newly created {@code CombinedConfigurationBuilder}
- */
- public CombinedConfigurationBuilder combinedBuilder(final String path) {
- return new CombinedConfigurationBuilder().configure(fileParams(path));
- }
- /**
- * Creates a builder for a {@code CombinedConfiguration} and initializes it with the given URL to be loaded.
- *
- * @param url the URL to be loaded
- * @return the newly created {@code CombinedConfigurationBuilder}
- */
- public CombinedConfigurationBuilder combinedBuilder(final URL url) {
- return new CombinedConfigurationBuilder().configure(fileParams(url));
- }
- /**
- * Creates a configured builder for a file-based configuration of the specified type.
- *
- * @param configClass the configuration class
- * @param <T> the type of the configuration to be constructed
- * @return the newly created builder
- * @since 2.6
- */
- private <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> createFileBasedBuilder(final Class<T> configClass) {
- return new FileBasedConfigurationBuilder<>(configClass);
- }
- /**
- * Creates a configured builder for a file-based configuration of the specified type.
- *
- * @param configClass the configuration class
- * @param params the parameters object for configuring the builder
- * @param <T> the type of the configuration to be constructed
- * @return the newly created builder
- */
- private <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> createFileBasedBuilder(final Class<T> configClass,
- final FileBasedBuilderParameters params) {
- return createFileBasedBuilder(configClass).configure(params);
- }
- /**
- * 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).
- *
- * @param configClass the configuration class
- * @param file the file to be loaded
- * @param <T> the type of the configuration to be constructed
- * @return a {@code FileBasedConfiguration} object initialized from this file
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public <T extends FileBasedConfiguration> T fileBased(final Class<T> configClass, final File file) throws ConfigurationException {
- return fileBasedBuilder(configClass, file).getConfiguration();
- }
- /**
- * 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).
- *
- * @param configClass the configuration class
- * @param path the path to the file to be loaded
- * @param <T> the type of the configuration to be constructed
- * @return a {@code FileBasedConfiguration} object initialized from this file
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public <T extends FileBasedConfiguration> T fileBased(final Class<T> configClass, final String path) throws ConfigurationException {
- return fileBasedBuilder(configClass, path).getConfiguration();
- }
- /**
- * 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).
- *
- * @param configClass the configuration class
- * @param url the URL to be loaded
- * @param <T> the type of the configuration to be constructed
- * @return a {@code FileBasedConfiguration} object initialized from this file
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public <T extends FileBasedConfiguration> T fileBased(final Class<T> configClass, final URL url) throws ConfigurationException {
- return fileBasedBuilder(configClass, url).getConfiguration();
- }
- /**
- * Creates a {@code FileBasedConfigurationBuilder} for the specified configuration class and initializes it with the
- * file to be loaded.
- *
- * @param configClass the configuration class
- * @param file the file to be loaded
- * @param <T> the type of the configuration to be constructed
- * @return the new {@code FileBasedConfigurationBuilder}
- */
- public <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> fileBasedBuilder(final Class<T> configClass, final File file) {
- return createFileBasedBuilder(configClass, fileParams(file));
- }
- /**
- * Creates a {@code FileBasedConfigurationBuilder} for the specified configuration class and initializes it with the
- * path to the file to be loaded.
- *
- * @param configClass the configuration class
- * @param path the path to the file to be loaded
- * @param <T> the type of the configuration to be constructed
- * @return the new {@code FileBasedConfigurationBuilder}
- */
- public <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> fileBasedBuilder(final Class<T> configClass, final String path) {
- return createFileBasedBuilder(configClass, fileParams(path));
- }
- /**
- * Creates a {@code FileBasedConfigurationBuilder} for the specified configuration class and initializes it with the URL
- * to the file to be loaded.
- *
- * @param configClass the configuration class
- * @param url the URL to be loaded
- * @param <T> the type of the configuration to be constructed
- * @return the new {@code FileBasedConfigurationBuilder}
- */
- public <T extends FileBasedConfiguration> FileBasedConfigurationBuilder<T> fileBasedBuilder(final Class<T> configClass, final URL url) {
- return createFileBasedBuilder(configClass, fileParams(url));
- }
- /**
- * Convenience method for creating a parameters object for a file-based configuration.
- *
- * @return the newly created parameters object
- */
- private FileBasedBuilderParameters fileParams() {
- return getParameters().fileBased();
- }
- /**
- * Convenience method for creating a file-based parameters object initialized with the given file.
- *
- * @param file the file to be loaded
- * @return the initialized parameters object
- */
- private FileBasedBuilderParameters fileParams(final File file) {
- return fileParams().setFile(file);
- }
- /**
- * Convenience method for creating a file-based parameters object initialized with the given file path.
- *
- * @param path the path to the file to be loaded
- * @return the initialized parameters object
- */
- private FileBasedBuilderParameters fileParams(final String path) {
- return fileParams().setFileName(path);
- }
- /**
- * Convenience method for creating a file-based parameters object initialized with the given file.
- *
- * @param url the URL to be loaded
- * @return the initialized parameters object
- */
- private FileBasedBuilderParameters fileParams(final URL url) {
- return fileParams().setURL(url);
- }
- /**
- * Gets the {@code Parameters} instance associated with this object.
- *
- * @return the associated {@code Parameters} object
- */
- public Parameters getParameters() {
- return parameters;
- }
- /**
- * Creates a {@code 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).
- *
- * @param file the file to be loaded
- * @return a {@code INIConfiguration} object initialized from this file
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public INIConfiguration ini(final File file) throws ConfigurationException {
- return iniBuilder(file).getConfiguration();
- }
- /**
- * Creates a {@code 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).
- *
- * @param path the path to the file to be loaded
- * @return a {@code INIConfiguration} object initialized from this file
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public INIConfiguration ini(final String path) throws ConfigurationException {
- return iniBuilder(path).getConfiguration();
- }
- /**
- * Creates a {@code 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).
- *
- * @param url the URL to be loaded
- * @return a {@code INIConfiguration} object initialized from this file
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public INIConfiguration ini(final URL url) throws ConfigurationException {
- return iniBuilder(url).getConfiguration();
- }
- /**
- * Creates a builder for a {@code INIConfiguration} and initializes it with the given file to be loaded.
- *
- * @param file the file to be loaded
- * @return the newly created {@code FileBasedConfigurationBuilder}
- */
- public FileBasedConfigurationBuilder<INIConfiguration> iniBuilder(final File file) {
- return fileBasedBuilder(INIConfiguration.class, file);
- }
- /**
- * Creates a builder for a {@code INIConfiguration} and initializes it with the file file identified by the given path.
- *
- * @param path the path to the file to be loaded
- * @return the newly created {@code FileBasedConfigurationBuilder}
- */
- public FileBasedConfigurationBuilder<INIConfiguration> iniBuilder(final String path) {
- return fileBasedBuilder(INIConfiguration.class, path);
- }
- /**
- * Creates a builder for a {@code INIConfiguration} and initializes it with the given URL to be loaded.
- *
- * @param url the URL to be loaded
- * @return the newly created {@code FileBasedConfigurationBuilder}
- */
- public FileBasedConfigurationBuilder<INIConfiguration> iniBuilder(final URL url) {
- return fileBasedBuilder(INIConfiguration.class, url);
- }
- /**
- * Creates a {@code 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).
- *
- * @param file the file to be loaded
- * @return a {@code PropertiesConfiguration} object initialized from this file
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public PropertiesConfiguration properties(final File file) throws ConfigurationException {
- return propertiesBuilder(file).getConfiguration();
- }
- /**
- * Creates a {@code 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).
- *
- * @param path the path to the file to be loaded
- * @return a {@code PropertiesConfiguration} object initialized from this path
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public PropertiesConfiguration properties(final String path) throws ConfigurationException {
- return propertiesBuilder(path).getConfiguration();
- }
- /**
- * Creates a {@code 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).
- *
- * @param url the URL to be loaded
- * @return a {@code PropertiesConfiguration} object initialized from this URL
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public PropertiesConfiguration properties(final URL url) throws ConfigurationException {
- return propertiesBuilder(url).getConfiguration();
- }
- /**
- * Creates a builder for a {@code PropertiesConfiguration}.
- *
- * @return the newly created {@code FileBasedConfigurationBuilder}
- * @since 2.6
- */
- public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder() {
- return createFileBasedBuilder(PropertiesConfiguration.class);
- }
- /**
- * Creates a builder for a {@code PropertiesConfiguration} and initializes it with the given file to be loaded.
- *
- * @param file the file to be loaded
- * @return the newly created {@code FileBasedConfigurationBuilder}
- */
- public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(final File file) {
- return fileBasedBuilder(PropertiesConfiguration.class, file);
- }
- /**
- * Creates a builder for a {@code PropertiesConfiguration} and initializes it with the given parameters to be loaded.
- *
- * @param parameters the parameters to be loaded
- * @return the newly created {@code FileBasedConfigurationBuilder}
- * @since 2.6
- */
- public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(final PropertiesBuilderParameters parameters) {
- return propertiesBuilder().configure(parameters);
- }
- /**
- * Creates a builder for a {@code PropertiesConfiguration} and initializes it with the given path to the file to be
- * loaded.
- *
- * @param path the path to the file to be loaded
- * @return the newly created {@code FileBasedConfigurationBuilder}
- */
- public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(final String path) {
- return fileBasedBuilder(PropertiesConfiguration.class, path);
- }
- /**
- * Creates a builder for a {@code PropertiesConfiguration} and initializes it with the given URL to be loaded.
- *
- * @param url the URL to be loaded
- * @return the newly created {@code FileBasedConfigurationBuilder}
- */
- public FileBasedConfigurationBuilder<PropertiesConfiguration> propertiesBuilder(final URL url) {
- return fileBasedBuilder(PropertiesConfiguration.class, url);
- }
- /**
- * Creates a {@code 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).
- *
- * @param file the file to be loaded
- * @return a {@code XMLConfiguration} object initialized from this file
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public XMLConfiguration xml(final File file) throws ConfigurationException {
- return xmlBuilder(file).getConfiguration();
- }
- /**
- * Creates a {@code 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).
- *
- * @param path the path to the file to be loaded
- * @return a {@code XMLConfiguration} object initialized from this file
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public XMLConfiguration xml(final String path) throws ConfigurationException {
- return xmlBuilder(path).getConfiguration();
- }
- /**
- * Creates a {@code 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).
- *
- * @param url the URL to be loaded
- * @return a {@code XMLConfiguration} object initialized from this file
- * @throws ConfigurationException if an error occurred when loading the configuration
- */
- public XMLConfiguration xml(final URL url) throws ConfigurationException {
- return xmlBuilder(url).getConfiguration();
- }
- /**
- * Creates a builder for a {@code XMLConfiguration} and initializes it with the given file to be loaded.
- *
- * @param file the file to be loaded
- * @return the newly created {@code FileBasedConfigurationBuilder}
- */
- public FileBasedConfigurationBuilder<XMLConfiguration> xmlBuilder(final File file) {
- return fileBasedBuilder(XMLConfiguration.class, file);
- }
- /**
- * Creates a builder for a {@code XMLConfiguration} and initializes it with the given path to the file to be loaded.
- *
- * @param path the path to the file to be loaded
- * @return the newly created {@code FileBasedConfigurationBuilder}
- */
- public FileBasedConfigurationBuilder<XMLConfiguration> xmlBuilder(final String path) {
- return fileBasedBuilder(XMLConfiguration.class, path);
- }
- /**
- * Creates a builder for a {@code XMLConfiguration} and initializes it with the given URL to be loaded.
- *
- * @param url the URL to be loaded
- * @return the newly created {@code FileBasedConfigurationBuilder}
- */
- public FileBasedConfigurationBuilder<XMLConfiguration> xmlBuilder(final URL url) {
- return fileBasedBuilder(XMLConfiguration.class, url);
- }
- }