bill.util.config
Class Configuration

java.lang.Object
  |
  +--bill.util.config.Configuration
Direct Known Subclasses:
ConConfiguration, CSVConfiguration, PersistConfiguration

public class Configuration
extends Object

This class controls the reading and accessing of configuration information stored in the equivalent of Windows "ini" files.


Field Summary
protected  ConfigurationSection _currentSection
          Internal pointer to the current section being manipulated when reading a configuration from a file.
protected  String _fileName
          Name of the file associated with the configuration data
protected  Vector _sectionNames
          A list of the section names for the configuration in the order they appear in the configuration.
protected  Hashtable _sections
          The list of section in the configuration.
static short ENTRY_CONFLICT_APPEND
          Indicates that when a duplicate entry is added, the original will be left as is and another entry with the same name will be added as well.
static short ENTRY_CONFLICT_DISCARD
          Indicates that when a duplicate entry is added, it should be discarded (ignored) and the value of the existing one is left unchanged.
static short ENTRY_CONFLICT_OVERWRITE
          Indicates that when a duplicate entry is added, it should overwrite the value of the existing one.
static short SECTION_CONFLICT_APPEND
          Indicates that when a duplicate section is added, the original will be left as is and another section with the same name will be added as well.
static short SECTION_CONFLICT_DISCARD
          Indicates that when a duplicate section is added, it should be discarded (ignored) and the value of the existing one is left unchanged.
static short SECTION_CONFLICT_INCLUDE
          Indicates that when a duplicate section is added, the original will be left as is and and we will just add entries for this section to the existing section's entries.
static short SECTION_CONFLICT_OVERWRITE
          Indicates that when a duplicate section is added, it should overwrite the value of the existing one.
 
Constructor Summary
Configuration()
          Default creator, just sets our section list information to empty containers.
Configuration(String fileName)
          Class creator.
 
Method Summary
 ConfigurationSection addSection(String sectionName)
          Adds a new section to this configuration.
 ConfigurationSection addSection(String sectionName, int index)
          Adds a new section to this configuration.
 ConfigurationEntry addSectionEntry(ConfigurationSection section, ConfigurationEntry entry)
          Adds a new entry to a section in this configuration.
 ConfigurationEntry addSectionEntry(String sectionName, String entryName, String entryValue)
          Adds a new entry to a section in this configuration.
 Vector getEntryNames(String sectionName)
          Used to retrieve a Vector of the entries contained in the specified section within this configuration.
 String getFileName()
          Getter for the name of the file this configuration data belongs to.
 int getNumberOfEntries(String sectionName)
          Determines the number of entries contained in specified section.
 int getNumberOfSections()
          Determines the number of sections contained in this configuration.
 ConfigurationSection getSection(String sectionName)
          Finds the requested ConfigurationSection entry in the list of sections the configuration file contains.
 ConfigurationSection getSection(String sectionName, int sectionInstance)
          Finds the requested instance of the ConfigurationSection entry in the list of sections the configuration file contains.
 short getSectionConflictMode()
          Gets the section conflict mode a section uses to resolve duplicate section adds.
 ConfigurationEntry getSectionEntry(String sectionName, int sectionInstance, String entryName)
          Finds the requested ConfigurationEntry class instance from the specified section.
 ConfigurationEntry getSectionEntry(String sectionName, String entryName)
          Finds the requested ConfigurationEntry class instance from the specified section.
 short getSectionEntryConflictMode(String sectionName)
          Gets the entry conflict mode a section uses to resolve duplicate entry adds.
 int getSectionEntryQuantity(String sectionName, int sectionInstance, String entryName)
          Determines how many entries of the specified name exist for the specified section.
 int getSectionEntryQuantity(String sectionName, String entryName)
          Determines how many entries of the specified name exist for the specified section.
 String getSectionEntryValue(String sectionName, int sectionInstance, String entryName)
          Finds the requested entry's value from the specified section.
 String getSectionEntryValue(String sectionName, int sectionInstance, String entryName, int entryInstance)
          Finds the requested entry's value from the specified section.
 String getSectionEntryValue(String sectionName, String entryName)
          Finds the requested entry's value from the specified section.
 String getSectionEntryValue(String sectionName, String entryName, int entryInstance)
          Finds the requested entry's value from the specified section.
 int getSectionEntryValueAsInteger(String sectionName, int sectionInstance, String entryName)
          Finds the requested entry's value from the specified section.
 int getSectionEntryValueAsInteger(String sectionName, int sectionInstance, String entryName, int entryInstance)
          Retrieves the value of the specified entry from this section.
 int getSectionEntryValueAsInteger(String sectionName, String entryName)
          Finds the requested entry's value from the specified section.
 int getSectionEntryValueAsInteger(String sectionName, String entryName, int entryInstance)
          Finds the requested entry's value from the specified section.
 Vector getSectionNames()
          Used to retrieve a Vector of the sections contained in this configuration.
 int getSectionQuantity(String sectionName)
          Determines how many sections of the specified name exist in this configuration.
 Hashtable getSections()
          Getter for the hashtable of sections in a Configuration instance.
 int indexOf(String sectionName)
          Determines the index of the first section with the specified name.
 int indexOf(String sectionName, int index)
          Determines the index of the first section with the specified name beginning the search at the specified index.
 boolean isSection(String sectionName)
          Checks to see if this section exists in the configuration.
 boolean isSection(String sectionName, int sectionInstance)
          Checks to see if this section exists in the configuration.
 boolean isSectionEntry(String sectionName, String entryName)
          Checks to see if this section entry exists in the configuration.
 void merge(Configuration config)
          Merges the sections from the specified configuration into the current configuration.
 void mergeSections(String target, int targetInstance, String source)
          Merges the entries from one section with the entries from another.
 void mergeSections(String target, int targetInstance, String source, int sourceInstance)
          Merges the entries from one section with the entries from another.
 void mergeSections(String target, String source)
          Merges the entries from one section with the entries from another.
 void mergeSections(String target, String source, int sourceInstance)
          Merges the entries from one section with the entries from another.
 boolean removeSection(ConfigurationSection section)
          Removes a section from this configuration.
 boolean removeSection(String sectionName)
          Removes a section from this configuration.
 boolean removeSectionEntry(String sectionName, String entryName)
          Removes an entry from a section in this configuration.
 ConfigurationSection renameSection(String oldName, String newName)
          Renames an existing section to the given new name.
 void save()
          Method to save the configuration back to a file.
 boolean setFileName(String fileName)
          Setter for the name of the file this configuration data belongs to.
 void setSectionConflictMode(short sectionConflictMode)
          Sets the section conflict mode a section uses to resolve duplicate section adds.
 void setSectionEntryConflictMode(String sectionName, short entryConflictMode)
          Sets the entry conflict mode a section uses to resolve duplicate entry adds.
 void setSectionEntryValue(String sectionName, String entryName, String entryValue)
          Adds a new entry to a section in this configuration.
 void swapSections(int first, int second)
          Swap the position of two sections in the ordered list of sections.
 void swapSections(String firstName, String secondName)
          Swap the position of two sections in the ordered list of sections.
 String toString()
          Returns a string representation of the Configuration class.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

SECTION_CONFLICT_OVERWRITE

public static final short SECTION_CONFLICT_OVERWRITE
Indicates that when a duplicate section is added, it should overwrite the value of the existing one.

SECTION_CONFLICT_DISCARD

public static final short SECTION_CONFLICT_DISCARD
Indicates that when a duplicate section is added, it should be discarded (ignored) and the value of the existing one is left unchanged. In addition, a ConfigurationException will be thrown. This is most meaningful when merging configurations.

SECTION_CONFLICT_APPEND

public static final short SECTION_CONFLICT_APPEND
Indicates that when a duplicate section is added, the original will be left as is and another section with the same name will be added as well. This is most meaningful when merging configurations.

SECTION_CONFLICT_INCLUDE

public static final short SECTION_CONFLICT_INCLUDE
Indicates that when a duplicate section is added, the original will be left as is and and we will just add entries for this section to the existing section's entries. This is most meaningful when merging configurations.

ENTRY_CONFLICT_OVERWRITE

public static final short ENTRY_CONFLICT_OVERWRITE
Indicates that when a duplicate entry is added, it should overwrite the value of the existing one. This is most meaningful when merging configurations.

ENTRY_CONFLICT_DISCARD

public static final short ENTRY_CONFLICT_DISCARD
Indicates that when a duplicate entry is added, it should be discarded (ignored) and the value of the existing one is left unchanged. In addition, a ConfigurationException will be thrown.

