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.BufferedReader;
    21  import java.io.File;
    22  import java.io.IOException;
    23  import java.io.PrintWriter;
    24  import java.io.Reader;
    25  import java.io.Writer;
    26  import java.net.URL;
    27  import java.util.Collection;
    28  import java.util.Iterator;
    29  import java.util.Set;
    30  import java.util.TreeSet;
    31
    32  import org.apache.commons.lang.StringUtils;
    33
    34  /***
    35   * <p>
    36   * An initialization or ini file is a configuration file typically found on
    37   * Microsoft's Windows operating system and contains data for Windows based
    38   * applications.
    39   * </p>
    40   *
    41   * <p>
    42   * Although popularized by Windows, ini files can be used on any system or
    43   * platform due to the fact that they are merely text files that can easily be
    44   * parsed and modified by both humans and computers.
    45   * </p>
    46   *
    47   * <p>
    48   * A typcial ini file could look something like:
    49   * </p>
    50   * <code>
    51   * [section1]<br>
    52   * ; this is a comment!<br>
    53   * var1 = foo<br>
    54   * var2 = bar<br>
    55   *<br>
    56   * [section2]<br>
    57   * var1 = doo<br>
    58   * </code>
    59   *
    60   * <p>
    61   * The format of ini files is fairly straight forward and is composed of three
    62   * components:<br>
    63   * <ul>
    64   * <li><b>Sections:</b> Ini files are split into sections, each section
    65   * starting with a section declaration. A section declaration starts with a '['
    66   * and ends with a ']'. Sections occur on one line only.</li>
    67   * <li><b>Parameters:</b> Items in a section are known as parameters.
    68   * Parameters have a typical <code>key = value</code> format.</li>
    69   * <li><b>Comments:</b> Lines starting with a ';' are assumed to be comments.
    70   * </li>
    71   * </ul>
    72   * </p>
    73   *
    74   * <p>
    75   * There are various implementations of the ini file format by various vendors
    76   * which has caused a number of differences to appear. As far as possible this
    77   * configuration tries to be lenient and support most of the differences.
    78   * </p>
    79   *
    80   * <p>
    81   * Some of the differences supported are as follows:
    82   * <ul>
    83   * <li><b>Comments:</b> The '#' character is also accepted as a comment
    84   * signifier.</li>
    85   * <li><b>Key value separtor:</b> The ':' character is also accepted in place
    86   * of '=' to separate keys and values in parameters, for example
    87   * <code>var1 : foo</code>.</li>
    88   * <li><b>Duplicate sections:</b> Typically duplicate sections are not allowed ,
    89   * this configuration does however support it. In the event of a duplicate
    90   * section, the two section's values are merged.</li>
    91   * <li><b>Duplicate parameters:</b> Typically duplicate parameters are only
    92   * allowed if they are in two different sections, thus they are local to
    93   * sections; this configuration simply merges duplicates; if a section has a
    94   * duplicate parameter the values are then added to the key as a list. </li>
    95   * </ul>
    96   * </p>
    97   * <p>
    98   * Global parameters are also allowed; any parameters declared before a section
    99   * is declared are added to a global section. It is important to note that this
    100  * global section does not have a name.
    101  * </p>
    102  * <p>
    103  * In all instances, a parameter's key is prepended with its section name and a
    104  * '.' (period). Thus a parameter named "var1" in "section1" will have the key
    105  * <code>section1.var1</code> in this configuration. Thus, a section's
    106  * parameters can easily be retrieved using the <code>subset</code> method
    107  * using the section name as the prefix.
    108  * </p>
    109  * <p>
    110  * <h3>Implementation Details:</h3>
    111  * Consider the following ini file:<br>
    112  * <code>
    113  *  default = ok<br>
    114  *  <br>
    115  *  [section1]<br>
    116  *  var1 = foo<br>
    117  *  var2 = doodle<br>
    118  *   <br>
    119  *  [section2]<br>
    120  *  ; a comment<br>
    121  *  var1 = baz<br>
    122  *  var2 = shoodle<br>
    123  *  bad =<br>
    124  *  = worse<br>
    125  *  <br>
    126  *  [section3]<br>
    127  *  # another comment<br>
    128  *  var1 : foo<br>
    129  *  var2 : bar<br>
    130  *  var5 : test1<br>
    131  *  <br>
    132  *  [section3]<br>
    133  *  var3 = foo<br>
    134  *  var4 = bar<br>
    135  *  var5 = test2<br>
    136  *  </code>
    137  * </p>
    138  * <p>
    139  * This ini file will be parsed without error. Note:
    140  * <ul>
    141  * <li>The parameter named "default" is added to the global section, it's value
    142  * is accessed simply using <code>getProperty("default")</code>.</li>
    143  * <li>Section 1's parameters can be accessed using
    144  * <code>getProperty("section1.var1")</code>.</li>
    145  * <li>The parameter named "bad" simply adds the parameter with an empty value.
    146  * </li>
    147  * <li>The empty key with value "= worse" is added using an empty key. This key
    148  * is still added to section 2 and the value can be accessed using
    149  * <code>getProperty("section2.")</code>, notice the period '.' following the
    150  * section name.</li>
    151  * <li>Section three uses both '=' and ':' to separate keys and values.</li>
    152  * <li>Section 3 has a duplicate key named "var5". The value for this key is
    153  * [test1, test2], and is represented as a List.</li>
    154  * </ul>
    155  * </p>
    156  * <p>
    157  * The set of sections in this configuration can be retrieved using the
    158  * <code>getSections</code> method.
    159  * </p>
    160  * <p>
    161  * <em>Note:</em> Configuration objects of this type can be read concurrently
    162  * by multiple threads. However if one of these threads modifies the object,
    163  * synchronization has to be performed manually.
    164  * </p>
    165  *
    166  * @author Trevor Miller
    167  * @version $Id: INIConfiguration.java 720600 2008-11-25 21:20:01Z oheger $
    168  * @since 1.4
    169  * @deprecated This class has been replaced by HierarchicalINIConfiguration,
    170  * which provides a superset of the functionality offered by this class.
    171  */
    172 public class INIConfiguration extends AbstractFileConfiguration
    173 {
    174     /***
    175      * The characters that signal the start of a comment line.
    176      */
    177     protected static final String COMMENT_CHARS = "#;";
    178
    179     /***
    180      * The characters used to separate keys from values.
    181      */
    182     protected static final String SEPARATOR_CHARS = "=:";
    183
    184     /***
    185      * Create a new empty INI Configuration.
    186      */
    187     public INIConfiguration()
    188     {
    189         super();
    190     }
    191
    192     /***
    193      * Create and load the ini configuration from the given file.
    194      *
    195      * @param filename The name pr path of the ini file to load.
    196      * @throws ConfigurationException If an error occurs while loading the file
    197      */
    198     public INIConfiguration(String filename) throws ConfigurationException
    199     {
    200         super(filename);
    201     }
    202
    203     /***
    204      * Create and load the ini configuration from the given file.
    205      *
    206      * @param file The ini file to load.
    207      * @throws ConfigurationException If an error occurs while loading the file
    208      */
    209     public INIConfiguration(File file) throws ConfigurationException
    210     {
    211         super(file);
    212     }
    213
    214     /***
    215      * Create and load the ini configuration from the given url.
    216      *
    217      * @param url The url of the ini file to load.
    218      * @throws ConfigurationException If an error occurs while loading the file
    219      */
    220     public INIConfiguration(URL url) throws ConfigurationException
    221     {
    222         super(url);
    223     }
    224
    225     /***
    226      * Save the configuration to the specified writer.
    227      *
    228      * @param writer - The writer to save the configuration to.
    229      * @throws ConfigurationException If an error occurs while writing the
    230      * configuration
    231      */
    232     public void save(Writer writer) throws ConfigurationException
    233     {
    234         PrintWriter out = new PrintWriter(writer);
    235         Iterator it = getSections().iterator();
    236         while (it.hasNext())
    237         {
    238             String section = (String) it.next();
    239             out.print("[");
    240             out.print(section);
    241             out.print("]");
    242             out.println();
    243
    244             Configuration subset = subset(section);
    245             Iterator keys = subset.getKeys();
    246             while (keys.hasNext())
    247             {
    248                 String key = (String) keys.next();
    249                 Object value = subset.getProperty(key);
    250                 if (value instanceof Collection)
    251                 {
    252                     Iterator values = ((Collection) value).iterator();
    253                     while (values.hasNext())
    254                     {
    255                         value = (Object) values.next();
    256                         out.print(key);
    257                         out.print(" = ");
    258                         out.print(formatValue(value.toString()));
    259                         out.println();
    260                     }
    261                 }
    262                 else
    263                 {
    264                     out.print(key);
    265                     out.print(" = ");
    266                     out.print(formatValue(value.toString()));
    267                     out.println();
    268                 }
    269             }
    270
    271             out.println();
    272         }
    273
    274         out.flush();
    275     }
    276
    277     /***
    278      * Load the configuration from the given reader. Note that the
    279      * <code>clear</code> method is not called so the configuration read in
    280      * will be merged with the current configuration.
    281      *
    282      * @param reader The reader to read the configuration from.
    283      * @throws ConfigurationException If an error occurs while reading the
    284      * configuration
    285      */
    286     public void load(Reader reader) throws ConfigurationException
    287     {
    288         try
    289         {
    290             BufferedReader bufferedReader = new BufferedReader(reader);
    291             String line = bufferedReader.readLine();
    292             String section = "";
    293             while (line != null)
    294             {
    295                 line = line.trim();
    296                 if (!isCommentLine(line))
    297                 {
    298                     if (isSectionLine(line))
    299                     {
    300                         section = line.substring(1, line.length() - 1) + ".";
    301                     }
    302                     else
    303                     {
    304                         String key = "";
    305                         String value = "";
    306                         int index = line.indexOf("=");
    307                         if (index >= 0)
    308                         {
    309                             key = section + line.substring(0, index);
    310                             value = parseValue(line.substring(index + 1));
    311                         }
    312                         else
    313                         {
    314                             index = line.indexOf(":");
    315                             if (index >= 0)
    316                             {
    317                                 key = section + line.substring(0, index);
    318                                 value = parseValue(line.substring(index + 1));
    319                             }
    320                             else
    321                             {
    322                                 key = section + line;
    323                             }
    324                         }
    325                         addProperty(key.trim(), value);
    326                     }
    327                 }
    328                 line = bufferedReader.readLine();
    329             }
    330         }
    331         catch (IOException e)
    332         {
    333             throw new ConfigurationException("Unable to load the configuration", e);
    334         }
    335     }
    336
    337     /***
    338      * Parse the value to remove the quotes and ignoring the comment.
    339      * Example:
    340      *
    341      * <pre>"value" ; comment -> value</pre>
    342      *
    343      * <pre>'value' ; comment -> value</pre>
    344      *
    345      * @param value
    346      */
    347     private String parseValue(String value)
    348     {
    349         value = value.trim();
    350
    351         boolean quoted = value.startsWith("\"") || value.startsWith("'");
    352         boolean stop = false;
    353         boolean escape = false;
    354
    355         char quote = quoted ? value.charAt(0) : 0;
    356
    357         int i = quoted ? 1 : 0;
    358
    359         StringBuffer result = new StringBuffer();
    360         while (i < value.length() && !stop)
    361         {
    362             char c = value.charAt(i);
    363
    364             if (quoted)
    365             {
    366                 if ('//' == c && !escape)
    367                 {
    368                     escape = true;
    369                 }
    370                 else if (!escape && quote == c)
    371                 {
    372                     stop = true;
    373                 }
    374                 else if (escape && quote == c)
    375                 {
    376                     escape = false;
    377                     result.append(c);
    378                 }
    379                 else
    380                 {
    381                     if (escape)
    382                     {
    383                         escape = false;
    384                         result.append('//');
    385                     }
    386
    387                     result.append(c);
    388                 }
    389             }
    390             else
    391             {
    392                 if (COMMENT_CHARS.indexOf(c) == -1)
    393                 {
    394                     result.append(c);
    395                 }
    396                 else
    397                 {
    398                     stop = true;
    399                 }
    400             }
    401
    402             i++;
    403         }
    404
    405         String v = result.toString();
    406         if (!quoted)
    407         {
    408             v = v.trim();
    409         }
    410         return v;
    411     }
    412
    413     /***
    414      * Add quotes around the specified value if it contains a comment character.
    415      */
    416     private String formatValue(String value)
    417     {
    418         boolean quoted = false;
    419
    420         for (int i = 0; i < COMMENT_CHARS.length() && !quoted; i++)
    421         {
    422             char c = COMMENT_CHARS.charAt(i);
    423             if (value.indexOf(c) != -1)
    424             {
    425                 quoted = true;
    426             }
    427         }
    428
    429         if (quoted)
    430         {
    431             return '"' + StringUtils.replace(value, "\"", "//\"") + '"';
    432         }
    433         else
    434         {
    435             return value;
    436         }
    437     }
    438
    439     /***
    440      * Determine if the given line is a comment line.
    441      *
    442      * @param line The line to check.
    443      * @return true if the line is empty or starts with one of the comment
    444      * characters
    445      */
    446     protected boolean isCommentLine(String line)
    447     {
    448         if (line == null)
    449         {
    450             return false;
    451         }
    452         // blank lines are also treated as comment lines
    453         return line.length() < 1 || COMMENT_CHARS.indexOf(line.charAt(0)) >= 0;
    454     }
    455
    456     /***
    457      * Determine if the given line is a section.
    458      *
    459      * @param line The line to check.
    460      * @return true if the line contains a secion
    461      */
    462     protected boolean isSectionLine(String line)
    463     {
    464         if (line == null)
    465         {
    466             return false;
    467         }
    468         return line.startsWith("[") && line.endsWith("]");
    469     }
    470
    471     /***
    472      * Return a set containing the sections in this ini configuration. Note that
    473      * changes to this set do not affect the configuration.
    474      *
    475      * @return a set containing the sections.
    476      */
    477     public Set getSections()
    478     {
    479         Set sections = new TreeSet();
    480
    481         Iterator keys = getKeys();
    482         while (keys.hasNext())
    483         {
    484             String key = (String) keys.next();
    485             int index = key.indexOf(".");
    486             if (index >= 0)
    487             {
    488                 sections.add(key.substring(0, index));
    489             }
    490         }
    491
    492         return sections;
    493     }
    494 }