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

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

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

ASF GitHub Bot (Jira)

     [ https://issues.apache.org/jira/browse/CONFIGURATION-756?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Gary Gregory updated CONFIGURATION-756:
---------------------------------------
    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}}:
{code:java}
/**
 * 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;
}
{code}
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:
{code:java}
    /**
     * 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;
    };
{code}
In addition, a noop implementation is provided for simple use cases and tests:
{code:java}
    /**
     * 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
    };
{code}
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}}.
  

  was:
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.

 

* I am reworking the whole PR ATM, please hold... *

[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 interface defined in {{PropertiesConfiguration}}:
{code:java}
    /**
     * Defines error handling for the special {@code "include"} key.
     *
     * @since 2.6
     */
    public interface IncludeListener
    {
        /**
         * Defines what to do when an include file is missing.
         *
         * @param fileName the missing file name.
         * @throws ConfigurationException Optionally thrown by the implementation to stop processing.
         */
        void onFileNotFound(String fileName) throws ConfigurationException;

        /**
         * Defines what to do when an exception is caught loading a property file.
         *
         * @param e The exception.
         * @throws ConfigurationException Optionally thrown by the implementation to stop processing.
         */
        void onLoadException(ConfigurationException e) throws ConfigurationException;
    }
{code}
Where the default behavior does not change and is implemented as:
{code:java}
    /**
     * Defines the default behavior.
     *
     * @since 2.6
     */
    public static class DefaultIncludeListener implements IncludeListener
    {
        /**
         * The singleton instance.
         */
        public static final DefaultIncludeListener INSTANCE = new DefaultIncludeListener();

        @Override
        public void onFileNotFound(final String fileName) throws ConfigurationException
        {
            throw new ConfigurationException("Cannot resolve include file " + fileName);
        }

        @Override
        public void onLoadException(ConfigurationException e) throws ConfigurationException
        {
            throw e;
        }
    }
{code}
In addition, a NOOP implementation is provided for simple use cases and tests:
{code:java}
    /**
     * Implements all methods as noops.
     *
     * @since 2.6
     */
    public static class NoopIncludeListener implements IncludeListener
    {
        /**
         * The singleton instance.
         */
        public static final NoopIncludeListener INSTANCE = new NoopIncludeListener();

        @Override
        public void onFileNotFound(final String fileName) throws ConfigurationException
        {
            // noop
        }

        @Override
        public void onLoadException(ConfigurationException e) throws ConfigurationException
        {
            // noop
        }
    }
{code}
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}}.
  


> Allow for custom behavior to handle errors loading included properties files.
> -----------------------------------------------------------------------------
>
>                 Key: CONFIGURATION-756
>                 URL: https://issues.apache.org/jira/browse/CONFIGURATION-756
>             Project: Commons Configuration
>          Issue Type: New Feature
>            Reporter: Gary Gregory
>            Assignee: Gary Gregory
>            Priority: Major
>
> 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}}:
> {code:java}
> /**
>  * 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;
> }
> {code}
> 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:
> {code:java}
>     /**
>      * 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;
>     };
> {code}
> In addition, a noop implementation is provided for simple use cases and tests:
> {code:java}
>     /**
>      * 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
>     };
> {code}
> 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}}.
>   



--
This message was sent by Atlassian Jira
(v8.3.2#803003)