org.dtools.ini
Class IniSection

java.lang.Object
  extended by org.dtools.ini.IniSection
All Implemented Interfaces:
Cloneable, Iterable<IniItem>, Commentable
Direct Known Subclasses:
AdvancedIniSection, BasicIniSection

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

An IniSection represents a section within a configuration file (aka INI file). A section can contain zero or more items (which have unique names within a section), and those items have a value. In this API, an item is represented by the class IniItem.

Since:
0.1.10
Version:
1.1.0
Author:
David Lewis

Field Summary
protected  IniValidator validator
          A reference to this (and subclasses) IniSection's IniValidator which validates the name of this IniSection and all IniItems within this IniSection.
 
Fields inherited from interface org.dtools.ini.Commentable
COMMENT_SYMBOL
 
Constructor Summary
IniSection(String name)
          Default constructor which creates a new instance of this abstract IniSection and sets the IniSection to have a default IniValidator and to be case insensitive.
IniSection(String name, boolean caseSensitive)
          Constructor which creates a new instance of this abstract IniSection and sets the IniSection to have a default IniValidator.
IniSection(String name, IniValidator validator)
          Constructor which creates a new instance of this abstract IniSection and sets the IniSection to be case insensitive.
IniSection(String name, IniValidator validator, boolean caseSensitive)
          Constructor which creates a new instance of this abstract IniSection.
 
Method Summary
 boolean addItem(IniItem item)
          Adds an IniItem to this section.
abstract  boolean addItem(IniItem item, int index)
          Adds an IniItem to this section at the given index.
 IniItem addItem(String itemName)
          Adds a new IniItem to this section with the given name.
 IniItem addItem(String itemName, int index)
          Adds an IniItem to this section at the given index.
 void addItems(String... itemNames)
          Add multiple new items to this section.
abstract  Object clone()
          This class implements the Cloneable interface, but leaves implementation to subclasses which override this class.
protected abstract  IniItem createItem(String name)
          This method creates and returns a new instance of an IniItem with the same IniValidator and case sensitivity as this object.
 boolean equals(Object other)
          This predicate returns true if this IniSection is equal to the given object.
 String getEndLineComment()
          Returns the comment that comes after the object on the same line.
abstract  IniItem getItem(int index)
          Get the item which is at the given index.
 IniItem getItem(String name)
          Returns the item with the given name, or null if no item exists with the given name.
 Collection<String> getItemNames()
          This method returns a collection of all the names of all the items within this section.
abstract  Collection<IniItem> getItems()
          Get a collection of all the items within this section.
 String getName()
          This method returns the name of this section.
 int getNumberOfItems()
          Return the number of IniItems that this array has.
 String getPostComment()
          Returns the comment that comes after the object.
 String getPreComment()
          Returns the comment that comes before the object.
 IniValidator getValidator()
          Gets a reference to this object's IniValidator.
 int hashCode()
           
 boolean hasItem(IniItem item)
          Predicate that returns true if an item is in this section.
 boolean hasItem(String itemName)
          Predicate that returns true if an item already exists.
abstract  int indexOf(IniItem item)
          Returns the index of item that is in this section.
 int indexOf(String itemName)
          Returns the index of item that is in this section.
 boolean isCaseSensitive()
          Predicate that returns true if this IniSection is case sensitive, or false if this IniSection is case insensitive.
 boolean isEmpty()
          Predicate that returns true if the section has no items, false if it does have at least one item.
 boolean merge(IniSection otherSection)
          This method merges another IniSection to this section.
 void moveItem(int fromIndex, int toIndex)
          This method moves an item at index fromIndex to the index toIndex.
 void moveItem(String name, int toIndex)
          This method moves the item whose names is given to the the index toIndex.
 void removeAll()
          Removes all the items and its values from the section.
 void removeEndLineComment()
          Removes an end line comment from the object.
abstract  boolean removeItem(IniItem item)
          Removes the item this section.
 IniItem removeItem(int index)
          Removes the item that is at the given index from this section.
 IniItem removeItem(String name)
          Removes an item whose name matches the given name the section.
 Collection<IniItem> removeItems(String[] names)
          Removes all the items from this section whose names are within the given array.
 void removePostComment()
          Removes a post-comment from the object.
 void removePreComment()
          Removes a pre-comment from the object.
 void setEndLineComment(String comment)
          Set the comment that comes after the object but on the same line.
 void setPostComment(String comment)
          Set the comment that comes after the object.
 void setPreComment(String comment)
          Set the comment that comes before the object.
 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 (and subclasses) IniSection's IniValidator which validates the name of this IniSection and all IniItems within this IniSection.

Constructor Detail

IniSection

public IniSection(String name)

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

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

IniSection

public IniSection(String name,
                  boolean caseSensitive)

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

Parameters:
name - The name of this IniSection.
caseSensitive - Sets whether this IniSection is case sensitive or not.
Throws:
InvalidNameException - if the name of the IniSection given is not considered valid by this object's IniValidator.

IniSection

public IniSection(String name,
                  IniValidator validator)

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