ENTRY_CONFLICT_APPEND

public static final short ENTRY_CONFLICT_APPEND
Indicates that when a duplicate entry is added, the original will be left as is and another entry with the same name will be added as well.

_fileName

protected String _fileName
Name of the file associated with the configuration data

_sections

protected Hashtable _sections
The list of section in the configuration. The key is the name of the section, the result is either the ConfigurationSection object for the name, or a Vector of ConfigurationSections for the name.

_sectionNames

protected Vector _sectionNames
A list of the section names for the configuration in the order they appear in the configuration.

_currentSection

protected ConfigurationSection _currentSection
Internal pointer to the current section being manipulated when reading a configuration from a file.
Constructor Detail

Configuration

public Configuration()
Default creator, just sets our section list information to empty containers.

Configuration

public Configuration(String fileName)
              throws FileNotFoundException,
                     IOException,
                     ConfigurationException
Class creator. Initializes class variables and attempts to process the indicated configuration file. If the file cannot be opened or errors occur during reading, we throw the appropriate exception.
Parameters:
fileName - Name of the configuration file to process.
Throws:
FileNotFoundException - Indicates the file name passed in does not exist or cannot be accessed.
IOException - File was found but an error occurred while reading it.
ConfigurationException - A processing error was encountered while reading the configuration file, typically a syntax error.
Method Detail

getFileName

public String getFileName()
Getter for the name of the file this configuration data belongs to.
Returns:
The name of this configuration's file.

setFileName

public boolean setFileName(String fileName)
Setter for the name of the file this configuration data belongs to. Also checks to see if the name we are changing to matches the current name.
Parameters:
fileName - Value to set the file name to.
Returns:
If the new name does not match the current name, returns true, otherwise returns false.

getSections

public Hashtable getSections()
Getter for the hashtable of sections in a Configuration instance. The hashtable has one entry for each section contained in the Configuration instance. Note that the order of sections in this hashtable is not guaranteed to match the order the sections were read from the configuration file or later added to the configuration. The key to the hashtable is the section name, while the result is the ConfigurationSection class instance for the section name.
Returns:
The hashtable of sections in the configuration file

getSection

public ConfigurationSection getSection(String sectionName)
Finds the requested ConfigurationSection entry in the list of sections the configuration file contains. The section name must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to find
Returns:
The ConfigurationSection for the requested section or null if the section does not exist.

getSection

public ConfigurationSection getSection(String sectionName,
                                       int sectionInstance)
Finds the requested instance of the ConfigurationSection entry in the list of sections the configuration file contains. The section name must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to find
sectionInstance - Which instance of the section to retrieve. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
Returns:
The ConfigurationSection for the requested section or null if the section does not exist.

getSectionEntry

public ConfigurationEntry getSectionEntry(String sectionName,
                                          String entryName)
Finds the requested ConfigurationEntry class instance from the specified section. The section and entry names must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to find entry in
entryName - Name of the entry to find
Returns:
The ConfigurationEntry for the requested entry or null if the entry does not exist.

getSectionEntry

public ConfigurationEntry getSectionEntry(String sectionName,
                                          int sectionInstance,
                                          String entryName)
Finds the requested ConfigurationEntry class instance from the specified section. The section and entry names must match exactly, case and whitespaces both count. This version of this method supports retrieval of entries when the section allows duplicate entries.
Parameters:
sectionName - Name of the section to find entry in.
sectionInstance - Which instance of the section to retrieve entry from. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
entryName - Name of the entry to find.
Returns:
The ConfigurationEntry for the requested entry or null if the entry does not exist.

getSectionEntryValue

public String getSectionEntryValue(String sectionName,
                                   String entryName)
Finds the requested entry's value from the specified section. The section and entry names must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to find entry in.
entryName - Name of the entry to find value for.
Returns:
The value of the requested entry or null if the entry does not exist.

getSectionEntryValueAsInteger

public int getSectionEntryValueAsInteger(String sectionName,
                                         String entryName)
Finds the requested entry's value from the specified section. The section and entry names must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to find entry in.
entryName - Name of the entry to find value for.
Returns:
The value of the requested entry or 0 if the entry does not exist.

getSectionEntryValue

