View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17
    18  package org.apache.commons.configuration;
    19
    20  import java.io.File;
    21  import java.io.FilterWriter;
    22  import java.io.IOException;
    23  import java.io.LineNumberReader;
    24  import java.io.Reader;
    25  import java.io.Writer;
    26  import java.net.URL;
    27  import java.util.ArrayList;
    28  import java.util.Iterator;
    29  import java.util.List;
    30
    31  import org.apache.commons.lang.ArrayUtils;
    32  import org.apache.commons.lang.StringEscapeUtils;
    33  import org.apache.commons.lang.StringUtils;
    34
    35  /***
    36   * This is the "classic" Properties loader which loads the values from
    37   * a single or multiple files (which can be chained with "include =".
    38   * All given path references are either absolute or relative to the
    39   * file name supplied in the constructor.
    40   * <p>
    41   * In this class, empty PropertyConfigurations can be built, properties
    42   * added and later saved. include statements are (obviously) not supported
    43   * if you don't construct a PropertyConfiguration from a file.
    44   *
    45   * <p>The properties file syntax is explained here, basically it follows
    46   * the syntax of the stream parsed by {@link java.util.Properties#load} and
    47   * adds several useful extensions:
    48   *
    49   * <ul>
    50   *  <li>
    51   *   Each property has the syntax <code>key &lt;separator> value</code>. The
    52   *   separators accepted are <code>'='</code>, <code>':'</code> and any white
    53   *   space character. Examples:
    54   * <pre>
    55   *  key1 = value1
    56   *  key2 : value2
    57   *  key3   value3</pre>
    58   *  </li>
    59   *  <li>
    60   *   The <i>key</i> may use any character, separators must be escaped:
    61   * <pre>
    62   *  key\:foo = bar</pre>
    63   *  </li>
    64   *  <li>
    65   *   <i>value</i> may be separated on different lines if a backslash
    66   *   is placed at the end of the line that continues below.
    67   *  </li>
    68   *  <li>
    69   *   <i>value</i> can contain <em>value delimiters</em> and will then be interpreted
    70   *   as a list of tokens. Default value delimiter is the comma ','. So the
    71   *   following property definition
    72   * <pre>
    73   *  key = This property, has multiple, values
    74   * </pre>
    75   *   will result in a property with three values. You can change the value
    76   *   delimiter using the <code>{@link AbstractConfiguration#setListDelimiter(char)}</code>
    77   *   method. Setting the delimiter to 0 will disable value splitting completely.
    78   *  </li>
    79   *  <li>
    80   *   Commas in each token are escaped placing a backslash right before
    81   *   the comma.
    82   *  </li>
    83   *  <li>
    84   *   If a <i>key</i> is used more than once, the values are appended
    85   *   like if they were on the same line separated with commas.
    86   *  </li>
    87   *  <li>
    88   *   Blank lines and lines starting with character '#' or '!' are skipped.
    89   *  </li>
    90   *  <li>
    91   *   If a property is named "include" (or whatever is defined by
    92   *   setInclude() and getInclude() and the value of that property is
    93   *   the full path to a file on disk, that file will be included into
    94   *   the configuration. You can also pull in files relative to the parent
    95   *   configuration file. So if you have something like the following:
    96   *
    97   *   include = additional.properties
    98   *
    99   *   Then "additional.properties" is expected to be in the same
    100  *   directory as the parent configuration file.
    101  *
    102  *   The properties in the included file are added to the parent configuration,
    103  *   they do not replace existing properties with the same key.
    104  *
    105  *  </li>
    106  * </ul>
    107  *
    108  * <p>Here is an example of a valid extended properties file:
    109  *
    110  * <p><pre>
    111  *      # lines starting with # are comments
    112  *
    113  *      # This is the simplest property
    114  *      key = value
    115  *
    116  *      # A long property may be separated on multiple lines
    117  *      longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
    118  *                  aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
    119  *
    120  *      # This is a property with many tokens
    121  *      tokens_on_a_line = first token, second token
    122  *
    123  *      # This sequence generates exactly the same result
    124  *      tokens_on_multiple_lines = first token
    125  *      tokens_on_multiple_lines = second token
    126  *
    127  *      # commas may be escaped in tokens
    128  *      commas.escaped = Hi\, what'up?
    129  *
    130  *      # properties can reference other properties
    131  *      base.prop = /base
    132  *      first.prop = ${base.prop}/first
    133  *      second.prop = ${first.prop}/second
    134  * </pre>
    135  *
    136  * <p>A <code>PropertiesConfiguration</code> object is associated with an
    137  * instance of the <code>{@link PropertiesConfigurationLayout}</code> class,
    138  * which is responsible for storing the layout of the parsed properties file
    139  * (i.e. empty lines, comments, and such things). The <code>getLayout()</code>
    140  * method can be used to obtain this layout object. With <code>setLayout()</code>
    141  * a new layout object can be set. This should be done before a properties file
    142  * was loaded.
    143  *
    144  * @see java.util.Properties#load
    145  *
    146  * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
    147  * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
    148  * @author <a href="mailto:daveb@miceda-data">Dave Bryson</a>
    149  * @author <a href="mailto:geirm@optonline.net">Geir Magnusson Jr.</a>
    150  * @author <a href="mailto:leon@opticode.co.za">Leon Messerschmidt</a>
    151  * @author <a href="mailto:kjohnson@transparent.com">Kent Johnson</a>
    152  * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
    153  * @author <a href="mailto:ipriha@surfeu.fi">Ilkka Priha</a>
    154  * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
    155  * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
    156  * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    157  * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a>
    158  * @author <a href="mailto:oliver.heger@t-online.de">Oliver Heger</a>
    159  * @author <a href="mailto:ebourg@apache.org">Emmanuel Bourg</a>
    160  * @version $Id: PropertiesConfiguration.java 439648 2006-09-02 20:42:10Z oheger $
    161  */
    162 public class PropertiesConfiguration extends AbstractFileConfiguration
    163 {
    164     /*** Constant for the supported comment characters.*/
    165     static final String COMMENT_CHARS = "#!";
    166
    167     /***
    168      * This is the name of the property that can point to other
    169      * properties file for including other properties files.
    170      */
    171     private static String include = "include";
    172
    173     /*** The list of possible key/value separators */
    174     private static final char[] SEPARATORS = new char[] {'=', ':'};
    175
    176     /*** The white space characters used as key/value separators. */
    177     private static final char[] WHITE_SPACE = new char[]{' ', '\t', '\f'};
    178
    179     /***
    180      * The default encoding (ISO-8859-1 as specified by
    181      * http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html)
    182      */
    183     private static final String DEFAULT_ENCODING = "ISO-8859-1";
    184
    185     /*** Constant for the platform specific line separator.*/
    186     private static final String LINE_SEPARATOR = System.getProperty("line.separator");
    187
    188     /*** Constant for the radix of hex numbers.*/
    189     private static final int HEX_RADIX = 16;
    190
    191     /*** Constant for the length of a unicode literal.*/
    192     private static final int UNICODE_LEN = 4;
    193
    194     /*** Stores the layout object.*/
    195     private PropertiesConfigurationLayout layout;
    196
    197     /*** Allow file inclusion or not */
    198     private boolean includesAllowed;
    199
    200     // initialization block to set the encoding before loading the file in the constructors
    201     {
    202         setEncoding(DEFAULT_ENCODING);
    203     }
    204
    205     /***
    206      * Creates an empty PropertyConfiguration object which can be
    207      * used to synthesize a new Properties file by adding values and
    208      * then saving().
    209      */
    210     public PropertiesConfiguration()
    211     {
    212         layout = createLayout();
    213         setIncludesAllowed(false);
    214     }
    215
    216     /***
    217      * Creates and loads the extended properties from the specified file.
    218      * The specified file can contain "include = " properties which then
    219      * are loaded and merged into the properties.
    220      *
    221      * @param fileName The name of the properties file to load.
    222      * @throws ConfigurationException Error while loading the properties file
    223      */
    224     public PropertiesConfiguration(String fileName) throws ConfigurationException
    225     {
    226         super(fileName);
    227     }
    228
    229     /***
    230      * Creates and loads the extended properties from the specified file.
    231      * The specified file can contain "include = " properties which then
    232      * are loaded and merged into the properties.
    233      *
    234      * @param file The properties file to load.
    235      * @throws ConfigurationException Error while loading the properties file
    236      */
    237     public PropertiesConfiguration(File file) throws ConfigurationException
    238     {
    239         super(file);
    240     }
    241
    242     /***
    243      * Creates and loads the extended properties from the specified URL.
    244      * The specified file can contain "include = " properties which then
    245      * are loaded and merged into the properties.
    246      *
    247      * @param url The location of the properties file to load.
    248      * @throws ConfigurationException Error while loading the properties file
    249      */
    250     public PropertiesConfiguration(URL url) throws ConfigurationException
    251     {
    252         super(url);
    253     }
    254
    255     /***
    256      * Gets the property value for including other properties files.
    257      * By default it is "include".
    258      *
    259      * @return A String.
    260      */
    261     public static String getInclude()
    262     {
    263         return PropertiesConfiguration.include;
    264     }
    265
    266     /***
    267      * Sets the property value for including other properties files.
    268      * By default it is "include".
    269      *
    270      * @param inc A String.
    271      */
    272     public static void setInclude(String inc)
    273     {
    274         PropertiesConfiguration.include = inc;
    275     }
    276
    277     /***
    278      * Controls whether additional files can be loaded by the include = <xxx>
    279      * statement or not. Base rule is, that objects created by the empty
    280      * C'tor can not have included files.
    281      *
    282      * @param includesAllowed includesAllowed True if Includes are allowed.
    283      */
    284     protected void setIncludesAllowed(boolean includesAllowed)
    285     {
    286         this.includesAllowed = includesAllowed;
    287     }
    288
    289     /***
    290      * Reports the status of file inclusion.
    291      *
    292      * @return True if include files are loaded.
    293      */
    294     public boolean getIncludesAllowed()
    295     {
    296         return this.includesAllowed;
    297     }
    298
    299     /***
    300      * Return the comment header.
    301      *
    302      * @return the comment header
    303      * @since 1.1
    304      */
    305     public String getHeader()
    306     {
    307         return getLayout().getHeaderComment();
    308     }
    309
    310     /***
    311      * Set the comment header.
    312      *
    313      * @param header the header to use
    314      * @since 1.1
    315      */
    316     public void setHeader(String header)
    317     {
    318         getLayout().setHeaderComment(header);
    319     }
    320
    321     /***
    322      * Returns the associated layout object.
    323      *
    324      * @return the associated layout object
    325      * @since 1.3
    326      */
    327     public synchronized PropertiesConfigurationLayout getLayout()
    328     {
    329         if (layout == null)
    330         {
    331             layout = createLayout();
    332         }
    333         return layout;
    334     }
    335
    336     /***
    337      * Sets the associated layout object.
    338      *
    339      * @param layout the new layout object; can be <b>null</b>, then a new
    340      * layout object will be created
    341      * @since 1.3
    342      */
    343     public synchronized void setLayout(PropertiesConfigurationLayout layout)
    344     {
    345         // only one layout must exist
    346         if (this.layout != null)
    347         {
    348             removeConfigurationListener(this.layout);
    349         }
    350
    351         if (layout == null)
    352         {
    353             this.layout = createLayout();
    354         }
    355         else
    356         {
    357             this.layout = layout;
    358         }
    359     }
    360
    361     /***
    362      * Creates the associated layout object. This method is invoked when the
    363      * layout object is accessed and has not been created yet. Derived classes
    364      * can override this method to hook in a different layout implementation.
    365      *
    366      * @return the layout object to use
    367      * @since 1.3
    368      */
    369     protected PropertiesConfigurationLayout createLayout()
    370     {
    371         return new PropertiesConfigurationLayout(this);
    372     }
    373
    374     /***
    375      * Load the properties from the given reader.
    376      * Note that the <code>clear()</code> method is not called, so
    377      * the properties contained in the loaded file will be added to the
    378      * actual set of properties.
    379      *
    380      * @param in An InputStream.
    381      *
    382      * @throws ConfigurationException if an error occurs
    383      */
    384     public synchronized void load(Reader in) throws ConfigurationException
    385     {
    386         boolean oldAutoSave = isAutoSave();
    387         setAutoSave(false);
    388
    389         try
    390         {
    391             getLayout().load(in);
    392         }
    393         finally
    394         {
    395             setAutoSave(oldAutoSave);
    396         }
    397     }
    398
    399     /***
    400      * Save the configuration to the specified stream.
    401      *
    402      * @param writer the output stream used to save the configuration
    403      * @throws ConfigurationException if an error occurs
    404      */
    405     public void save(Writer writer) throws ConfigurationException
    406     {
    407         enterNoReload();
    408         try
    409         {
    410             getLayout().save(writer);
    411         }
    412         finally
    413         {
    414             exitNoReload();
    415         }
    416     }
    417
    418     /***
    419      * Extend the setBasePath method to turn includes
    420      * on and off based on the existence of a base path.
    421      *
    422      * @param basePath The new basePath to set.
    423      */
    424     public void setBasePath(String basePath)
    425     {
    426         super.setBasePath(basePath);
    427         setIncludesAllowed(StringUtils.isNotEmpty(basePath));
    428     }
    429
    430     /***
    431      * Creates a copy of this object.
    432      *
    433      * @return the copy
    434      */
    435     public Object clone()
    436     {
    437         PropertiesConfiguration copy = (PropertiesConfiguration) super.clone();
    438         if (layout != null)
    439         {
    440             copy.setLayout(new PropertiesConfigurationLayout(copy, layout));
    441         }
    442         return copy;
    443     }
    444
    445     /***
    446      * This method is invoked by the associated
    447      * <code>{@link PropertiesConfigurationLayout}</code> object for each
    448      * property definition detected in the parsed properties file. Its task is
    449      * to check whether this is a special property definition (e.g. the
    450      * <code>include</code> property). If not, the property must be added to
    451      * this configuration. The return value indicates whether the property
    452      * should be treated as a normal property. If it is <b>false</b>, the
    453      * layout object will ignore this property.
    454      *
    455      * @param key the property key
    456      * @param value the property value
    457      * @return a flag whether this is a normal property
    458      * @throws ConfigurationException if an error occurs
    459      * @since 1.3
    460      */
    461     boolean propertyLoaded(String key, String value)
    462             throws ConfigurationException
    463     {
    464         boolean result;
    465
    466         if (StringUtils.isNotEmpty(getInclude())
    467                 && key.equalsIgnoreCase(getInclude()))
    468         {
    469             if (getIncludesAllowed())
    470             {
    471                 String[] files;
    472                 if (!isDelimiterParsingDisabled())
    473                 {
    474                     files = StringUtils.split(value, getListDelimiter());
    475                 }
    476                 else
    477                 {
    478                     files = new String[]{value};
    479                 }
    480                 for (int i = 0; i < files.length; i++)
    481                 {
    482                     loadIncludeFile(files[i].trim());
    483                 }
    484             }
    485             result = false;
    486         }
    487
    488         else
    489         {
    490             addProperty(key, value);
    491             result = true;
    492         }
    493
    494         return result;
    495     }
    496
    497     /***
    498      * Tests whether a line is a comment, i.e. whether it starts with a comment
    499      * character.
    500      *
    501      * @param line the line
    502      * @return a flag if this is a comment line
    503      * @since 1.3
    504      */
    505     static boolean isCommentLine(String line)
    506     {
    507         String s = line.trim();
    508         // blanc lines are also treated as comment lines
    509         return s.length() < 1 || COMMENT_CHARS.indexOf(s.charAt(0)) >= 0;
    510     }
    511
    512     /***
    513      * This class is used to read properties lines. These lines do
    514      * not terminate with new-line chars but rather when there is no
    515      * backslash sign a the end of the line.  This is used to
    516      * concatenate multiple lines for readability.
    517      */
    518     public static class PropertiesReader extends LineNumberReader
    519     {
    520         /*** Stores the comment lines for the currently processed property.*/
    521         private List commentLines;
    522
    523         /*** Stores the name of the last read property.*/
    524         private String propertyName;
    525
    526         /*** Stores the value of the last read property.*/
    527         private String propertyValue;
    528
    529         /*** Stores the list delimiter character.*/
    530         private char delimiter;
    531
    532         /***
    533          * Constructor.
    534          *
    535          * @param reader A Reader.
    536          */
    537         public PropertiesReader(Reader reader)
    538         {
    539             this(reader, AbstractConfiguration.getDefaultListDelimiter());
    540         }
    541
    542         /***
    543          * Creates a new instance of <code>PropertiesReader</code> and sets
    544          * the underlaying reader and the list delimiter.
    545          *
    546          * @param reader the reader
    547          * @param listDelimiter the list delimiter character
    548          * @since 1.3
    549          */
    550         public PropertiesReader(Reader reader, char listDelimiter)
    551         {
    552             super(reader);
    553             commentLines = new ArrayList();
    554             delimiter = listDelimiter;
    555         }
    556
    557         /***
    558          * Reads a property line. Returns null if Stream is
    559          * at EOF. Concatenates lines ending with "\".
    560          * Skips lines beginning with "#" or "!" and empty lines.
    561          * The return value is a property definition (<code>&lt;name&gt;</code>
    562          * = <code>&lt;value&gt;</code>)
    563          *
    564          * @return A string containing a property value or null
    565          *
    566          * @throws IOException in case of an I/O error
    567          */
    568         public String readProperty() throws IOException
    569         {
    570             commentLines.clear();
    571             StringBuffer buffer = new StringBuffer();
    572
    573             while (true)
    574             {
    575                 String line = readLine();
    576                 if (line == null)
    577                 {
    578                     // EOF
    579                     return null;
    580                 }
    581
    582                 if (isCommentLine(line))
    583                 {
    584                     commentLines.add(line);
    585                     continue;
    586                 }
    587
    588                 line = line.trim();
    589
    590                 if (checkCombineLines(line))
    591                 {
    592                     line = line.substring(0, line.length() - 1);
    593                     buffer.append(line);
    594                 }
    595                 else
    596                 {
    597                     buffer.append(line);
    598                     break;
    599                 }
    600             }
    601             return buffer.toString();
    602         }
    603
    604         /***
    605          * Parses the next property from the input stream and stores the found
    606          * name and value in internal fields. These fields can be obtained using
    607          * the provided getter methods. The return value indicates whether EOF
    608          * was reached (<b>false</b>) or whether further properties are
    609          * available (<b>true</b>).
    610          *
    611          * @return a flag if further properties are available
    612          * @throws IOException if an error occurs
    613          * @since 1.3
    614          */
    615         public boolean nextProperty() throws IOException
    616         {
    617             String line = readProperty();
    618
    619             if (line == null)
    620             {
    621                 return false; // EOF
    622             }
    623
    624             // parse the line
    625             String[] property = parseProperty(line);
    626             propertyName = StringEscapeUtils.unescapeJava(property[0]);
    627             propertyValue = unescapeJava(property[1], delimiter);
    628             return true;
    629         }
    630
    631         /***
    632          * Returns the comment lines that have been read for the last property.
    633          *
    634          * @return the comment lines for the last property returned by
    635          * <code>readProperty()</code>
    636          * @since 1.3
    637          */
    638         public List getCommentLines()
    639         {
    640             return commentLines;
    641         }
    642
    643         /***
    644          * Returns the name of the last read property. This method can be called
    645          * after <code>{@link #nextProperty()}</code> was invoked and its
    646          * return value was <b>true</b>.
    647          *
    648          * @return the name of the last read property
    649          * @since 1.3
    650          */
    651         public String getPropertyName()
    652         {
    653             return propertyName;
    654         }
    655
    656         /***
    657          * Returns the value of the last read property. This method can be
    658          * called after <code>{@link #nextProperty()}</code> was invoked and
    659          * its return value was <b>true</b>.
    660          *
    661          * @return the value of the last read property
    662          * @since 1.3
    663          */
    664         public String getPropertyValue()
    665         {
    666             return propertyValue;
    667         }
    668
    669         /***
    670          * Checks if the passed in line should be combined with the following.
    671          * This is true, if the line ends with an odd number of backslashes.
    672          *
    673          * @param line the line
    674          * @return a flag if the lines should be combined
    675          */
    676         private static boolean checkCombineLines(String line)
    677         {
    678             int bsCount = 0;
    679             for (int idx = line.length() - 1; idx >= 0 && line.charAt(idx) == '//'; idx--)
    680             {
    681                 bsCount++;
    682             }
    683
    684             return bsCount % 2 == 1;
    685         }
    686
    687         /***
    688          * Parse a property line and return the key and the value in an array.
    689          *
    690          * @param line the line to parse
    691          * @return an array with the property's key and value
    692          * @since 1.2
    693          */
    694         private static String[] parseProperty(String line)
    695         {
    696             // sorry for this spaghetti code, please replace it as soon as
    697             // possible with a regexp when the Java 1.3 requirement is dropped
    698
    699             String[] result = new String[2];
    700             StringBuffer key = new StringBuffer();
    701             StringBuffer value = new StringBuffer();
    702
    703             // state of the automaton:
    704             // 0: key parsing
    705             // 1: antislash found while parsing the key
    706             // 2: separator crossing
    707             // 3: value parsing
    708             int state = 0;
    709
    710             for (int pos = 0; pos < line.length(); pos++)
    711             {
    712                 char c = line.charAt(pos);
    713
    714                 switch (state)
    715                 {
    716                     case 0:
    717                         if (c == '//')
    718                         {
    719                             state = 1;
    720                         }
    721                         else if (ArrayUtils.contains(WHITE_SPACE, c))
    722                         {
    723                             // switch to the separator crossing state
    724                             state = 2;
    725                         }
    726                         else if (ArrayUtils.contains(SEPARATORS, c))
    727                         {
    728                             // switch to the value parsing state
    729                             state = 3;
    730                         }
    731                         else
    732                         {
    733                             key.append(c);
    734                         }
    735
    736                         break;
    737
    738                     case 1:
    739                         if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c))
    740                         {
    741                             // this is an escaped separator or white space
    742                             key.append(c);
    743                         }
    744                         else
    745                         {
    746                             // another escaped character, the '\' is preserved
    747                             key.append('//');
    748                             key.append(c);
    749                         }
    750
    751                         // return to the key parsing state
    752                         state = 0;
    753
    754                         break;
    755
    756                     case 2:
    757                         if (ArrayUtils.contains(WHITE_SPACE, c))
    758                         {
    759                             // do nothing, eat all white spaces
    760                             state = 2;
    761                         }
    762                         else if (ArrayUtils.contains(SEPARATORS, c))
    763                         {
    764                             // switch to the value parsing state
    765                             state = 3;
    766                         }
    767                         else
    768                         {
    769                             // any other character indicates we encoutered the beginning of the value
    770                             value.append(c);
    771
    772                             // switch to the value parsing state
    773                             state = 3;
    774                         }
    775
    776                         break;
    777
    778                     case 3:
    779                         value.append(c);
    780                         break;
    781                 }
    782             }
    783
    784             result[0] = key.toString().trim();
    785             result[1] = value.toString().trim();
    786
    787             return result;
    788         }
    789     } // class PropertiesReader
    790
    791     /***
    792      * This class is used to write properties lines.
    793      */
    794     public static class PropertiesWriter extends FilterWriter
    795     {
    796         /*** The delimiter for multi-valued properties.*/
    797         private char delimiter;
    798
    799         /***
    800          * Constructor.
    801          *
    802          * @param writer a Writer object providing the underlying stream
    803          * @param delimiter the delimiter character for multi-valued properties
    804          */
    805         public PropertiesWriter(Writer writer, char delimiter)
    806         {
    807             super(writer);
    808             this.delimiter = delimiter;
    809         }
    810
    811         /***
    812          * Write a property.
    813          *
    814          * @param key the key of the property
    815          * @param value the value of the property
    816          *
    817          * @throws IOException if an I/O error occurs
    818          */
    819         public void writeProperty(String key, Object value) throws IOException
    820         {
    821             writeProperty(key, value, false);
    822         }
    823
    824         /***
    825          * Write a property.
    826          *
    827          * @param key The key of the property
    828          * @param values The array of values of the property
    829          *
    830          * @throws IOException if an I/O error occurs
    831          */
    832         public void writeProperty(String key, List values) throws IOException
    833         {
    834             for (int i = 0; i < values.size(); i++)
    835             {
    836                 writeProperty(key, values.get(i));
    837             }
    838         }
    839
    840         /***
    841          * Writes the given property and its value. If the value happens to be a
    842          * list, the <code>forceSingleLine</code> flag is evaluated. If it is
    843          * set, all values are written on a single line using the list delimiter
    844          * as separator.
    845          *
    846          * @param key the property key
    847          * @param value the property value
    848          * @param forceSingleLine the &quot;force single line&quot; flag
    849          * @throws IOException if an error occurs
    850          * @since 1.3
    851          */
    852         public void writeProperty(String key, Object value,
    853                 boolean forceSingleLine) throws IOException
    854         {
    855             String v;
    856
    857             if (value instanceof List)
    858             {
    859                 List values = (List) value;
    860                 if (forceSingleLine)
    861                 {
    862                     v = makeSingleLineValue(values);
    863                 }
    864                 else
    865                 {
    866                     writeProperty(key, values);
    867                     return;
    868                 }
    869             }
    870             else
    871             {
    872                 v = escapeValue(value);
    873             }
    874
    875             write(escapeKey(key));
    876             write(" = ");
    877             write(v);
    878
    879             writeln(null);
    880         }
    881
    882         /***
    883          * Write a comment.
    884          *
    885          * @param comment the comment to write
    886          * @throws IOException if an I/O error occurs
    887          */
    888         public void writeComment(String comment) throws IOException
    889         {
    890             writeln("# " + comment);
    891         }
    892
    893         /***
    894          * Escape the separators in the key.
    895          *
    896          * @param key the key
    897          * @return the escaped key
    898          * @since 1.2
    899          */
    900         private String escapeKey(String key)
    901         {
    902             StringBuffer newkey = new StringBuffer();
    903
    904             for (int i = 0; i < key.length(); i++)
    905             {
    906                 char c = key.charAt(i);
    907
    908                 if (ArrayUtils.contains(SEPARATORS, c) || ArrayUtils.contains(WHITE_SPACE, c))
    909                 {
    910                     // escape the separator
    911                     newkey.append('//');
    912                     newkey.append(c);
    913                 }
    914                 else
    915                 {
    916                     newkey.append(c);
    917                 }
    918             }
    919
    920             return newkey.toString();
    921         }
    922
    923         /***
    924          * Escapes the given property value. Delimiter characters in the value
    925          * will be escaped.
    926          *
    927          * @param value the property value
    928          * @return the escaped property value
    929          * @since 1.3
    930          */
    931         private String escapeValue(Object value)
    932         {
    933             String v = StringEscapeUtils.escapeJava(String.valueOf(value));
    934             return StringUtils.replace(v, String.valueOf(delimiter), "//"
    935                     + delimiter);
    936         }
    937
    938         /***
    939          * Transforms a list of values into a single line value.
    940          *
    941          * @param values the list with the values
    942          * @return a string with the single line value (can be <b>null</b>)
    943          * @since 1.3
    944          */
    945         private String makeSingleLineValue(List values)
    946         {
    947             if (!values.isEmpty())
    948             {
    949                 Iterator it = values.iterator();
    950                 StringBuffer buf = new StringBuffer(escapeValue(it.next()));
    951                 while (it.hasNext())
    952                 {
    953                     buf.append(delimiter);
    954                     buf.append(escapeValue(it.next()));
    955                 }
    956                 return buf.toString();
    957             }
    958             else
    959             {
    960                 return null;
    961             }
    962         }
    963
    964         /***
    965          * Helper method for writing a line with the platform specific line
    966          * ending.
    967          *
    968          * @param s the content of the line (may be <b>null</b>)
    969          * @throws IOException if an error occurs
    970          * @since 1.3
    971          */
    972         public void writeln(String s) throws IOException
    973         {
    974             if (s != null)
    975             {
    976                 write(s);
    977             }
    978             write(LINE_SEPARATOR);
    979         }
    980
    981     } // class PropertiesWriter
    982
    983     /***
    984      * <p>Unescapes any Java literals found in the <code>String</code> to a
    985      * <code>Writer</code>.</p> This is a slightly modified version of the
    986      * StringEscapeUtils.unescapeJava() function in commons-lang that doesn't
    987      * drop escaped separators (i.e '\,').
    988      *
    989      * @param str  the <code>String</code> to unescape, may be null
    990      * @param delimiter the delimiter for multi-valued properties
    991      * @return the processed string
    992      * @throws IllegalArgumentException if the Writer is <code>null</code>
    993      */
    994     protected static String unescapeJava(String str, char delimiter)
    995     {
    996         if (str == null)
    997         {
    998             return null;
    999         }
    1000         int sz = str.length();
    1001         StringBuffer out = new StringBuffer(sz);
    1002         StringBuffer unicode = new StringBuffer(UNICODE_LEN);
    1003         boolean hadSlash = false;
    1004         boolean inUnicode = false;
    1005         for (int i = 0; i < sz; i++)
    1006         {
    1007             char ch = str.charAt(i);
    1008             if (inUnicode)
    1009             {
    1010                 // if in unicode, then we're reading unicode
    1011                 // values in somehow
    1012                 unicode.append(ch);
    1013                 if (unicode.length() == UNICODE_LEN)
    1014                 {
    1015                     // unicode now contains the four hex digits
    1016                     // which represents our unicode character
    1017                     try
    1018                     {
    1019                         int value = Integer.parseInt(unicode.toString(), HEX_RADIX);
    1020                         out.append((char) value);
    1021                         unicode.setLength(0);
    1022                         inUnicode = false;
    1023                         hadSlash = false;
    1024                     }
    1025                     catch (NumberFormatException nfe)
    1026                     {
    1027                         throw new ConfigurationRuntimeException("Unable to parse unicode value: " + unicode, nfe);
    1028                     }
    1029                 }
    1030                 continue;
    1031             }
    1032
    1033             if (hadSlash)
    1034             {
    1035                 // handle an escaped value
    1036                 hadSlash = false;
    1037
    1038                 if (ch == '//')
    1039                 {
    1040                     out.append('//');
    1041                 }
    1042                 else if (ch == '\'')
    1043                 {
    1044                     out.append('\'');
    1045                 }
    1046                 else if (ch == '\"')
    1047                 {
    1048                     out.append('"');
    1049                 }
    1050                 else if (ch == 'r')
    1051                 {
    1052                     out.append('\r');
    1053                 }
    1054                 else if (ch == 'f')
    1055                 {
    1056                     out.append('\f');
    1057                 }
    1058                 else if (ch == 't')
    1059                 {
    1060                     out.append('\t');
    1061                 }
    1062                 else if (ch == 'n')
    1063                 {
    1064                     out.append('\n');
    1065                 }
    1066                 else if (ch == 'b')
    1067                 {
    1068                     out.append('\b');
    1069                 }
    1070                 else if (ch == delimiter)
    1071                 {
    1072                     out.append('//');
    1073                     out.append(delimiter);
    1074                 }
    1075                 else if (ch == 'u')
    1076                 {
    1077                     // uh-oh, we're in unicode country....
    1078                     inUnicode = true;
    1079                 }
    1080                 else
    1081                 {
    1082                     out.append(ch);
    1083                 }
    1084
    1085                 continue;
    1086             }
    1087             else if (ch == '//')
    1088             {
    1089                 hadSlash = true;
    1090                 continue;
    1091             }
    1092             out.append(ch);
    1093         }
    1094
    1095         if (hadSlash)
    1096         {
    1097             // then we're in the weird case of a \ at the end of the
    1098             // string, let's output it anyway.
    1099             out.append('//');
    1100         }
    1101
    1102         return out.toString();
    1103     }
    1104
    1105     /***
    1106      * Helper method for loading an included properties file. This method is
    1107      * called by <code>load()</code> when an <code>include</code> property
    1108      * is encountered. It tries to resolve relative file names based on the
    1109      * current base path. If this fails, a resolution based on the location of
    1110      * this properties file is tried.
    1111      *
    1112      * @param fileName the name of the file to load
    1113      * @throws ConfigurationException if loading fails
    1114      */
    1115     private void loadIncludeFile(String fileName) throws ConfigurationException
    1116     {
    1117         URL url = ConfigurationUtils.locate(getBasePath(), fileName);
    1118         if (url == null)
    1119         {
    1120             URL baseURL = getURL();
    1121             if (baseURL != null)
    1122             {
    1123                 url = ConfigurationUtils.locate(baseURL.toString(), fileName);
    1124             }
    1125         }
    1126
    1127         if (url == null)
    1128         {
    1129             throw new ConfigurationException("Cannot resolve include file "
    1130                     + fileName);
    1131         }
    1132         load(url);
    1133     }
    1134 }