Parameters:
name - The name of this IniSection.
validator - The IniValidator of this IniSection.
Throws:
InvalidNameException - if the name of the IniSection given is not considered valid by this object's IniValidator.

IniSection

public IniSection(String name,
                  IniValidator validator,
                  boolean caseSensitive)

Constructor which creates a new instance of this abstract IniSection.

Parameters:
name - The name of this IniSection.
validator - The IniValidator of this IniSection.
caseSensitive - Sets whether this IniSection is case sensitive or not.
Throws:
InvalidNameException - if the name of the IniSection given is not considered valid by this object's IniValidator.
Method Detail

addItem

public boolean addItem(IniItem item)
Adds an IniItem to this section. If an item already in the section has the same name as the one being added, then the method will not overwrite the item and will instead return false. The index of the item, if it added successfully, is unknown and depends on the implementation of this interface. Programmers should not make any assumptions on where new items are added.

Parameters:
item - the item to add
Returns:
true if the item was added successfully, false if the item already existed or could not be added

addItem

public abstract boolean addItem(IniItem item,
                                int index)
Adds an IniItem to this section at the given index. If an item already in the section has the same name as the one being added, then the method will not overwrite the item and will instead return false.

Parameters:
item - the item to add
index - the index where to add the item, where 0 is the index of the first item. Any items that already exists at this index will be moved to index + 1. If the value is greater than the number of items within this section, then the item is appended to the end of the section.
Returns:
true if the item was added successfully, false if the item already existed or could not be added
Throws:
IndexOutOfBoundsException - if the value of index is less than 0.

addItem

public IniItem addItem(String itemName)
Adds a new IniItem to this section with the given name. If an item already in the section has an the same name, then the method returns false. The index of the item, if it added successfully, is unknown and depends on the implementation of this interface. Programmers should not make any assumptions on where new items are added.

Parameters:
itemName - The name of the item to add.
Returns:
A reference to the Item added to this section, or null if the item could not be created.

addItem

public IniItem addItem(String itemName,
                       int index)
Adds an IniItem to this section at the given index. If an item already in the section has an the same name, then the method returns false.

Parameters:
itemName - The name of the item to add.
index - The index where to add the item, where 0 is the index of the first item. Any items that already exists at this index will be moved to index + 1. If the value is greater than the number of items within this section, then the item is appended to the end of the section.
Returns:
A reference to the Item added to this section, or null if the item could not be created.
Throws:
IndexOutOfBoundsException - if the value of index is less than 0.

addItems

public void addItems(String... itemNames)
Add multiple new items to this section. The values of the new items will be null. If any of the given names are duplicates, or if a name is identical to an item that already exist. The index of the item, if it added successfully, is unknown and depends on the implementation of this interface. Programmers should not make any assumptions on where new items are added.

Parameters:
itemNames - the names of the items to add.

createItem

protected abstract IniItem createItem(String name)

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

Parameters:
name - The name of the IniItem to create.
Returns:
A new instance of an IniItem with the same IniValidator and case sensitivity as this object.
Throws:
InvalidNameException - if the name of the IniItem given is not considered valid by this object's IniValidator.

equals

public boolean equals(Object other)

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

* If the two IniSections are case-sensitive, then these are compared using the equals(Object) method. If the two IniSections are case-insensitive, then these are compared using the String.equalsIgnoreCase(String) method.

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

getEndLineComment

public String getEndLineComment()
Description copied from interface: Commentable

Returns the comment that comes after the object on the same line. If not such comment exists an empty string is returned.

Specified by:
getEndLineComment in interface Commentable
Returns:
the comment or "" if no comment exists.

getItem

public abstract IniItem getItem(int index)
Get the item which is at the given index.

