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

Field Summary
private static boolean isInitialized
          to avoid initializing twice
private static Properties userProperties
          the properties object that is chained to the system-wide properties which is chained to the built-in properties which is chained to the Java System properties
 
Constructor Summary
private ThdlOptions()
          So that you're not tempted to instantiate this class, the constructor is private:
 
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.
private static Properties getPropertiesFromResource(Class resourceHolder, String resourceName, boolean suppressErrors, Properties defaults)
           
private static Properties getPropertiesFromStream(InputStream in, boolean suppressErrors, Properties defaults)
           
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.
private static String getSystemValue(String optionName)
           
static String getUserPreferencesPath()
          This returns the location of the user's preferences file.
private static void init()
           
private static void initialize(Class resourceHolder, String resourceName, boolean suppressErrors)
          Sets userProperties so that it represents the entire, chained preferences hierarchy.
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.
private static boolean suppressErrs()
           
private static Properties tryToGetPropsFromFile(String pName, String defaultLoc, Properties defaultProps, boolean suppressErrors)
          Returns a new, nonnull Properties object if (1) a preferences file is found at the location specified by the value of the System property pName, if it is set, or at defaultLoc, if pName is not set, and (2) if that file is successfully read in.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

userProperties

private static Properties userProperties
the properties object that is chained to the system-wide properties which is chained to the built-in properties which is chained to the Java System properties


isInitialized

private static boolean isInitialized
to avoid initializing twice

Constructor Detail

ThdlOptions

private ThdlOptions()
So that you're not tempted to instantiate this class, the constructor is private:

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)

getSystemValue

private static String getSystemValue(String optionName)

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)

suppressErrs

private static boolean suppressErrs()

init

private static void init()

initialize

private static void initialize(Class resourceHolder,
                               String resourceName,
                               boolean suppressErrors)
                        throws FileNotFoundException
Sets userProperties so that it represents the entire, chained preferences hierarchy.

Parameters:
resourceHolder - the class associated with the builtin defaults properties file resource
resourceName - the name of the builtin defaults properties file resource
suppressErrors - true if the show must go on, false if you want unchecked exceptions thrown when bad things happen
Throws:
FileNotFoundException - if !suppressErrors and if the user gave the location of the system-wide or user preferences files, but gave it incorrectly.

tryToGetPropsFromFile

private static Properties tryToGetPropsFromFile(String pName,
                                                String defaultLoc,
                                                Properties defaultProps,
                                                boolean suppressErrors)
                                         throws FileNotFoundException,
                                                SecurityException
Returns a new, nonnull Properties object if (1) a preferences file is found at the location specified by the value of the System property pName, if it is set, or at defaultLoc, if pName is not set, and (2) if that file is successfully read in. Otherwise, this returns defaultProps.

Parameters:
pName - the name of the System property that overrides this application's default idea of where to look for the file
defaultLoc - the default preferences file name
suppressErrors - true iff you want to proceed without throwing exceptions whenever possible
Throws:
FileNotFoundException - if !suppressErrors and if the user gave the location of the system-wide or user preferences files, but gave it incorrectly. @throws SecurityException if playing with files or system properties is not OK
SecurityException

getPropertiesFromResource

private static Properties getPropertiesFromResource(Class resourceHolder,
                                                    String resourceName,
                                                    boolean suppressErrors,
                                                    Properties defaults)

getPropertiesFromStream

private static Properties getPropertiesFromStream(InputStream in,
                                                  boolean suppressErrors,
                                                  Properties defaults)
                                           throws NullPointerException
NullPointerException

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:20 PM.
Copyright © 2001-2002 Tibetan and Himalayan Digital Library. All Rights Reserved.
Hosted by SourceForge_Logo