org.gjt.btools.utilities
Class OptionSet

java.lang.Object
  |
  +--org.gjt.btools.utilities.OptionSet

public class OptionSet
extends java.lang.Object

Provides a mechanism for a program to keep a set of options that can be stored in a file between program sessions. Each option has a string name associated with it, and can be read or altered using the various get and set member functions.


Constructor Summary
OptionSet()
          Creates a new option set not associated with any file.
OptionSet(java.io.File optionFile, java.lang.String comment)
          Creates a new option set based on the given file.
OptionSet(java.io.File optionFile, java.lang.String comment, boolean forceLoad)
          Creates a new option set based on the given file.
 
Method Summary
 boolean getBooleanOption(java.lang.String key)
          Retrieves the value of a boolean option.
 boolean getBooleanOption(java.lang.String key, boolean defaultOption)
          Retrieves the value of a boolean option.
 int getIntOption(java.lang.String key)
          Retrieves the value of an integer option.
 int getIntOption(java.lang.String key, int defaultOption)
          Retrieves the value of an integer option.
 java.lang.String getStringOption(java.lang.String key)
          Retrieves the value of a string option.
 java.lang.String getStringOption(java.lang.String key, java.lang.String defaultOption)
          Retrieves the value of a string option.
static java.lang.String getSystemProperty(java.lang.String key)
          Gets the system property indicated by the specified key.
static java.lang.String getSystemProperty(java.lang.String key, java.lang.String def)
          Gets the system property indicated by the specified key.
protected  void init()
          Performs extra initialisation for a new option set that should take place before the options are read from file.
protected  void readFromFile()
          Attempt to read this option set from file.
 void removeOption(java.lang.String key)
          Removes the given option from this option set.
 void setBooleanOption(java.lang.String key, boolean value)
          Sets the value of a given boolean option.
 void setIntOption(java.lang.String key, int value)
          Sets the value of a given integer option.
 void setStringOption(java.lang.String key, java.lang.String value)
          Sets the value of a given string option.
 void writeToFile()
          Attempt to write this option set to file.
 void writeToFile(boolean forceWrite)
          Attempt to write this option set to file.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

OptionSet

public OptionSet()
Creates a new option set not associated with any file. For such an option set, when routines writeToFile() and readFromFile() are called, nothing will be done.

The initialisation routine init() will be called from this constructor.

See Also:
init()

OptionSet

public OptionSet(java.io.File optionFile,
                 java.lang.String comment)
Creates a new option set based on the given file. All options stored in the file will be loaded. Any errors that occur when reading from file will be ignored.

The initialisation routine init() will be called before the attempt to read the file.

Parameters:
optionFile - the file to/from which this option set is to be written/read.
comment - a comment to place at the beginning of the option file when writing; this parameter is essentially irrelevant unless you wish to hand-examine the option file. It does not matter if the comment passed here is different to the existing comment in the file; the existing comment will simply be overwritten.
See Also:
OptionSet(File, String, boolean), init()

OptionSet

public OptionSet(java.io.File optionFile,
                 java.lang.String comment,
                 boolean forceLoad)
          throws java.io.IOException
Creates a new option set based on the given file. All options stored in the file will be loaded.

The initialisation routine init() will be called before the attempt to read the file.

Parameters:
optionFile - the file to/from which this option set is to be written/read.
comment - a comment to place at the beginning of the option file when writing; this parameter is essentially irrelevant unless you wish to hand-examine the option file. It does not matter if the comment passed here is different to the existing comment in the file; the existing comment will simply be overwritten.
forceLoad - if set to false, we will ignore any errors in reading from file. If set to true, an exception will be thrown if an error occurs.
Throws:
java.io.IOException - thrown if an error occurs in reading from file.
See Also:
OptionSet(File, String), init()
Method Detail

init

protected void init()
Performs extra initialisation for a new option set that should take place before the options are read from file. This implementation does nothing, but subclasses may wish to override this routine. It is called from every OptionSet constructor.


readFromFile

protected void readFromFile()
                     throws java.io.IOException
Attempt to read this option set from file.

Throws:
java.io.IOException - thrown if an error occurs in reading from file.

removeOption

public void removeOption(java.lang.String key)
Removes the given option from this option set.

Parameters:
key - the name of the requested option.

getStringOption

public java.lang.String getStringOption(java.lang.String key)
Retrieves the value of a string option.

Parameters:
key - the name of the requested option.
Returns:
the value of the requested option, or null if no such option is in the set.

getStringOption

public java.lang.String getStringOption(java.lang.String key,
                                        java.lang.String defaultOption)
Retrieves the value of a string option.

Parameters:
key - the name of the requested option.
defaultOption - the value to use if the requested option is not in the set.
Returns:
the value of the requested option, or defaultOption if no such option is in the set.

setStringOption

public void setStringOption(java.lang.String key,
                            java.lang.String value)
Sets the value of a given string option. The options will not be written to file until writeToFile() is called.

Parameters:
key - the name of the option to set.
value - the value to assign to the option.
See Also:
writeToFile()

getBooleanOption

public boolean getBooleanOption(java.lang.String key)
Retrieves the value of a boolean option.

Parameters:
key - the name of the requested option.
Returns:
the value of the requested option, or false if no such option is in the set.

getBooleanOption

public boolean getBooleanOption(java.lang.String key,
                                boolean defaultOption)
Retrieves the value of a boolean option.

Parameters:
key - the name of the requested option.
defaultOption - the value to use if the requested option is not in the set.
Returns:
the value of the requested option, or defaultOption if no such option is in the set.

setBooleanOption

public void setBooleanOption(java.lang.String key,
                             boolean value)
Sets the value of a given boolean option. The options will not be written to file until writeToFile() is called.

Parameters:
key - the name of the option to set.
value - the value to assign to the option.
See Also:
writeToFile()

getIntOption

public int getIntOption(java.lang.String key)
Retrieves the value of an integer option.

Parameters:
key - the name of the requested option.
Returns:
the value of the requested option, or 0 if no such option is in the set.

getIntOption

public int getIntOption(java.lang.String key,
                        int defaultOption)
Retrieves the value of an integer option. If the option is not an integer, 0 will be returned.

Parameters:
key - the name of the requested option.
defaultOption - the value to use if the requested option is not in the set.
Returns:
the value of the requested option, or defaultOption if no such option is in the set.

setIntOption

public void setIntOption(java.lang.String key,
                         int value)
Sets the value of a given integer option. The options will not be written to file until writeToFile() is called.

Parameters:
key - the name of the option to set.
value - the value to assign to the option.
See Also:
writeToFile()

writeToFile

public void writeToFile()
Attempt to write this option set to file. Don't worry if the operation failed.


writeToFile

public void writeToFile(boolean forceWrite)
                 throws java.io.IOException
Attempt to write this option set to file.

Parameters:
forceWrite - if set to false, we will ignore any errors in writing to file. If set to true, an exception will be thrown if an error occurs.
Throws:
java.io.IOException - thrown if an error occurs in writing to file.

getSystemProperty

public static java.lang.String getSystemProperty(java.lang.String key)
Gets the system property indicated by the specified key. This is a convenience wrapper for System.getProperty() that does exception handling. If any exception or error (such as a security exception) is thrown, this routine will catch it and simply return null.

Parameters:
key - the name of the system property to retrieve.
Returns:
the string value of the requested system property, or null if there is no property with that key or if an error occurs.

getSystemProperty

public static java.lang.String getSystemProperty(java.lang.String key,
                                                 java.lang.String def)
Gets the system property indicated by the specified key. This is a convenience wrapper for System.getProperty() that does exception handling. If any exception or error (such as a security exception) is thrown, this routine will catch it and simply return the given default value.

Parameters:
key - the name of the system property to retrieve.
def - the default value to use if there is no property with the given key.
Returns:
the string value of the requested system property, or def if there is no property with that key or if an error occurs.


Copyright © 1998-2001, Ben Burton
This software is released under the GNU Public License.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).