Parameters:
index - the index of the item to retrieve.
Returns:
The item that is at the given index.
Throws:
IndexOutOfBoundsException - if the given value is less than 0 or greater or equal to the number of items in this section (i.e. > getNumberOfItems()-1.

getItem

public IniItem getItem(String name)
Returns the item with the given name, or null if no item exists with the given name.

Parameters:
name - The name of the item.
Returns:
The IniItem with the given name, or null if the item doesn't exists.

getItemNames

public Collection<String> getItemNames()
This method returns a collection of all the names of all the items within this section.

Returns:
A collection of all the names.

getItems

public abstract Collection<IniItem> getItems()
Get a collection of all the items within this section.

Returns:
A collection of all the items.

getName

public String getName()
This method returns the name of this section. Note that a section cannot change its name.

Returns:
The name of this section

getNumberOfItems

public int getNumberOfItems()
Return the number of IniItems that this array has.

Returns:
the number of items that this array has

getPostComment

public String getPostComment()
Description copied from interface: Commentable

Returns the comment that comes after the object. If not such comment exists an empty string is returned.

Specified by:
getPostComment in interface Commentable
Returns:
the comment or "" if no comment exists.

getPreComment

public String getPreComment()
Description copied from interface: Commentable

Returns the comment that comes before the object. If not such comment exists an empty string is returned.

Specified by:
getPreComment in interface Commentable
Returns:
the comment or "" if no comment exists.

getValidator

public IniValidator getValidator()

Gets a reference to this object's IniValidator.

Returns:
The IniValidator used by this IniSection.
Since:
0.1.17

hashCode

public int hashCode()
Overrides:
hashCode in class Object

hasItem

public boolean hasItem(IniItem item)
Predicate that returns true if an item is in this section. More specifically this method returns true if the class contains a reference to the given item, and not if this class has a similar item with the same name and value.

Parameters:
item - The item to test.
Returns:
True if an item that matches that name exists, false otherwise.

hasItem

public boolean hasItem(String itemName)
Predicate that returns true if an item already exists.

Parameters:
itemName - the name of the item to test
Returns:
true if an item that matches that name exists, false otherwise.

indexOf

public abstract int indexOf(IniItem item)
Returns the index of item that is in this section. If no such item exists, then the value -1 is returned.

Parameters:
item - The IniItem whose index will be returned.
Returns:
The index of the given item.

indexOf

public int indexOf(String itemName)
Returns the index of item that is in this section. If no such item exists, then the value -1 is returned.

Parameters:
itemName - The name of the item whose index will be returned.
Returns:
The index of the item.

isCaseSensitive

public boolean isCaseSensitive()

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

Returns:
boolean
Since:
0.1.16

isEmpty

public boolean isEmpty()
Predicate that returns true if the section has no items, false if it does have at least one item.

Returns:
true or false

merge

public boolean merge(IniSection otherSection)
This method merges another IniSection to this section. All the items that the other section has will be copied over to this section providing that no item has the same name in both section.

Parameters:
otherSection - the other section to merge to this section
Returns:
true if the merge was successful, false if the merge failed due to an item that had the same name in both sections.

moveItem

public void moveItem(int fromIndex,
                     int toIndex)
This method moves an item at index fromIndex to the index toIndex.

Parameters:
fromIndex - The index of the item to move
toIndex - The index where to place the item, any items 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 items in this section (i.e. > getNumberOfItems()-1).

moveItem

public void moveItem(String name,
                     int toIndex)
This method moves the item whose names is given to the the index toIndex.

Parameters:
name - The name of the item to move.
toIndex - The index where to place the item, any items already at that index will be moved to index+1.
Throws:
IndexOutOfBoundsException - if toIndex is below 0 or greater than or equal to the number of items in this section (i.e. > getNumberOfItems()-1), or if the given name of the item doesn't exist.

removeAll

public void removeAll()
Removes all the items and its values from the section.


removeEndLineComment

public void removeEndLineComment()
Description copied from interface: Commentable
Removes an end line comment from the object. This is the equivalent to:
setEndLineComment("");

Specified by:
removeEndLineComment in interface Commentable

removeItem

public abstract boolean removeItem(IniItem item)
Removes the item this section. If the given item does not exists in the section, then the method does nothing.

Parameters:
item - The item to remove.
Returns:
boolean, true if the IniItem was removed, false it the given IniItem did not exists in the first place.

removeItem

public IniItem removeItem(int index)
Removes the item that is at the given index from this section.

Parameters:
index - the index of the item to remove
Returns:
The IniItem that was removed.
Throws:
IndexOutOfBoundsException - if index is below 0 or greater than or equal to the number of items in this section (i.e. > getNumberOfItems() - 1).

removeItem

public IniItem removeItem(String name)
Removes an item whose name matches the given name the section.

Parameters:
name - The name of the name of the item to remove.
Returns:
The IniItem that was removed.

removeItems

public Collection<IniItem> removeItems(String[] names)
Removes all the items from this section whose names are within the given array.

Parameters:
names - An array of the names of the items to remove
Returns:
A collection of all the IniItems that were removed.

removePostComment

public void removePostComment()
Description copied from interface: Commentable
Removes a post-comment from the object. This is the equivalent to:
setPostComment("");

Specified by:
removePostComment in interface Commentable

removePreComment

public void removePreComment()
Description copied from interface: Commentable
Removes a pre-comment from the object. This is the equivalent to:
setPreComment("");

Specified by:
removePreComment in interface Commentable

setEndLineComment

public void setEndLineComment(String comment)
Description copied from interface: Commentable

Set the comment that comes after the object but on the same line.

Specified by:
setEndLineComment in interface Commentable
Parameters:
comment - The text comment, if this value is null, then the comment is set to an empty string.

setPostComment

public void setPostComment(String comment)
Description copied from interface: Commentable
Set the comment that comes after the object.

Specified by:
setPostComment in interface Commentable
Parameters:
comment - the text comment, if this value is null, then the comment is set to an empty string.

setPreComment

public void setPreComment(String comment)
Description copied from interface: Commentable

Set the comment that comes before the object.

Specified by:
setPreComment in interface Commentable
Parameters:
comment - the text comment, if this value is null, then the comment is set to an empty string.

toString

public String toString()
Overrides:
toString in class Object

clone

public abstract Object clone()

This class implements the Cloneable interface, but leaves implementation to subclasses which override this class.

Overrides:
clone in class Object
Returns:
An object which is an instance of class, has the same values as this object, would return true for thisObject.equals( thisObject.clone() );, but returns false for thisObject == thisObject.clone();
Since:
1.0.00