org.dtools.ini
Class IniFile

java.lang.Object
  org.dtools.ini.IniFile

All Implemented Interfaces:

Cloneable, Iterable<IniSection>

Direct Known Subclasses:

AdvancedIniFile, BasicIniFile

public abstract class IniFile
extends Object
implements Cloneable, Iterable<IniSection>

An IniFile is an abstract class which defines the public and protected methods of an IniFile implementation. This class is designed to represent a physical INI file (a.k.a. a configuration file) on a hard disk, which is a type of file that stores properties of configuration data for applications.

Since:

0.1.10

Version:

1.1.0

Author:

David Lewis

Field Summary

protected IniValidator

validator A reference to this IniFile's IniValidator which validates all names for IniSections and IniItems.

Constructor Summary

IniFile()
Default constructor which creates a new instance of this abstract IniFile and sets the IniFile to have a default IniValidator and to be case insensitive.

IniFile(boolean caseSensitive)
Constructor which creates a new instance of this abstract IniFile and sets the IniFile to have a default IniValidator.

IniFile(IniValidator validator)
Constructor which creates a new instance of this abstract IniFile and sets the IniFile to be case insensitive.

IniFile(IniValidator validator, boolean caseSensitive)
Constructor which creates a new instance of this abstract IniFile.

Method Summary

boolean	addOrMergeSection(IniSection otherSection) This method adds the given section to the end of the IniFile if a section with the same name does not already exist.
boolean	addSection(IniSection section) This method adds the given IniSection to the IniFile providing that there are no existing sections with the same name as the given IniSection.
abstract boolean	addSection(IniSection section, int index) Adds a section to this INI file.
IniSection	addSection(String sectionName) Adds a section to this INI file.
IniSection	addSection(String sectionName, int index) Adds a new section to this INI file which has the given name.
void	addSections(String... names) Adds multiple new sections to this INI file.
abstract Object	clone()
protected abstract IniSection	createSection(String name) This method creates and returns a new instance of an IniSection with the same IniValidator and case sensitivity as this object.
boolean	equals(Object other) This predicate returns true if this IniFile is equal to the given object.
int	getNumberOfItems() Returns the total number of all the items, in every section, that this IniFile has.
int	getNumberOfSections() Returns the number of sections this IniFile object has.
abstract IniSection	getSection(int index) Get the section which is at the given index.
IniSection	getSection(String name) Returns the section that is called name, or null if no such section exists.
Collection<String>	getSectionNames() Gets a collection of the names of all the sections in this IniFile.
abstract Collection<IniSection>	getSections() Gets a collection of all the sections within this INI file.
IniValidator	getValidator() Returns a reference to this object's IniValidator which is used to validate names of this IniFile's IniSections and their IniItems.
int	hashCode()
boolean	hasSection(IniSection section) Predicate that returns true if this IniFile has a given section.
boolean	hasSection(String name) Predicate that returns true if this IniFile has a section with the given name.
abstract int	indexOf(IniSection section) Get the index of the given section, where 0 is the index is the first section.
int	indexOf(String sectionName) Get the index of the section whose name is given, where 0 is the index is the first section.
boolean	isCaseSensitive() Predicate that returns true if this object is case sensitive, or false if it is case insensitive.
boolean	isEmpty() Predicate that returns true if this IniFile has no sections.
boolean	merge(IniFile otherIni) This method merges an IniFile with this IniFile, and that all the sections within the other IniFile are copied to this IniFile, and if the two IniFiles share any similarly named sections, then those sections are merged together.
void	moveSection(int fromIndex, int toIndex) This method moves a section at index fromIndex to the index toIndex.
boolean	moveSection(String name, int toIndex) This method moves the section whose names is given to the the index toIndex.
void	removeAll() Removes all the sections from this IniFile.
abstract boolean	removeSection(IniSection section) Removes the given section only if the section is within this IniFile
IniSection	removeSection(int index) Removes a section from the IniFile.
IniSection	removeSection(String name) Removes a section from the IniFile.
Collection<IniSection>	removeSections(String[] names) Removes all the sections whose names are in the given array.
String	toString()

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

iterator

Field Detail

validator

protected IniValidator validator

A reference to this IniFile's IniValidator which validates all names for IniSections and IniItems.

Constructor Detail

IniFile

public IniFile()

Default constructor which creates a new instance of this abstract IniFile and sets the IniFile to have a default IniValidator and to be case insensitive.

IniFile

public IniFile(boolean caseSensitive)

Constructor which creates a new instance of this abstract IniFile and sets the IniFile to have a default IniValidator.

Parameters:

caseSensitive - Sets whether this instance of IniFile is case sensitive or not.

IniFile

public IniFile(IniValidator validator)

Constructor which creates a new instance of this abstract IniFile and sets the IniFile to be case insensitive.

Parameters:

validator - Sets the IniValidator if this instance of IniFile.

IniFile

public IniFile(IniValidator validator,
               boolean caseSensitive)

Constructor which creates a new instance of this abstract IniFile.

Parameters:

validator - Sets the IniValidator if this instance of IniFile.

caseSensitive - Sets whether this instance of IniFile is case sensitive or not.

Method Detail

addOrMergeSection

public boolean addOrMergeSection(IniSection otherSection)

This method adds the given section to the end of the IniFile if a section with the same name does not already exist. If a section with the same name does exists, then the given section is merged with the existing section providing that the two sections do not contain identically named items.

A merge is also not possible if the given section is not compatible with the policies of the IniFile. That is to say, the IniSection has a different case-sensitivity, or an unequal IniValidator to the IniFile.

If a merge is performed, then the index of the existing section does not change.

Parameters:

otherSection - the new section to add or merge to this IniFile

Returns:

true if the section was added or merged successfully, false only if a merge could not be performed as the given section is incompatible.

Throws:

InvalidNameException - If the name of the given section is not considered valid by the IniFile's IniValidator.

addSection

public boolean addSection(IniSection section)

This method adds the given IniSection to the IniFile providing that there are no existing sections with the same name as the given IniSection.

The given section can also not be added if the given section is not compatible with the policies of the IniFile. That is to say the IniSection has a different case-sensitivity, or an unequal IniValidator to the IniFile.

Parameters:

section - The section to add to this INI file.

Returns:

True if the section was added successfully, false if a section with the same name already exists, or if the given section is incompatible with the IniFile.

Throws:

InvalidNameException - If the name of the given section is not considered valid by the IniFile's IniValidator.

addSection

public abstract boolean addSection(IniSection section,
                                   int index)

Adds a section to this INI file. If an existing section has the same name as the given section, then the new section is not added and the method returns false. If the given section is of a type that is not compatible with the class that implements this interface, then a compatible copy of the section is made which is then added to the class.

Parameters:

section - The section to add to this INI file.

index - The index where to add the section, where 0 is the index of the first section. Any section that already exists at this index will be moved to index + 1. If the value is greater than the number of sections within this INI file, then the section is appended to the end of the INI file.

Returns:

True if the section was added successfully, false if a section with the same name already exists.

Throws:

IndexOutOfBoundsException - if the value of index is less than 0.

addSection

public IniSection addSection(String sectionName)

Adds a section to this INI file. If an existing section has the same name as the given section, then the method returns false. The index of the section, if it added successfully, is unknown and depends on the implementation of this interface. Programmers should not make any assumptions on where the new section is added.

Parameters:

sectionName -

Returns:

A reference to the IniSection created, or null if, the section could not be created.

addSection

public IniSection addSection(String sectionName,
                             int index)

Adds a new section to this INI file which has the given name. If an existing section has the same name as the given section, then the method returns false.

Parameters:

sectionName - The name of the new section to add.

index - The index where to add the section, where 0 is the index of the first section. Any section that already exists at this index will be moved to index + 1. If the value is greater than the number of sections within this INI file, then the section is appended to the end of the INI file.

Returns:

A reference to the IniSection created, or null if, the section could not be created.

Throws:

IndexOutOfBoundsException - if the value of index is less than 0.

addSections

public void addSections(String... names)

Adds multiple new sections to this INI file.

Parameters:

names - a list of names for the new sections.

createSection

protected abstract IniSection createSection(String name)

This method creates and returns a new instance of an IniSection with the same IniValidator and case sensitivity as this object.

Parameters:

name - The name of the IniSection to create.

Returns:

A new instance of an IniSection with the same IniValidator and case sensitivity as this object.

Throws:

InvalidNameException - if the name of the IniSection given is not considered valid by this object's IniValidator.

equals

public boolean equals(Object other)

This predicate returns true if this IniFile is equal to the given object. For other to be equal to this one it must:

• be an instance of IniFile.
• have the same case-sensitivity as this IniFile.
• have an equal IniValidator as this IniFile's IniValidator.
• have the same number of IniSections as this IniFile.
• have equal IniSections as this IniFile.
• have the same order of IniSections as this IniFile.

Overrides:

equals in class Object

Parameters:

other - The other Object to test for equality.

Returns:

True if equal, false if not equal.

Since:

0.1.15

getNumberOfItems

public int getNumberOfItems()

Returns the total number of all the items, in every section, that this IniFile has.

Returns:

the total number of items in the IniFile

getNumberOfSections

public int getNumberOfSections()

Returns the number of sections this IniFile object has.

Returns:

the number of sections

getSection

public abstract IniSection getSection(int index)

Get the section which is at the given index.

Parameters:

index - the index of the section to retrieve.

Returns:

The section that is at the given index.

Throws:

IndexOutOfBoundsException - if the given value is less than 0 or greater or equal to the number of sections in this INI file (i.e. > getNumberOfSections()-1.

getSection

public IniSection getSection(String name)

Returns the section that is called name, or null if no such section exists.

Parameters:

name - the name of the section to return

Returns:

The IniSection with the given name, or null if no section with that name exists.

getSectionNames

public Collection<String> getSectionNames()

Gets a collection of the names of all the sections in this IniFile.

Returns:

a collection of all the names.

getSections

public abstract Collection<IniSection> getSections()

Gets a collection of all the sections within this INI file.

Returns:

A collection of all the Sections.

getValidator

public IniValidator getValidator()

Returns a reference to this object's IniValidator which is used to validate names of this IniFile's IniSections and their IniItems.

Returns:

This IniFile's IniValidator.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

hasSection

public boolean hasSection(IniSection section)

Predicate that returns true if this IniFile has a given section. More specifically this method returns true if the class contains a reference to the given section, and not if this class has a similar section with the same name, items and values.

Parameters:

section - The section to test.

Returns:

True if this IniFile has the section, false otherwise

hasSection

public boolean hasSection(String name)

Predicate that returns true if this IniFile has a section with the given name.

Parameters:

name - The name of the section to test

Returns:

True if this IniFile has the section, false otherwise

indexOf

public abstract int indexOf(IniSection section)

Get the index of the given section, where 0 is the index is the first section. If the given section is not in this INI file, then -1 is returned.

Parameters:

section - The section whose index will be retured

Returns:

The index of the section, or -1 is no such section exists.

indexOf

public int indexOf(String sectionName)

Get the index of the section whose name is given, where 0 is the index is the first section. If the given section name doesn't exists, then -1 is returned.

Parameters:

sectionName - The name of the section whose index will be retured

Returns:

The index of the section, or -1 is no such section exists.

isCaseSensitive

public boolean isCaseSensitive()

Predicate that returns true if this object is case sensitive, or false if it is case insensitive.

Returns:

boolean

isEmpty

public boolean isEmpty()

Predicate that returns true if this IniFile has no sections.

Returns:

True if the object has no sections, false if the object has at least one section.

merge

public boolean merge(IniFile otherIni)

This method merges an IniFile with this IniFile, and that all the sections within the other IniFile are copied to this IniFile, and if the two IniFiles share any similarly named sections, then those sections are merged together. If this IniFile already has some sections, then they will not be removed, and will still be present after a successful merge.

Parameters:

otherIni - the other IniFile that will be merged with this IniFile.

Returns:

true if the merge was successful, false if the was not successful do to a similarly named item that exists in the same section in both IniFiles.

See Also:

IniSection.merge(org.dtools.ini.IniSection)

moveSection

public void moveSection(int fromIndex,
                        int toIndex)

This method moves a section at index fromIndex to the index toIndex.

Parameters:

fromIndex - The index of the section to move.

toIndex - The index where to place the section, any sections already at that index will be moved to index+1.

Throws:

IndexOutOfBoundsException - if either fromIndex or toIndex is below 0 or greater than or equal to the number of sections in this INI file (i.e. > getNumberOfSections()-1).

moveSection

public boolean moveSection(String name,
                           int toIndex)

This method moves the section whose names is given to the the index toIndex.

Parameters:

name - The name of the section to move.

toIndex - The index where to place the section, any sections already at that index will be moved to index+1.

Returns:

boolean, true if the move was sucessful, false otherwise.

Throws:

IndexOutOfBoundsException - if toIndex is below 0 or greater than or equal to the number of section in this INI file (i.e. > getNumberOfSections()-1).

NullPointerException - if no section in the section exists called name.

removeAll

public void removeAll()

Removes all the sections from this IniFile.

removeSection

public abstract boolean removeSection(IniSection section)

Removes the given section only if the section is within this IniFile

Parameters:

section - The section to remove.

Returns:

boolean, true if the IniSection was removed, false it the given IniSection did not exists in the first place.

removeSection

public IniSection removeSection(int index)

Removes a section from the IniFile.

Parameters:

index - The index of the item to remove.

Returns:

The IniSection that has just been removed.

Throws:

IndexOutOfBoundsException - if index is below 0 or greater than or equal to the number of section in this INI file (i.e. > getNumberOfSections()-1).

removeSection

public IniSection removeSection(String name)

Removes a section from the IniFile.

Parameters:

name - The name of the section to remove

Returns:

The IniSection that has just been removed, or null if no section matches the given name

removeSections

public Collection<IniSection> removeSections(String[] names)

Removes all the sections whose names are in the given array. If none of the names in the given array existed, then an empty Collection is returned.

Parameters:

names - The names of all the sections to remove

Returns:

A collection of all the sections that have just been removed.

toString

public String toString()

Overrides:

toString in class Object

clone

public abstract Object clone()

Overrides:

clone in class Object