vmm.core
Class Prefs

java.lang.Object
  vmm.core.Prefs

public class Prefs
extends java.lang.Object

Provides a simple mechanism for saving and retrieving user preferences, with a default implementation based on the standard package java.util.prefs. (There is a way to use a different implementation, which is provided to allow, for example, using the WebStart Persistance service for storing the preferences. See setPrefs(Prefs).)

Preferences are stored as aset of key/value pairs, where both the key and value are Strings. The key string must be non-null and cannot be the empty string. (Also, it should probably not contain the "/" character. Some convenience methods are provided for working with values of type int, double, and boolean, but these just automate the converions of the values to and from Strings.

Note that the design philosopy of this class is that it should always be harmless to call methods from this class, even in applets where security restrictions might make it impossible to access the Preferences database.

Field Summary

protected static java.lang.String

DEFAULT_PREFIX This string (in the default Prefs implementation) is prepended to the key parameter in all the methods defined in this class to give the key that is actually used in cals to the Java Preferences API.

Constructor Summary

protected

Prefs() Prevents the creation of objects of type Prefs, except by a subclass.

Method Summary

protected java.lang.String	doGet(java.lang.String key) Get the preference value associated with a key.
protected void	doPut(java.lang.String key, java.lang.String value) Associates a given preference value with a given key.
protected boolean	doSave() Tries to save any modified preference values to persistent storage, using Java's Preferences API.
protected boolean	doSave(java.lang.String key) Tries to save any modified preference values to persistent storage, using Java's Preferences API.
static java.lang.String	get(java.lang.String key) Get the preferences value associated with a given key.
static java.lang.String	get(java.lang.String key, java.lang.String deflt) Returns the preference string associated with a given key, or deflt if no value is associated with the key.
static boolean	getBoolean(java.lang.String key, boolean deflt) Returns true if get(key) equals "true", or false if get(key) equals "false", or deflt if the value of get(key) is some other value.
static double	getDouble(java.lang.String key, double deflt) Returns Double.parseDouble(get(key)), or deflt if no value is associated with the given key or if the string associated with that key is not an integer.
static int	getInt(java.lang.String key, int deflt) Returns Integer.parseInt(get(key)), or deflt if no value is associated with the given key or if the string associated with that key is not an integer.
static Prefs	getPrefs() Returns the object that is used to handle storage of preference values.
static void	put(java.lang.String key, java.lang.String value) Associate a value with a key in the preferences database.
static boolean	putAndSave(java.lang.String key, java.lang.String value) Associate a value with a key in the preferences database, and then save that preference to persistent storage if possible.
static void	putBoolean(java.lang.String key, boolean value) A convenience method that calls put(key,"true") or put(key,"false"), depending on the value.
static void	putDouble(java.lang.String key, double value) A convenience method that calls put(key,""+value), except that the values Double.NaN, Double.POSITIVE_INFINITY, and Double.NEGATIVE_INFINITY are encoded as "NaN", "+INF", and "-INF", respectively.
static void	putInt(java.lang.String key, int value) A convenience method that calls put(key,""+value).
static boolean	save() All preference values that have been associated with keys by calling put(String, String), putInt(String, int), etc., are not acutally sent to persistent storage until this method is called.
static boolean	save(java.lang.String key) The preference value, if any, that has been associated with the given key is saved to persitent on-disk storage.
static void	setPrefs(Prefs prefs) Set the object of type Prefs that actually handles the storage and retrival of prefernce values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_PREFIX

protected static final java.lang.String DEFAULT_PREFIX

This string (in the default Prefs implementation) is prepended to the key parameter in all the methods defined in this class to give the key that is actually used in cals to the Java Preferences API. It represents a unique path name that should not be used by any other program.

See Also:

Constant Field Values

Constructor Detail

Prefs

protected Prefs()

Prevents the creation of objects of type Prefs, except by a subclass. This is here only to make it possible to create objects belonging to a subclass. This constructor does nothing.

Method Detail

save

public static boolean save()

All preference values that have been associated with keys by calling put(String, String), putInt(String, int), etc., are not acutally sent to persistent storage until this method is called. They are, however, remembered by this class so that subsequent calles to get(String), getInt(String, int), etc., will return the correct values while the program is running. This method does not throw any exception (in the default implementation), but is not guaranteed to save the data. For example, it will probably fail to save the data if called from an applet.

Returns:

true if the data is successfully saved, false if it cannot be saved. The return value will probably be disregarded in most cases.

See Also:

save(String)

save

public static boolean save(java.lang.String key)

The preference value, if any, that has been associated with the given key is saved to persitent on-disk storage.

Parameters:

key - the key whose value is to be saved to persistent storage.

Returns:

true if the data is successfully saved, false if it cannot be saved. The return value will probably be disregarded in most cases.

See Also:

save()

put

public static void put(java.lang.String key,
                       java.lang.String value)

Associate a value with a key in the preferences database. This is not automatically saved to persistent storage.

Parameters:

key - a non-null, non-empty string that identifies the preference value. A null or empty string will generate an IllegalArgumentException (in the default implementation).

value - The value that is to be associated to the key. The value can be null. However, note that no way is provided to differentiate between a key that has a null value and a key that has no value at all.

See Also:

save()

putAndSave

public static boolean putAndSave(java.lang.String key,
                                 java.lang.String value)

Associate a value with a key in the preferences database, and then save that preference to persistent storage if possible. The return value tells whether the value was successfully saved to persistent storage. This methos simply calls put(String, String) and save(String).

get

public static java.lang.String get(java.lang.String key)

Get the preferences value associated with a given key. This method never throws an exception (in the default implemtation).

Parameters:

key - a non-null, non-empty string that identifies the preference value. If the key is a null or empty string, no error occurs, but the return value is null.

Returns:

the preference value associated with the key. This value can be null. If a value has been set for the key with a put method, that value is returned. Otherwise, an attempt is made to read the value from persistant storage; if attempt fails, the return value is null.

See Also:

put(String, String)

putInt

public static void putInt(java.lang.String key,
                          int value)

A convenience method that calls put(key,""+value).

See Also:

put(String, String)

putDouble

public static void putDouble(java.lang.String key,
                             double value)

A convenience method that calls put(key,""+value), except that the values Double.NaN, Double.POSITIVE_INFINITY, and Double.NEGATIVE_INFINITY are encoded as "NaN", "+INF", and "-INF", respectively.

See Also:

put(String, String)

putBoolean

public static void putBoolean(java.lang.String key,
                              boolean value)

A convenience method that calls put(key,"true") or put(key,"false"), depending on the value.

See Also:

put(String, String)

get

public static java.lang.String get(java.lang.String key,
                                   java.lang.String deflt)

Returns the preference string associated with a given key, or deflt if no value is associated with the key. This method never throws an exception.

Parameters:

key - the key whose associated preference value is to be returned

deflt - the value that will be returned if the key has no associated preference value or if an error occurs when trying to read the preferenece value from persistent storage.

getInt

public static int getInt(java.lang.String key,
                         int deflt)

Returns Integer.parseInt(get(key)), or deflt if no value is associated with the given key or if the string associated with that key is not an integer. This method never throws an exception.

Parameters:

key - the key whose associated preference value is to be returned

deflt - the value that will be returned if the key has no associated preference value or if the value does not represent an integer, or if an error occurs while trying to read the value from persistent storage.

See Also:

get(String)

getDouble

public static double getDouble(java.lang.String key,
                               double deflt)

Returns Double.parseDouble(get(key)), or deflt if no value is associated with the given key or if the string associated with that key is not an integer. The strings "NaN", "+INF", and "-INF" are traslated into the special values Double.NaN, Double.POSITIVE_INFINTY, and Double.NEGATIVE_INFINITY. This method never throws an exception.

Parameters:

key - the key whose associated preference value is to be returned

deflt - the value that will be returned if the key has no associated preference value or if the value does not represent a real number, or if an error occurs while trying to read the value from persistent storage.

See Also:

get(String)

getBoolean

public static boolean getBoolean(java.lang.String key,
                                 boolean deflt)

Returns true if get(key) equals "true", or false if get(key) equals "false", or deflt if the value of get(key) is some other value. This method never throws an exception.

Parameters:

key - the key whose associated preference value is to be returned

deflt - the value that will be returned if the key has no associated preference value or if the value does not represent a boolean value, or if an error occurs while trying to read the value from persistent storage.

See Also:

get(String)

setPrefs

public static void setPrefs(Prefs prefs)

Set the object of type Prefs that actually handles the storage and retrival of prefernce values. By default, the object is just an object of type Prefs, but it could be changed to an object belonging to a sub-class of Prefs by calling this method. This method should ordinarily be called at the start of a program, before any calls to other static methods in this class. If prefs is null, then a default object will be created of type Prefs.

getPrefs

public static Prefs getPrefs()

Returns the object that is used to handle storage of preference values. The return value is non-null.

See Also:

setPrefs(Prefs)

doGet

protected java.lang.String doGet(java.lang.String key)

Get the preference value associated with a key.

Parameters:

key - The non-null, non-empty string that identifies the preference value. If the value is null or empty, no error occurs; the return value is null.

Returns:

The associated value. If a value has been set with a call to doPut(String, String), then that value is returned. If not, then an attempt is made to read the value from user preferenced in persistent storage. If an error occurs while tyring to read the value from persistene storage, then the return value is null. Note that the return value is cached so that only one access of persistent storage will be made for a given key, even if there are multiple calls to this method for this key.

doPut

protected void doPut(java.lang.String key,
                     java.lang.String value)

Associates a given preference value with a given key. The associate is made only in memory, not to persistent storage. For the value to be saved to persistent storage, doSave() must be called.

Parameters:

key - the non-null, non-empty key string. A null or empty string will cause an IllegalArgumentException. The string should ordinarly not contain the "/" character (which would put the preference value into a differenet Preferences node on disk).

value - the value to be associated with the key. This value can be null. Null values are generally to be interpreted as "use the default".

doSave

protected boolean doSave()

Tries to save any modified preference values to persistent storage, using Java's Preferences API. No exception will be thrown if the attempt fails. (Null values are not saved to persistent storage; if the value is null, the associated key is removed from the Preferences database.)

Returns:

true, if the attempt to save the values succeeds, false if it fails. If there is nothing to save, the return value is true; a return value of false indicates that an error occurred.

doSave

protected boolean doSave(java.lang.String key)

Tries to save any modified preference values to persistent storage, using Java's Preferences API. No exception will be thrown if the attempt fails. (Null values are not saved to persistent storage; if the value is null, the associated key is removed from the Preferences database.)

Returns:

true, if the attempt to save the values succeeds, false if it fails. If there is nothing to save, the return value is true; a return value of false indicates that an error occurred.