org.rhq.core.util
Class IniEditor

java.lang.Object
  org.rhq.core.util.IniEditor

public class IniEditor
extends Object

Loads, edits and saves INI-style configuration files. While loading from and saving to streams and files, IniEditor preserves comments and blank lines as well as the order of sections and lines in general.

IniEditor assumes configuration files to be split in sections. A section starts out with a header, which consists of the section name enclosed in brackets ('[' and ']'). Everything before the first section header is ignored when loading from a stream or file. The IniEditor.Section class can be used to load configuration files without sections (ie Java-style properties).

A "common section" may be named. All sections inherit the options of this section but can overwrite them.

IniEditor represents an INI file (or rather, its sections) line by line, as comment, blank and option lines. A comment is a line which has a comment delimiter as its first non-white space character. The default comment delimiters, which may be overwritten, are '#' and ';'.

A blank line is any line that consists only of white space.

Everything else is an option line. Option names and values are separated by option delimiters '=', ':' or white space (spaces and tabs).

Here's a minimal example. Suppose, we have this in a file called users.ini:

   [root]
   role = administrator
   last_login = 2003-05-04

   [joe]
   role = author
   last_login = 2003-05-13
 

Let's load that file, add something to it and save the changes:

   IniEditor users = new IniEditor();
   users.load("users.ini");
   users.set("root", "last_login", "2003-05-16");
   users.addComment("root", "Must change password often");
   users.set("root", "change_pwd", "10 days");
   users.addBlankLine("root");
   users.save("users.ini");
 

Now, the file looks like this:

   [root]
   role = administrator
   last_login = 2003-05-16

   # Must change password often
   change_pwd = 10 days

   [joe]
   role = author
   last_login = 2003-05-13
 

IniEditor provides services simliar to the standard Java API class java.util.Properties. It uses its own parser, though, which differs in these respects from that of Properties:

• Line continuations (backslashes at the end of an option line) are not supported.
• No kind of character escaping is performed or recognized. Characters are read and written in in the default character encoding. If you want to use a different character encoding, use the load(InputStreamReader) and save(OutputStreamWriter) methods with a reader and writer tuned to the desired character encoding.
• As a consequence, option names may not contain option/value separators (normally '=', ':' and white space).

Version:

r4 (8/10/2005)

Author:

Nik Haldimann, me at ubique.ch

Nested Class Summary

static class	IniEditor.NoSuchSectionException Thrown when an inexistent section is addressed.
static class	IniEditor.Section Loads, edits and saves a section of an INI-style configuration file.

Constructor Summary

IniEditor()
Constructs new bare IniEditor instance.

IniEditor(boolean isCaseSensitive)
Constructs new bare IniEditor instance specifying case-sensitivity.

IniEditor(char[] delims)
Constructs new IniEditor defining comment delimiters.

IniEditor(char[] delims, boolean isCaseSensitive)
Constructs new IniEditor defining comment delimiters.

IniEditor(String commonName)
Constructs new IniEditor instance with a common section.

IniEditor(String commonName, boolean isCaseSensitive)
Constructs new IniEditor instance with a common section.

IniEditor(String commonName, char[] delims)
Constructs new IniEditor instance with a common section, defining comment delimiters.

IniEditor(String commonName, char[] delims, boolean isCaseSensitive)
Constructs new IniEditor instance with a common section, defining comment delimiters.

Method Summary

