Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.configuration
Class HierarchicalINIConfiguration

    java.lang.Object
      org.apache.commons.configuration.event.EventSource
          org.apache.commons.configuration.AbstractConfiguration
              org.apache.commons.configuration.HierarchicalConfiguration
                  org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
                      org.apache.commons.configuration.HierarchicalINIConfiguration

All Implemented Interfaces:
  Serializable, Cloneable, Configuration, ConfigurationErrorListener, ConfigurationListener, FileConfiguration, FileSystemBased, Reloadable

    public class HierarchicalINIConfiguration

extends AbstractHierarchicalFileConfiguration

A specialized hierarchical configuration implementation for parsing ini files.

An initialization or ini file is a configuration file typically found on Microsoft's Windows operating system and contains data for Windows based applications.

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.

A typical ini file could look something like:

     [section1]
     ; this is a comment!
     var1 = foo
     var2 = bar

     [section2]
     var1 = doo

The format of ini files is fairly straight forward and is composed of three components:

- Sections: 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.
- Parameters: Items in a section are known as parameters. Parameters have a typical `key = value` format.
- Comments: Lines starting with a ';' are assumed to be comments.

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.

Some of the differences supported are as follows:

- Comments: The '#' character is also accepted as a comment signifier.
- Key value separator: The ':' character is also accepted in place of '=' to separate keys and values in parameters, for example `var1 : foo`.
- Duplicate sections: Typically duplicate sections are not allowed, this configuration does however support this feature. In the event of a duplicate section, the two section's values are merged so that there is only a single section. Note: This also affects the internal data of the configuration. If it is saved, only a single section is written!
- Duplicate parameters: 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.

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.

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 `section1.var1` in this configuration. (This is the default behavior. Because this is a hierarchical configuration you can change this by setting a different `ExpressionEngine`.)

### Implementation Details:

Consider the following ini file:

      default = ok

      [section1]
      var1 = foo
      var2 = doodle

      [section2]
      ; a comment
      var1 = baz
      var2 = shoodle
      bad =
      = worse

      [section3]
      # another comment
      var1 : foo
      var2 : bar
      var5 : test1

      [section3]
      var3 = foo
      var4 = bar
      var5 = test2

      [sectionSeparators]
      passwd : abc=def
      a:b = "value"

This ini file will be parsed without error. Note:

- The parameter named "default" is added to the global section, it's value is accessed simply using `getProperty("default")`.
- Section 1's parameters can be accessed using `getProperty("section1.var1")`.
- The parameter named "bad" simply adds the parameter with an empty value.
- 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 `getProperty("section2. ")`, notice the period '.' and the space following the section name.
- Section three uses both '=' and ':' to separate keys and values.
- Section 3 has a duplicate key named "var5". The value for this key is [test1, test2], and is represented as a List.
- The section called sectionSeparators demonstrates how the configuration deals with multiple occurrences of separator characters. Per default the first separator character in a line is detected and used to split the key from the value. Therefore the first property definition in this section has the key `passwd` and the value `abc=def`. This default behavior can be changed by using quotes. If there is a separator character before the first quote character (ignoring whitespace), this character is used as separator. Thus the second property definition in the section has the key `a:b` and the value `value`.

Internally, this configuration maps the content of the represented ini file to its node structure in the following way:

- Sections are represented by direct child nodes of the root node.
- For the content of a section, corresponding nodes are created as children of the section node.

This explains how the keys for the properties can be constructed. You can also use other methods of `HierarchicalConfiguration` for querying or manipulating the hierarchy of configuration nodes, for instance the `configurationAt()` method for obtaining the data of a specific section. However, be careful that the storage scheme described above is not violated (e.g. by adding multiple levels of nodes or inserting duplicate section nodes). Otherwise, the special methods for ini configurations may not work correctly!

The set of sections in this configuration can be retrieved using the `getSections()` method. For obtaining a `SubnodeConfiguration` with the content of a specific section the `getSection()` method can be used.

Note: 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.