public String getSectionEntryValue(String sectionName,
                                   int sectionInstance,
                                   String entryName)
Finds the requested entry's value from the specified section. The section and entry names must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to find entry in.
sectionInstance - Which instance of the section to get an entry value for. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
entryName - Name of the entry to find value for.
Returns:
The value of the requested entry or null if the entry does not exist.

getSectionEntryValueAsInteger

public int getSectionEntryValueAsInteger(String sectionName,
                                         int sectionInstance,
                                         String entryName)
Finds the requested entry's value from the specified section. The section and entry names must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to find entry in.
sectionInstance - Which instance of the section to get an entry value for. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
entryName - Name of the entry to find value for.
Returns:
The value of the requested entry or 0 if the entry does not exist.

getSectionEntryValue

public String getSectionEntryValue(String sectionName,
                                   String entryName,
                                   int entryInstance)
Finds the requested entry's value from the specified section. The section and entry names must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to find entry in.
entryName - Name of the entry to find value for.
entryInstance - Which instance of the entry within the section to get an value for. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
Returns:
The value of the requested entry or null if the entry does not exist.

getSectionEntryValueAsInteger

public int getSectionEntryValueAsInteger(String sectionName,
                                         String entryName,
                                         int entryInstance)
Finds the requested entry's value from the specified section. The section and entry names must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to find entry in.
entryName - Name of the entry to find value for.
entryInstance - Which instance of the entry within the section to get an value for. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
Returns:
The value of the requested entry or null if the entry does not exist.

getSectionEntryValue

public String getSectionEntryValue(String sectionName,
                                   int sectionInstance,
                                   String entryName,
                                   int entryInstance)
Finds the requested entry's value from the specified section. The section and entry names must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to find entry in.
sectionInstance - Which instance of the section to get an entry value for. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
entryName - Name of the entry to find value for.
entryInstance - Which instance of the entry within the section to get an value for. This is a 0 based value.
Returns:
The value of the requested entry or null if the entry does not exist.

getSectionEntryValueAsInteger

