com.ccg.util
Class LookupINI

java.lang.Object
  com.ccg.util.LookupINI

All Implemented Interfaces:

Lookup, LookupKeyed, Cloneable

public class LookupINI
extends Object
implements LookupKeyed, Cloneable

Class to read/write Windows style INI files. Java has a standard Properties file format which is used to list key/value pairs in a ASCII file. The INI files commonly used by Windows for configuration are similar in nature, but have the concept of "sections". This class is designed to work with (and extend slightly) the usage of INI configuration files. The following features are provided:

• It should read standard INI files.
• It should write standard INI files.
• It makes the key/value pairs contained in the INI file look like a LookupKeyed object.
• It extends the INI by providing a "default" section.

The best way to see how this works, is to look at the commented example.ini file and the sample TestINI.java test class.

The INI file format recognized by this class uses the following rules:

Default Section

The default section is optional. The default section is a list of "key=value" pairs which occur at the start of the INI file (prior to the first [section]). All defined sections will fall back to using these "key=value" pairs if a lookup fails in their section. For example, if you define "author=Paul" in the default section and then define a "[Flowers]" section later on, then an attempt to get the value of "[Flowers]authoer" will return "Paul" unless the "author=NAME" was specifically defined in the "[Flowers]" section of your INI file. Refer to the examples mentioned above for more information.

Ignored Lines

All lines which are considered comments are ignored. In addition all lines which are not either "key=value" lines or "[section]" lines are also ignored.

key=value

All lines which are not ignored and have a equals sign somewhere AFTER the first position will be considered a "key=value" definition. The "value", which can be omitted, will be keyed in the current "[section]" (or default "[section]" if no section has been defined yet).

[section]

All lines which begin with a left bracket and end with a right bracket will be considered new "sections". Any "key=value" lines which follow will be grouped with this section.

To look up values from this object, you should set your keys to be preceded with the "[section]" of the area you want to find the value for. For example consider the following INI file:

#
# Comment lines (blank lines OK too)
#

width=640

[Dog]
width=800

[Cat]

To get the cat's width, you would use getString("[Cat]width") and you would get the value "640" (from the default section). If you used getString("[Dog]width") you would get the value "800" returned.

Since:

1.0

Version:

$Revision: 1.8 $

Author:

$Author: pkb $

See Also:

TagLookup

Constructor Summary

LookupINI()
Initializes object to a empty state.

LookupINI(InputStream is)
Initializes object and load from INI file.

Method Summary

void	add(InputStream is) Parse the contents of a InputStream This method parses a ASCII stream and applies the INI rules mentioned in the class documentation to load settings (ignoring comments).
void	add(String section, String key, Object data) Add/update a key/value pair in a particular section.
Object	clone() Makes a fairly light weight clone of the object.
Object	get(Object key) Fetch the value associated with a "key" Try to lookup the Object which is associated with the key.
Enumeration	getKeys() Get enumeration of all of the keys in the lookup table.
LookupOrdered	getSection(String sectName) Get the key/value pairs for a particular section.
Enumeration	getSectionKeys() Get a list of the defined sections.
String	getString(Object key) Fetch a String "value" associated with a "key".
String	getString(String section, String key, boolean allowDef) A "finer control" lookup of a particular key under a particular section.
boolean	hasSection(String sectName) Determine if a particular section is currently defined in the INI file.
void	orderSections(Enumeration ia, boolean addNew, boolean keepUnlisted) Method to re-arrange (order) the sections as they would appear when written to a file.
void	print(PrintWriter pw) Print the contents like a Windows INI file.
static String	removeBrackets(String s) Removes (but only if necessary) square brackets from a String.
void	removeSection(String sectName) Removes a entire section from the table based on key value.
static String	requireBrackets(String s) Adds (but only if necessary) square brackets to a String.
void	setCommentChars(String chars) Specify what set of characters should indicate EOL comments.

Methods inherited from class java.lang.Object

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

Constructor Detail

LookupINI

public LookupINI()

Initializes object to a empty state. After constructing a LookupINI object in this manner you will want to use a add method to fill it with data.

Since:

1.0

See Also:

LookupINI(InputStream)

LookupINI

public LookupINI(InputStream is)

Initializes object and load from INI file. This method creates the object and fills it with the information from the INI file passed as a InputStream.

Parameters:

is - Source to read ASCII INI data from.

Since:

1.0

See Also:

LookupINI(java.io.InputStream)

Method Detail

setCommentChars

public void setCommentChars(String chars)

Specify what set of characters should indicate EOL comments. When parsing ASCII files, it is desirable to ignore lines which contain comments. By default, the add(InputStream) method ignores all lines which start with "#;/\\ \t\r\n". If this is unacceptable for your source files, you can use this method to change what characters appearing at the start of a line indicate a comment.

Parameters:

chars - String containing the characters which will indicate that a ASCII line read by add(InputStream) should be ignored. Pass null if you want the default values.

Since:

1.0

add

public void add(String section,
                String key,
                Object data)

Add/update a key/value pair in a particular section. Most of the time, you will just read INI data from a file. However, this method allows you to add/update sections and key/value pairs within sections. Here are the things you can do:

Add a section

If you set the key/value pair parameters to null, you can use this method to add a section. Section names must be in the form of "[NAME]", or null/"" (for the default section).

Add a key/value pair to a section

By specifying all 3 parameters, you can add a key/value pair to a particular section.

Add a key/value pair to the default section

By setting your section name to null (or ""), you can add a key/value pair to the default section of the INI file. Once in the "default" section, the key/value pair will become a default lookup value for ALL sections.

Parameters:

section - Set this to the name of the section you want to add/update. This should be in the form of "[NAME]" to identify the section. Alternatively, you can set this parameter to null to indicate that the key/value pair is to be used as a default value for ALL sections. If both this this and the key are null, then nothing is done.

key - Must be non-null and have a length greater than zero if you want to actually add a key/value pair to the section. Set this to null if you just want to add a section, but don't want to also add a key/value pair.

data - The data to be associated with the key. You can set this to null if you like.

Since:

1.0

See Also:

add(InputStream)

add

public void add(InputStream is)

Parse the contents of a InputStream This method parses a ASCII stream and applies the INI rules mentioned in the class documentation to load settings (ignoring comments).

Parameters:

is - Source to read ASCII INI data from.

Since:

1.0

See Also:

getKeys()

getString

public String getString(String section,
                        String key,
                        boolean allowDef)

A "finer control" lookup of a particular key under a particular section.

This method provides the most flexible mechanism to lookup a string value under a one of the INI "sections". It is also more efficient than the methods used to implement the Lookup interface.

