|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.thdl.util.ThdlOptions
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.
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 |
private static Properties userProperties
private static boolean isInitialized
Constructor Detail |
private ThdlOptions()
Method Detail |
public static boolean getBooleanOption(String optionName)
optionName
- the option whose value you wish to retrieve
(note the naming conventions detailed in the class comment)private static String getSystemValue(String optionName)
public static String getStringOption(String optionName)
optionName
- the option whose value you wish to retrieve
(note the naming conventions detailed in the class comment)public static String getStringOption(String optionName, String defaultValue)
optionName
- the option whose value you wish to retrieve
(note the naming conventions detailed in the class comment)defaultValue
- the default valuepublic static int getIntegerOption(String optionName, int defaultValue)
optionName
- the option whose value you wish to retrieve
(note the naming conventions detailed in the class comment)defaultValue
- the default valuepublic static Integer getIntegerOption(String optionName)
optionName
- the option whose value you wish to retrieve
(note the naming conventions detailed in the class comment)private static boolean suppressErrs()
private static void init()
private static void initialize(Class resourceHolder, String resourceName, boolean suppressErrors) throws FileNotFoundException
resourceHolder
- the class associated with the builtin
defaults properties file resourceresourceName
- the name of the builtin defaults
properties file resourcesuppressErrors
- true if the show must go on, false if
you want unchecked exceptions thrown when bad things happen
FileNotFoundException
- if !suppressErrors and if the
user gave the location of the system-wide or user preferences
files, but gave it incorrectly.private static Properties tryToGetPropsFromFile(String pName, String defaultLoc, Properties defaultProps, boolean suppressErrors) throws FileNotFoundException, SecurityException
pName
- the name of the System property that overrides
this application's default idea of where to look for the filedefaultLoc
- the default preferences file namesuppressErrors
- true iff you want to proceed without
throwing exceptions whenever possible
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
private static Properties getPropertiesFromResource(Class resourceHolder, String resourceName, boolean suppressErrors, Properties defaults)
private static Properties getPropertiesFromStream(InputStream in, boolean suppressErrors, Properties defaults) throws NullPointerException
NullPointerException
public static void saveUserPreferences() throws IOException
getUserPreferencesPath()
. You must call
setUserPreference(..)
for this to be effective.
IOException
- if an IO exception occurs while writing to
the disk.public static String getUserPreferencesPath()
thdl.user.options.directory
public static void setUserPreference(String pref, int value)
pref
- the preference the user is settingvalue
- the user's new preferencepublic static void setUserPreference(String pref, boolean value)
pref
- the preference the user is settingvalue
- the user's new preferencepublic static void setUserPreference(String pref, String value)
pref
- the preference the user is settingvalue
- the user's new preference
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |