org.apache.commons.configuration.INIConfiguration Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-configuration Show documentation
Show all versions of commons-configuration Show documentation
Tools to assist in the reading of configuration/preferences files in
various formats
/*
* 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.Set;
import java.util.TreeSet;
import org.apache.commons.lang.StringUtils;
/**
*
* 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 typcial 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 separtor: 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 it. In the event of a duplicate
* section, the two section's values are merged.
* - 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. Thus, a section's
* parameters can easily be retrieved using the subset method
* using the section name as the prefix.
*
*
*
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
*
*
*
* 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 an empty key. This key
* is still added to section 2 and the value can be accessed using
*
getProperty("section2."), notice the period '.' 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 set of sections in this configuration can be retrieved using the
* getSections method.
*
*
* 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.
*
*
* @author Trevor Miller
* @version $Id: INIConfiguration.java 720600 2008-11-25 21:20:01Z oheger $
* @since 1.4
* @deprecated This class has been replaced by HierarchicalINIConfiguration,
* which provides a superset of the functionality offered by this class.
*/
public class INIConfiguration extends AbstractFileConfiguration
{
/**
* 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 = "=:";
/**
* Create a new empty INI Configuration.
*/
public INIConfiguration()
{
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 INIConfiguration(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 INIConfiguration(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 INIConfiguration(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();
out.print("[");
out.print(section);
out.print("]");
out.println();
Configuration subset = subset(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
* clear 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);
String line = bufferedReader.readLine();
String section = "";
while (line != null)
{
line = line.trim();
if (!isCommentLine(line))
{
if (isSectionLine(line))
{
section = line.substring(1, line.length() - 1) + ".";
}
else
{
String key = "";
String value = "";
int index = line.indexOf("=");
if (index >= 0)
{
key = section + line.substring(0, index);
value = parseValue(line.substring(index + 1));
}
else
{
index = line.indexOf(":");
if (index >= 0)
{
key = section + line.substring(0, index);
value = parseValue(line.substring(index + 1));
}
else
{
key = section + line;
}
}
addProperty(key.trim(), value);
}
}
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:
*
* "value" ; comment -> value
*
* 'value' ; comment -> value
*
* @param value
*/
private String parseValue(String value)
{
value = value.trim();
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 (COMMENT_CHARS.indexOf(c) == -1)
{
result.append(c);
}
else
{
stop = true;
}
}
i++;
}
String v = result.toString();
if (!quoted)
{
v = v.trim();
}
return v;
}
/**
* 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 TreeSet();
Iterator keys = getKeys();
while (keys.hasNext())
{
String key = (String) keys.next();
int index = key.indexOf(".");
if (index >= 0)
{
sections.add(key.substring(0, index));
}
}
return sections;
}
}