Since:
  1.6
Version:
  $Id: HierarchicalINIConfiguration.java 1234362 2012-01-21 16:59:48Z oheger $
Author:
  Commons Configuration team
See Also:
  Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
`AbstractHierarchicalFileConfiguration.FileConfigurationDelegate`

Nested classes/interfaces inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`HierarchicalConfiguration.BuilderVisitor, HierarchicalConfiguration.Node, HierarchicalConfiguration.NodeVisitor`

Field Summary
`protected static String` | `COMMENT_CHARS` The characters that signal the start of a comment line.
`protected static String` | `SEPARATOR_CHARS` The characters used to separate keys from values.

Fields inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`EVENT_ADD_NODES, EVENT_CLEAR_TREE, EVENT_SUBNODE_CHANGED`

Fields inherited from class org.apache.commons.configuration.AbstractConfiguration
`END_TOKEN, EVENT_ADD_PROPERTY, EVENT_CLEAR, EVENT_CLEAR_PROPERTY, EVENT_READ_PROPERTY, EVENT_SET_PROPERTY, START_TOKEN`

Constructor Summary
`HierarchicalINIConfiguration()` Create a new empty INI Configuration.
`HierarchicalINIConfiguration(File file)` Create and load the ini configuration from the given file.
`HierarchicalINIConfiguration(String filename)` Create and load the ini configuration from the given file.
`HierarchicalINIConfiguration(URL url)` Create and load the ini configuration from the given url.

Method Summary
`SubnodeConfiguration` | `getSection(String name)` Returns a configuration with the content of the specified section.
`Set<String>` | `getSections()` Return a set containing the sections in this ini configuration.
`protected boolean` | `isCommentLine(String line)` Determine if the given line is a comment line.
`protected boolean` | `isSectionLine(String line)` Determine if the given line is a section.
`void` | `load(Reader reader)` Load the configuration from the given reader.
`void` | `save(Writer writer)` Save the configuration to the specified writer.

Methods inherited from class org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
`addNodes, addPropertyDirect, clearProperty, clearTree, configurationChanged, configurationError, containsKey, createDelegate, fetchNodeList, getBasePath, getDelegate, getEncoding, getFile, getFileName, getFileSystem, getKeys, getKeys, getProperty, getReloadingStrategy, getReloadLock, getURL, isAutoSave, isEmpty, load, load, load, load, load, load, refresh, reload, resetFileSystem, save, save, save, save, save, save, setAutoSave, setBasePath, setDelegate, setEncoding, setFile, setFileName, setFileSystem, setProperty, setReloadingStrategy, setURL, subnodeConfigurationChanged`

Methods inherited from class org.apache.commons.configuration.HierarchicalConfiguration
`clear, clearNode, clearNode, clearReferences, clone, configurationAt, configurationAt, configurationsAt, createAddPath, createNode, createSubnodeConfiguration, createSubnodeConfiguration, fetchAddNode, findLastPathNode, findPropertyNodes, getDefaultExpressionEngine, getExpressionEngine, getMaxIndex, getRoot, getRootNode, interpolatedConfiguration, nodeDefined, nodeDefined, removeNode, removeNode, setDefaultExpressionEngine, setExpressionEngine, setRoot, setRootNode, subset`

Methods inherited from class org.apache.commons.configuration.AbstractConfiguration
`addErrorLogListener, addProperty, append, clearPropertyDirect, copy, createInterpolator, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDefaultListDelimiter, getDelimiter, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getInterpolator, getList, getList, getListDelimiter, getLogger, getLong, getLong, getLong, getProperties, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, getSubstitutor, interpolate, interpolate, interpolateHelper, isDelimiterParsingDisabled, isScalarValue, isThrowExceptionOnMissing, resolveContainerStore, setDefaultListDelimiter, setDelimiter, setDelimiterParsingDisabled, setListDelimiter, setLogger, setThrowExceptionOnMissing`

