Coverage Report

Coverage Report - org.apache.commons.configuration.HierarchicalINIConfiguration

Classes in this File
Line Coverage
Branch Coverage
Complexity
HierarchicalINIConfiguration
98%
161/164
100%
44/44
3,368
 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.apache.commons.configuration;
 
 import java.io.BufferedReader;
 import java.io.File;
 import java.io.IOException;
 import java.io.PrintWriter;
 import java.io.Reader;
 import java.io.Writer;
 import java.net.URL;
 import java.util.Collection;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Set;
 
 import org.apache.commons.collections.set.ListOrderedSet;
 import org.apache.commons.configuration.tree.ConfigurationNode;
 import org.apache.commons.configuration.tree.DefaultConfigurationNode;
 import org.apache.commons.configuration.tree.ViewNode;
 import org.apache.commons.lang.StringUtils;
 
 /**
  * <p>
  * A specialized hierarchical configuration implementation for parsing ini
  * files.
  * </p>
  * <p>
  * An initialization or ini file is a configuration file typically found on
  * Microsoft's Windows operating system and contains data for Windows based
  * applications.
  * </p>
  * <p>
  * Although popularized by Windows, ini files can be used on any system or
  * platform due to the fact that they are merely text files that can easily be
  * parsed and modified by both humans and computers.
  * </p>
  * <p>
  * A typcial ini file could look something like:
  * </p>
  * <code>
  * [section1]<br>
  * ; this is a comment!<br>
  * var1 = foo<br>
  * var2 = bar<br>
  * <br>
  * [section2]<br>
  * var1 = doo<br>
  * </code>
  * <p>
  * The format of ini files is fairly straight forward and is composed of three
  * components:<br>
  * <ul>
  * <li><b>Sections:</b> Ini files are split into sections, each section starting
  * with a section declaration. A section declaration starts with a '[' and ends
  * with a ']'. Sections occur on one line only.</li>
  * <li><b>Parameters:</b> Items in a section are known as parameters. Parameters
  * have a typical <code>key = value</code> format.</li>
  * <li><b>Comments:</b> Lines starting with a ';' are assumed to be comments.</li>
  * </ul>
  * </p>
  * <p>
  * There are various implementations of the ini file format by various vendors
  * which has caused a number of differences to appear. As far as possible this
  * configuration tries to be lenient and support most of the differences.
  * </p>
  * <p>
  * Some of the differences supported are as follows:
  * <ul>
  * <li><b>Comments:</b> The '#' character is also accepted as a comment
  * signifier.</li>
  * <li><b>Key value separtor:</b> The ':' character is also accepted in place of
  * '=' to separate keys and values in parameters, for example
  * <code>var1 : foo</code>.</li>
  * <li><b>Duplicate sections:</b> Typically duplicate sections are not allowed,
  * this configuration does however support it. In the event of a duplicate
  * section, the two section's values are merged.</li>
  * <li><b>Duplicate parameters:</b> Typically duplicate parameters are only
  * allowed if they are in two different sections, thus they are local to
  * sections; this configuration simply merges duplicates; if a section has a
  * duplicate parameter the values are then added to the key as a list.</li>
  * </ul>
  * </p>
  * <p>
  * Global parameters are also allowed; any parameters declared before a section
  * is declared are added to a global section. It is important to note that this
  * global section does not have a name.
  * </p>
  * <p>
  * In all instances, a parameter's key is prepended with its section name and a
  * '.' (period). Thus a parameter named "var1" in "section1" will have the key
  * <code>section1.var1</code> in this configuration. (This is the default
  * behavior. Because this is a hierarchical configuration you can change this by
  * setting a different {@link org.apache.commons.configuration.tree.ExpressionEngine}.)
  * </p>
  * <p>
  * <h3>Implementation Details:</h3> Consider the following ini file:<br>
  * <code>
  *  default = ok<br>
  *  <br>
  *  [section1]<br>
  *  var1 = foo<br>
  *  var2 = doodle<br>
  *   <br>
  *  [section2]<br>
  *  ; a comment<br>
  *  var1 = baz<br>
  *  var2 = shoodle<br>
  *  bad =<br>
  *  = worse<br>
  *  <br>
  *  [section3]<br>
  *  # another comment<br>
  *  var1 : foo<br>
  *  var2 : bar<br>
  *  var5 : test1<br>
  *  <br>
  *  [section3]<br>
  *  var3 = foo<br>
  *  var4 = bar<br>
  *  var5 = test2<br>
  *  </code>
  * </p>
  * <p>
  * This ini file will be parsed without error. Note:
  * <ul>
  * <li>The parameter named "default" is added to the global section, it's value
  * is accessed simply using <code>getProperty("default")</code>.</li>
  * <li>Section 1's parameters can be accessed using
  * <code>getProperty("section1.var1")</code>.</li>
  * <li>The parameter named "bad" simply adds the parameter with an empty value.</li>
  * <li>The empty key with value "= worse" is added using a key consisting of a
  * single space character. This key is still added to section 2 and the value
  * can be accessed using <code>getProperty("section2. ")</code>, notice the
  * period '.' and the space following the section name.</li>
  * <li>Section three uses both '=' and ':' to separate keys and values.</li>
  * <li>Section 3 has a duplicate key named "var5". The value for this key is
  * [test1, test2], and is represented as a List.</li>
  * </ul>
  * </p>
  * <p>
  * Internally, this configuration maps the content of the represented ini file
  * to its node structure in the following way:
  * <ul>
  * <li>Sections are represented by direct child nodes of the root node.</li>
  * <li>For the content of a section, corresponding nodes are created as children
  * of the section node.</li>
  * </ul>
  * This explains how the keys for the properties can be constructed. You can
  * also use other methods of {@link HierarchicalConfiguration} for querying or
  * manipulating the hierarchy of configuration nodes, for instance the
  * <code>configurationAt()</code> method for obtaining the data of a specific
  * section.
  * </p>
  * <p>
  * The set of sections in this configuration can be retrieved using the
  * <code>getSections()</code> method. For obtaining a
  * <code>SubnodeConfiguration</code> with the content of a specific section the
  * <code>getSection()</code> method can be used.
  * </p>
  * <p>
  * <em>Note:</em> Configuration objects of this type can be read concurrently by
  * multiple threads. However if one of these threads modifies the object,
  * synchronization has to be performed manually.
  * </p>
  *
  * @author <a
  *         href="http://commons.apache.org/configuration/team-list.html">Commons
  *         Configuration team</a>
  * @version $Id: HierarchicalINIConfiguration.java 720295 2008-11-24 21:29:42Z oheger $
  * @since 1.6
  */
 public class HierarchicalINIConfiguration extends
         AbstractHierarchicalFileConfiguration
 {
     /**
      * The characters that signal the start of a comment line.
      */
     protected static final String COMMENT_CHARS = "#;";
 
     /**
      * The characters used to separate keys from values.
      */
     protected static final String SEPARATOR_CHARS = "=:";
 
     /**
      * The serial version UID.
      */
     private static final long serialVersionUID = 2548006161386850670L;
 
     /**
      * Constant for the line separator.
      */
     private static final String LINE_SEPARATOR = System.getProperty("line.separator");
 
     /**
      * The line continuation character.
      */
     private static final String LINE_CONT = "\\";
 
     /**
      * Create a new empty INI Configuration.
      */
     public HierarchicalINIConfiguration()
     {
         super();
     }
 
     /**
      * Create and load the ini configuration from the given file.
      *
      * @param filename The name pr path of the ini file to load.
      * @throws ConfigurationException If an error occurs while loading the file
      */
     public HierarchicalINIConfiguration(String filename)
             throws ConfigurationException
     {
         super(filename);
     }
 
     /**
      * Create and load the ini configuration from the given file.
      *
      * @param file The ini file to load.
      * @throws ConfigurationException If an error occurs while loading the file
      */
     public HierarchicalINIConfiguration(File file)
             throws ConfigurationException
     {
         super(file);
     }
 
     /**
      * Create and load the ini configuration from the given url.
      *
      * @param url The url of the ini file to load.
      * @throws ConfigurationException If an error occurs while loading the file
      */
     public HierarchicalINIConfiguration(URL url) throws ConfigurationException
     {
         super(url);
     }
 
     /**
      * Save the configuration to the specified writer.
      *
      * @param writer - The writer to save the configuration to.
      * @throws ConfigurationException If an error occurs while writing the
      *         configuration
      */
     public void save(Writer writer) throws ConfigurationException
     {
         PrintWriter out = new PrintWriter(writer);
         Iterator it = getSections().iterator();
         while (it.hasNext())
         {
             String section = (String) it.next();
             if (section != null)
             {
                 out.print("[");
                 out.print(section);
                 out.print("]");
                 out.println();
             }
 
             Configuration subset = getSection(section);
             Iterator keys = subset.getKeys();
             while (keys.hasNext())
             {
                 String key = (String) keys.next();
                 Object value = subset.getProperty(key);
                 if (value instanceof Collection)
                 {
                     Iterator values = ((Collection) value).iterator();
                     while (values.hasNext())
                     {
                         value = (Object) values.next();
                         out.print(key);
                         out.print(" = ");
                         out.print(formatValue(value.toString()));
                         out.println();
                     }
                 }
                 else
                 {
                     out.print(key);
                     out.print(" = ");
                     out.print(formatValue(value.toString()));
                     out.println();
                 }
             }
 
             out.println();
         }
 
         out.flush();
     }
 
     /**
      * Load the configuration from the given reader. Note that the
      * <code>clear</code> method is not called so the configuration read in will
      * be merged with the current configuration.
      *
      * @param reader The reader to read the configuration from.
      * @throws ConfigurationException If an error occurs while reading the
      *         configuration
      */
     public void load(Reader reader) throws ConfigurationException
     {
         try
         {
             BufferedReader bufferedReader = new BufferedReader(reader);
             ConfigurationNode sectionNode = getRootNode();
 
             String line = bufferedReader.readLine();
             while (line != null)
             {
                 line = line.trim();
                 if (!isCommentLine(line))
                 {
                     if (isSectionLine(line))
                     {
                         String section = line.substring(1, line.length() - 1);
                         sectionNode = getSectionNode(section);
                     }
 
                     else
                     {
                         String key = "";
                         String value = "";
                         int index = line.indexOf("=");
                         if (index >= 0)
                         {
                             key = line.substring(0, index);
                             value = parseValue(line.substring(index + 1), bufferedReader);
                         }
                         else
                         {
                             index = line.indexOf(":");
                             if (index >= 0)
                             {
                                 key = line.substring(0, index);
                                 value = parseValue(line.substring(index + 1), bufferedReader);
                             }
                             else
                             {
                                 key = line;
                             }
                         }
                         key = key.trim();
                         if (key.length() < 1)
                         {
                             // use space for properties with no key
                             key = " ";
                         }
                         ConfigurationNode node = createNode(key);
                         node.setValue(value);
                         sectionNode.addChild(node);
                     }
                 }
 
                 line = bufferedReader.readLine();
             }
         }
         catch (IOException e)
         {
             throw new ConfigurationException(
                     "Unable to load the configuration", e);
         }
     }
 
     /**
      * Parse the value to remove the quotes and ignoring the comment. Example:
      *
      * <pre>
      * &quot;value&quot; ; comment -&gt; value
      * </pre>
      *
      * <pre>
      * 'value' ; comment -&gt; value
      * </pre>
      *
      * @param val the value to be parsed
      * @param reader the reader (needed if multiple lines have to be read)
      * @throws IOException if an IO error occurs
      */
     private static String parseValue(String val, BufferedReader reader) throws IOException
     {
         StringBuffer propertyValue = new StringBuffer();
         boolean lineContinues;
         String value = val.trim();
 
         do
         {
             boolean quoted = value.startsWith("\"") || value.startsWith("'");
             boolean stop = false;
             boolean escape = false;
 
             char quote = quoted ? value.charAt(0) : 0;
 
             int i = quoted ? 1 : 0;
 
             StringBuffer result = new StringBuffer();
             while (i < value.length() && !stop)
             {
                 char c = value.charAt(i);
 
                 if (quoted)
                 {
                     if ('\\' == c && !escape)
                     {
                         escape = true;
                     }
                     else if (!escape && quote == c)
                     {
                         stop = true;
                     }
                     else if (escape && quote == c)
                     {
                         escape = false;
                         result.append(c);
                     }
                     else
                     {
                         if (escape)
                         {
                             escape = false;
                             result.append('\\');
                         }
 
                         result.append(c);
                     }
                 }
                 else
                 {
                     if (!isCommentChar(c))
                     {
                         result.append(c);
                     }
                     else
                     {
                         stop = true;
                     }
                 }
 
                 i++;
             }
 
             String v = result.toString();
             if (!quoted)
             {
                 v = v.trim();
                 lineContinues = lineContinues(v);
                 if (lineContinues)
                 {
                     // remove trailing "\"
                     v = v.substring(0, v.length() - 1).trim();
                 }
             }
             else
             {
                 lineContinues = lineContinues(value, i);
             }
             propertyValue.append(v);
 
             if (lineContinues)
             {
                 propertyValue.append(LINE_SEPARATOR);
                 value = reader.readLine();
             }
         } while (lineContinues && value != null);
 
         return propertyValue.toString();
     }
 
     /**
      * Tests whether the specified string contains a line continuation marker.
      *
      * @param line the string to check
      * @return a flag whether this line continues
      */
     private static boolean lineContinues(String line)
     {
         String s = line.trim();
         return s.equals(LINE_CONT)
                 || (s.length() > 2 && s.endsWith(LINE_CONT) && Character
                         .isWhitespace(s.charAt(s.length() - 2)));
     }
 
     /**
      * Tests whether the specified string contains a line continuation marker
      * after the specified position. This method parses the string to remove a
      * comment that might be present. Then it checks whether a line continuation
      * marker can be found at the end.
      *
      * @param line the line to check
      * @param pos the start position
      * @return a flag whether this line continues
      */
     private static boolean lineContinues(String line, int pos)
     {
         String s;
 
         if (pos >= line.length())
         {
             s = line;
         }
         else
         {
             int end = pos;
             while (end < line.length() && !isCommentChar(line.charAt(end)))
             {
                 end++;
             }
             s = line.substring(pos, end);
         }
 
         return lineContinues(s);
     }
 
     /**
      * Tests whether the specified character is a comment character.
      *
      * @param c the character
      * @return a flag whether this character starts a comment
      */
     private static boolean isCommentChar(char c)
     {
         return COMMENT_CHARS.indexOf(c) >= 0;
     }
 
     /**
      * Add quotes around the specified value if it contains a comment character.
      */
     private String formatValue(String value)
     {
         boolean quoted = false;
 
         for (int i = 0; i < COMMENT_CHARS.length() && !quoted; i++)
         {
             char c = COMMENT_CHARS.charAt(i);
             if (value.indexOf(c) != -1)
             {
                 quoted = true;
             }
         }
 
         if (quoted)
         {
             return '"' + StringUtils.replace(value, "\"", "\\\"") + '"';
         }
         else
         {
             return value;
         }
     }
 
     /**
      * Determine if the given line is a comment line.
      *
      * @param line The line to check.
      * @return true if the line is empty or starts with one of the comment
      *         characters
      */
     protected boolean isCommentLine(String line)
     {
         if (line == null)
         {
             return false;
         }
         // blank lines are also treated as comment lines
         return line.length() < 1 || COMMENT_CHARS.indexOf(line.charAt(0)) >= 0;
     }
 
     /**
      * Determine if the given line is a section.
      *
      * @param line The line to check.
      * @return true if the line contains a secion
      */
     protected boolean isSectionLine(String line)
     {
         if (line == null)
         {
             return false;
         }
         return line.startsWith("[") && line.endsWith("]");
     }
 
     /**
      * Return a set containing the sections in this ini configuration. Note that
      * changes to this set do not affect the configuration.
      *
      * @return a set containing the sections.
      */
     public Set getSections()
     {
         Set sections = new ListOrderedSet();
         boolean globalSection = false;
 
         for (Iterator it = getRootNode().getChildren().iterator(); it.hasNext();)
         {
             ConfigurationNode node = (ConfigurationNode) it.next();
             if (isSectionNode(node))
             {
                 if (globalSection)
                 {
                     sections.add(null);
                     globalSection = false;
                 }
                 sections.add(node.getName());
             }
             else
             {
                 globalSection = true;
             }
         }
 
         return sections;
     }
 
     /**
      * Returns a configuration with the content of the specified section. This
      * provides an easy way of working with a single section only. The way this
      * configuration is structured internally, this method is very similar to
      * calling
      * <code>{@link HierarchicalConfiguration#configurationAt(String)}</code>
      * with the name of the section in question. There are the following
      * differences however:
      * <ul>
      * <li>This method never throws an exception. If the section does not exist,
      * an empty configuration is returned.</li>
      * <li>There is special support for the global section: Passing in
      * <b>null</b> as section name returns a configuration with the content of
      * the global section (which may also be empty).</li>
      * </ul>
      *
      * @param name the name of the section in question; <b>null</b> represents
      *        the global section
      * @return a configuration containing only the properties of the specified
      *         section
      */
     public SubnodeConfiguration getSection(String name)
     {
         if (name == null)
         {
             return getGlobalSection();
         }
 
         else
         {
             try
             {
                 return configurationAt(name);
             }
             catch (IllegalArgumentException iex)
             {
                 // the passed in key does not map to exactly one node
                 // return an empty configuration
                 return new SubnodeConfiguration(this,
                         new DefaultConfigurationNode());
             }
         }
     }
 
     /**
      * Obtains the node representing the specified section. This method is
      * called while the configuration is loaded. If a node for this section
      * already exists, it is returned. Otherwise a new node is created.
      *
      * @param sectionName the name of the section
      * @return the node for this section
      */
     private ConfigurationNode getSectionNode(String sectionName)
     {
         List nodes = getRootNode().getChildren(sectionName);
         if (!nodes.isEmpty())
         {
             return (ConfigurationNode) nodes.get(0);
         }
 
         ConfigurationNode node = createNode(sectionName);
         markSectionNode(node);
         getRootNode().addChild(node);
         return node;
     }
 
     /**
      * Creates a sub configuration for the global section of the represented INI
      * configuration.
      *
      * @return the sub configuration for the global section
      */
     private SubnodeConfiguration getGlobalSection()
     {
         ViewNode parent = new ViewNode();
 
         for (Iterator it = getRootNode().getChildren().iterator(); it.hasNext();)
         {
             ConfigurationNode node = (ConfigurationNode) it.next();
             if (!isSectionNode(node))
             {
                 parent.addChild(node);
             }
         }
 
         return createSubnodeConfiguration(parent);
     }
 
     /**
      * Marks a configuration node as a section node. This means that this node
      * represents a section header. This implementation uses the node's
      * reference property to store a flag.
      *
      * @param node the node to be marked
      */
     private static void markSectionNode(ConfigurationNode node)
     {
         node.setReference(Boolean.TRUE);
     }
 
     /**
      * Checks whether the specified configuration node represents a section.
      *
      * @param node the node in question
      * @return a flag whether this node represents a section
      */
     private static boolean isSectionNode(ConfigurationNode node)
     {
         return node.getReference() != null || node.getChildrenCount() > 0;
     }
 }