[CONFIGURATION-756] Allow for custom behavior to handle errors loading included properties files.

• Type: New Feature
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 2.6
• External issue URL: https://github.com/apache/commons-configuration/pull/34
• External issue ID: 34
• Assignee: Gary D. Gregory
• Reporter: Gary D. Gregory
• Created: 10/Sep/19 13:37
• Updated: 12/Sep/19 14:53
• Resolved: 12/Sep/19 14:53

Description

The properties file format in Commons Configuration allows for a properties file to load external properties files through a special key called "include". This PR allows for a call site to customize what happens when an included file does not exist or is in error.
 
https://github.com/apache/commons-configuration/pull/34

The main change is to re-implement the current behavior for include error handing through a new consumer used in PropertiesConfiguration by introducing a functional interface to consume any type and throw ConfigurationException:

/**
 * A Configuration task that may throw a ConfigurationException.
 *
 * @param <T> the type of the input to the operation.
 * @since 2.6
 */
@FunctionalInterface
public interface ConfigurationConsumer<T>
{

    /**
     * Performs this operation on the given argument.
     *
     * @param t the input argument
     * @throws ConfigurationException TODO
     */
    void accept(T t) throws ConfigurationException;
}

The above is the common pattern when you need a consumer to throw a checked exception.

The PropertiesConfiguration default behavior does not change and is implemented as:

    /**
     * Defines default error handling for the special {@code "include"} key by throwing the given exception.
     *
     * @since 2.6
     */
    public static final ConfigurationConsumer<ConfigurationException> DEFAULT_INCLUDE_LISTENER = e ->
    {
        throw e;
    };

In addition, a noop implementation is provided for simple use cases and tests:

    /**
     * Defines error handling as a noop for the special {@code "include"} key.
     *
     * @since 2.6
     */
    public static final ConfigurationConsumer<ConfigurationException> NOOP_INCLUDE_LISTENER = e ->
    {
        // noop
    };

You can set an include listener through new methods in PropertiesConfiguration and through the fluent API as well. See the PR for details.

Note that this PR does not address detecting cyclical include files but does include a new test method which is decorated with @Ignore.
 

Issue Links

• links to: GitHub Pull Request #34