001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.configuration2;
019
020import java.io.FilterWriter;
021import java.io.IOException;
022import java.io.LineNumberReader;
023import java.io.Reader;
024import java.io.Writer;
025import java.net.URL;
026import java.util.ArrayList;
027import java.util.Collection;
028import java.util.Collections;
029import java.util.HashMap;
030import java.util.List;
031import java.util.Map;
032import java.util.regex.Matcher;
033import java.util.regex.Pattern;
034
035import org.apache.commons.configuration2.convert.ListDelimiterHandler;
036import org.apache.commons.configuration2.convert.ValueTransformer;
037import org.apache.commons.configuration2.event.ConfigurationEvent;
038import org.apache.commons.configuration2.ex.ConfigurationException;
039import org.apache.commons.configuration2.ex.ConfigurationRuntimeException;
040import org.apache.commons.configuration2.io.FileHandler;
041import org.apache.commons.configuration2.io.FileLocator;
042import org.apache.commons.configuration2.io.FileLocatorAware;
043import org.apache.commons.configuration2.io.FileLocatorUtils;
044import org.apache.commons.lang3.ArrayUtils;
045import org.apache.commons.lang3.StringUtils;
046import org.apache.commons.text.StringEscapeUtils;
047import org.apache.commons.text.translate.AggregateTranslator;
048import org.apache.commons.text.translate.CharSequenceTranslator;
049import org.apache.commons.text.translate.EntityArrays;
050import org.apache.commons.text.translate.LookupTranslator;
051import org.apache.commons.text.translate.UnicodeEscaper;
052
053/**
054 * This is the "classic" Properties loader which loads the values from
055 * a single or multiple files (which can be chained with "include =".
056 * All given path references are either absolute or relative to the
057 * file name supplied in the constructor.
058 * <p>
059 * In this class, empty PropertyConfigurations can be built, properties
060 * added and later saved. include statements are (obviously) not supported
061 * if you don't construct a PropertyConfiguration from a file.
062 *
063 * <p>The properties file syntax is explained here, basically it follows
064 * the syntax of the stream parsed by {@link java.util.Properties#load} and
065 * adds several useful extensions:
066 *
067 * <ul>
068 *  <li>
069 *   Each property has the syntax <code>key &lt;separator&gt; value</code>. The
070 *   separators accepted are {@code '='}, {@code ':'} and any white
071 *   space character. Examples:
072 * <pre>
073 *  key1 = value1
074 *  key2 : value2
075 *  key3   value3</pre>
076 *  </li>
077 *  <li>
078 *   The <i>key</i> may use any character, separators must be escaped:
079 * <pre>
080 *  key\:foo = bar</pre>
081 *  </li>
082 *  <li>
083 *   <i>value</i> may be separated on different lines if a backslash
084 *   is placed at the end of the line that continues below.
085 *  </li>
086 *  <li>
087 *   The list delimiter facilities provided by {@link AbstractConfiguration}
088 *   are supported, too. If an appropriate {@link ListDelimiterHandler} is
089 *   set (for instance
090 *   a {@link org.apache.commons.configuration2.convert.DefaultListDelimiterHandler D
091 *   efaultListDelimiterHandler} object configured
092 *   with a comma as delimiter character), <i>value</i> can contain <em>value
093 *   delimiters</em> and will then be interpreted as a list of tokens. So the
094 *   following property definition
095 * <pre>
096 *  key = This property, has multiple, values
097 * </pre>
098 *   will result in a property with three values. You can change the handling
099 *   of delimiters using the
100 *   {@link AbstractConfiguration#setListDelimiterHandler(ListDelimiterHandler)}
101 *   method. Per default, list splitting is disabled.
102 *  </li>
103 *  <li>
104 *   Commas in each token are escaped placing a backslash right before
105 *   the comma.
106 *  </li>
107 *  <li>
108 *   If a <i>key</i> is used more than once, the values are appended
109 *   like if they were on the same line separated with commas. <em>Note</em>:
110 *   When the configuration file is written back to disk the associated
111 *   {@link PropertiesConfigurationLayout} object (see below) will
112 *   try to preserve as much of the original format as possible, i.e. properties
113 *   with multiple values defined on a single line will also be written back on
114 *   a single line, and multiple occurrences of a single key will be written on
115 *   multiple lines. If the {@code addProperty()} method was called
116 *   multiple times for adding multiple values to a property, these properties
117 *   will per default be written on multiple lines in the output file, too.
118 *   Some options of the {@code PropertiesConfigurationLayout} class have
119 *   influence on that behavior.
120 *  </li>
121 *  <li>
122 *   Blank lines and lines starting with character '#' or '!' are skipped.
123 *  </li>
124 *  <li>
125 *   If a property is named "include" (or whatever is defined by
126 *   setInclude() and getInclude() and the value of that property is
127 *   the full path to a file on disk, that file will be included into
128 *   the configuration. You can also pull in files relative to the parent
129 *   configuration file. So if you have something like the following:
130 *
131 *   include = additional.properties
132 *
133 *   Then "additional.properties" is expected to be in the same
134 *   directory as the parent configuration file.
135 *
136 *   The properties in the included file are added to the parent configuration,
137 *   they do not replace existing properties with the same key.
138 *
139 *  </li>
140 * </ul>
141 *
142 * <p>Here is an example of a valid extended properties file:</p>
143 *
144 * <pre>
145 *      # lines starting with # are comments
146 *
147 *      # This is the simplest property
148 *      key = value
149 *
150 *      # A long property may be separated on multiple lines
151 *      longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
152 *                  aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
153 *
154 *      # This is a property with many tokens
155 *      tokens_on_a_line = first token, second token
156 *
157 *      # This sequence generates exactly the same result
158 *      tokens_on_multiple_lines = first token
159 *      tokens_on_multiple_lines = second token
160 *
161 *      # commas may be escaped in tokens
162 *      commas.escaped = Hi\, what'up?
163 *
164 *      # properties can reference other properties
165 *      base.prop = /base
166 *      first.prop = ${base.prop}/first
167 *      second.prop = ${first.prop}/second
168 * </pre>
169 *
170 * <p>A {@code PropertiesConfiguration} object is associated with an
171 * instance of the {@link PropertiesConfigurationLayout} class,
172 * which is responsible for storing the layout of the parsed properties file
173 * (i.e. empty lines, comments, and such things). The {@code getLayout()}
174 * method can be used to obtain this layout object. With {@code setLayout()}
175 * a new layout object can be set. This should be done before a properties file
176 * was loaded.
177 * <p>Like other {@code Configuration} implementations, this class uses a
178 * {@code Synchronizer} object to control concurrent access. By choosing a
179 * suitable implementation of the {@code Synchronizer} interface, an instance
180 * can be made thread-safe or not. Note that access to most of the properties
181 * typically set through a builder is not protected by the {@code Synchronizer}.
182 * The intended usage is that these properties are set once at construction
183 * time through the builder and after that remain constant. If you wish to
184 * change such properties during life time of an instance, you have to use
185 * the {@code lock()} and {@code unlock()} methods manually to ensure that
186 * other threads see your changes.
187 * <p>As this class extends {@link AbstractConfiguration}, all basic features
188 * like variable interpolation, list handling, or data type conversions are
189 * available as well. This is described in the chapter
190 * <a href="http://commons.apache.org/proper/commons-configuration/userguide/howto_basicfeatures.html">
191 * Basic features and AbstractConfiguration</a> of the user's guide. There is
192 * also a separate chapter dealing with
193 * <a href="commons.apache.org/proper/commons-configuration/userguide/howto_properties.html">
194 * Properties files</a> in special.
195 *
196 * @see java.util.Properties#load
197 *
198 * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
199 * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
200 * @author <a href="mailto:daveb@miceda-data">Dave Bryson</a>
201 * @author <a href="mailto:geirm@optonline.net">Geir Magnusson Jr.</a>
202 * @author <a href="mailto:leon@opticode.co.za">Leon Messerschmidt</a>
203 * @author <a href="mailto:kjohnson@transparent.com">Kent Johnson</a>
204 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
205 * @author <a href="mailto:ipriha@surfeu.fi">Ilkka Priha</a>
206 * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
207 * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
208 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
209 * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a>
210 * @author <a href="mailto:ebourg@apache.org">Emmanuel Bourg</a>
211 */
212public class PropertiesConfiguration extends BaseConfiguration
213    implements FileBasedConfiguration, FileLocatorAware
214{
215    /**
216     * The default encoding (ISO-8859-1 as specified by
217     * http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html)
218     */
219    public static final String DEFAULT_ENCODING = "ISO-8859-1";
220
221    /** Constant for the supported comment characters.*/
222    static final String COMMENT_CHARS = "#!";
223
224    /** Constant for the default properties separator.*/
225    static final String DEFAULT_SEPARATOR = " = ";
226
227    /**
228     * Constant for the default {@code IOFactory}. This instance is used
229     * when no specific factory was set.
230     */
231    private static final IOFactory DEFAULT_IO_FACTORY = new DefaultIOFactory();
232
233    /**
234     * A string with special characters that need to be unescaped when reading
235     * a properties file. {@code java.util.Properties} escapes these characters
236     * when writing out a properties file.
237     */
238    private static final String UNESCAPE_CHARACTERS = ":#=!\\\'\"";
239
240    /**
241     * This is the name of the property that can point to other
242     * properties file for including other properties files.
243     */
244    private static String include = "include";
245
246    /**
247     * This is the name of the property that can point to other
248     * properties file for including other properties files.
249     * <p>
250     * If the file is absent, processing continues normally.
251     * </p>
252     */
253    private static String includeOptional = "includeoptional";
254
255    /** The list of possible key/value separators */
256    private static final char[] SEPARATORS = new char[] {'=', ':'};
257
258    /** The white space characters used as key/value separators. */
259    private static final char[] WHITE_SPACE = new char[]{' ', '\t', '\f'};
260
261    /** Constant for the platform specific line separator.*/
262    private static final String LINE_SEPARATOR = System.getProperty("line.separator");
263
264    /** Constant for the radix of hex numbers.*/
265    private static final int HEX_RADIX = 16;
266
267    /** Constant for the length of a unicode literal.*/
268    private static final int UNICODE_LEN = 4;
269
270    /** Stores the layout object.*/
271    private PropertiesConfigurationLayout layout;
272
273    /** The IOFactory for creating readers and writers.*/
274    private IOFactory ioFactory;
275
276    /** The current {@code FileLocator}. */
277    private FileLocator locator;
278
279    /** Allow file inclusion or not */
280    private boolean includesAllowed = true;
281
282    /**
283     * Creates an empty PropertyConfiguration object which can be
284     * used to synthesize a new Properties file by adding values and
285     * then saving().
286     */
287    public PropertiesConfiguration()
288    {
289        installLayout(createLayout());
290    }
291
292    /**
293     * Gets the property value for including other properties files.
294     * By default it is "include".
295     *
296     * @return A String.
297     */
298    public static String getInclude()
299    {
300        return PropertiesConfiguration.include;
301    }
302
303    /**
304     * Gets the property value for including other properties files.
305     * By default it is "include".
306     * <p>
307     * If the file is absent, processing continues normally.
308     * </p>
309     *
310     * @return A String.
311     * @since 2.5
312     */
313    public static String getIncludeOptional()
314    {
315        return PropertiesConfiguration.includeOptional;
316    }
317
318    /**
319     * Sets the property value for including other properties files.
320     * By default it is "include".
321     *
322     * @param inc A String.
323     */
324    public static void setInclude(final String inc)
325    {
326        PropertiesConfiguration.include = inc;
327    }
328
329    /**
330     * Sets the property value for including other properties files.
331     * By default it is "include".
332     * <p>
333     * If the file is absent, processing continues normally.
334     * </p>
335     *
336     * @param inc A String.
337     * @since 2.5
338     */
339    public static void setIncludeOptional(final String inc)
340    {
341        PropertiesConfiguration.includeOptional = inc;
342    }
343
344    /**
345     * Controls whether additional files can be loaded by the {@code include = <xxx>}
346     * statement or not. This is <b>true</b> per default.
347     *
348     * @param includesAllowed True if Includes are allowed.
349     */
350    public void setIncludesAllowed(final boolean includesAllowed)
351    {
352        this.includesAllowed = includesAllowed;
353    }
354
355    /**
356     * Reports the status of file inclusion.
357     *
358     * @return True if include files are loaded.
359     */
360    public boolean isIncludesAllowed()
361    {
362        return this.includesAllowed;
363    }
364
365    /**
366     * Return the comment header.
367     *
368     * @return the comment header
369     * @since 1.1
370     */
371    public String getHeader()
372    {
373        beginRead(false);
374        try
375        {
376            return getLayout().getHeaderComment();
377        }
378        finally
379        {
380            endRead();
381        }
382    }
383
384    /**
385     * Set the comment header.
386     *
387     * @param header the header to use
388     * @since 1.1
389     */
390    public void setHeader(final String header)
391    {
392        beginWrite(false);
393        try
394        {
395            getLayout().setHeaderComment(header);
396        }
397        finally
398        {
399            endWrite();
400        }
401    }
402
403    /**
404     * Returns the footer comment. This is a comment at the very end of the
405     * file.
406     *
407     * @return the footer comment
408     * @since 2.0
409     */
410    public String getFooter()
411    {
412        beginRead(false);
413        try
414        {
415            return getLayout().getFooterComment();
416        }
417        finally
418        {
419            endRead();
420        }
421    }
422
423    /**
424     * Sets the footer comment. If set, this comment is written after all
425     * properties at the end of the file.
426     *
427     * @param footer the footer comment
428     * @since 2.0
429     */
430    public void setFooter(final String footer)
431    {
432        beginWrite(false);
433        try
434        {
435            getLayout().setFooterComment(footer);
436        }
437        finally
438        {
439            endWrite();
440        }
441    }
442
443    /**
444     * Returns the associated layout object.
445     *
446     * @return the associated layout object
447     * @since 1.3
448     */
449    public PropertiesConfigurationLayout getLayout()
450    {
451        return layout;
452    }
453
454    /**
455     * Sets the associated layout object.
456     *
457     * @param layout the new layout object; can be <b>null</b>, then a new
458     * layout object will be created
459     * @since 1.3
460     */
461    public void setLayout(final PropertiesConfigurationLayout layout)
462    {
463        installLayout(layout);
464    }
465
466    /**
467     * Installs a layout object. It has to be ensured that the layout is
468     * registered as change listener at this configuration. If there is already
469     * a layout object installed, it has to be removed properly.
470     *
471     * @param layout the layout object to be installed
472     */
473    private void installLayout(final PropertiesConfigurationLayout layout)
474    {
475        // only one layout must exist
476        if (this.layout != null)
477        {
478            removeEventListener(ConfigurationEvent.ANY, this.layout);
479        }
480
481        if (layout == null)
482        {
483            this.layout = createLayout();
484        }
485        else
486        {
487            this.layout = layout;
488        }
489        addEventListener(ConfigurationEvent.ANY, this.layout);
490    }
491
492    /**
493     * Creates a standard layout object. This configuration is initialized with
494     * such a standard layout.
495     *
496     * @return the newly created layout object
497     */
498    private PropertiesConfigurationLayout createLayout()
499    {
500        return new PropertiesConfigurationLayout();
501    }
502
503    /**
504     * Returns the {@code IOFactory} to be used for creating readers and
505     * writers when loading or saving this configuration.
506     *
507     * @return the {@code IOFactory}
508     * @since 1.7
509     */
510    public IOFactory getIOFactory()
511    {
512        return (ioFactory != null) ? ioFactory : DEFAULT_IO_FACTORY;
513    }
514
515    /**
516     * Sets the {@code IOFactory} to be used for creating readers and
517     * writers when loading or saving this configuration. Using this method a
518     * client can customize the reader and writer classes used by the load and
519     * save operations. Note that this method must be called before invoking
520     * one of the {@code load()} and {@code save()} methods.
521     * Especially, if you want to use a custom {@code IOFactory} for
522     * changing the {@code PropertiesReader}, you cannot load the
523     * configuration data in the constructor.
524     *
525     * @param ioFactory the new {@code IOFactory} (must not be <b>null</b>)
526     * @throws IllegalArgumentException if the {@code IOFactory} is
527     *         <b>null</b>
528     * @since 1.7
529     */
530    public void setIOFactory(final IOFactory ioFactory)
531    {
532        if (ioFactory == null)
533        {
534            throw new IllegalArgumentException("IOFactory must not be null!");
535        }
536
537        this.ioFactory = ioFactory;
538    }
539
540    /**
541     * Stores the current {@code FileLocator} for a following IO operation. The
542     * {@code FileLocator} is needed to resolve include files with relative file
543     * names.
544     *
545     * @param locator the current {@code FileLocator}
546     * @since 2.0
547     */
548    @Override
549    public void initFileLocator(final FileLocator locator)
550    {
551        this.locator = locator;
552    }
553
554    /**
555     * {@inheritDoc} This implementation delegates to the associated layout
556     * object which does the actual loading. Note that this method does not
557     * do any synchronization. This lies in the responsibility of the caller.
558     * (Typically, the caller is a {@code FileHandler} object which takes
559     * care for proper synchronization.)
560     *
561     * @since 2.0
562     */
563    @Override
564    public void read(final Reader in) throws ConfigurationException, IOException
565    {
566        getLayout().load(this, in);
567    }
568
569    /**
570     * {@inheritDoc} This implementation delegates to the associated layout
571     * object which does the actual saving. Note that, analogous to
572     * {@link #read(Reader)}, this method does not do any synchronization.
573     *
574     * @since 2.0
575     */
576    @Override
577    public void write(final Writer out) throws ConfigurationException, IOException
578    {
579        getLayout().save(this, out);
580    }
581
582    /**
583     * Creates a copy of this object.
584     *
585     * @return the copy
586     */
587    @Override
588    public Object clone()
589    {
590        final PropertiesConfiguration copy = (PropertiesConfiguration) super.clone();
591        if (layout != null)
592        {
593            copy.setLayout(new PropertiesConfigurationLayout(layout));
594        }
595        return copy;
596    }
597
598    /**
599     * This method is invoked by the associated
600     * {@link PropertiesConfigurationLayout} object for each
601     * property definition detected in the parsed properties file. Its task is
602     * to check whether this is a special property definition (e.g. the
603     * {@code include} property). If not, the property must be added to
604     * this configuration. The return value indicates whether the property
605     * should be treated as a normal property. If it is <b>false</b>, the
606     * layout object will ignore this property.
607     *
608     * @param key the property key
609     * @param value the property value
610     * @return a flag whether this is a normal property
611     * @throws ConfigurationException if an error occurs
612     * @since 1.3
613     */
614    boolean propertyLoaded(final String key, final String value)
615            throws ConfigurationException
616    {
617        boolean result;
618
619        if (StringUtils.isNotEmpty(getInclude())
620                && key.equalsIgnoreCase(getInclude()))
621        {
622            if (isIncludesAllowed())
623            {
624                final Collection<String> files =
625                        getListDelimiterHandler().split(value, true);
626                for (final String f : files)
627                {
628                    loadIncludeFile(interpolate(f), false);
629                }
630            }
631            result = false;
632        }
633
634        else if (StringUtils.isNotEmpty(getIncludeOptional())
635            && key.equalsIgnoreCase(getIncludeOptional()))
636        {
637            if (isIncludesAllowed())
638            {
639                final Collection<String> files =
640                        getListDelimiterHandler().split(value, true);
641                for (final String f : files)
642                {
643                    loadIncludeFile(interpolate(f), true);
644                }
645            }
646            result = false;
647        }
648
649        else
650        {
651            addPropertyInternal(key, value);
652            result = true;
653        }
654
655        return result;
656    }
657
658    /**
659     * Tests whether a line is a comment, i.e. whether it starts with a comment
660     * character.
661     *
662     * @param line the line
663     * @return a flag if this is a comment line
664     * @since 1.3
665     */
666    static boolean isCommentLine(final String line)
667    {
668        final String s = line.trim();
669        // blanc lines are also treated as comment lines
670        return s.length() < 1 || COMMENT_CHARS.indexOf(s.charAt(0)) >= 0;
671    }
672
673    /**
674     * Returns the number of trailing backslashes. This is sometimes needed for
675     * the correct handling of escape characters.
676     *
677     * @param line the string to investigate
678     * @return the number of trailing backslashes
679     */
680    private static int countTrailingBS(final String line)
681    {
682        int bsCount = 0;
683        for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '\\'; idx--)
684        {
685            bsCount++;
686        }
687
688        return bsCount;
689    }
690
691    /**
692     * This class is used to read properties lines. These lines do
693     * not terminate with new-line chars but rather when there is no
694     * backslash sign a the end of the line.  This is used to
695     * concatenate multiple lines for readability.
696     */
697    public static class PropertiesReader extends LineNumberReader
698    {
699        /** The regular expression to parse the key and the value of a property. */
700        private static final Pattern PROPERTY_PATTERN = Pattern
701                .compile("(([\\S&&[^\\\\" + new String(SEPARATORS)
702                        + "]]|\\\\.)*)(\\s*(\\s+|[" + new String(SEPARATORS)
703                        + "])\\s*)?(.*)");
704
705        /** Constant for the index of the group for the key. */
706        private static final int IDX_KEY = 1;
707
708        /** Constant for the index of the group for the value. */
709        private static final int IDX_VALUE = 5;
710
711        /** Constant for the index of the group for the separator. */
712        private static final int IDX_SEPARATOR = 3;
713
714        /** Stores the comment lines for the currently processed property.*/
715        private final List<String> commentLines;
716
717        /** Stores the name of the last read property.*/
718        private String propertyName;
719
720        /** Stores the value of the last read property.*/
721        private String propertyValue;
722
723        /** Stores the property separator of the last read property.*/
724        private String propertySeparator = DEFAULT_SEPARATOR;
725
726        /**
727         * Constructor.
728         *
729         * @param reader A Reader.
730         */
731        public PropertiesReader(final Reader reader)
732        {
733            super(reader);
734            commentLines = new ArrayList<>();
735        }
736
737        /**
738         * Reads a property line. Returns null if Stream is
739         * at EOF. Concatenates lines ending with "\".
740         * Skips lines beginning with "#" or "!" and empty lines.
741         * The return value is a property definition (<code>&lt;name&gt;</code>
742         * = <code>&lt;value&gt;</code>)
743         *
744         * @return A string containing a property value or null
745         *
746         * @throws IOException in case of an I/O error
747         */
748        public String readProperty() throws IOException
749        {
750            commentLines.clear();
751            final StringBuilder buffer = new StringBuilder();
752
753            while (true)
754            {
755                String line = readLine();
756                if (line == null)
757                {
758                    // EOF
759                    return null;
760                }
761
762                if (isCommentLine(line))
763                {
764                    commentLines.add(line);
765                    continue;
766                }
767
768                line = line.trim();
769
770                if (checkCombineLines(line))
771                {
772                    line = line.substring(0, line.length() - 1);
773                    buffer.append(line);
774                }
775                else
776                {
777                    buffer.append(line);
778                    break;
779                }
780            }
781            return buffer.toString();
782        }
783
784        /**
785         * Parses the next property from the input stream and stores the found
786         * name and value in internal fields. These fields can be obtained using
787         * the provided getter methods. The return value indicates whether EOF
788         * was reached (<b>false</b>) or whether further properties are
789         * available (<b>true</b>).
790         *
791         * @return a flag if further properties are available
792         * @throws IOException if an error occurs
793         * @since 1.3
794         */
795        public boolean nextProperty() throws IOException
796        {
797            final String line = readProperty();
798
799            if (line == null)
800            {
801                return false; // EOF
802            }
803
804            // parse the line
805            parseProperty(line);
806            return true;
807        }
808
809        /**
810         * Returns the comment lines that have been read for the last property.
811         *
812         * @return the comment lines for the last property returned by
813         * {@code readProperty()}
814         * @since 1.3
815         */
816        public List<String> getCommentLines()
817        {
818            return commentLines;
819        }
820
821        /**
822         * Returns the name of the last read property. This method can be called
823         * after {@link #nextProperty()} was invoked and its
824         * return value was <b>true</b>.
825         *
826         * @return the name of the last read property
827         * @since 1.3
828         */
829        public String getPropertyName()
830        {
831            return propertyName;
832        }
833
834        /**
835         * Returns the value of the last read property. This method can be
836         * called after {@link #nextProperty()} was invoked and
837         * its return value was <b>true</b>.
838         *
839         * @return the value of the last read property
840         * @since 1.3
841         */
842        public String getPropertyValue()
843        {
844            return propertyValue;
845        }
846
847        /**
848         * Returns the separator that was used for the last read property. The
849         * separator can be stored so that it can later be restored when saving
850         * the configuration.
851         *
852         * @return the separator for the last read property
853         * @since 1.7
854         */
855        public String getPropertySeparator()
856        {
857            return propertySeparator;
858        }
859
860        /**
861         * Parses a line read from the properties file. This method is called
862         * for each non-comment line read from the source file. Its task is to
863         * split the passed in line into the property key and its value. The
864         * results of the parse operation can be stored by calling the
865         * {@code initPropertyXXX()} methods.
866         *
867         * @param line the line read from the properties file
868         * @since 1.7
869         */
870        protected void parseProperty(final String line)
871        {
872            final String[] property = doParseProperty(line, true);
873            initPropertyName(property[0]);
874            initPropertyValue(property[1]);
875            initPropertySeparator(property[2]);
876        }
877
878        /**
879         * Sets the name of the current property. This method can be called by
880         * {@code parseProperty()} for storing the results of the parse
881         * operation. It also ensures that the property key is correctly
882         * escaped.
883         *
884         * @param name the name of the current property
885         * @since 1.7
886         */
887        protected void initPropertyName(final String name)
888        {
889            propertyName = unescapePropertyName(name);
890        }
891
892        /**
893         * Performs unescaping on the given property name.
894         *
895         * @param name the property name
896         * @return the unescaped property name
897         * @since 2.4
898         */
899        protected String unescapePropertyName(final String name)
900        {
901            return StringEscapeUtils.unescapeJava(name);
902        }
903
904        /**
905         * Sets the value of the current property. This method can be called by
906         * {@code parseProperty()} for storing the results of the parse
907         * operation. It also ensures that the property value is correctly
908         * escaped.
909         *
910         * @param value the value of the current property
911         * @since 1.7
912         */
913        protected void initPropertyValue(final String value)
914        {
915            propertyValue = unescapePropertyValue(value);
916        }
917
918        /**
919         * Performs unescaping on the given property value.
920         *
921         * @param value the property value
922         * @return the unescaped property value
923         * @since 2.4
924         */
925        protected String unescapePropertyValue(final String value)
926        {
927            return unescapeJava(value);
928        }
929
930        /**
931         * Sets the separator of the current property. This method can be called
932         * by {@code parseProperty()}. It allows the associated layout
933         * object to keep track of the property separators. When saving the
934         * configuration the separators can be restored.
935         *
936         * @param value the separator used for the current property
937         * @since 1.7
938         */
939        protected void initPropertySeparator(final String value)
940        {
941            propertySeparator = value;
942        }
943
944        /**
945         * Checks if the passed in line should be combined with the following.
946         * This is true, if the line ends with an odd number of backslashes.
947         *
948         * @param line the line
949         * @return a flag if the lines should be combined
950         */
951        static boolean checkCombineLines(final String line)
952        {
953            return countTrailingBS(line) % 2 != 0;
954        }
955
956        /**
957         * Parse a property line and return the key, the value, and the separator in an
958         * array.
959         *
960         * @param line the line to parse
961         * @param trimValue flag whether the value is to be trimmed
962         * @return an array with the property's key, value, and separator
963         */
964        static String[] doParseProperty(final String line, final boolean trimValue)
965        {
966            final Matcher matcher = PROPERTY_PATTERN.matcher(line);
967
968            final String[] result = {"", "", ""};
969
970            if (matcher.matches())
971            {
972                result[0] = matcher.group(IDX_KEY).trim();
973
974                String value = matcher.group(IDX_VALUE);
975                if (trimValue)
976                {
977                    value = value.trim();
978                }
979                result[1] = value;
980
981                result[2] = matcher.group(IDX_SEPARATOR);
982            }
983
984            return result;
985        }
986    } // class PropertiesReader
987
988    /**
989     * This class is used to write properties lines. The most important method
990     * is {@code writeProperty(String, Object, boolean)}, which is called
991     * during a save operation for each property found in the configuration.
992     */
993    public static class PropertiesWriter extends FilterWriter
994    {
995
996        /**
997         * Properties escape map.
998         */
999        private static final Map<CharSequence, CharSequence> PROPERTIES_CHARS_ESCAPE;
1000        static
1001        {
1002            final Map<CharSequence, CharSequence> initialMap = new HashMap<>();
1003            initialMap.put("\\", "\\\\");
1004            PROPERTIES_CHARS_ESCAPE = Collections.unmodifiableMap(initialMap);
1005        }
1006
1007        /**
1008         * A translator for escaping property values. This translator performs a
1009         * subset of transformations done by the ESCAPE_JAVA translator from
1010         * Commons Lang 3.
1011         */
1012        private static final CharSequenceTranslator ESCAPE_PROPERTIES =
1013                new AggregateTranslator(
1014                        new LookupTranslator(PROPERTIES_CHARS_ESCAPE),
1015                        new LookupTranslator(EntityArrays.JAVA_CTRL_CHARS_ESCAPE),
1016                        UnicodeEscaper.outsideOf(32, 0x7f));
1017
1018        /**
1019         * A {@code ValueTransformer} implementation used to escape property
1020         * values. This implementation applies the transformation defined by the
1021         * {@link #ESCAPE_PROPERTIES} translator.
1022         */
1023        private static final ValueTransformer DEFAULT_TRANSFORMER =
1024                new ValueTransformer()
1025                {
1026                    @Override
1027                    public Object transformValue(final Object value)
1028                    {
1029                        final String strVal = String.valueOf(value);
1030                        return ESCAPE_PROPERTIES.translate(strVal);
1031                    }
1032                };
1033
1034        /** The value transformer used for escaping property values. */
1035        private final ValueTransformer valueTransformer;
1036
1037        /** The list delimiter handler.*/
1038        private final ListDelimiterHandler delimiterHandler;
1039
1040        /** The separator to be used for the current property. */
1041        private String currentSeparator;
1042
1043        /** The global separator. If set, it overrides the current separator.*/
1044        private String globalSeparator;
1045
1046        /** The line separator.*/
1047        private String lineSeparator;
1048
1049        /**
1050         * Creates a new instance of {@code PropertiesWriter}.
1051         *
1052         * @param writer a Writer object providing the underlying stream
1053         * @param delHandler the delimiter handler for dealing with properties
1054         *        with multiple values
1055         */
1056        public PropertiesWriter(final Writer writer, final ListDelimiterHandler delHandler)
1057        {
1058            this(writer, delHandler, DEFAULT_TRANSFORMER);
1059        }
1060
1061        /**
1062         * Creates a new instance of {@code PropertiesWriter}.
1063         *
1064         * @param writer a Writer object providing the underlying stream
1065         * @param delHandler the delimiter handler for dealing with properties
1066         *        with multiple values
1067         * @param valueTransformer the value transformer used to escape property values
1068         */
1069        public PropertiesWriter(final Writer writer, final ListDelimiterHandler delHandler,
1070            final ValueTransformer valueTransformer)
1071        {
1072            super(writer);
1073            delimiterHandler = delHandler;
1074            this.valueTransformer = valueTransformer;
1075        }
1076
1077        /**
1078         * Returns the delimiter handler for properties with multiple values.
1079         * This object is used to escape property values so that they can be
1080         * read in correctly the next time they are loaded.
1081         *
1082         * @return the delimiter handler for properties with multiple values
1083         * @since 2.0
1084         */
1085        public ListDelimiterHandler getDelimiterHandler()
1086        {
1087            return delimiterHandler;
1088        }
1089
1090        /**
1091         * Returns the current property separator.
1092         *
1093         * @return the current property separator
1094         * @since 1.7
1095         */
1096        public String getCurrentSeparator()
1097        {
1098            return currentSeparator;
1099        }
1100
1101        /**
1102         * Sets the current property separator. This separator is used when
1103         * writing the next property.
1104         *
1105         * @param currentSeparator the current property separator
1106         * @since 1.7
1107         */
1108        public void setCurrentSeparator(final String currentSeparator)
1109        {
1110            this.currentSeparator = currentSeparator;
1111        }
1112
1113        /**
1114         * Returns the global property separator.
1115         *
1116         * @return the global property separator
1117         * @since 1.7
1118         */
1119        public String getGlobalSeparator()
1120        {
1121            return globalSeparator;
1122        }
1123
1124        /**
1125         * Sets the global property separator. This separator corresponds to the
1126         * {@code globalSeparator} property of
1127         * {@link PropertiesConfigurationLayout}. It defines the separator to be
1128         * used for all properties. If it is undefined, the current separator is
1129         * used.
1130         *
1131         * @param globalSeparator the global property separator
1132         * @since 1.7
1133         */
1134        public void setGlobalSeparator(final String globalSeparator)
1135        {
1136            this.globalSeparator = globalSeparator;
1137        }
1138
1139        /**
1140         * Returns the line separator.
1141         *
1142         * @return the line separator
1143         * @since 1.7
1144         */
1145        public String getLineSeparator()
1146        {
1147            return (lineSeparator != null) ? lineSeparator : LINE_SEPARATOR;
1148        }
1149
1150        /**
1151         * Sets the line separator. Each line written by this writer is
1152         * terminated with this separator. If not set, the platform-specific
1153         * line separator is used.
1154         *
1155         * @param lineSeparator the line separator to be used
1156         * @since 1.7
1157         */
1158        public void setLineSeparator(final String lineSeparator)
1159        {
1160            this.lineSeparator = lineSeparator;
1161        }
1162
1163        /**
1164         * Write a property.
1165         *
1166         * @param key the key of the property
1167         * @param value the value of the property
1168         *
1169         * @throws IOException if an I/O error occurs
1170         */
1171        public void writeProperty(final String key, final Object value) throws IOException
1172        {
1173            writeProperty(key, value, false);
1174        }
1175
1176        /**
1177         * Write a property.
1178         *
1179         * @param key The key of the property
1180         * @param values The array of values of the property
1181         *
1182         * @throws IOException if an I/O error occurs
1183         */
1184        public void writeProperty(final String key, final List<?> values) throws IOException
1185        {
1186            for (int i = 0; i < values.size(); i++)
1187            {
1188                writeProperty(key, values.get(i));
1189            }
1190        }
1191
1192        /**
1193         * Writes the given property and its value. If the value happens to be a
1194         * list, the {@code forceSingleLine} flag is evaluated. If it is
1195         * set, all values are written on a single line using the list delimiter
1196         * as separator.
1197         *
1198         * @param key the property key
1199         * @param value the property value
1200         * @param forceSingleLine the &quot;force single line&quot; flag
1201         * @throws IOException if an error occurs
1202         * @since 1.3
1203         */
1204        public void writeProperty(final String key, final Object value,
1205                final boolean forceSingleLine) throws IOException
1206        {
1207            String v;
1208
1209            if (value instanceof List)
1210            {
1211                v = null;
1212                final List<?> values = (List<?>) value;
1213                if (forceSingleLine)
1214                {
1215                    try
1216                    {
1217                        v = String.valueOf(getDelimiterHandler()
1218                                        .escapeList(values, valueTransformer));
1219                    }
1220                    catch (final UnsupportedOperationException uoex)
1221                    {
1222                        // the handler may not support escaping lists,
1223                        // then the list is written in multiple lines
1224                    }
1225                }
1226                if (v == null)
1227                {
1228                    writeProperty(key, values);
1229                    return;
1230                }
1231            }
1232            else
1233            {
1234                v = String.valueOf(getDelimiterHandler().escape(value, valueTransformer));
1235            }
1236
1237            write(escapeKey(key));
1238            write(fetchSeparator(key, value));
1239            write(v);
1240
1241            writeln(null);
1242        }
1243
1244        /**
1245         * Write a comment.
1246         *
1247         * @param comment the comment to write
1248         * @throws IOException if an I/O error occurs
1249         */
1250        public void writeComment(final String comment) throws IOException
1251        {
1252            writeln("# " + comment);
1253        }
1254
1255        /**
1256         * Escapes the key of a property before it gets written to file. This
1257         * method is called on saving a configuration for each property key.
1258         * It ensures that separator characters contained in the key are
1259         * escaped.
1260         *
1261         * @param key the key
1262         * @return the escaped key
1263         * @since 2.0
1264         */
1265        protected String escapeKey(final String key)
1266        {
1267            final StringBuilder newkey = new StringBuilder();
1268
1269            for (int i = 0; i < key.length(); i++)
1270            {
1271                final char c = key.charAt(i);
1272
1273                if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c) || c == '\\')
1274                {
1275                    // escape the separator
1276                    newkey.append('\\');
1277                    newkey.append(c);
1278                }
1279                else
1280                {
1281                    newkey.append(c);
1282                }
1283            }
1284
1285            return newkey.toString();
1286        }
1287
1288        /**
1289         * Helper method for writing a line with the platform specific line
1290         * ending.
1291         *
1292         * @param s the content of the line (may be <b>null</b>)
1293         * @throws IOException if an error occurs
1294         * @since 1.3
1295         */
1296        public void writeln(final String s) throws IOException
1297        {
1298            if (s != null)
1299            {
1300                write(s);
1301            }
1302            write(getLineSeparator());
1303        }
1304
1305        /**
1306         * Returns the separator to be used for the given property. This method
1307         * is called by {@code writeProperty()}. The string returned here
1308         * is used as separator between the property key and its value. Per
1309         * default the method checks whether a global separator is set. If this
1310         * is the case, it is returned. Otherwise the separator returned by
1311         * {@code getCurrentSeparator()} is used, which was set by the
1312         * associated layout object. Derived classes may implement a different
1313         * strategy for defining the separator.
1314         *
1315         * @param key the property key
1316         * @param value the value
1317         * @return the separator to be used
1318         * @since 1.7
1319         */
1320        protected String fetchSeparator(final String key, final Object value)
1321        {
1322            return (getGlobalSeparator() != null) ? getGlobalSeparator()
1323                    : StringUtils.defaultString(getCurrentSeparator());
1324        }
1325    } // class PropertiesWriter
1326
1327    /**
1328     * <p>
1329     * Definition of an interface that allows customization of read and write
1330     * operations.
1331     * </p>
1332     * <p>
1333     * For reading and writing properties files the inner classes
1334     * {@code PropertiesReader} and {@code PropertiesWriter} are used.
1335     * This interface defines factory methods for creating both a
1336     * {@code PropertiesReader} and a {@code PropertiesWriter}. An
1337     * object implementing this interface can be passed to the
1338     * {@code setIOFactory()} method of
1339     * {@code PropertiesConfiguration}. Every time the configuration is
1340     * read or written the {@code IOFactory} is asked to create the
1341     * appropriate reader or writer object. This provides an opportunity to
1342     * inject custom reader or writer implementations.
1343     * </p>
1344     *
1345     * @since 1.7
1346     */
1347    public interface IOFactory
1348    {
1349        /**
1350         * Creates a {@code PropertiesReader} for reading a properties
1351         * file. This method is called whenever the
1352         * {@code PropertiesConfiguration} is loaded. The reader returned
1353         * by this method is then used for parsing the properties file.
1354         *
1355         * @param in the underlying reader (of the properties file)
1356         * @return the {@code PropertiesReader} for loading the
1357         *         configuration
1358         */
1359        PropertiesReader createPropertiesReader(Reader in);
1360
1361        /**
1362         * Creates a {@code PropertiesWriter} for writing a properties
1363         * file. This method is called before the
1364         * {@code PropertiesConfiguration} is saved. The writer returned by
1365         * this method is then used for writing the properties file.
1366         *
1367         * @param out the underlying writer (to the properties file)
1368         * @param handler the list delimiter delimiter for list parsing
1369         * @return the {@code PropertiesWriter} for saving the
1370         *         configuration
1371         */
1372        PropertiesWriter createPropertiesWriter(Writer out,
1373                ListDelimiterHandler handler);
1374    }
1375
1376    /**
1377     * <p>
1378     * A default implementation of the {@code IOFactory} interface.
1379     * </p>
1380     * <p>
1381     * This class implements the {@code createXXXX()} methods defined by
1382     * the {@code IOFactory} interface in a way that the default objects
1383     * (i.e. {@code PropertiesReader} and {@code PropertiesWriter} are
1384     * returned. Customizing either the reader or the writer (or both) can be
1385     * done by extending this class and overriding the corresponding
1386     * {@code createXXXX()} method.
1387     * </p>
1388     *
1389     * @since 1.7
1390     */
1391    public static class DefaultIOFactory implements IOFactory
1392    {
1393        @Override
1394        public PropertiesReader createPropertiesReader(final Reader in)
1395        {
1396            return new PropertiesReader(in);
1397        }
1398
1399        @Override
1400        public PropertiesWriter createPropertiesWriter(final Writer out,
1401                final ListDelimiterHandler handler)
1402        {
1403            return new PropertiesWriter(out, handler);
1404        }
1405    }
1406
1407    /**
1408     * An alternative {@link IOFactory} that tries to mimic the behavior of
1409     * {@link java.util.Properties} (Jup) more closely. The goal is to allow both of
1410     * them be used interchangeably when reading and writing properties files
1411     * without losing or changing information.
1412     * <p>
1413     * It also has the option to <em>not</em> use Unicode escapes. When using UTF-8
1414     * encoding (which is e.g. the new default for resource bundle properties files
1415     * since Java 9), Unicode escapes are no longer required and avoiding them makes
1416     * properties files more readable with regular text editors.
1417     * <p>
1418     * Some of the ways this implementation differs from {@link DefaultIOFactory}:
1419     * <ul>
1420     * <li>Trailing whitespace will not be trimmed from each line.</li>
1421     * <li>Unknown escape sequences will have their backslash removed.</li>
1422     * <li>{@code \b} is not a recognized escape sequence.</li>
1423     * <li>Leading spaces in property values are preserved by escaping them.</li>
1424     * <li>All natural lines (i.e. in the file) of a logical property line will have
1425     * their leading whitespace trimmed.</li>
1426     * <li>Natural lines that look like comment lines within a logical line are not
1427     * treated as such; they're part of the property value.</li>
1428     * </ul>
1429     *
1430     * @since 2.4
1431     */
1432    public static class JupIOFactory implements IOFactory
1433    {
1434
1435        /**
1436         * Whether characters less than {@code \u0020} and characters greater than
1437         * {@code \u007E} in property keys or values should be escaped using
1438         * Unicode escape sequences. Not necessary when e.g. writing as UTF-8.
1439         */
1440        private final boolean escapeUnicode;
1441
1442        /**
1443         * Constructs a new {@link JupIOFactory} with Unicode escaping.
1444         */
1445        public JupIOFactory()
1446        {
1447            this(true);
1448        }
1449
1450        /**
1451         * Constructs a new {@link JupIOFactory} with optional Unicode escaping. Whether
1452         * Unicode escaping is required depends on the encoding used to save the
1453         * properties file. E.g. for ISO-8859-1 this must be turned on, for UTF-8 it's
1454         * not necessary. Unfortunately this factory can't determine the encoding on its
1455         * own.
1456         *
1457         * @param escapeUnicode whether Unicode characters should be escaped
1458         */
1459        public JupIOFactory(final boolean escapeUnicode)
1460        {
1461            this.escapeUnicode = escapeUnicode;
1462        }
1463
1464        @Override
1465        public PropertiesReader createPropertiesReader(final Reader in)
1466        {
1467            return new JupPropertiesReader(in);
1468        }
1469
1470        @Override
1471        public PropertiesWriter createPropertiesWriter(final Writer out, final ListDelimiterHandler handler)
1472        {
1473            return new JupPropertiesWriter(out, handler, escapeUnicode);
1474        }
1475
1476    }
1477
1478    /**
1479     * A {@link PropertiesReader} that tries to mimic the behavior of
1480     * {@link java.util.Properties}.
1481     *
1482     * @since 2.4
1483     */
1484    public static class JupPropertiesReader extends PropertiesReader
1485    {
1486
1487        /**
1488         * Constructor.
1489         *
1490         * @param reader A Reader.
1491         */
1492        public JupPropertiesReader(final Reader reader)
1493        {
1494            super(reader);
1495        }
1496
1497
1498        @Override
1499        public String readProperty() throws IOException
1500        {
1501            getCommentLines().clear();
1502            final StringBuilder buffer = new StringBuilder();
1503
1504            while (true)
1505            {
1506                String line = readLine();
1507                if (line == null)
1508                {
1509                    // EOF
1510                    if (buffer.length() > 0)
1511                    {
1512                        break;
1513                    }
1514                    return null;
1515                }
1516
1517                // while a property line continues there are no comments (even if the line from
1518                // the file looks like one)
1519                if (isCommentLine(line) && (buffer.length() == 0))
1520                {
1521                    getCommentLines().add(line);
1522                    continue;
1523                }
1524
1525                // while property line continues left trim all following lines read from the
1526                // file
1527                if (buffer.length() > 0)
1528                {
1529                    // index of the first non-whitespace character
1530                    int i;
1531                    for (i = 0; i < line.length(); i++)
1532                    {
1533                        if (!Character.isWhitespace(line.charAt(i)))
1534                        {
1535                            break;
1536                        }
1537                    }
1538
1539                    line = line.substring(i);
1540                }
1541
1542                if (checkCombineLines(line))
1543                {
1544                    line = line.substring(0, line.length() - 1);
1545                    buffer.append(line);
1546                }
1547                else
1548                {
1549                    buffer.append(line);
1550                    break;
1551                }
1552            }
1553            return buffer.toString();
1554        }
1555
1556        @Override
1557        protected void parseProperty(final String line)
1558        {
1559            final String[] property = doParseProperty(line, false);
1560            initPropertyName(property[0]);
1561            initPropertyValue(property[1]);
1562            initPropertySeparator(property[2]);
1563        }
1564
1565        @Override
1566        protected String unescapePropertyValue(final String value)
1567        {
1568            return unescapeJava(value, true);
1569        }
1570
1571    }
1572
1573    /**
1574     * A {@link PropertiesWriter} that tries to mimic the behavior of
1575     * {@link java.util.Properties}.
1576     *
1577     * @since 2.4
1578     */
1579    public static class JupPropertiesWriter extends PropertiesWriter
1580    {
1581
1582        /**
1583         * The starting ASCII printable character.
1584         */
1585        private static final int PRINTABLE_INDEX_END = 0x7e;
1586
1587        /**
1588         * The ending ASCII printable character.
1589         */
1590        private static final int PRINTABLE_INDEX_START = 0x20;
1591
1592        /**
1593         * A UnicodeEscaper for characters outside the ASCII printable range.
1594         */
1595        private static final UnicodeEscaper ESCAPER = UnicodeEscaper.outsideOf(PRINTABLE_INDEX_START,
1596            PRINTABLE_INDEX_END);
1597
1598        /**
1599         * Characters that need to be escaped when wring a properties file.
1600         */
1601        private static final Map<CharSequence, CharSequence> JUP_CHARS_ESCAPE;
1602        static
1603        {
1604            final Map<CharSequence, CharSequence> initialMap = new HashMap<>();
1605            initialMap.put("\\", "\\\\");
1606            initialMap.put("\n", "\\n");
1607            initialMap.put("\t", "\\t");
1608            initialMap.put("\f", "\\f");
1609            initialMap.put("\r", "\\r");
1610            JUP_CHARS_ESCAPE = Collections.unmodifiableMap(initialMap);
1611        }
1612
1613        /**
1614         * Creates a new instance of {@code JupPropertiesWriter}.
1615         *
1616         * @param writer a Writer object providing the underlying stream
1617         * @param delHandler the delimiter handler for dealing with properties with
1618         *        multiple values
1619         * @param escapeUnicode whether Unicode characters should be escaped using
1620         *        Unicode escapes
1621         */
1622        public JupPropertiesWriter(final Writer writer, final ListDelimiterHandler delHandler,
1623            final boolean escapeUnicode)
1624        {
1625            super(writer, delHandler, new ValueTransformer()
1626            {
1627                @Override
1628                public Object transformValue(final Object value)
1629                {
1630                    String valueString = String.valueOf(value);
1631
1632                    CharSequenceTranslator translator;
1633                    if (escapeUnicode)
1634                    {
1635                        translator = new AggregateTranslator(new LookupTranslator(JUP_CHARS_ESCAPE), ESCAPER);
1636                    }
1637                    else
1638                    {
1639                        translator = new AggregateTranslator(new LookupTranslator(JUP_CHARS_ESCAPE));
1640                    }
1641
1642                    valueString = translator.translate(valueString);
1643
1644                    // escape the first leading space to preserve it (and all after it)
1645                    if (valueString.startsWith(" "))
1646                    {
1647                        valueString = "\\" + valueString;
1648                    }
1649
1650                    return valueString;
1651                }
1652            });
1653        }
1654
1655    }
1656
1657    /**
1658     * <p>Unescapes any Java literals found in the {@code String} to a
1659     * {@code Writer}.</p> This is a slightly modified version of the
1660     * StringEscapeUtils.unescapeJava() function in commons-lang that doesn't
1661     * drop escaped separators (i.e '\,').
1662     *
1663     * @param str  the {@code String} to unescape, may be null
1664     * @return the processed string
1665     * @throws IllegalArgumentException if the Writer is {@code null}
1666     */
1667    protected static String unescapeJava(final String str)
1668    {
1669        return unescapeJava(str, false);
1670    }
1671
1672    /**
1673     * Unescapes Java literals found in the {@code String} to a {@code Writer}.
1674     * </p>
1675     * When the parameter {@code jupCompatible} is {@code false}, the classic
1676     * behavior is used (see {@link #unescapeJava(String)}). When it's {@code true}
1677     * a slightly different behavior that's compatible with
1678     * {@link java.util.Properties} is used (see {@link JupIOFactory}).
1679     *
1680     * @param str the {@code String} to unescape, may be null
1681     * @param jupCompatible whether unescaping is compatible with
1682     *        {@link java.util.Properties}; otherwise the classic behavior is used
1683     * @return the processed string
1684     * @throws IllegalArgumentException if the Writer is {@code null}
1685     */
1686    protected static String unescapeJava(final String str, final boolean jupCompatible)
1687    {
1688        if (str == null)
1689        {
1690            return null;
1691        }
1692        final int sz = str.length();
1693        final StringBuilder out = new StringBuilder(sz);
1694        final StringBuilder unicode = new StringBuilder(UNICODE_LEN);
1695        boolean hadSlash = false;
1696        boolean inUnicode = false;
1697        for (int i = 0; i < sz; i++)
1698        {
1699            final char ch = str.charAt(i);
1700            if (inUnicode)
1701            {
1702                // if in unicode, then we're reading unicode
1703                // values in somehow
1704                unicode.append(ch);
1705                if (unicode.length() == UNICODE_LEN)
1706                {
1707                    // unicode now contains the four hex digits
1708                    // which represents our unicode character
1709                    try
1710                    {
1711                        final int value = Integer.parseInt(unicode.toString(), HEX_RADIX);
1712                        out.append((char) value);
1713                        unicode.setLength(0);
1714                        inUnicode = false;
1715                        hadSlash = false;
1716                    }
1717                    catch (final NumberFormatException nfe)
1718                    {
1719                        throw new ConfigurationRuntimeException("Unable to parse unicode value: " + unicode, nfe);
1720                    }
1721                }
1722                continue;
1723            }
1724
1725            if (hadSlash)
1726            {
1727                // handle an escaped value
1728                hadSlash = false;
1729
1730                if (ch == 'r')
1731                {
1732                    out.append('\r');
1733                }
1734                else if (ch == 'f')
1735                {
1736                    out.append('\f');
1737                }
1738                else if (ch == 't')
1739                {
1740                    out.append('\t');
1741                }
1742                else if (ch == 'n')
1743                {
1744                    out.append('\n');
1745                }
1746                // JUP does not recognize \b
1747                else if (!jupCompatible && ch == 'b')
1748                {
1749                    out.append('\b');
1750                }
1751                else if (ch == 'u')
1752                {
1753                    // uh-oh, we're in unicode country....
1754                    inUnicode = true;
1755                }
1756                else if (needsUnescape(ch))
1757                {
1758                    out.append(ch);
1759                }
1760                else
1761                {
1762                    // JUP simply throws away the \ of unknown escape sequences
1763                    if (!jupCompatible)
1764                    {
1765                        out.append('\\');
1766                    }
1767                    out.append(ch);
1768                }
1769
1770                continue;
1771            }
1772            else if (ch == '\\')
1773            {
1774                hadSlash = true;
1775                continue;
1776            }
1777            out.append(ch);
1778        }
1779
1780        if (hadSlash)
1781        {
1782            // then we're in the weird case of a \ at the end of the
1783            // string, let's output it anyway.
1784            out.append('\\');
1785        }
1786
1787        return out.toString();
1788    }
1789
1790    /**
1791     * Checks whether the specified character needs to be unescaped. This method
1792     * is called when during reading a property file an escape character ('\')
1793     * is detected. If the character following the escape character is
1794     * recognized as a special character which is escaped per default in a Java
1795     * properties file, it has to be unescaped.
1796     *
1797     * @param ch the character in question
1798     * @return a flag whether this character has to be unescaped
1799     */
1800    private static boolean needsUnescape(final char ch)
1801    {
1802        return UNESCAPE_CHARACTERS.indexOf(ch) >= 0;
1803    }
1804
1805    /**
1806     * Helper method for loading an included properties file. This method is
1807     * called by {@code load()} when an {@code include} property
1808     * is encountered. It tries to resolve relative file names based on the
1809     * current base path. If this fails, a resolution based on the location of
1810     * this properties file is tried.
1811     *
1812     * @param fileName the name of the file to load
1813     * @param optional whether or not the {@code fileName} is optional
1814     * @throws ConfigurationException if loading fails
1815     */
1816    private void loadIncludeFile(final String fileName, final boolean optional) throws ConfigurationException
1817    {
1818        if (locator == null)
1819        {
1820            throw new ConfigurationException("Load operation not properly "
1821                    + "initialized! Do not call read(InputStream) directly,"
1822                    + " but use a FileHandler to load a configuration.");
1823        }
1824
1825        URL url = locateIncludeFile(locator.getBasePath(), fileName);
1826        if (url == null)
1827        {
1828            final URL baseURL = locator.getSourceURL();
1829            if (baseURL != null)
1830            {
1831                url = locateIncludeFile(baseURL.toString(), fileName);
1832            }
1833        }
1834
1835        if (optional && url == null)
1836        {
1837            return;
1838        }
1839
1840        if (url == null)
1841        {
1842            throw new ConfigurationException("Cannot resolve include file "
1843                    + fileName);
1844        }
1845
1846        final FileHandler fh = new FileHandler(this);
1847        fh.setFileLocator(locator);
1848        final FileLocator orgLocator = locator;
1849        try
1850        {
1851            fh.load(url);
1852        }
1853        finally
1854        {
1855            locator = orgLocator; // reset locator which is changed by load
1856        }
1857    }
1858
1859    /**
1860     * Tries to obtain the URL of an include file using the specified (optional)
1861     * base path and file name.
1862     *
1863     * @param basePath the base path
1864     * @param fileName the file name
1865     * @return the URL of the include file or <b>null</b> if it cannot be
1866     *         resolved
1867     */
1868    private URL locateIncludeFile(final String basePath, final String fileName)
1869    {
1870        final FileLocator includeLocator =
1871                FileLocatorUtils.fileLocator(locator).sourceURL(null)
1872                        .basePath(basePath).fileName(fileName).create();
1873        return FileLocatorUtils.locate(includeLocator);
1874    }
1875}