vmm3d.core

Class Prefs

java.lang.Object

vmm3d.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.

Method Summary

Modifier and Type	Method and Description
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

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

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)