View Javadoc

    1   /*
    2    * Copyright 2001-2004 The Apache Software Foundation.
    3    *
    4    * Licensed under the Apache License, Version 2.0 (the "License")
    5    * you may not use this file except in compliance with the License.
    6    * You may obtain a copy of the License at
    7    *
    8    *     http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16
    17  package org.apache.commons.configuration;
    18
    19  import java.io.File;
    20  import java.io.FilterWriter;
    21  import java.io.IOException;
    22  import java.io.LineNumberReader;
    23  import java.io.Reader;
    24  import java.io.Writer;
    25  import java.net.URL;
    26  import java.util.Date;
    27  import java.util.Iterator;
    28  import java.util.List;
    29
    30  import org.apache.commons.lang.StringEscapeUtils;
    31  import org.apache.commons.lang.StringUtils;
    32
    33  /***
    34   * This is the "classic" Properties loader which loads the values from
    35   * a single or multiple files (which can be chained with "include =".
    36   * All given path references are either absolute or relative to the
    37   * file name supplied in the Constructor.
    38   * <p>
    39   * In this class, empty PropertyConfigurations can be built, properties
    40   * added and later saved. include statements are (obviously) not supported
    41   * if you don't construct a PropertyConfiguration from a file.
    42   *
    43   * <p>The properties file syntax is explained here:
    44   *
    45   * <ul>
    46   *  <li>
    47   *   Each property has the syntax <code>key = value</code>
    48   *  </li>
    49   *  <li>
    50   *   The <i>key</i> may use any character but the equal sign '='.
    51   *  </li>
    52   *  <li>
    53   *   <i>value</i> may be separated on different lines if a backslash
    54   *   is placed at the end of the line that continues below.
    55   *  </li>
    56   *  <li>
    57   *   If <i>value</i> is a list of strings, each token is separated
    58   *   by a comma ',' by default.
    59   *  </li>
    60   *  <li>
    61   *   Commas in each token are escaped placing a backslash right before
    62   *   the comma.
    63   *  </li>
    64   *  <li>
    65   *   If a <i>key</i> is used more than once, the values are appended
    66   *   like if they were on the same line separated with commas.
    67   *  </li>
    68   *  <li>
    69   *   Blank lines and lines starting with character '#' are skipped.
    70   *  </li>
    71   *  <li>
    72   *   If a property is named "include" (or whatever is defined by
    73   *   setInclude() and getInclude() and the value of that property is
    74   *   the full path to a file on disk, that file will be included into
    75   *   the ConfigurationsRepository. You can also pull in files relative
    76   *   to the parent configuration file. So if you have something
    77   *   like the following:
    78   *
    79   *   include = additional.properties
    80   *
    81   *   Then "additional.properties" is expected to be in the same
    82   *   directory as the parent configuration file.
    83   *
    84   *   Duplicate name values will be replaced, so be careful.
    85   *
    86   *  </li>
    87   * </ul>
    88   *
    89   * <p>Here is an example of a valid extended properties file:
    90   *
    91   * <p><pre>
    92   *      # lines starting with # are comments
    93   *
    94   *      # This is the simplest property
    95   *      key = value
    96   *
    97   *      # A long property may be separated on multiple lines
    98   *      longvalue = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
    99   *                  aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
    100  *
    101  *      # This is a property with many tokens
    102  *      tokens_on_a_line = first token, second token
    103  *
    104  *      # This sequence generates exactly the same result
    105  *      tokens_on_multiple_lines = first token
    106  *      tokens_on_multiple_lines = second token
    107  *
    108  *      # commas may be escaped in tokens
    109  *      commas.excaped = Hi\, what'up?
    110  *
    111  *      # properties can reference other properties
    112  *      base.prop = /base
    113  *      first.prop = ${base.prop}/first
    114  *      second.prop = ${first.prop}/second
    115  * </pre>
    116  *
    117  * @author <a href="mailto:e.bourg@cross-systems.com">Emmanuel Bourg</a>
    118  * @author <a href="mailto:stefano@apache.org">Stefano Mazzocchi</a>
    119  * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
    120  * @author <a href="mailto:daveb@miceda-data">Dave Bryson</a>
    121  * @author <a href="mailto:geirm@optonline.net">Geir Magnusson Jr.</a>
    122  * @author <a href="mailto:leon@opticode.co.za">Leon Messerschmidt</a>
    123  * @author <a href="mailto:kjohnson@transparent.com">Kent Johnson</a>
    124  * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
    125  * @author <a href="mailto:ipriha@surfeu.fi">Ilkka Priha</a>
    126  * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
    127  * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
    128  * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    129  * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a>
    130  * @author <a href="mailto:oliver.heger@t-online.de">Oliver Heger</a>
    131  * @version $Id: PropertiesConfiguration.java,v 1.15 2004/09/23 11:45:07 ebourg Exp $
    132  */
    133 public class PropertiesConfiguration extends AbstractFileConfiguration
    134 {
    135     /***
    136      * This is the name of the property that can point to other
    137      * properties file for including other properties files.
    138      */
    139     static String include = "include";
    140
    141     /*** Allow file inclusion or not */
    142     private boolean includesAllowed;
    143
    144     /***
    145      * Creates an empty PropertyConfiguration object which can be
    146      * used to synthesize a new Properties file by adding values and
    147      * then saving(). An object constructed by this C'tor can not be
    148      * tickled into loading included files because it cannot supply a
    149      * base for relative includes.
    150      */
    151     public PropertiesConfiguration()
    152     {
    153         setIncludesAllowed(false);
    154     }
    155
    156     /***
    157      * Creates and loads the extended properties from the specified file.
    158      * The specified file can contain "include = " properties which then
    159      * are loaded and merged into the properties.
    160      *
    161      * @param fileName The name of the properties file to load.
    162      * @throws ConfigurationException Error while loading the properties file
    163      */
    164     public PropertiesConfiguration(String fileName) throws ConfigurationException
    165     {
    166         // enable includes
    167         setIncludesAllowed(true);
    168
    169         // store the file name
    170         this.fileName = fileName;
    171
    172         // locate the resource
    173         url = ConfigurationUtils.locate(fileName);
    174
    175         // update the base path
    176         setBasePath(ConfigurationUtils.getBasePath(url));
    177
    178         // load the file
    179         load();
    180     }
    181
    182     /***
    183      * Creates and loads the extended properties from the specified file.
    184      * The specified file can contain "include = " properties which then
    185      * are loaded and merged into the properties.
    186      *
    187      * @param file The properties file to load.
    188      * @throws ConfigurationException Error while loading the properties file
    189      */
    190     public PropertiesConfiguration(File file) throws ConfigurationException
    191     {
    192         // enable includes
    193         setIncludesAllowed(true);
    194
    195         // set the file and update the url, the base path and the file name
    196         setFile(file);
    197
    198         // load the file
    199         load();
    200     }
    201
    202     /***
    203      * Creates and loads the extended properties from the specified URL.
    204      * The specified file can contain "include = " properties which then
    205      * are loaded and merged into the properties.
    206      *
    207      * @param url The location of the properties file to load.
    208      * @throws ConfigurationException Error while loading the properties file
    209      */
    210     public PropertiesConfiguration(URL url) throws ConfigurationException
    211     {
    212         // enable includes
    213         setIncludesAllowed(true);
    214
    215         // set the URL and update the base path and the file name
    216         setURL(url);
    217
    218         // load the file
    219         load();
    220     }
    221
    222     /***
    223      * Gets the property value for including other properties files.
    224      * By default it is "include".
    225      *
    226      * @return A String.
    227      */
    228     public static String getInclude()
    229     {
    230         return PropertiesConfiguration.include;
    231     }
    232
    233     /***
    234      * Sets the property value for including other properties files.
    235      * By default it is "include".
    236      *
    237      * @param inc A String.
    238      */
    239     public static void setInclude(String inc)
    240     {
    241         PropertiesConfiguration.include = inc;
    242     }
    243
    244     /***
    245      * Controls whether additional files can be loaded by the include = <xxx>
    246      * statement or not. Base rule is, that objects created by the empty
    247      * C'tor can not have included files.
    248      *
    249      * @param includesAllowed includesAllowed True if Includes are allowed.
    250      */
    251     protected void setIncludesAllowed(boolean includesAllowed)
    252     {
    253         this.includesAllowed = includesAllowed;
    254     }
    255
    256     /***
    257      * Reports the status of file inclusion.
    258      *
    259      * @return True if include files are loaded.
    260      */
    261     public boolean getIncludesAllowed()
    262     {
    263         return this.includesAllowed;
    264     }
    265
    266     /***
    267      * Load the properties from the given input stream and using the specified
    268      * encoding.
    269      *
    270      * @param in An InputStream.
    271      *
    272      * @throws ConfigurationException
    273      */
    274     public synchronized void load(Reader in) throws ConfigurationException
    275     {
    276         PropertiesReader reader = new PropertiesReader(in);
    277
    278         try
    279         {
    280             while (true)
    281             {
    282                 String line = reader.readProperty();
    283
    284                 if (line == null)
    285                 {
    286                     break; // EOF
    287                 }
    288
    289                 int equalSign = line.indexOf('=');
    290                 if (equalSign > 0)
    291                 {
    292                     String key = line.substring(0, equalSign).trim();
    293                     String value = line.substring(equalSign + 1).trim();
    294
    295                     // Though some software (e.g. autoconf) may produce
    296                     // empty values like foo=\n, emulate the behavior of
    297                     // java.util.Properties by setting the value to the
    298                     // empty string.
    299
    300                     if (StringUtils.isNotEmpty(getInclude())
    301                         && key.equalsIgnoreCase(getInclude()))
    302                     {
    303                         if (getIncludesAllowed() && url != null)
    304                         {
    305                             String [] files = StringUtils.split(value, getDelimiter());
    306                             for (int i = 0; i < files.length; i++)
    307                             {
    308                                 load(ConfigurationUtils.locate(getBasePath(), files[i].trim()));
    309                             }
    310                         }
    311                     }
    312                     else
    313                     {
    314                         addProperty(key, unescapeJava(value));
    315                     }
    316                 }
    317             }
    318         }
    319         catch (IOException ioe)
    320         {
    321             throw new ConfigurationException("Could not load configuration from input stream.", ioe);
    322         }
    323     }
    324
    325     /***
    326      * Save the configuration to the specified stream.
    327      *
    328      * @param writer the output stream used to save the configuration
    329      */
    330     public void save(Writer writer) throws ConfigurationException
    331     {
    332         try
    333         {
    334             PropertiesWriter out = new PropertiesWriter(writer);
    335
    336             out.writeComment("written by PropertiesConfiguration");
    337             out.writeComment(new Date().toString());
    338
    339             Iterator keys = getKeys();
    340             while (keys.hasNext())
    341             {
    342                 String key = (String) keys.next();
    343                 Object value = getProperty(key);
    344
    345                 if (value instanceof List)
    346                 {
    347                     out.writeProperty(key, (List) value);
    348                 }
    349                 else
    350                 {
    351                     out.writeProperty(key, value);
    352                 }
    353             }
    354
    355             out.flush();
    356         }
    357         catch (IOException e)
    358         {
    359             throw new ConfigurationException(e.getMessage(), e);
    360         }
    361     }
    362
    363     /***
    364      * Extend the setBasePath method to turn includes
    365      * on and off based on the existence of a base path.
    366      *
    367      * @param basePath The new basePath to set.
    368      */
    369     public void setBasePath(String basePath)
    370     {
    371         super.setBasePath(basePath);
    372         setIncludesAllowed(StringUtils.isNotEmpty(basePath));
    373     }
    374
    375     /***
    376      * This class is used to read properties lines.  These lines do
    377      * not terminate with new-line chars but rather when there is no
    378      * backslash sign a the end of the line.  This is used to
    379      * concatenate multiple lines for readability.
    380      */
    381     public static class PropertiesReader extends LineNumberReader
    382     {
    383         /***
    384          * Constructor.
    385          *
    386          * @param reader A Reader.
    387          */
    388         public PropertiesReader(Reader reader)
    389         {
    390             super(reader);
    391         }
    392
    393         /***
    394          * Read a property. Returns null if Stream is
    395          * at EOF. Concatenates lines ending with "\".
    396          * Skips lines beginning with "#" and empty lines.
    397          *
    398          * @return A string containing a property value or null
    399          *
    400          * @throws IOException
    401          */
    402         public String readProperty() throws IOException
    403         {
    404             StringBuffer buffer = new StringBuffer();
    405
    406             while (true)
    407             {
    408                 String line = readLine();
    409                 if (line == null)
    410                 {
    411                     // EOF
    412                     return null;
    413                 }
    414
    415                 line = line.trim();
    416
    417                 if (StringUtils.isEmpty(line)
    418                         || (line.charAt(0) == '#'))
    419                 {
    420                     continue;
    421                 }
    422
    423                 if (line.endsWith("//"))
    424                 {
    425                     line = line.substring(0, line.length() - 1);
    426                     buffer.append(line);
    427                 }
    428                 else
    429                 {
    430                     buffer.append(line);
    431                     break;
    432                 }
    433             }
    434             return buffer.toString();
    435         }
    436     } // class PropertiesReader
    437
    438     /***
    439      * This class is used to write properties lines.
    440      */
    441     public static class PropertiesWriter extends FilterWriter
    442     {
    443         /***
    444          * Constructor.
    445          *
    446          * @param writer a Writer object providing the underlying stream
    447          */
    448         public PropertiesWriter(Writer writer) throws IOException
    449         {
    450             super(writer);
    451         }
    452
    453         /***
    454          * Write a property.
    455          *
    456          * @param key
    457          * @param value
    458          * @throws IOException
    459          */
    460         public void writeProperty(String key, Object value) throws IOException
    461         {
    462             write(key);
    463             write(" = ");
    464             if (value != null)
    465             {
    466                 String v = StringEscapeUtils.escapeJava(String.valueOf(value));
    467                 v = StringUtils.replace(v, String.valueOf(getDelimiter()), "//" + getDelimiter());
    468                 write(v);
    469             }
    470
    471             write('\n');
    472         }
    473
    474         /***
    475          * Write a property.
    476          *
    477          * @param key The key of the property
    478          * @param values The array of values of the property
    479          */
    480         public void writeProperty(String key, List values) throws IOException
    481         {
    482             for (int i = 0; i < values.size(); i++)
    483             {
    484                 writeProperty(key, values.get(i));
    485             }
    486         }
    487
    488         /***
    489          * Write a comment.
    490          *
    491          * @param comment
    492          * @throws IOException
    493          */
    494         public void writeComment(String comment) throws IOException
    495         {
    496             write("# " + comment + "\n");
    497         }
    498     } // class PropertiesWriter
    499
    500     /***
    501      * <p>Unescapes any Java literals found in the <code>String</code> to a
    502      * <code>Writer</code>.</p> This is a slightly modified version of the
    503      * StringEscapeUtils.unescapeJava() function in commons-lang that doesn't
    504      * drop escaped commas (i.e '\,').
    505      *
    506      * @param str  the <code>String</code> to unescape, may be null
    507      *
    508      * @throws IllegalArgumentException if the Writer is <code>null</code>
    509      */
    510     protected static String unescapeJava(String str)
    511     {
    512         if (str == null)
    513         {
    514             return null;
    515         }
    516         int sz = str.length();
    517         StringBuffer out = new StringBuffer(sz);
    518         StringBuffer unicode = new StringBuffer(4);
    519         boolean hadSlash = false;
    520         boolean inUnicode = false;
    521         for (int i = 0; i < sz; i++)
    522         {
    523             char ch = str.charAt(i);
    524             if (inUnicode)
    525             {
    526                 // if in unicode, then we're reading unicode
    527                 // values in somehow
    528                 unicode.append(ch);
    529                 if (unicode.length() == 4)
    530                 {
    531                     // unicode now contains the four hex digits
    532                     // which represents our unicode character
    533                     try
    534                     {
    535                         int value = Integer.parseInt(unicode.toString(), 16);
    536                         out.append((char) value);
    537                         unicode.setLength(0);
    538                         inUnicode = false;
    539                         hadSlash = false;
    540                     }
    541                     catch (NumberFormatException nfe)
    542                     {
    543                         throw new ConfigurationRuntimeException("Unable to parse unicode value: " + unicode, nfe);
    544                     }
    545                 }
    546                 continue;
    547             }
    548
    549             if (hadSlash)
    550             {
    551                 // handle an escaped value
    552                 hadSlash = false;
    553
    554                 if (ch=='//'){
    555                     out.append('//');
    556                 }
    557                 else if (ch=='\''){
    558                     out.append('\'');
    559                 }
    560                 else if (ch=='\"'){
    561                     out.append('"');
    562                 }
    563                 else if (ch=='r'){
    564                     out.append('\r');
    565                 }
    566                 else if (ch=='f'){
    567                     out.append('\f');
    568                 }
    569                 else if (ch=='t'){
    570                     out.append('\t');
    571                 }
    572                 else if (ch=='n'){
    573                     out.append('\n');
    574                 }
    575                 else if (ch=='b'){
    576                     out.append('\b');
    577                 }
    578                 else if (ch==getDelimiter()){
    579                     out.append('//');
    580                     out.append(getDelimiter());
    581                 }
    582                 else if (ch=='u'){
    583                     //                  uh-oh, we're in unicode country....
    584                     inUnicode = true;
    585                 }
    586                 else {
    587                     out.append(ch);
    588                 }
    589
    590                 continue;
    591             }
    592             else if (ch == '//')
    593             {
    594                 hadSlash = true;
    595                 continue;
    596             }
    597             out.append(ch);
    598         }
    599
    600         if (hadSlash)
    601         {
    602             // then we're in the weird case of a \ at the end of the
    603             // string, let's output it anyway.
    604             out.append('//');
    605         }
    606
    607         return out.toString();
    608     }
    609
    610 }