org.thdl.util
Class ThdlOptions

java.lang.Object
  |
  +--org.thdl.util.ThdlOptions

public final class ThdlOptions
extends Object

Provides a clean interface to the multi-tiered system of user preferences (also known as options).

The java.util.Properties class makes it easy for us to provide a hierarchical preferences (that is, options) structure. One option a user might wish to set is the font size for Tibetan, for example. The highest precedence goes to a pref that the user set on the Java command line using something like java -Dpref=value -jar jskad_or_whatever.jar. If the user went to the trouble of doing this, we definitely want to respect his or her wish. The next highest precedence goes to an individual user's preferences file (a file readable and writable by java.util.Properties, but also hand-editable), if one exists. Next is the system-wide preferences file, if one exists. Finally, we fall back on the preferences file shipped with the application inside the JAR.

ThdlOptions is not instantiable. It contains only static methods for answering questions about the user's preferences.

There are three kinds of preferences: boolean-valued preferences ("true" or "false"), integer-valued preferences, and string-valued preferences. Boolean-valued preferences should, by convention, be false by default. If you want to enable feature foo by default, but give a preference for disabling it, then call the preference "DisableFeatureFoo". If you want to disable feature foo by default, call it "EnableFeatureFoo". This makes the users' lives easier.

ThdlOptions is a final class so that compilers can make this code run efficiently.

Author:
David Chandler

Method Summary
static boolean getBooleanOption(String optionName)
          Returns the value of a boolean-valued option, or false if that option is set nowhere in the hierarchy of properties files.
static Integer getIntegerOption(String optionName)
          Returns the value of an integer-valued option, or null if that option is set nowhere in the hierarchy of properties files or is set to something that cannot be decoded to an integer.
static int getIntegerOption(String optionName, int defaultValue)
          Returns the value of an integer-valued option, or defaultValue if that option is set nowhere in the hierarchy of properties files or is set to something that cannot be decoded to an integer.
static String getStringOption(String optionName)
          Returns the value of a string-valued option, or null if that option is set nowhere in the hierarchy of properties files.
static String getStringOption(String optionName, String defaultValue)
          Returns the value of a string-valued option, or defaultValue if that option is set nowhere in the hierarchy of properties files.
static String getUserPreferencesPath()
          This returns the location of the user's preferences file.
static void saveUserPreferences()
          Saves the user's preferences to a file whose path is the value of getUserPreferencesPath().
static void setUserPreference(String pref, boolean value)
          In order to save preferences, this class must know that the user (explicitly or implicitly) has changed a preference, either through selecting something in a ComboBox, going through a Preferences GUI, or the like.
static void setUserPreference(String pref, int value)
          In order to save preferences, this class must know that the user (explicitly or implicitly) has changed a preference, either through selecting something in a ComboBox, going through a Preferences GUI, or the like.
static void setUserPreference(String pref, String value)
          In order to save preferences, this class must know that the user (explicitly or implicitly) has changed a preference, either through selecting something in a ComboBox, going through a Preferences GUI, or the like.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getBooleanOption

public static boolean getBooleanOption(String optionName)
Returns the value of a boolean-valued option, or false if that option is set nowhere in the hierarchy of properties files.

Parameters:
optionName - the option whose value you wish to retrieve (note the naming conventions detailed in the class comment)

getStringOption

public static String getStringOption(String optionName)
Returns the value of a string-valued option, or null if that option is set nowhere in the hierarchy of properties files.

Parameters:
optionName - the option whose value you wish to retrieve (note the naming conventions detailed in the class comment)

getStringOption

public static String getStringOption(String optionName,
                                     String defaultValue)
Returns the value of a string-valued option, or defaultValue if that option is set nowhere in the hierarchy of properties files.

Parameters:
optionName - the option whose value you wish to retrieve (note the naming conventions detailed in the class comment)
defaultValue - the default value

getIntegerOption

public static int getIntegerOption(String optionName,
                                   int defaultValue)
Returns the value of an integer-valued option, or defaultValue if that option is set nowhere in the hierarchy of properties files or is set to something that cannot be decoded to an integer.

Parameters:
optionName - the option whose value you wish to retrieve (note the naming conventions detailed in the class comment)
defaultValue - the default value

getIntegerOption

public static Integer getIntegerOption(String optionName)
Returns the value of an integer-valued option, or null if that option is set nowhere in the hierarchy of properties files or is set to something that cannot be decoded to an integer.

Parameters:
optionName - the option whose value you wish to retrieve (note the naming conventions detailed in the class comment)

saveUserPreferences

public static void saveUserPreferences()
                                throws IOException
Saves the user's preferences to a file whose path is the value of getUserPreferencesPath(). You must call setUserPreference(..) for this to be effective.

Throws:
IOException - if an IO exception occurs while writing to the disk.

getUserPreferencesPath

public static String getUserPreferencesPath()
This returns the location of the user's preferences file. This value may be overridden, by, you guessed it, a JVM, built-in, or system-wide preference thdl.user.options.directory


setUserPreference

public static void setUserPreference(String pref,
                                     int value)
In order to save preferences, this class must know that the user (explicitly or implicitly) has changed a preference, either through selecting something in a ComboBox, going through a Preferences GUI, or the like. Calling this method indicates that the user has changed an integer-valued preference pref to value.

Parameters:
pref - the preference the user is setting
value - the user's new preference

setUserPreference

public static void setUserPreference(String pref,
                                     boolean value)
In order to save preferences, this class must know that the user (explicitly or implicitly) has changed a preference, either through selecting something in a ComboBox, going through a Preferences GUI, or the like. Calling this method indicates that the user has changed a boolean-valued preference pref to value.

Parameters:
pref - the preference the user is setting
value - the user's new preference

setUserPreference

public static void setUserPreference(String pref,
                                     String value)
In order to save preferences, this class must know that the user (explicitly or implicitly) has changed a preference, either through selecting something in a ComboBox, going through a Preferences GUI, or the like. Calling this method indicates that the user has changed a String-valued preference pref to value.

Parameters:
pref - the preference the user is setting
value - the user's new preference


These API docs were created 02/02/2003 08:19 PM.
Copyright © 2001-2002 Tibetan and Himalayan Digital Library. All Rights Reserved.
Hosted by SourceForge_Logo