public int getSectionEntryValueAsInteger(String sectionName,
                                         int sectionInstance,
                                         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.

getSectionQuantity

public int getSectionQuantity(String sectionName)
Determines how many sections of the specified name exist in this configuration. Unless duplicate entry names are allowed this always returns 0 or 1.
Parameters:
sectionName - Name of the section to find quantity of.

getSectionEntryQuantity

public int getSectionEntryQuantity(String sectionName,
                                   String entryName)
Determines how many entries of the specified name exist for the specified section. Unless duplicate entry names are allowed this always returns 0 or 1.
Parameters:
sectionName - Name of the section to find entry in.
entryName - Name of the entry to find quantity of.

getSectionEntryQuantity

public int getSectionEntryQuantity(String sectionName,
                                   int sectionInstance,
                                   String entryName)
Determines how many entries of the specified name exist for the specified section. Unless duplicate entry names are allowed this always returns 0 or 1.
Parameters:
sectionName - Name of the section to find entry in.
sectionInstance - Which instance of the section to get an entry quantity for. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
entryName - Name of the entry to find quantity of.

setSectionConflictMode

public void setSectionConflictMode(short sectionConflictMode)
Sets the section conflict mode a section uses to resolve duplicate section adds.
Parameters:
sectionConflictMode - The section conflict mode.

getSectionConflictMode

public short getSectionConflictMode()
Gets the section conflict mode a section uses to resolve duplicate section adds.
Returns:
The section conflict mode.

setSectionEntryConflictMode

public void setSectionEntryConflictMode(String sectionName,
                                        short entryConflictMode)
                                 throws ConfigurationException
Sets the entry conflict mode a section uses to resolve duplicate entry adds.
Parameters:
sectionName - Name of the section to set the mode of.
entryConflictMode - The entry conflict mode.

getSectionEntryConflictMode

public short getSectionEntryConflictMode(String sectionName)
Gets the entry conflict mode a section uses to resolve duplicate entry adds.
Parameters:
sectionName - Name of the section to get the mode of.
Returns:
The entry conflict mode, or -1 if the section does not exist.

setSectionEntryValue

public void setSectionEntryValue(String sectionName,
                                 String entryName,
                                 String entryValue)
Adds a new entry to a section in this configuration. If the section does not yet exist, it is created. If the entry already exists than it's value is updated, otherwise the entry is added.
Parameters:
sectionName - Name of the section to add or set an entry in.
entryName - Name of the new entry to add or set.
entryValue - Value to give the entry.

swapSections

public void swapSections(int first,
                         int second)
Swap the position of two sections in the ordered list of sections.
Parameters:
first - Index of the first section we are switching
second - Index of the second section we are switching

swapSections

public void swapSections(String firstName,
                         String secondName)
                  throws ConfigurationException
Swap the position of two sections in the ordered list of sections.
Parameters:
firstName - Name of the first section we are switching
secondName - Name of the second section we are switching
Throws:
ConfigurationException - Thrown when there is no section by one (or both) of the section names.

indexOf

public int indexOf(String sectionName)
Determines the index of the first section with the specified name. Indexes are 0 based.
Parameters:
sectionName - The name of the section to look for.
Returns:
The index of the first occurrence of the specified section, or -1 if no sections by the specified name exist.

indexOf

public int indexOf(String sectionName,
                   int index)
Determines the index of the first section with the specified name beginning the search at the specified index. Indexes are 0 based.
Parameters:
sectionName - The name of the section to look for.
index - The index to start the search at.
Returns:
The index of the first occurrence of the specified section starting at the specified index, or -1 if no sections by the specified name exist.

getNumberOfSections

public int getNumberOfSections()
Determines the number of sections contained in this configuration.
Returns:
The number of sections defined to this configuration.

getNumberOfEntries

public int getNumberOfEntries(String sectionName)
                       throws ConfigurationException
Determines the number of entries contained in specified section.
Parameters:
sectionName - Name of the section to get the entry count for
Returns:
The number of entries defined to the section.
Throws:
ConfigurationException - Thrown when the specified section does not exist in the configuration.

isSection

public boolean isSection(String sectionName)
Checks to see if this section exists in the configuration. The section name must match exactly, case and whitespaces both count.
Returns:
true if the section exists, false otherwise.

isSection

public boolean isSection(String sectionName,
                         int sectionInstance)
Checks to see if this section exists in the configuration. The section name must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to check for.
sectionInstance - Which instance of the section to look for. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
Returns:
true if the section exists, false otherwise.

isSectionEntry

public boolean isSectionEntry(String sectionName,
                              String entryName)
Checks to see if this section entry exists in the configuration. The section and entry names must match exactly, case and whitespaces both count.
Returns:
true if the section entry exists, false otherwise.

renameSection

public ConfigurationSection renameSection(String oldName,
                                          String newName)
Renames an existing section to the given new name.
Parameters:
oldName - Name of the section being renamed.
newName - Value to rename the section to.
Returns:
Reference to the newly named section if successful, null otherwise.

addSection

public ConfigurationSection addSection(String sectionName)
                                throws ConfigurationException
Adds a new section to this configuration. Note that the section will not contain any entries.
Parameters:
sectionName - Name of the new section to add.
Returns:
On success, the new section that was added, null otherwise.

addSection

public ConfigurationSection addSection(String sectionName,
                                       int index)
                                throws ConfigurationException
Adds a new section to this configuration. Note that the section will not contain any entries.
Parameters:
sectionName - Name of the new section to add.
Returns:
On success, the new section that was added, null otherwise.

removeSection

public boolean removeSection(String sectionName)
Removes a section from this configuration. The section name must match an existing section's name exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section to remove.
Returns:
trueon success, false otherwise.

addSectionEntry

public ConfigurationEntry addSectionEntry(String sectionName,
                                          String entryName,
                                          String entryValue)
                                   throws ConfigurationException
Adds a new entry to a section in this configuration. If the section does not yet exist, it is created.
Parameters:
sectionName - Name of the section to add an entry to.
entryName - Name of the new entry to add.
entryValue - Value to give the new entry.
Returns:
On success, the new entry that was added, null otherwise.
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.

addSectionEntry

public ConfigurationEntry addSectionEntry(ConfigurationSection section,
                                          ConfigurationEntry entry)
                                   throws ConfigurationException
Adds a new entry to a section in this configuration. If the section does not yet exist, it is created.
Parameters:
section - The section to add the entry to.
entry - The configuration entry to add.
Returns:
On success, the new entry that was added, null otherwise.
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.

removeSectionEntry

public boolean removeSectionEntry(String sectionName,
                                  String entryName)
Removes an entry from a section in this configuration. The section and entry names must match exactly, case and whitespaces both count.
Parameters:
sectionName - Name of the section the entry is in.
entryName - Name of the entry to remove.
Returns:
trueon success, false otherwise.

removeSection

public boolean removeSection(ConfigurationSection section)
Removes a section from this configuration.
Parameters:
section - The section to remove.
Returns:
trueon success, false otherwise.

merge

public void merge(Configuration config)
           throws ConfigurationException
Merges the sections from the specified configuration into the current configuration. Keeps track of any failures and gathers them up so they can all be reported in a single exception. Merging means all the sections from the specified configuration are added to this configuration.
Parameters:
config - The configuration to be merged in.
Throws:
ConfigurationException - Thrown when one or more sections from the specified configuration cannot be added to the current configuration. This is typically caused by duplicate sections when the target configuration has a Section Conflict Mode of Configuration.SECTION_CONFLICT_DISCARD.

mergeSections

public void mergeSections(String target,
                          String source)
                   throws ConfigurationException
Merges the entries from one section with the entries from another. Merging means all the entries from the 'source' section are added to the 'target' section.
Parameters:
target - Name of the section entries are being merged into.
source - Name of the section entries are being copied from.
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 as a Entry Conflict Mode of Configuration.ENTRY_CONFLICT_DISCARD.

mergeSections

public void mergeSections(String target,
                          int targetInstance,
                          String source)
                   throws ConfigurationException
Merges the entries from one section with the entries from another. Merging means all the entries from the 'source' section are added to the 'target' section. This version of this method supports merging target sections that have multiple instances.
Parameters:
target - Name of the section entries are being merged into.
targetInstance - Which instance of the target section to retrieve. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
source - Name of the section entries are being copied from.
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 as a Entry Conflict Mode of Configuration.ENTRY_CONFLICT_DISCARD.

mergeSections

public void mergeSections(String target,
                          String source,
                          int sourceInstance)
                   throws ConfigurationException
Merges the entries from one section with the entries from another. Merging means all the entries from the 'source' section are added to the 'target' section. This version of this method supports merging source sections that have multiple instances.
Parameters:
target - Name of the section entries are being merged into.
source - Name of the section entries are being copied from.
sourceInstance - Which instance of the source section to retrieve. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
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 as a Entry Conflict Mode of Configuration.ENTRY_CONFLICT_DISCARD.

mergeSections

public void mergeSections(String target,
                          int targetInstance,
                          String source,
                          int sourceInstance)
                   throws ConfigurationException
Merges the entries from one section with the entries from another. Merging means all the entries from the 'source' section are added to the 'target' section. This version of this method supports merging source and target sections that have multiple instances.
Parameters:
target - Name of the section entries are being merged into.
targetInstance - Which instance of the target section to retrieve. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
source - Name of the section entries are being copied from.
sourceInstance - Which instance of the source section to retrieve. This is a 0 based value, so the first instance is instance 0, the second is 1, etc.
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 as a Entry Conflict Mode of Configuration.ENTRY_CONFLICT_DISCARD.

getSectionNames

public Vector getSectionNames()
Used to retrieve a Vector of the sections contained in this configuration. The vector contains the section names in the same order they were read from the configuration file. As non configuration file sections are added they are appended to the existing section name list.
Returns:
Vector containing the ordered list of section names. Note that this is the actual list so it should be treated as read only data.

getEntryNames

public Vector getEntryNames(String sectionName)
Used to retrieve a Vector of the entries contained in the specified section within this configuration. 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.
Parameters:
sectionName - Name of the section to retrieve entry names for.
Returns:
Vector containing the ordered list of entry names. Note that this is the actual list so it should be treated as read only data. If the section does not exist than null is returned.

save

public void save()
          throws Exception
Method to save the configuration back to a file. This method ensures that sections are written back to the file in the same order that they were read. The same is true for entries within each section. Sections that were added after reading the file are written after all the file's original sections. Similarly, entries added to sections are written after all the original section entries.
Throws:
Exception - Thrown when the save file could not be opened or has no sections.

toString

public String toString()
Returns a string representation of the Configuration class. We are using the file name as the string representation.
Overrides:
toString in class Object