Methods inherited from class org.apache.commons.configuration.event.EventSource
`addConfigurationListener, addErrorListener, clearConfigurationListeners, clearErrorListeners, createErrorEvent, createEvent, fireError, fireEvent, getConfigurationListeners, getErrorListeners, isDetailEvents, removeConfigurationListener, removeErrorListener, setDetailEvents`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface org.apache.commons.configuration.Configuration
`addProperty, clear, getBigDecimal, getBigDecimal, getBigInteger, getBigInteger, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getDouble, getDouble, getDouble, getFloat, getFloat, getFloat, getInt, getInt, getInteger, getList, getList, getLong, getLong, getLong, getProperties, getShort, getShort, getShort, getString, getString, getStringArray, subset`

Field Detail

### COMMENT_CHARS

    protected static final String COMMENT_CHARS

  The characters that signal the start of a comment line.

  See Also:
    Constant Field Values

### SEPARATOR_CHARS

    protected static final String SEPARATOR_CHARS

  The characters used to separate keys from values.

  See Also:
    Constant Field Values

Constructor Detail

### HierarchicalINIConfiguration

    public HierarchicalINIConfiguration()

  Create a new empty INI Configuration.

### HierarchicalINIConfiguration

    public HierarchicalINIConfiguration(String filename)
                                 throws ConfigurationException

  Create and load the ini configuration from the given file.

  Parameters:
    `filename` - The name pr path of the ini file to load.
  Throws:
    `ConfigurationException` - If an error occurs while loading the file

### HierarchicalINIConfiguration

    public HierarchicalINIConfiguration(File file)
                                 throws ConfigurationException

  Create and load the ini configuration from the given file.

  Parameters:
    `file` - The ini file to load.
  Throws:
    `ConfigurationException` - If an error occurs while loading the file

### HierarchicalINIConfiguration

    public HierarchicalINIConfiguration(URL url)
                                 throws ConfigurationException

  Create and load the ini configuration from the given url.

  Parameters:
    `url` - The url of the ini file to load.
  Throws:
    `ConfigurationException` - If an error occurs while loading the file

Method Detail

### save

    public void save(Writer writer)
              throws ConfigurationException

  Save the configuration to the specified writer.

  Parameters:
    `writer` - - The writer to save the configuration to.
  Throws:
    `ConfigurationException` - If an error occurs while writing the configuration

### load

    public void load(Reader reader)
              throws ConfigurationException

  Load the configuration from the given reader. Note that the `clear()` method is not called so the configuration read in will be merged with the current configuration.

  Parameters:
    `reader` - The reader to read the configuration from.
  Throws:
    `ConfigurationException` - If an error occurs while reading the configuration

### isCommentLine

    protected boolean isCommentLine(String line)

  Determine if the given line is a comment line.

  Parameters:
    `line` - The line to check.
  Returns:
    true if the line is empty or starts with one of the comment characters

### isSectionLine

    protected boolean isSectionLine(String line)

  Determine if the given line is a section.

  Parameters:
    `line` - The line to check.
  Returns:
    true if the line contains a section

### getSections

    public Set<String> getSections()

  Return a set containing the sections in this ini configuration. Note that changes to this set do not affect the configuration.

  Returns:
    a set containing the sections.

### getSection

    public SubnodeConfiguration getSection(String name)

  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 `HierarchicalConfiguration.configurationAt(String)` with the name of the section in question. There are the following differences however:
  - This method never throws an exception. If the section does not exist, it is created now. The configuration returned in this case is empty.
  - If section is contained multiple times in the configuration, the configuration returned by this method is initialized with the first occurrence of the section. (This can only happen if `addProperty()` has been used in a way that does not conform to the storage scheme used by `HierarchicalINIConfiguration`. If used correctly, there will not be duplicate sections.)
  - There is special support for the global section: Passing in null as section name returns a configuration with the content of the global section (which may also be empty).

  Parameters:
    `name` - the name of the section in question; null represents the global section
  Returns:
    a configuration containing only the properties of the specified section

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2012 The Apache Software Foundation. All Rights Reserved.