It should be noted that the "section" specified should be in its "bracket" form (pass values like: "[Login]", not "Login". You can use the requireBrackets(java.lang.String) method to help with this.

Parameters:

section - This should be the name of the section to look the value up with, it can be null if you want to just check the default section.

key - The "key" to look the value up for under the section specified. Must not be null.

allowDef - Set this parameter to true if you want us to check the default section if the item isn't found under the specific section you specified. Set to false to prohibit this extra check.

Returns:

String representation of value (or null if not found)

Since:

1.0

get

public Object get(Object key)

Fetch the value associated with a "key" Try to lookup the Object which is associated with the key. This method will never throw an exception.

Specified by:

get in interface Lookup

Specified by:

get in interface LookupKeyed

Parameters:

key - Key to use to look up object with (if you pass null, you will get null back).

Returns:

Object found (if exists) or null if not found.

Since:

1.0

See Also:

LookupCreate

getString

public String getString(Object key)

Fetch a String "value" associated with a "key". Try to lookup the String object which is associated with the key.

Specified by:

getString in interface Lookup

Specified by:

getString in interface LookupKeyed

Parameters:

key - Key to use to look up object with (if you pass null, you will get null back).

Returns:

Object found (if exists) returned as a String or null if not found. This implies that the objects contained by the Lookup table all support the Object.toString() method without Exception.

Since:

1.0

See Also:

LookupCreate

getKeys

public Enumeration getKeys()

Get enumeration of all of the keys in the lookup table. This implementation returns the list of all of the keys - in the order the keys were added to the lookup table.

Specified by:

getKeys in interface LookupKeyed

Returns:

Enumeration list of all keys in the Lookup table.

Since:

1.0

requireBrackets

public static String requireBrackets(String s)

Adds (but only if necessary) square brackets to a String.

This method forces a string to have the form "[TEXT]". If the original string passed is missing either the start bracket "[" and/or the ending bracket "]", they will be added.

Parameters:

s - String to remove the brackets (if any) from - must not be null. String to add the brackets to (if missing) - must not be null.

Returns:

A string which starts with "[" and ends with "]".

Since:

1.0

See Also:

removeBrackets(java.lang.String)

removeBrackets

public static String removeBrackets(String s)

Removes (but only if necessary) square brackets from a String.

This method takes a string of the form "[TEXT]", "TEXT]", "[TEXT" or "TEXT" and returns "TEXT". It can be useful to remove the brackets off the ends of a source string.

Parameters:

s - String to remove the brackets (if any) from - must not be null.

Returns:

A string which may have had square brackets removed from either or both ends of the original.

Since:

1.0

See Also:

requireBrackets(java.lang.String)

getSectionKeys

public Enumeration getSectionKeys()

Get a list of the defined sections. This method allows one to retrieve a Enumeration of the names of the defined sections. You can cast each element to a string if desired, or use it as a parameter to getSection(java.lang.String).

Returns:

A enumeration of the section names.

Since:

1.0

See Also:

getKeys()

print

public void print(PrintWriter pw)

Print the contents like a Windows INI file. This method prints the contents of the lookup table in a INI form maintaining the original ordering of the various [sections] and the components (key/value pairs) within each section.

Comments are not preserved by this object, so if the original INI file had comments in it and you use this method to print over it, the comments will be lost.

Parameters:

pw - Where to print the lookup table in ASCII form.

Since:

1.0

See Also:

add(java.lang.String, java.lang.String, java.lang.Object)

getSection

public LookupOrdered getSection(String sectName)

Get the key/value pairs for a particular section. If you want to work with just the key/value pairs from a specific section of the INI file, then you can use this method to retrieve the key/value lookup table associated with that section.

Since you will get a reference to the LookupOrdered object which this object also refers to, it is important to note that any modifications you make to sections lookup table will affect this object as well.

Parameters:

sectName - Name of the section in the INI file you want the properties for (like: "[maps]"). You can pass null if you want to get the "default" properties (you might get null back if this section wasn't created).

Returns:

A ordered lookup table of the properties specifically listed in the section. Any properties inherited from the default section (if any) will not be included. In addition, you may get null back if the section you specify doesn't exist.

Since:

1.0

See Also:

print(java.io.PrintWriter)

hasSection

public boolean hasSection(String sectName)

Determine if a particular section is currently defined in the INI file.

This method allows one to test to see if a particular section (like: "[Cat]", "[Internet]", etc) is defined in the LookupINI object. Be sure to enclose your section name with brackets (use the requireBrackets method to help with this).

Note: it is OK to pass null or "" to this method, it will detect this and return false.

Parameters:

sectName - The name of the section (with brackets - like "[Dog]"). If you pass null or zero length string we return false.

Returns:

true if the specified section exists, false if not.

Since:

1.0

See Also:

getSection(java.lang.String), requireBrackets(java.lang.String)

removeSection

public void removeSection(String sectName)

Removes a entire section from the table based on key value.

Parameters:

sectName - Name of the section to be removed. If you pass null or the name of a section which does not exist, nothing is done.

Since:

1.0

See Also:

get(Object)

orderSections

public void orderSections(Enumeration ia,
                          boolean addNew,
                          boolean keepUnlisted)

Method to re-arrange (order) the sections as they would appear when written to a file.

This method allows one to re-order the way sections will appear in the output when the INI object is written to a text file.

You have the option of specifying whether or not sections which are not explicitly listed in the new order should be retained or tossed.

It is important to realize that the LookupINI object itself does not care about the ordering (in other words, look ups will always work).

It is also important to realize that the default section (the one that is not preceded by a section name within square brackets) will ALWAYS be at the start of the output file (its the only way possible).

Parameters:

ia - A enumeration (iterator) which we can used to get the names of sections from. You must not pass null.

addNew - Set this to true if you want any new sections to be added to your INI object (if the enumeration contains sections which don't currently exist).

keepUnlisted - Set this to true if you want us to keep the sections which are not explicitly listed by your iterator (they will be added at the end). Set this to false if sections not explicitly listed should be removed.

Since:

1.0

clone

public Object clone()

Makes a fairly light weight clone of the object.

This method constructs a lightweight clone of the object. The relationship between the "cloned" object and the original object will be as follows:

• Key/data pairs will be the same at the time of the cloning (by reference).
• Any key/data data pairs added/removed will to either the "clone" or the "original" will NOT affect their counter part (they will NOT stay in sync).
• Since the references to the same data values are shared between the "clone" and "original" object at the time of cloning, if the data values are mutable (keys should never be mutated in a lookup object), then any data values which remain in both the "clone" and "original" values will share in any mutation.

Overrides:

clone in class Object

Returns:

Clone of the original object (you may cast it to a LookupOrdered object.

Since:

1.0