bill.util.config
Class ConfigurationSection

java.lang.Object
  |
  +--bill.util.config.ConfigurationSection

public class ConfigurationSection

extends Object

This class contains the information associated with a section of a configuration file. It also contains methods for searching the list of entries associated with the section.

Constructor Summary

ConfigurationSection(String sectionName)
Class creator.

ConfigurationSection(String sectionName, short entryConflictMode)
Class creator.

Method Summary

void	addEntry(ConfigurationEntry newEntry) Inserts a new entry into the hashtable of this section's entries.
void	addEntry(ConfigurationEntry newEntry, int index) Inserts a new entry into the hashtable of this section's entries at the specified index.
void	addEntry(String entryName, String entryValue) Inserts a new entry into the hashtable of this section's entries.
void	addEntry(String entryName, String entryValue, int index) Inserts a new entry into the hashtable of this section's entries at the specified index.
Hashtable	getEntries() Getter for this hashtable of entries for this section.
ConfigurationEntry	getEntry(String entryName) Retrieves the ConfigurationEntry class instance of the specified entry from this section.
ConfigurationEntry	getEntry(String entryName, int entryInstance) Retrieves the ConfigurationEntry class instance of the specified entry from this section.
short	getEntryConflictMode() Retrieves the entry conflict mode this section uses to resolve duplicate entry adds.
Vector	getEntryNames() Used to retrieve a Vector of the entries contained in this section.
int	getEntryQuantity(String entryName) Determines how many entries of the specified name exist for this section.
String	getEntryValue(String entryName) Retrieves the value of the specified entry from this section.
String	getEntryValue(String entryName, int entryInstance) Retrieves the value of the specified entry from this section.
int	getEntryValueAsInteger(String entryName) Retrieves the value of the specified entry from this section as an Integer.
int	getEntryValueAsInteger(String entryName, int entryInstance) Retrieves the value of the specified entry from this section.
int	getNumberOfEntries() Determines the number of entries contained in this section.
String	getSectionName() Retrieves the name of this section.
int	indexOf(String entryName) Determines the index of the first entry with the specified name.
int	indexOf(String entryName, int index) Determines the index of the first entry with the specified name beginning the search at the specified index.
boolean	isEntry(String entryName) Checks to see if this entry exists in the section.
boolean	isEntry(String entryName, int entryInstance) Checks to see if this entry exists in the section.
void	merge(ConfigurationSection section) Merges the entries from the specified section into the current section.
boolean	removeEntry(ConfigurationEntry entry) Removes an entry from this section.
boolean	removeEntry(String entryName) Removes the ConfigurationEntry class instance of the specified entry from this section.
void	setEntries(Hashtable entries) Setter for the hashtable of entries for this section.
void	setEntryConflictMode(short entryConflictMode) Sets the entry conflict mode this section uses to resolve duplicate entry adds.
void	setEntryNames(Vector entryNames) Setter for the ordered list of this section's entry names.
void	setEntryValue(String entryName, String entryValue) Adds a new entry to this section.
void	setSectionName(String sectionName) Sets the name of this section.
void	swapEntries(ConfigurationEntry firstEntry, ConfigurationEntry secondEntry) Swap the position of two entries in the ordered list of entries.
void	swapEntries(int first, int second) Swap the position of two entries in the ordered list of entries.
void	swapEntries(String firstName, String secondName) Swap the position of two entries in the ordered list of entries.
String	toFullString() Returns a string representation of the ConfigurationSection class, including all it's ConfigurationEntities.
String	toString() Returns a string representation of the ConfigurationSection class.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConfigurationSection

public ConfigurationSection(String sectionName)

Class creator. Initializes class variables.

Parameters:

sectionName - Name of the section being created

ConfigurationSection

public ConfigurationSection(String sectionName,
                            short entryConflictMode)

Class creator. Initializes class variables.

Parameters:

sectionName - Name of the section being created

entryConflictMode - Specifies the entry conflict resolution mode to use when duplicate entries are added to a section.

Method Detail

getSectionName

public String getSectionName()

Retrieves the name of this section.

Returns:

The name of the section.

getEntryConflictMode

public short getEntryConflictMode()

Retrieves the entry conflict mode this section uses to resolve duplicate entry adds.

Returns:

The entry conflict mode.

getEntryValue

public String getEntryValue(String entryName)

Retrieves the value of the specified entry from this section.

Parameters:

entryName - Name of the entry whose value is to be retrieved

Returns:

The entry's value or null if the entry could not be found.

getEntryValueAsInteger

public int getEntryValueAsInteger(String entryName)

Retrieves the value of the specified entry from this section as an Integer.

Parameters:

entryName - Name of the entry whose value is to be retrieved

Returns:

The entry's value or 0 if the entry could not be found.

getEntryValue

public String getEntryValue(String entryName,
                            int entryInstance)

Retrieves the value of the specified entry from this section. This version of this method supports retrieval of entries when the section allows duplicate entries. The user may specify which instance of the entry that want to retrieve.

Parameters:

entryName - Name of the entry whose value is to be retrieved

entryInstance - Which instance of the entry to retrieve. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.

Returns:

The entry's value or null if the entry could not be found.

getEntryValueAsInteger

public int getEntryValueAsInteger(String entryName,
                                  int entryInstance)

Retrieves the value of the specified entry from this section. This version of this method supports retrieval of entries when the section allows duplicate entries. The user may specify which instance of the entry that want to retrieve.

Parameters:

entryName - Name of the entry whose value is to be retrieved

entryInstance - Which instance of the entry to retrieve. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.

Returns:

The entry's value or 0 if the entry could not be found.

getEntryQuantity

public int getEntryQuantity(String entryName)

Determines how many entries of the specified name exist for this section. Unless duplicate entry names are allowed this always returns 0 or 1.

Parameters:

entryName - The name of the entry to get the quantity of.

Returns:

The number of entries by the specified name exist in this section.

getEntry

public ConfigurationEntry getEntry(String entryName)

Retrieves the ConfigurationEntry class instance of the specified entry from this section.

Parameters:

entryName - Name of the entry to be retrieved

Returns:

The entry's class instance or null if the entry could not be found.

getEntry

public ConfigurationEntry getEntry(String entryName,
                                   int entryInstance)

Retrieves the ConfigurationEntry class instance of the specified entry from this section. This version of this method supports retrieval of entries when the section allows duplicate entries. The user may specify which instance of the entry that want to retrieve.

Parameters:

entryName - Name of the entry to be retrieved

entryInstance - Which instance of the entry to retrieve. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.

Returns:

The entry's class instance or null if the entry could not be found.

removeEntry

public boolean removeEntry(String entryName)

Removes the ConfigurationEntry class instance of the specified entry from this section.

Parameters:

entryName - Name of the entry to be removed

Returns:

True if the entry is removed, false if the entry is not.

removeEntry

public boolean removeEntry(ConfigurationEntry entry)

Removes an entry from this section.

Parameters:

entry - The entry to remove.

Returns:

trueon success, false otherwise.

addEntry

public void addEntry(ConfigurationEntry newEntry)
              throws ConfigurationException

Inserts a new entry into the hashtable of this section's entries.

Parameters:

newEntry - The entry to be inserted

Throws:

ConfigurationException - Thrown when there is already an existing entry by this name and entry conflict resolution has been set to Configuration.ENTRY_CONFLICT_DISCARD.

addEntry

public void addEntry(ConfigurationEntry newEntry,
                     int index)
              throws ConfigurationException

Inserts a new entry into the hashtable of this section's entries at the specified index. All existing entries at this index and lower will be shifter one index lower. Indexes are 0 based. The hashtable does not care about the index, but we also keep a vector of the entry names so we know their order, the index is used by this vector.

Parameters:

newEntry - The entry to be inserted

index - The index to insert the entry at.

Throws:

ConfigurationException - Thrown when there is already an existing entry by this name and entry conflict resolution has been set to Configuration.ENTRY_CONFLICT_DISCARD.

addEntry

public void addEntry(String entryName,
                     String entryValue)
              throws ConfigurationException

Inserts a new entry into the hashtable of this section's entries.

Parameters:

entryName - The name of the entry to be inserted

entryValue - The value of the entry to be inserted

Throws:

ConfigurationException - Thrown when there is already an existing entry by this name and entry conflict resolution has been set to Configuration.ENTRY_CONFLICT_DISCARD.

addEntry

public void addEntry(String entryName,
                     String entryValue,
                     int index)
              throws ConfigurationException

Inserts a new entry into the hashtable of this section's entries at the specified index. All existing entries at this index and lower will be shifter one index lower. Indexes are 0 based.

Parameters:

entryName - The name of the entry to be inserted.

entryValue - The value of the entry to be inserted.

index - The index to insert the entry at.

Throws:

ConfigurationException - Thrown when there is already an existing entry by this name and entry conflict resolution has been set to Configuration.ENTRY_CONFLICT_DISCARD.

merge

public void merge(ConfigurationSection section)
           throws ConfigurationException

Merges the entries from the specified section into the current section. Keeps track of any failures and gathers them up so they can all be reported in a single exception. Merging means all the entries from the specified section are added to this section.

Parameters:

section - The section to be merged in.

Throws:

ConfigurationException - Thrown when one or more entries from the specified section cannot be added to the current section. This is typically caused by duplicate entries when the target section has an Entry Conflict Mode of Configuration.ENTRY_CONFLICT_DISCARD.