void	addBlankLine(String section) Adds a blank line to the end of a section.
void	addComment(String section, String comment) Adds a comment line to the end of a section.
boolean	addSection(String name) Adds a section if it doesn't exist yet.
String	get(String section, String option) Returns the value of a given option in a given section or null if either the section or the option don't exist.
boolean	hasOption(String section, String option) Checks whether an option exists in a given section.
boolean	hasSection(String name) Checks whether a section with a particular name exists in this instance.
void	load(File file) Loads INI formatted input from a file into this instance, using the default character encoding.
void	load(InputStream stream) Loads INI formatted input from a stream into this instance, using the default character encoding.
void	load(InputStreamReader streamReader) Loads INI formatted input from a stream reader into this instance.
void	load(String filename) Loads INI formatted input from a file into this instance, using the default character encoding.
List<String>	optionNames(String section) Returns all option names of a section, not including options from the common section.
boolean	remove(String section, String option) Removes an option from a section if it exists.
boolean	removeSection(String name) Removes a section if it exists.
void	save(File file) Writes this instance in INI format to a file.
void	save(OutputStream stream) Writes this instance in INI format to an output stream.
void	save(OutputStreamWriter streamWriter) Writes this instance in INI format to an output stream writer.
void	save(String filename) Writes this instance in INI format to a file.
List<String>	sectionNames() Returns all section names in this instance minus the common section if one was defined.
void	set(String section, String option, String value) Sets the value of an option in a section, if the option exist, otherwise adds the option to the section.
void	setOptionFormatString(String formatString) Sets the option format for this instance to the given string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IniEditor

public IniEditor()

Constructs new bare IniEditor instance.

IniEditor

public IniEditor(boolean isCaseSensitive)

Constructs new bare IniEditor instance specifying case-sensitivity.

Parameters:

isCaseSensitive - section and option names are case-sensitive if this is true

IniEditor

public IniEditor(String commonName)

Constructs new IniEditor instance with a common section. Options in the common section are used as defaults for all other sections.

Parameters:

commonName - name of the common section

IniEditor

public IniEditor(String commonName,
                 boolean isCaseSensitive)

Constructs new IniEditor instance with a common section. Options in the common section are used as defaults for all other sections.

Parameters:

commonName - name of the common section

isCaseSensitive - section and option names are case-sensitive if this is true

IniEditor

public IniEditor(char[] delims)

Constructs new IniEditor defining comment delimiters.

Parameters:

delims - an array of characters to be recognized as starters of comment lines; the first of them will be used for newly created comments

IniEditor

public IniEditor(char[] delims,
                 boolean isCaseSensitive)

Constructs new IniEditor defining comment delimiters.

Parameters:

delims - an array of characters to be recognized as starters of comment lines; the first of them will be used for newly created comments

isCaseSensitive - section and option names are case-sensitive if this is true

IniEditor

public IniEditor(String commonName,
                 char[] delims)

Constructs new IniEditor instance with a common section, defining comment delimiters. Options in the common section are used as defaults for all other sections.

Parameters:

commonName - name of the common section

delims - an array of characters to be recognized as starters of comment lines; the first of them will be used for newly created comments

IniEditor

public IniEditor(String commonName,
                 char[] delims,
                 boolean isCaseSensitive)

Constructs new IniEditor instance with a common section, defining comment delimiters. Options in the common section are used as defaults for all other sections.

Parameters:

commonName - name of the common section

delims - an array of characters to be recognized as starters of comment lines; the first of them will be used for newly created comments

Method Detail

setOptionFormatString

public void setOptionFormatString(String formatString)

Sets the option format for this instance to the given string. Options will be rendered according to the given format string when printed. The string must contain %s three times, these will be replaced with the option name, the option separator and the option value in this order. Literal percentage signs must be escaped by preceding them with another percentage sign (i.e., %% corresponds to one percentage sign). The default format string is "%s %s %s". Option formats may look like format strings as supported by Java 1.5, but the string is in fact parsed in a custom fashion to guarantee backwards compatibility. So don't try clever stuff like using format conversion types other than %s.

Parameters:

formatString - a format string, containing %s exactly three times

Throws:

IllegalArgumentException - if the format string is illegal

get

public String get(String section,
                  String option)

Returns the value of a given option in a given section or null if either the section or the option don't exist. If a common section was defined options are also looked up there if they're not present in the specific section.

Parameters:

section - the section's name

option - the option's name

Returns:

the option's value

Throws:

NullPointerException - any of the arguments is null

set

public void set(String section,
                String option,
                String value)

Sets the value of an option in a section, if the option exist, otherwise adds the option to the section. Trims white space from the start and the end of the value and deletes newline characters it might contain.

Parameters:

section - the section's name

option - the option's name

value - the option's value

Throws:

IniEditor.NoSuchSectionException - no section with the given name exists

IllegalArgumentException - the option name is illegal, ie contains a '=' character or consists only of white space

NullPointerException - section or option are null

remove

public boolean remove(String section,
                      String option)

Removes an option from a section if it exists. Will not remove options from the common section if it's not directly addressed.

Parameters:

section - the section's name

option - the option's name

Returns:

true if the option was actually removed

Throws:

IniEditor.NoSuchSectionException - no section with the given name exists

hasOption

public boolean hasOption(String section,
                         String option)

Checks whether an option exists in a given section. Options in the common section are assumed to not exist in particular sections, unless they're overwritten.

Parameters:

section - the section's name

option - the option's name

Returns:

true if the given section has the option

hasSection

public boolean hasSection(String name)

Checks whether a section with a particular name exists in this instance.

Parameters:

name - the name of the section

Returns:

true if the section exists

addSection

public boolean addSection(String name)

Adds a section if it doesn't exist yet.

Parameters:

name - the name of the section

Returns:

true if the section didn't already exist

Throws:

IllegalArgumentException - the name is illegal, ie contains one of the characters '[' and ']' or consists only of white space

removeSection

public boolean removeSection(String name)

Removes a section if it exists.

Parameters:

name - the section's name

Returns:

true if the section actually existed

Throws:

IllegalArgumentException - when trying to remove the common section

sectionNames

public List<String> sectionNames()

Returns all section names in this instance minus the common section if one was defined.

Returns:

list of the section names in original/insertion order

optionNames

public List<String> optionNames(String section)

Returns all option names of a section, not including options from the common section.

Parameters:

section - the section's name

Returns:

list of option names

Throws:

IniEditor.NoSuchSectionException - no section with the given name exists

addComment

public void addComment(String section,
                       String comment)

Adds a comment line to the end of a section. A comment spanning several lines (ie with line breaks) will be split up, one comment line for each line.

Parameters:

section - the section's name

comment - the comment

Throws:

IniEditor.NoSuchSectionException - no section with the given name exists

addBlankLine

public void addBlankLine(String section)

Adds a blank line to the end of a section.

Parameters:

section - the section's name

Throws:

IniEditor.NoSuchSectionException - no section with the given name exists

save

public void save(String filename)
          throws IOException

Writes this instance in INI format to a file.

Parameters:

filename - the file to write to

Throws:

IOException - at an I/O problem

save

public void save(File file)
          throws IOException

Writes this instance in INI format to a file.

Parameters:

file - where to save to

Throws:

IOException - at an I/O problem

save

public void save(OutputStream stream)
          throws IOException

Writes this instance in INI format to an output stream. This method takes an OutputStream for maximum flexibility, internally it does of course use a writer for character based output.

Parameters:

stream - where to write

Throws:

IOException - at an I/O problem

save

public void save(OutputStreamWriter streamWriter)
          throws IOException

Writes this instance in INI format to an output stream writer.

Parameters:

streamWriter - where to write

Throws:

IOException - at an I/O problem

load

public void load(String filename)
          throws IOException

Loads INI formatted input from a file into this instance, using the default character encoding. Everything in the file before the first section header is ignored.

Parameters:

filename - file to read from

Throws:

IOException - at an I/O problem

load

public void load(File file)
          throws IOException

Loads INI formatted input from a file into this instance, using the default character encoding. Everything in the file before the first section header is ignored.

Parameters:

file - file to read from

Throws:

IOException - at an I/O problem

load

public void load(InputStream stream)
          throws IOException

Loads INI formatted input from a stream into this instance, using the default character encoding. This method takes an InputStream for maximum flexibility, internally it does use a reader (using the default character encoding) for character based input. Everything in the stream before the first section header is ignored.

Parameters:

stream - where to read from

Throws:

IOException - at an I/O problem

load

public void load(InputStreamReader streamReader)
          throws IOException

Loads INI formatted input from a stream reader into this instance. Everything in the stream before the first section header is ignored.

Parameters:

streamReader - where to read from

Throws:

IOException - at an I/O problem