org.apache.commons.configuration
Class HierarchicalINIConfiguration

java.lang.Object
  extended by org.apache.commons.configuration.event.EventSource
      extended by org.apache.commons.configuration.AbstractConfiguration
          extended by org.apache.commons.configuration.HierarchicalConfiguration
              extended by org.apache.commons.configuration.AbstractHierarchicalFileConfiguration
                  extended by org.apache.commons.configuration.HierarchicalINIConfiguration
All Implemented Interfaces:
java.io.Serializable, java.lang.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:

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:

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:

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

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 java.lang.String COMMENT_CHARS
          The characters that signal the start of a comment line.
protected static java.lang.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(java.io.File file)
          Create and load the ini configuration from the given file.
HierarchicalINIConfiguration(java.lang.String filename)
          Create and load the ini configuration from the given file.
HierarchicalINIConfiguration(java.net.URL url)
          Create and load the ini configuration from the given url.
 
Method Summary
 SubnodeConfiguration getSection(java.lang.String name)
          Returns a configuration with the content of the specified section.
 java.util.Set<java.lang.String> getSections()
          Return a set containing the sections in this ini configuration.
protected  boolean isCommentLine(java.lang.String line)
          Determine if the given line is a comment line.
protected  boolean isSectionLine(java.lang.String line)
          Determine if the given line is a section.
 void load(java.io.Reader reader)
          Load the configuration from the given reader.
 void save(java.io.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 java.lang.String COMMENT_CHARS
The characters that signal the start of a comment line.

See Also:
Constant Field Values

SEPARATOR_CHARS

protected static final java.lang.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(java.lang.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(java.io.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(java.net.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(java.io.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(java.io.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(java.lang.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(java.lang.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 java.util.Set<java.lang.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(java.lang.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:

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


Copyright © 2001-2013. All Rights Reserved.