getEntries

public Hashtable getEntries()

Getter for this hashtable of entries for this section. Note that the order of entries in this hashtable is not guaranteed to match the order the entries were read from the configuration file or later added to the section. The key to the hashtable is the entry name, while the result is the ConfigurationEntry class instance for the entry name. The exception to this is if this section allows duplicate entries, in which case the result will be a Vector if ConfigurationEntry objects for cases where an entry name is duplicated.

Returns:

The entries hashtable.

getEntryNames

public Vector getEntryNames()

Used to retrieve a Vector of the entries contained in this section. The vector contains the entry names in the same order they were read from the configuration file. As non configuration file entries are added to the section they are appended to the existing entry name list.

Returns:

Vector containing the ordered list of entry names.

setSectionName

public void setSectionName(String sectionName)

Sets the name of this section.

Parameters:

sectionName - Value to set the section name to.

setEntryConflictMode

public void setEntryConflictMode(short entryConflictMode)

Sets the entry conflict mode this section uses to resolve duplicate entry adds.

Parameters:

entryConflictMode - The entry conflict mode.

setEntries

public void setEntries(Hashtable entries)

Setter for the hashtable of entries for this section. Note that if this method is used, the order the entries are written to the configuration file is indeterminate when the Configuration.save method is used. To avoid this, be sure to call setEntryNames with the correctly ordered names.

Parameters:

entries - Hashtable of entries and their values to set this section to.

See Also:

Configuration.save(), setEntryNames(java.util.Vector)

setEntryNames

public void setEntryNames(Vector entryNames)

Setter for the ordered list of this section's entry names. This list is used when saving a Configuration class instance to make sure the entries are stored in the same order they were retrieved.

Parameters:

entryNames - Vector containing the ordered list of entry names.

setEntryValue

public void setEntryValue(String entryName,
                          String entryValue)
                   throws ConfigurationException

Adds a new entry to this section. If the entry already exists than it's value is updated, otherwise the entry is added.

Parameters:

entryName - Name of the new entry to add or set.

entryValue - Value to give the entry.

Throws:

ConfigurationException - Thrown when there is already an existing entry by this name and entry conflict resolution has been set to Configuration.ENTRY_CONFLICT_DISCARD.

swapEntries

public void swapEntries(int first,
                        int second)

Swap the position of two entries in the ordered list of entries.

Parameters:

first - Index of the first entry we are switching

second - Index of the second entry we are switching

swapEntries

public void swapEntries(String firstName,
                        String secondName)

Swap the position of two entries in the ordered list of entries.

Parameters:

firstName - Entry name of the first entry we are switching

secondName - Entry name of the second entry we are switching

swapEntries

public void swapEntries(ConfigurationEntry firstEntry,
                        ConfigurationEntry secondEntry)

Swap the position of two entries in the ordered list of entries.

Parameters:

firstEntry - First entry we are switching

secondEntry - Second entry we are switching

indexOf

public int indexOf(String entryName)

Determines the index of the first entry with the specified name. Indexes are 0 based.

Parameters:

entryName - The name of the entry to look for.

Returns:

The index of the first occurrence of the specified entry, or -1 if no entries by the specified name exist.

indexOf

public int indexOf(String entryName,
                   int index)

Determines the index of the first entry with the specified name beginning the search at the specified index. Indexes are 0 based.

Parameters:

entryName - The name of the entry to look for.

index - The index to start the search at.

Returns:

The index of the first occurrence of the specified entry starting at the specified index, or -1 if no entries by the specified name exist.

getNumberOfEntries

public int getNumberOfEntries()

Determines the number of entries contained in this section.

Returns:

The number of entries defined to this section.

isEntry

public boolean isEntry(String entryName)

Checks to see if this entry exists in the section. The entry name must match exactly, case and whitespaces both count.

Parameters:

entryName - The name of the entry to look for.

Returns:

true if the entry exists, false otherwise.

isEntry

public boolean isEntry(String entryName,
                       int entryInstance)

Checks to see if this entry exists in the section. The entry name must match exactly, case and whitespaces both count. This version of this method supports checking for entries when the section allows duplicate entries. The user may specify which instance of the entry that want to check for.

Parameters:

entryName - The name of the entry to look for.

entryInstance - Which instance of the entry to retrieve. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.

Returns:

true if the entry exists, false otherwise.

toString

public String toString()

Returns a string representation of the ConfigurationSection class. We are using the section name as the string representation.

Overrides:

toString in class Object

Returns:

The string representation of the section.

toFullString

public String toFullString()

Returns a string representation of the ConfigurationSection class, including all it's ConfigurationEntities.

Returns:

The full string representation of the section including entries.