/*
    * 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
    *
    *     https://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;
  
  import java.io.FileNotFoundException;
  import java.io.FilterWriter;
  import java.io.IOException;
  import java.io.LineNumberReader;
  import java.io.Reader;
  import java.io.Writer;
  import java.net.URL;
  import java.nio.charset.StandardCharsets;
  import java.util.ArrayList;
  import java.util.Collection;
  import java.util.Collections;
  import java.util.Deque;
  import java.util.HashMap;
  import java.util.List;
  import java.util.Map;
  import java.util.regex.Matcher;
  import java.util.regex.Pattern;
  
  import org.apache.commons.configuration2.convert.ListDelimiterHandler;
  import org.apache.commons.configuration2.convert.ValueTransformer;
  import org.apache.commons.configuration2.event.ConfigurationEvent;
  import org.apache.commons.configuration2.ex.ConfigurationDeniedException;
  import org.apache.commons.configuration2.ex.ConfigurationException;
  import org.apache.commons.configuration2.ex.ConfigurationRuntimeException;
  import org.apache.commons.configuration2.io.AbstractFileLocationStrategy;
  import org.apache.commons.configuration2.io.AbstractFileLocationStrategy.AbstractBuilder;
  import org.apache.commons.configuration2.io.FileHandler;
  import org.apache.commons.configuration2.io.FileLocator;
  import org.apache.commons.configuration2.io.FileLocatorAware;
  import org.apache.commons.configuration2.io.FileLocatorUtils;
  import org.apache.commons.lang3.ArrayUtils;
  import org.apache.commons.lang3.StringUtils;
  import org.apache.commons.text.StringEscapeUtils;
  import org.apache.commons.text.translate.AggregateTranslator;
  import org.apache.commons.text.translate.CharSequenceTranslator;
  import org.apache.commons.text.translate.EntityArrays;
  import org.apache.commons.text.translate.LookupTranslator;
  import org.apache.commons.text.translate.UnicodeEscaper;
  
  /**
   * This is the "classic" Properties loader which loads the values from a single or multiple files (which can be chained
   * with "include =". All given path references are either absolute or relative to the file name supplied in the
   * constructor.
   * <p>
   * In this class, empty PropertyConfigurations can be built, properties added and later saved. include statements are
   * (obviously) not supported if you don't construct a PropertyConfiguration from a file.
   *
   * <p>
   * The properties file syntax is explained here, basically it follows the syntax of the stream parsed by
   * {@link java.util.Properties#load} and adds several useful extensions:
   *
   * <ul>
   * <li>Each property has the syntax {@code key &lt;separator&gt; value}. The separators accepted are {@code '='},
   * {@code ':'} and any white space character. Examples:
   *
   * <pre>
   *  key1 = value1
   *  key2 : value2
   *  key3   value3
   * </pre>
   *
   * </li>
   * <li>The <em>key</em> may use any character, separators must be escaped:
   *
   * <pre>
   *  key\:foo = bar
   * </pre>
   *
   * </li>
   * <li><em>value</em> may be separated on different lines if a backslash is placed at the end of the line that continues
   * below.</li>
   * <li>The list delimiter facilities provided by {@link AbstractConfiguration} are supported, too. If an appropriate
   * {@link ListDelimiterHandler} is set (for instance a
   * {@link org.apache.commons.configuration2.convert.DefaultListDelimiterHandler D efaultListDelimiterHandler} object
   * configured with a comma as delimiter character), <em>value</em> can contain <em>value delimiters</em> and will then be
   * interpreted as a list of tokens. So the following property definition
   *
   * <pre>
   *  key = This property, has multiple, values
   * </pre>
  *
  * will result in a property with three values. You can change the handling of delimiters using the
  * {@link AbstractConfiguration#setListDelimiterHandler(ListDelimiterHandler)} method. Per default, list splitting is
  * disabled.</li>
  * <li>Commas in each token are escaped placing a backslash right before the comma.</li>
  * <li>If a <em>key</em> is used more than once, the values are appended like if they were on the same line separated with
  * commas. <em>Note</em>: When the configuration file is written back to disk the associated
  * {@link PropertiesConfigurationLayout} object (see below) will try to preserve as much of the original format as
  * possible, i.e. properties with multiple values defined on a single line will also be written back on a single line,
  * and multiple occurrences of a single key will be written on multiple lines. If the {@code addProperty()} method was
  * called multiple times for adding multiple values to a property, these properties will per default be written on
  * multiple lines in the output file, too. Some options of the {@code PropertiesConfigurationLayout} class have
  * influence on that behavior.</li>
  * <li>Blank lines and lines starting with character '#' or '!' are skipped.</li>
  * <li>If a property is named "include" (or whatever is defined by setInclude() and getInclude() and the value of that
  * property is the full path to a file on disk, that file will be included into the configuration. You can also pull in
  * files relative to the parent configuration file. So if you have something like the following:
  *
  * include = additional.properties
  *
  * Then "additional.properties" is expected to be in the same directory as the parent configuration file.
  *
  * The properties in the included file are added to the parent configuration, they do not replace existing properties
  * with the same key.
  *
  * </li>
  * <li>You can define custom error handling for the special key {@code "include"} by using
  * {@link #setIncludeListener(ConfigurationConsumer)}.</li>
  * </ul>
  *
  * <p>
  * Here is an example of a valid extended properties file:
  * </p>
  *
  * <pre>
  *      # lines starting with # are comments
  *
  *      # This is the simplest property
  *      key = value
  *
  *      # A long property may be separated on multiple lines
  *      longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
  *                  aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
  *
  *      # This is a property with many tokens
  *      tokens_on_a_line = first token, second token
  *
  *      # This sequence generates exactly the same result
  *      tokens_on_multiple_lines = first token
  *      tokens_on_multiple_lines = second token
  *
  *      # commas may be escaped in tokens
  *      commas.escaped = Hi\, what'up?
  *
  *      # properties can reference other properties
  *      base.prop = /base
  *      first.prop = ${base.prop}/first
  *      second.prop = ${first.prop}/second
  * </pre>
  *
  * <p>
  * A {@code PropertiesConfiguration} object is associated with an instance of the {@link PropertiesConfigurationLayout}
  * class, which is responsible for storing the layout of the parsed properties file (i.e. empty lines, comments, and
  * such things). The {@code getLayout()} method can be used to obtain this layout object. With {@code setLayout()} a new
  * layout object can be set. This should be done before a properties file was loaded.
  * </p>
  * <p>
  * Like other {@code Configuration} implementations, this class uses a {@code Synchronizer} object to control concurrent
  * access. By choosing a suitable implementation of the {@code Synchronizer} interface, an instance can be made
  * thread-safe or not. Note that access to most of the properties typically set through a builder is not protected by
  * the {@code Synchronizer}. The intended usage is that these properties are set once at construction time through the
  * builder and after that remain constant. If you wish to change such properties during life time of an instance, you
  * have to use the {@code lock()} and {@code unlock()} methods manually to ensure that other threads see your changes.
  * </p>
  * <p>
  * As this class extends {@link AbstractConfiguration}, all basic features like variable interpolation, list handling,
  * or data type conversions are available as well. This is described in the chapter
  * <a href="https://commons.apache.org/proper/commons-configuration/userguide/howto_basicfeatures.html"> Basic features
  * and AbstractConfiguration</a> of the user's guide. There is also a separate chapter dealing with
  * <a href="commons.apache.org/proper/commons-configuration/userguide/howto_properties.html"> Properties files</a> in
  * special.
  * </p>
  * <p>
  * As of version 2.15.0, by default, when including files, the only URL schemes allowed are {@code file} and {@code jar}. To override this default,
  * you can either use the system property {@code org.apache.commons.configuration2.io.FileLocationStrategy.schemes} or build a subclass of
  * {@link AbstractFileLocationStrategy}.
  * </p>
  * <strong>Using System Properties</strong>
  * <p>
  * The system property {@code org.apache.commons.configuration2.io.FileLocationStrategy.schemes} String value must be a comma-separated list of schemes,
  * where the default is {@code "file,jar"}, and the complete list is {@code "file,http,https,jar"}.
  * </p>
  * <strong>Using a Builder</strong>
  * <p>
  * The root builder for {@link AbstractFileLocationStrategy} is {@link AbstractBuilder} where you define allowed schemes and hosts through its setter
  * methods.
  * </p>
  * <p>
  * For example, to programatically enable the shemes "file", "http", "https", and "jar" for all strategies, see {@link AbstractFileLocationStrategy}.
  * </p>
  *
  * @see java.util.Properties#load
  * @see AbstractFileLocationStrategy
  */
 public class PropertiesConfiguration extends BaseConfiguration implements FileBasedConfiguration, FileLocatorAware {
 
     /**
      * <p>
      * A default implementation of the {@code IOFactory} interface.
      * </p>
      * <p>
      * This class implements the {@code createXXXX()} methods defined by the {@code IOFactory} interface in a way that the
      * default objects (i.e. {@code PropertiesReader} and {@code PropertiesWriter} are returned. Customizing either the
      * reader or the writer (or both) can be done by extending this class and overriding the corresponding
      * {@code createXXXX()} method.
      * </p>
      *
      * @since 1.7
      */
     public static class DefaultIOFactory implements IOFactory {
 
         /**
          * The singleton instance.
          */
         static final DefaultIOFactory INSTANCE = new DefaultIOFactory();
 
         /**
          * Constructs a new instance.
          */
         public DefaultIOFactory() {
             // empty
         }
 
         @Override
         public PropertiesReader createPropertiesReader(final Reader in) {
             return new PropertiesReader(in);
         }
 
         @Override
         public PropertiesWriter createPropertiesWriter(final Writer out, final ListDelimiterHandler handler) {
             return new PropertiesWriter(out, handler);
         }
     }
 
     /**
      * <p>
      * Definition of an interface that allows customization of read and write operations.
      * </p>
      * <p>
      * For reading and writing properties files the inner classes {@code PropertiesReader} and {@code PropertiesWriter} are
      * used. This interface defines factory methods for creating both a {@code PropertiesReader} and a
      * {@code PropertiesWriter}. An object implementing this interface can be passed to the {@code setIOFactory()} method of
      * {@code PropertiesConfiguration}. Every time the configuration is read or written the {@code IOFactory} is asked to
      * create the appropriate reader or writer object. This provides an opportunity to inject custom reader or writer
      * implementations.
      * </p>
      *
      * @since 1.7
      */
     public interface IOFactory {
 
         /**
          * Creates a {@code PropertiesReader} for reading a properties file. This method is called whenever the
          * {@code PropertiesConfiguration} is loaded. The reader returned by this method is then used for parsing the properties
          * file.
          *
          * @param in the underlying reader (of the properties file)
          * @return the {@code PropertiesReader} for loading the configuration
          */
         PropertiesReader createPropertiesReader(Reader in);
 
         /**
          * Creates a {@code PropertiesWriter} for writing a properties file. This method is called before the
          * {@code PropertiesConfiguration} is saved. The writer returned by this method is then used for writing the properties
          * file.
          *
          * @param out the underlying writer (to the properties file)
          * @param handler the list delimiter delimiter for list parsing
          * @return the {@code PropertiesWriter} for saving the configuration
          */
         PropertiesWriter createPropertiesWriter(Writer out, ListDelimiterHandler handler);
     }
 
     /**
      * An alternative {@link IOFactory} that tries to mimic the behavior of {@link java.util.Properties} (Jup) more closely.
      * The goal is to allow both of them be used interchangeably when reading and writing properties files without losing or
      * changing information.
      * <p>
      * It also has the option to <em>not</em> use Unicode escapes. When using UTF-8 encoding (which is for example the new default
      * for resource bundle properties files since Java 9), Unicode escapes are no longer required and avoiding them makes
      * properties files more readable with regular text editors.
      * <p>
      * Some of the ways this implementation differs from {@link DefaultIOFactory}:
      * <ul>
      * <li>Trailing whitespace will not be trimmed from each line.</li>
      * <li>Unknown escape sequences will have their backslash removed.</li>
      * <li>{@code \b} is not a recognized escape sequence.</li>
      * <li>Leading spaces in property values are preserved by escaping them.</li>
      * <li>All natural lines (i.e. in the file) of a logical property line will have their leading whitespace trimmed.</li>
      * <li>Natural lines that look like comment lines within a logical line are not treated as such; they're part of the
      * property value.</li>
      * </ul>
      *
      * @since 2.4
      */
     public static class JupIOFactory implements IOFactory {
 
         /**
          * Whether characters less than {@code \u0020} and characters greater than {@code \u007E} in property keys or values
          * should be escaped using Unicode escape sequences. Not necessary when for example writing as UTF-8.
          */
         private final boolean escapeUnicode;
 
         /**
          * Constructs a new {@link JupIOFactory} with Unicode escaping.
          */
         public JupIOFactory() {
             this(true);
         }
 
         /**
          * Constructs a new {@link JupIOFactory} with optional Unicode escaping. Whether Unicode escaping is required depends on
          * the encoding used to save the properties file. E.g. for ISO-8859-1 this must be turned on, for UTF-8 it's not
          * necessary. Unfortunately this factory can't determine the encoding on its own.
          *
          * @param escapeUnicode whether Unicode characters should be escaped
          */
         public JupIOFactory(final boolean escapeUnicode) {
             this.escapeUnicode = escapeUnicode;
         }
 
         @Override
         public PropertiesReader createPropertiesReader(final Reader in) {
             return new JupPropertiesReader(in);
         }
 
         @Override
         public PropertiesWriter createPropertiesWriter(final Writer out, final ListDelimiterHandler handler) {
             return new JupPropertiesWriter(out, handler, escapeUnicode);
         }
 
     }
 
     /**
      * A {@link PropertiesReader} that tries to mimic the behavior of {@link java.util.Properties}.
      *
      * @since 2.4
      */
     public static class JupPropertiesReader extends PropertiesReader {
 
         /**
          * Constructs a new instance.
          *
          * @param reader A Reader.
          */
         public JupPropertiesReader(final Reader reader) {
             super(reader);
         }
 
         @Override
         protected void parseProperty(final String line) {
             final String[] property = doParseProperty(line, false);
             initPropertyName(property[0]);
             initPropertyValue(property[1]);
             initPropertySeparator(property[2]);
         }
 
         @Override
         public String readProperty() throws IOException {
             getCommentLines().clear();
             final StringBuilder buffer = new StringBuilder();
 
             while (true) {
                 String line = readLine();
                 if (line == null) {
                     // EOF
                     if (buffer.length() > 0) {
                         break;
                     }
                     return null;
                 }
 
                 // while a property line continues there are no comments (even if the line from
                 // the file looks like one)
                 if (isCommentLine(line) && buffer.length() == 0) {
                     getCommentLines().add(line);
                     continue;
                 }
 
                 // while property line continues left trim all following lines read from the
                 // file
                 if (buffer.length() > 0) {
                     // index of the first non-whitespace character
                     int i;
                     for (i = 0; i < line.length(); i++) {
                         if (!Character.isWhitespace(line.charAt(i))) {
                             break;
                         }
                     }
 
                     line = line.substring(i);
                 }
 
                 if (!checkCombineLines(line)) {
                     buffer.append(line);
                     break;
                 }
                 line = line.substring(0, line.length() - 1);
                 buffer.append(line);
             }
             return buffer.toString();
         }
 
         @Override
         protected String unescapePropertyValue(final String value) {
             return unescapeJava(value, true);
         }
 
     }
 
     /**
      * A {@link PropertiesWriter} that tries to mimic the behavior of {@link java.util.Properties}.
      *
      * @since 2.4
      */
     public static class JupPropertiesWriter extends PropertiesWriter {
 
         /**
          * The starting ASCII printable character.
          */
         private static final int PRINTABLE_INDEX_END = 0x7e;
 
         /**
          * The ending ASCII printable character.
          */
         private static final int PRINTABLE_INDEX_START = 0x20;
 
         /**
          * A UnicodeEscaper for characters outside the ASCII printable range.
          */
         private static final UnicodeEscaper ESCAPER = UnicodeEscaper.outsideOf(PRINTABLE_INDEX_START, PRINTABLE_INDEX_END);
 
         /**
          * Characters that need to be escaped when wring a properties file.
          */
         private static final Map<CharSequence, CharSequence> JUP_CHARS_ESCAPE;
         static {
             final Map<CharSequence, CharSequence> initialMap = new HashMap<>();
             initialMap.put("\\", "\\\\");
             initialMap.put("\n", "\\n");
             initialMap.put("\t", "\\t");
             initialMap.put("\f", "\\f");
             initialMap.put("\r", "\\r");
             JUP_CHARS_ESCAPE = Collections.unmodifiableMap(initialMap);
         }
 
         /**
          * Creates a new instance of {@code JupPropertiesWriter}.
          *
          * @param writer a Writer object providing the underlying stream
          * @param delHandler the delimiter handler for dealing with properties with multiple values
          * @param escapeUnicode whether Unicode characters should be escaped using Unicode escapes
          */
         public JupPropertiesWriter(final Writer writer, final ListDelimiterHandler delHandler, final boolean escapeUnicode) {
             super(writer, delHandler, value -> {
                 String valueString = String.valueOf(value);
 
                 final CharSequenceTranslator translator;
                 if (escapeUnicode) {
                     translator = new AggregateTranslator(new LookupTranslator(JUP_CHARS_ESCAPE), ESCAPER);
                 } else {
                     translator = new AggregateTranslator(new LookupTranslator(JUP_CHARS_ESCAPE));
                 }
 
                 valueString = translator.translate(valueString);
 
                 // escape the first leading space to preserve it (and all after it)
                 if (valueString.startsWith(" ")) {
                     valueString = "\\" + valueString;
                 }
 
                 return valueString;
             });
         }
 
     }
 
     /**
      * This class is used to read properties lines. These lines do not terminate with new-line chars but rather when there
      * is no backslash sign a the end of the line. This is used to concatenate multiple lines for readability.
      */
     public static class PropertiesReader extends LineNumberReader {
 
         /** The regular expression to parse the key and the value of a property. */
         private static final Pattern PROPERTY_PATTERN = Pattern
             .compile("(([\\S&&[^\\\\" + new String(SEPARATORS) + "]]|\\\\.)*+)(\\s*(\\s+|[" + new String(SEPARATORS) + "])\\s*)?(.*)");
 
         /** Constant for the index of the group for the key. */
         private static final int IDX_KEY = 1;
 
         /** Constant for the index of the group for the value. */
         private static final int IDX_VALUE = 5;
 
         /** Constant for the index of the group for the separator. */
         private static final int IDX_SEPARATOR = 3;
 
         /**
          * Checks if the passed in line should be combined with the following. This is true, if the line ends with an odd number
          * of backslashes.
          *
          * @param line the line
          * @return a flag if the lines should be combined
          */
         static boolean checkCombineLines(final String line) {
             return countTrailingBS(line) % 2 != 0;
         }
 
         /**
          * Parse a property line and return the key, the value, and the separator in an array.
          *
          * @param line the line to parse
          * @param trimValue flag whether the value is to be trimmed
          * @return an array with the property's key, value, and separator
          */
         static String[] doParseProperty(final String line, final boolean trimValue) {
             final Matcher matcher = PROPERTY_PATTERN.matcher(line);
 
             final String[] result = {"", "", ""};
 
             if (matcher.matches()) {
                 result[0] = matcher.group(IDX_KEY).trim();
 
                 String value = matcher.group(IDX_VALUE);
                 if (trimValue) {
                     value = value.trim();
                 }
                 result[1] = value;
 
                 result[2] = matcher.group(IDX_SEPARATOR);
             }
 
             return result;
         }
 
         /** Stores the comment lines for the currently processed property. */
         private final List<String> commentLines;
 
         /** Stores the name of the last read property. */
         private String propertyName;
 
         /** Stores the value of the last read property. */
         private String propertyValue;
 
         /** Stores the property separator of the last read property. */
         private String propertySeparator = DEFAULT_SEPARATOR;
 
         /**
          * Constructs a new instance.
          *
          * @param reader A Reader.
          */
         public PropertiesReader(final Reader reader) {
             super(reader);
             commentLines = new ArrayList<>();
         }
 
         /**
          * Gets the comment lines that have been read for the last property.
          *
          * @return the comment lines for the last property returned by {@code readProperty()}
          * @since 1.3
          */
         public List<String> getCommentLines() {
             return commentLines;
         }
 
         /**
          * Gets the name of the last read property. This method can be called after {@link #nextProperty()} was invoked and
          * its return value was <strong>true</strong>.
          *
          * @return the name of the last read property
          * @since 1.3
          */
         public String getPropertyName() {
             return propertyName;
         }
 
         /**
          * Gets the separator that was used for the last read property. The separator can be stored so that it can later be
          * restored when saving the configuration.
          *
          * @return the separator for the last read property
          * @since 1.7
          */
         public String getPropertySeparator() {
             return propertySeparator;
         }
 
         /**
          * Gets the value of the last read property. This method can be called after {@link #nextProperty()} was invoked and
          * its return value was <strong>true</strong>.
          *
          * @return the value of the last read property
          * @since 1.3
          */
         public String getPropertyValue() {
             return propertyValue;
         }
 
         /**
          * Sets the name of the current property. This method can be called by {@code parseProperty()} for storing the results
          * of the parse operation. It also ensures that the property key is correctly escaped.
          *
          * @param name the name of the current property
          * @since 1.7
          */
         protected void initPropertyName(final String name) {
             propertyName = unescapePropertyName(name);
         }
 
         /**
          * Sets the separator of the current property. This method can be called by {@code parseProperty()}. It allows the
          * associated layout object to keep track of the property separators. When saving the configuration the separators can
          * be restored.
          *
          * @param value the separator used for the current property
          * @since 1.7
          */
         protected void initPropertySeparator(final String value) {
             propertySeparator = value;
         }
 
         /**
          * Sets the value of the current property. This method can be called by {@code parseProperty()} for storing the results
          * of the parse operation. It also ensures that the property value is correctly escaped.
          *
          * @param value the value of the current property
          * @since 1.7
          */
         protected void initPropertyValue(final String value) {
             propertyValue = unescapePropertyValue(value);
         }
 
         /**
          * Parses the next property from the input stream and stores the found name and value in internal fields. These fields
          * can be obtained using the provided getter methods. The return value indicates whether EOF was reached (<strong>false</strong>)
          * or whether further properties are available (<strong>true</strong>).
          *
          * @return a flag if further properties are available
          * @throws IOException if an error occurs
          * @since 1.3
          */
         public boolean nextProperty() throws IOException {
             final String line = readProperty();
 
             if (line == null) {
                 return false; // EOF
             }
 
             // parse the line
             parseProperty(line);
             return true;
         }
 
         /**
          * Parses a line read from the properties file. This method is called for each non-comment line read from the source
          * file. Its task is to split the passed in line into the property key and its value. The results of the parse operation
          * can be stored by calling the {@code initPropertyXXX()} methods.
          *
          * @param line the line read from the properties file
          * @since 1.7
          */
         protected void parseProperty(final String line) {
             final String[] property = doParseProperty(line, true);
             initPropertyName(property[0]);
             initPropertyValue(property[1]);
             initPropertySeparator(property[2]);
         }
 
         /**
          * Reads a property line. Returns null if Stream is at EOF. Concatenates lines ending with "\". Skips lines beginning
          * with "#" or "!" and empty lines. The return value is a property definition ({@code &lt;name&gt;} =
          * {@code &lt;value&gt;})
          *
          * @return A string containing a property value or null
          * @throws IOException in case of an I/O error
          */
         public String readProperty() throws IOException {
             commentLines.clear();
             final StringBuilder buffer = new StringBuilder();
 
             while (true) {
                 String line = readLine();
                 if (line == null) {
                     // EOF
                     return null;
                 }
 
                 if (isCommentLine(line)) {
                     commentLines.add(line);
                     continue;
                 }
 
                 line = line.trim();
 
                 if (!checkCombineLines(line)) {
                     buffer.append(line);
                     break;
                 }
                 line = line.substring(0, line.length() - 1);
                 buffer.append(line);
             }
             return buffer.toString();
         }
 
         /**
          * Performs unescaping on the given property name.
          *
          * @param name the property name
          * @return the unescaped property name
          * @since 2.4
          */
         protected String unescapePropertyName(final String name) {
             return StringEscapeUtils.unescapeJava(name);
         }
 
         /**
          * Performs unescaping on the given property value.
          *
          * @param value the property value
          * @return the unescaped property value
          * @since 2.4
          */
         protected String unescapePropertyValue(final String value) {
             return unescapeJava(value);
         }
     } // class PropertiesReader
 
     /**
      * This class is used to write properties lines. The most important method is
      * {@code writeProperty(String, Object, boolean)}, which is called during a save operation for each property found in
      * the configuration.
      */
     public static class PropertiesWriter extends FilterWriter {
 
         /**
          * Properties escape map.
          */
         private static final Map<CharSequence, CharSequence> PROPERTIES_CHARS_ESCAPE;
         static {
             final Map<CharSequence, CharSequence> initialMap = new HashMap<>();
             initialMap.put("\\", "\\\\");
             PROPERTIES_CHARS_ESCAPE = Collections.unmodifiableMap(initialMap);
         }
 
         /**
          * A translator for escaping property values. This translator performs a subset of transformations done by the
          * ESCAPE_JAVA translator from Commons Lang 3.
          */
         private static final CharSequenceTranslator ESCAPE_PROPERTIES = new AggregateTranslator(new LookupTranslator(PROPERTIES_CHARS_ESCAPE),
             new LookupTranslator(EntityArrays.JAVA_CTRL_CHARS_ESCAPE), UnicodeEscaper.outsideOf(32, 0x7f));
 
         /**
          * A {@code ValueTransformer} implementation used to escape property values. This implementation applies the
          * transformation defined by the {@link #ESCAPE_PROPERTIES} translator.
          */
         private static final ValueTransformer DEFAULT_TRANSFORMER = value -> {
             final String strVal = String.valueOf(value);
             return ESCAPE_PROPERTIES.translate(strVal);
         };
 
         /** The value transformer used for escaping property values. */
         private final ValueTransformer valueTransformer;
 
         /** The list delimiter handler. */
         private final ListDelimiterHandler delimiterHandler;
 
         /** The separator to be used for the current property. */
         private String currentSeparator;
 
         /** The global separator. If set, it overrides the current separator. */
         private String globalSeparator;
 
         /** The line separator. */
         private String lineSeparator;
 
         /**
          * Creates a new instance of {@code PropertiesWriter}.
          *
          * @param writer a Writer object providing the underlying stream
          * @param delHandler the delimiter handler for dealing with properties with multiple values
          */
         public PropertiesWriter(final Writer writer, final ListDelimiterHandler delHandler) {
             this(writer, delHandler, DEFAULT_TRANSFORMER);
         }
 
         /**
          * Creates a new instance of {@code PropertiesWriter}.
          *
          * @param writer a Writer object providing the underlying stream
          * @param delHandler the delimiter handler for dealing with properties with multiple values
          * @param valueTransformer the value transformer used to escape property values
          */
         public PropertiesWriter(final Writer writer, final ListDelimiterHandler delHandler, final ValueTransformer valueTransformer) {
             super(writer);
             delimiterHandler = delHandler;
             this.valueTransformer = valueTransformer;
         }
 
         /**
          * Escapes the key of a property before it gets written to file. This method is called on saving a configuration for
          * each property key. It ensures that separator characters contained in the key are escaped.
          *
          * @param key the key
          * @return the escaped key
          * @since 2.0
          */
         protected String escapeKey(final String key) {
             final StringBuilder newkey = new StringBuilder();
 
             for (int i = 0; i < key.length(); i++) {
                 final char c = key.charAt(i);
 
                 if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c) || c == '\\') {
                     // escape the separator
                     newkey.append('\\');
                 }
                 newkey.append(c);
             }
 
             return newkey.toString();
         }
 
         /**
          * Returns the separator to be used for the given property. This method is called by {@code writeProperty()}. The string
          * returned here is used as separator between the property key and its value. Per default the method checks whether a
          * global separator is set. If this is the case, it is returned. Otherwise the separator returned by
          * {@code getCurrentSeparator()} is used, which was set by the associated layout object. Derived classes may implement a
          * different strategy for defining the separator.
          *
          * @param key the property key
          * @param value the value
          * @return the separator to be used
          * @since 1.7
          */
         protected String fetchSeparator(final String key, final Object value) {
             return getGlobalSeparator() != null ? getGlobalSeparator() : StringUtils.defaultString(getCurrentSeparator());
         }
 
         /**
          * Gets the current property separator.
          *
          * @return the current property separator
          * @since 1.7
          */
         public String getCurrentSeparator() {
             return currentSeparator;
         }
 
         /**
          * Gets the delimiter handler for properties with multiple values. This object is used to escape property values so
          * that they can be read in correctly the next time they are loaded.
          *
          * @return the delimiter handler for properties with multiple values
          * @since 2.0
          */
         public ListDelimiterHandler getDelimiterHandler() {
             return delimiterHandler;
         }
 
         /**
          * Gets the global property separator.
          *
          * @return the global property separator
          * @since 1.7
          */
         public String getGlobalSeparator() {
             return globalSeparator;
         }
 
         /**
          * Gets the line separator.
          *
          * @return the line separator
          * @since 1.7
          */
         public String getLineSeparator() {
             return lineSeparator != null ? lineSeparator : LINE_SEPARATOR;
         }
 
         /**
          * Sets the current property separator. This separator is used when writing the next property.
          *
          * @param currentSeparator the current property separator
          * @since 1.7
          */
         public void setCurrentSeparator(final String currentSeparator) {
             this.currentSeparator = currentSeparator;
         }
 
         /**
          * Sets the global property separator. This separator corresponds to the {@code globalSeparator} property of
          * {@link PropertiesConfigurationLayout}. It defines the separator to be used for all properties. If it is undefined,
          * the current separator is used.
          *
          * @param globalSeparator the global property separator
          * @since 1.7
          */
         public void setGlobalSeparator(final String globalSeparator) {
             this.globalSeparator = globalSeparator;
         }
 
         /**
          * Sets the line separator. Each line written by this writer is terminated with this separator. If not set, the
          * platform-specific line separator is used.
          *
          * @param lineSeparator the line separator to be used
          * @since 1.7
          */
         public void setLineSeparator(final String lineSeparator) {
             this.lineSeparator = lineSeparator;
         }
 
         /**
          * Writes a comment.
          *
          * @param comment the comment to write
          * @throws IOException if an I/O error occurs.
          */
         public void writeComment(final String comment) throws IOException {
             writeln("# " + comment);
         }
 
         /**
          * Helper method for writing a line with the platform specific line ending.
          *
          * @param s the content of the line (may be <strong>null</strong>)
          * @throws IOException if an error occurs
          * @since 1.3
          */
         public void writeln(final String s) throws IOException {
             if (s != null) {
                 write(s);
             }
             write(getLineSeparator());
         }
 
         /**
          * Writes a property.
          *
          * @param key The key of the property
          * @param values The array of values of the property
          * @throws IOException if an I/O error occurs.
          */
         public void writeProperty(final String key, final List<?> values) throws IOException {
             for (final Object value : values) {
                 writeProperty(key, value);
             }
         }
 
         /**
          * Writes a property.
          *
          * @param key the key of the property
          * @param value the value of the property
          * @throws IOException if an I/O error occurs.
          */
         public void writeProperty(final String key, final Object value) throws IOException {
             writeProperty(key, value, false);
         }
 
         /**
          * Writes the given property and its value. If the value happens to be a list, the {@code forceSingleLine} flag is
          * evaluated. If it is set, all values are written on a single line using the list delimiter as separator.
          *
          * @param key the property key
          * @param value the property value
          * @param forceSingleLine the &quot;force single line&quot; flag
          * @throws IOException if an error occurs
          * @since 1.3
          */
         public void writeProperty(final String key, final Object value, final boolean forceSingleLine) throws IOException {
             String v;
 
             if (value instanceof List) {
                 v = null;
                 final List<?> values = (List<?>) value;
                 if (forceSingleLine) {
                     try {
                         v = String.valueOf(getDelimiterHandler().escapeList(values, valueTransformer));
                     } catch (final UnsupportedOperationException ignored) {
                         // the handler may not support escaping lists,
                         // then the list is written in multiple lines
                     }
                 }
                 if (v == null) {
                     writeProperty(key, values);
                     return;
                 }
             } else {
                 v = String.valueOf(getDelimiterHandler().escape(value, valueTransformer));
             }
 
             write(escapeKey(key));
             write(fetchSeparator(key, value));
             write(v);
 
             writeln(null);
         }
     } // class PropertiesWriter
 
     /**
      * 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;
     };
 
     /**
      * 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 */ };
 
     /**
      * The default encoding (ISO-8859-1 as specified by https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html)
      */
     public static final String DEFAULT_ENCODING = StandardCharsets.ISO_8859_1.name();
 
     /** Constant for the supported comment characters. */
     static final String COMMENT_CHARS = "#!";
 
     /** Constant for the default properties separator. */
     static final String DEFAULT_SEPARATOR = " = ";
 
     /**
      * A string with special characters that need to be unescaped when reading a properties file.
      * {@link java.util.Properties} escapes these characters when writing out a properties file.
      */
     private static final String UNESCAPE_CHARACTERS = ":#=!\\\'\"";
 
     /**
      * This is the name of the property that can point to other properties file for including other properties files.
      */
     private static String include = "include";
 
     /**
      * This is the name of the property that can point to other properties file for including other properties files.
      * <p>
      * If the file is absent, processing continues normally.
      * </p>
      */
     private static String includeOptional = "includeoptional";
 
     /** The list of possible key/value separators */
     private static final char[] SEPARATORS = {'=', ':'};
 
     /** The white space characters used as key/value separators. */
     private static final char[] WHITE_SPACE = {' ', '\t', '\f'};
 
     /** Constant for the platform specific line separator. */
     private static final String LINE_SEPARATOR = System.lineSeparator();
 
     /** Constant for the radix of hex numbers. */
     private static final int HEX_RADIX = 16;
 
     /** Constant for the length of a unicode literal. */
     private static final int UNICODE_LEN = 4;
 
     /**
      * Returns the number of trailing backslashes. This is sometimes needed for the correct handling of escape characters.
      *
      * @param line the string to investigate
      * @return the number of trailing backslashes
      */
     private static int countTrailingBS(final String line) {
         int bsCount = 0;
         for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '\\'; idx--) {
             bsCount++;
         }
 
         return bsCount;
     }
 
     /**
      * Gets the property value for including other properties files. By default it is "include".
      *
      * @return A String.
      */
     public static String getInclude() {
         return include;
     }
 
     /**
      * Gets the property value for including other properties files. By default it is "includeoptional".
      * <p>
      * If the file is absent, processing continues normally.
      * </p>
      *
      * @return A String.
      * @since 2.5
      */
     public static String getIncludeOptional() {
         return includeOptional;
     }
 
     /**
      * Tests whether a line is a comment, i.e. whether it starts with a comment character.
      *
      * @param line the line
      * @return a flag if this is a comment line
      * @since 1.3
      */
     static boolean isCommentLine(final String line) {
         final String s = line.trim();
         // blank lines are also treated as comment lines
         return s.isEmpty() || COMMENT_CHARS.indexOf(s.charAt(0)) >= 0;
     }
 
     /**
      * Checks whether the specified character needs to be unescaped. This method is called when during reading a property
      * file an escape character ('\') is detected. If the character following the escape character is recognized as a
      * special character which is escaped per default in a Java properties file, it has to be unescaped.
      *
      * @param ch the character in question
      * @return a flag whether this character has to be unescaped
      */
     private static boolean needsUnescape(final char ch) {
         return UNESCAPE_CHARACTERS.indexOf(ch) >= 0;
     }
 
     /**
      * Sets the property value for including other properties files. By default it is "include".
      *
      * @param inc A String.
      */
     public static void setInclude(final String inc) {
         include = inc;
     }
 
     /**
      * Sets the property value for including other properties files. By default it is "include".
      * <p>
      * If the file is absent, processing continues normally.
      * </p>
      *
      * @param inc A String.
      * @since 2.5
      */
     public static void setIncludeOptional(final String inc) {
         includeOptional = inc;
     }
 
     /**
      * <p>
      * Unescapes any Java literals found in the {@code String} to a {@code Writer}.
      * </p>
      * This is a slightly modified version of the StringEscapeUtils.unescapeJava() function in commons-lang that doesn't
      * drop escaped separators (i.e '\,').
      *
      * @param str the {@code String} to unescape, may be null
      * @return the processed string
      * @throws IllegalArgumentException if the Writer is {@code null}
      */
     protected static String unescapeJava(final String str) {
         return unescapeJava(str, false);
     }
 
     /**
      * Unescapes Java literals found in the {@code String} to a {@code Writer}.
      * <p>
      * When the parameter {@code jupCompatible} is {@code false}, the classic behavior is used (see
      * {@link #unescapeJava(String)}). When it's {@code true} a slightly different behavior that's compatible with
      * {@link java.util.Properties} is used (see {@link JupIOFactory}).
      * </p>
      *
      * @param str the {@code String} to unescape, may be null
      * @param jupCompatible whether unescaping is compatible with {@link java.util.Properties}; otherwise the classic
      *        behavior is used
      * @return the processed string
      * @throws IllegalArgumentException if the Writer is {@code null}
      */
     protected static String unescapeJava(final String str, final boolean jupCompatible) {
         if (str == null) {
             return null;
         }
         final int sz = str.length();
         final StringBuilder out = new StringBuilder(sz);
         final StringBuilder unicode = new StringBuilder(UNICODE_LEN);
         boolean hadSlash = false;
         boolean inUnicode = false;
         for (int i = 0; i < sz; i++) {
             final char ch = str.charAt(i);
             if (inUnicode) {
                 // if in unicode, then we're reading unicode
                 // values in somehow
                 unicode.append(ch);
                 if (unicode.length() == UNICODE_LEN) {
                     // unicode now contains the four hex digits
                     // which represents our unicode character
                     try {
                         final int value = Integer.parseInt(unicode.toString(), HEX_RADIX);
                         out.append((char) value);
                         unicode.setLength(0);
                         inUnicode = false;
                         hadSlash = false;
                     } catch (final NumberFormatException e) {
                         throw new ConfigurationRuntimeException(e, "Unable to parse unicode value: %s", unicode);
                     }
                 }
                 continue;
             }
 
             if (hadSlash) {
                 // handle an escaped value
                 hadSlash = false;
 
                 switch (ch) {
                 case 'r':
                     out.append('\r');
                     break;
                 case 'f':
                     out.append('\f');
                     break;
                 case 't':
                     out.append('\t');
                     break;
                 case 'n':
                     out.append('\n');
                     break;
                 default:
                     if (!jupCompatible && ch == 'b') {
                         out.append('\b');
                     } else if (ch == 'u') {
                         // uh-oh, we're in unicode country....
                         inUnicode = true;
                     } else {
                         // JUP simply throws away the \ of unknown escape sequences
                         if (!needsUnescape(ch) && !jupCompatible) {
                             out.append('\\');
                         }
                         out.append(ch);
                     }
                     break;
                 }
 
                 continue;
             }
             if (ch == '\\') {
                 hadSlash = true;
                 continue;
             }
             out.append(ch);
         }
 
         if (hadSlash) {
             // then we're in the weird case of a \ at the end of the
             // string, let's output it anyway.
             out.append('\\');
         }
 
         return out.toString();
     }
 
     /** Stores the layout object. */
     private PropertiesConfigurationLayout layout;
 
     /** The include listener for the special {@code "include"} key. */
     private ConfigurationConsumer<ConfigurationException> includeListener;
 
     /** The IOFactory for creating readers and writers. */
     private IOFactory ioFactory;
 
     /** The current {@code FileLocator}. */
     private FileLocator locator;
 
     /** Allow file inclusion or not */
     private boolean includesAllowed = true;
 
     /**
      * Creates an empty PropertyConfiguration object which can be used to synthesize a new Properties file by adding values
      * and then saving().
      */
     public PropertiesConfiguration() {
         installLayout(createLayout());
     }
 
     /**
      * Creates a copy of this object.
      *
      * @return the copy
      */
     @Override
     public Object clone() {
         final PropertiesConfiguration copy = (PropertiesConfiguration) super.clone();
         if (layout != null) {
             copy.setLayout(new PropertiesConfigurationLayout(layout));
         }
         return copy;
     }
 
     /**
      * Creates a standard layout object. This configuration is initialized with such a standard layout.
      *
      * @return the newly created layout object
      */
     private PropertiesConfigurationLayout createLayout() {
         return new PropertiesConfigurationLayout();
     }
 
     /**
      * Gets the footer comment. This is a comment at the very end of the file.
      *
      * @return the footer comment
      * @since 2.0
      */
     public String getFooter() {
         return syncRead(() -> getLayout().getFooterComment(), false);
     }
 
     /**
      * Gets the comment header.
      *
      * @return the comment header
      * @since 1.1
      */
     public String getHeader() {
         return syncRead(() -> getLayout().getHeaderComment(), false);
     }
 
     /**
      * Gets the current include listener, never null.
      *
      * @return the current include listener, never null.
      * @since 2.6
      */
     public ConfigurationConsumer<ConfigurationException> getIncludeListener() {
         return includeListener != null ? includeListener : DEFAULT_INCLUDE_LISTENER;
     }
 
     /**
      * Gets the {@code IOFactory} to be used for creating readers and writers when loading or saving this configuration.
      *
      * @return the {@code IOFactory}
      * @since 1.7
      */
     public IOFactory getIOFactory() {
         return ioFactory != null ? ioFactory : DefaultIOFactory.INSTANCE;
     }
 
     /**
      * Gets the associated layout object.
      *
      * @return the associated layout object
      * @since 1.3
      */
     public PropertiesConfigurationLayout getLayout() {
         return layout;
     }
 
     /**
      * Gets the file locator.
      *
      * @return the file locator.
      * @since 2.15.0
      */
     public FileLocator getLocator() {
         return locator;
     }
 
     /**
      * Sets the current {@code FileLocator} for a following IO operation. The {@code FileLocator} is needed to resolve
      * include files with relative file names.
      *
      * @param locator the current {@code FileLocator}
      * @since 2.0
      */
     @Override
     public void initFileLocator(final FileLocator locator) {
         this.locator = locator;
     }
 
     /**
      * Installs a layout object. It has to be ensured that the layout is registered as change listener at this
      * configuration. If there is already a layout object installed, it has to be removed properly.
      *
      * @param layout the layout object to be installed
      */
     private void installLayout(final PropertiesConfigurationLayout layout) {
         // only one layout must exist
         if (this.layout != null) {
             removeEventListener(ConfigurationEvent.ANY, this.layout);
         }
 
         if (layout == null) {
             this.layout = createLayout();
         } else {
             this.layout = layout;
         }
         addEventListener(ConfigurationEvent.ANY, this.layout);
     }
 
     /**
      * Reports the status of file inclusion.
      *
      * @return True if include files are loaded.
      */
     public boolean isIncludesAllowed() {
         return this.includesAllowed;
     }
 
     /**
      * Loads an included properties file. This method is called by {@code load()} when an
      * {@code include} property is encountered. It tries to resolve relative file names based on the current base path. If
      * this fails, a resolution based on the location of this properties file is tried.
      *
      * @param fileName the name of the file to load
      * @param optional whether or not the {@code fileName} is optional
      * @param seenStack Stack of seen include URLs
      * @throws ConfigurationException if loading fails
      */
     private void loadIncludeFile(final String fileName, final boolean optional, final Deque<URL> seenStack) throws ConfigurationException {
         if (locator == null) {
             throw new ConfigurationException(
                     "Load operation not properly initialized. Do not call read(InputStream) directly, use a FileHandler to load a configuration.");
         }
         URL url = null;
         try {
             url = locateIncludeFile(locator.getBasePath(), fileName);
             if (url == null) {
                 final URL baseURL = locator.getSourceURL();
                 if (baseURL != null) {
                     url = locateIncludeFile(baseURL.toString(), fileName);
                 }
             }
         } catch (final ConfigurationDeniedException e) {
             getIncludeListener().accept(new ConfigurationException(e));
         }
         if (optional && url == null) {
             return;
         }
         if (url == null) {
             getIncludeListener().accept(new ConfigurationException(new FileNotFoundException(fileName), "Cannot resolve include file %s", fileName));
         } else {
             final FileHandler fh = new FileHandler(this);
             fh.setFileLocator(locator);
             final FileLocator orgLocator = locator;
             try {
                 try {
                     // Check for cycles
                     if (seenStack.contains(url)) {
                         throw new ConfigurationException("Cycle detected loading %s, seen stack: %s", url, seenStack);
                     }
                     seenStack.add(url);
                     try {
                         fh.load(url);
                     } finally {
                         seenStack.pop();
                     }
                 } catch (final ConfigurationException e) {
                     getIncludeListener().accept(e);
                 }
             } finally {
                 locator = orgLocator; // reset locator which is changed by load
             }
         }
     }
 
     /**
      * Locates the URL of an include file using the specified (optional) base path and file name.
      *
      * @param basePath the base path
      * @param fileName the file name
      * @return the URL of the include file or <strong>null</strong> if it cannot be resolved
      */
     private URL locateIncludeFile(final String basePath, final String fileName) {
         final FileLocator includeLocator = FileLocatorUtils.fileLocator(locator).sourceURL(null).basePath(basePath).fileName(fileName).create();
         return FileLocatorUtils.locate(includeLocator);
     }
 
     /**
      * This method is invoked by the associated {@link PropertiesConfigurationLayout} object for each property definition
      * detected in the parsed properties file. Its task is to check whether this is a special property definition (for example the
      * {@code include} property). If not, the property must be added to this configuration. The return value indicates
      * whether the property should be treated as a normal property. If it is <strong>false</strong>, the layout object will ignore
      * this property.
      *
      * @param key the property key
      * @param value the property value
      * @param seenStack the stack of seen include URLs
      * @return a flag whether this is a normal property
      * @throws ConfigurationException if an error occurs
      * @since 1.3
      */
     boolean propertyLoaded(final String key, final String value, final Deque<URL> seenStack) throws ConfigurationException {
         final boolean result;
 
         if (StringUtils.isNotEmpty(getInclude()) && key.equalsIgnoreCase(getInclude())) {
             if (isIncludesAllowed()) {
                 final Collection<String> files = getListDelimiterHandler().split(value, true);
                 for (final String f : files) {
                     loadIncludeFile(interpolate(f), false, seenStack);
                 }
             }
             result = false;
         } else if (StringUtils.isNotEmpty(getIncludeOptional()) && key.equalsIgnoreCase(getIncludeOptional())) {
             if (isIncludesAllowed()) {
                 final Collection<String> files = getListDelimiterHandler().split(value, true);
                 for (final String f : files) {
                     loadIncludeFile(interpolate(f), true, seenStack);
                 }
             }
             result = false;
         } else {
             addPropertyInternal(key, value);
             result = true;
         }
 
         return result;
     }
 
     /**
      * {@inheritDoc} This implementation delegates to the associated layout object which does the actual loading. Note that
      * this method does not do any synchronization. This lies in the responsibility of the caller. (Typically, the caller is
      * a {@code FileHandler} object which takes care for proper synchronization.)
      *
      * @since 2.0
      */
     @Override
     public void read(final Reader in) throws ConfigurationException, IOException {
         getLayout().load(this, in);
     }
 
     /**
      * Sets the footer comment. If set, this comment is written after all properties at the end of the file.
      *
      * @param footer the footer comment
      * @since 2.0
      */
     public void setFooter(final String footer) {
         syncWrite(() -> getLayout().setFooterComment(footer), false);
     }
 
     /**
      * Sets the comment header.
      *
      * @param header the header to use
      * @since 1.1
      */
     public void setHeader(final String header) {
         syncWrite(() -> getLayout().setHeaderComment(header), false);
     }
 
     /**
      * Sets the current include listener, may not be null.
      *
      * @param includeListener the current include listener, may not be null.
      * @throws IllegalArgumentException if the {@code includeListener} is null.
      * @since 2.6
      */
     public void setIncludeListener(final ConfigurationConsumer<ConfigurationException> includeListener) {
         if (includeListener == null) {
             throw new IllegalArgumentException("includeListener must not be null.");
         }
         this.includeListener = includeListener;
     }
 
     /**
      * Controls whether additional files can be loaded by the {@code include = <xxx>} statement or not. This is <strong>true</strong>
      * per default.
      *
      * @param includesAllowed True if Includes are allowed.
      */
     public void setIncludesAllowed(final boolean includesAllowed) {
         this.includesAllowed = includesAllowed;
     }
 
     /**
      * Sets the {@code IOFactory} to be used for creating readers and writers when loading or saving this configuration.
      * Using this method a client can customize the reader and writer classes used by the load and save operations. Note
      * that this method must be called before invoking one of the {@code load()} and {@code save()} methods. Especially, if
      * you want to use a custom {@code IOFactory} for changing the {@code PropertiesReader}, you cannot load the
      * configuration data in the constructor.
      *
      * @param ioFactory the new {@code IOFactory} (must not be <strong>null</strong>)
      * @throws IllegalArgumentException if the {@code IOFactory} is <strong>null</strong>
      * @since 1.7
      */
     public void setIOFactory(final IOFactory ioFactory) {
         if (ioFactory == null) {
             throw new IllegalArgumentException("IOFactory must not be null.");
         }
 
         this.ioFactory = ioFactory;
     }
 
     /**
      * Sets the associated layout object.
      *
      * @param layout the new layout object; can be <strong>null</strong>, then a new layout object will be created
      * @since 1.3
      */
     public void setLayout(final PropertiesConfigurationLayout layout) {
         installLayout(layout);
     }
 
     /**
      * {@inheritDoc} This implementation delegates to the associated layout object which does the actual saving. Note that,
      * analogous to {@link #read(Reader)}, this method does not do any synchronization.
      *
      * @since 2.0
      */
     @Override
     public void write(final Writer out) throws ConfigurationException, IOException {
         getLayout().save(this, out);
     }
 
 }