com.xmlmind.util

Class Preferences

java.lang.Object

com.xmlmind.util.Preferences

public class Preferences
extends Object

Class used by an application to store the preferences of its user.

This class is basically a wrapper around a Properties object, implementing a number of convenience methods such as getBoolean(java.lang.String, boolean).

This class is thread-safe.

Field Summary

Fields

Modifier and Type	Field and Description
Properties	properties The Properties object being wrapped by this Preferences object.

Constructor Summary

Constructors

Constructor and Description
Preferences() Constructs an empty Preferences object.
Preferences(Properties properties) Constructs a Preferences object acting a a wrapper for specified Properties object.

Method Summary

Modifier and Type	Method and Description
String[]	getAll() Returns all preferences in the form of a list of key/value pairs.
boolean	getBoolean(String key, boolean fallback) Returns specified preference.
Color	getColor(String key, Color fallback) Returns specified preference.
double	getDouble(String key, double fallback) Returns specified preference.
double	getDouble(String key, double min, double max, double fallback) Returns specified preference.
double[]	getDoubles(String key, double[] fallback) Returns specified preference.
Font	getFont(String key, Font fallback) Returns specified preference.
int	getInt(String key, int fallback) Returns specified preference.
int	getInt(String key, int min, int max, int fallback) Returns specified preference.
int[]	getInts(String key, int[] fallback) Returns specified preference.
long	getLong(String key, long fallback) Returns specified preference.
long	getLong(String key, long min, long max, long fallback) Returns specified preference.
Paper	getPaper(String key, Paper fallback) Returns specified preference.
Rectangle	getRectangle(String key, Rectangle fallback) Returns specified preference.
String	getString(String key, String fallback) Returns specified preference.
String[]	getStrings(String key, String[] fallback) Returns specified preference.
URL	getURL(String key, URL fallback) Returns specified preference.
URL	getURLEntry(String key, URL urlKey, URL fallback) Considers that the specified preference contains a map which maps an URL to another URL; returns the value corresponding to specified key.
URL[]	getURLs(String key, URL[] fallback) Returns specified preference.
static Preferences	getUserPreferences() Returns the Preferences object containing application-wide user preferences.
boolean	load(File file) Merges the contents of specified Java properties file to this Preferences object.
boolean	load(URL url) Merges the contents of specified Java properties file to this Preferences object.
static void	load(URL url, Properties props) Helper method: adds to specified properties the contents of specified URL.
static Paper	newPaper(double paperW, double paperH, double x, double y, double width, double height) Helper function: returns a new Paper initialized using specified paper size and specified imageable area.
void	putAll(Preferences other) Adds or replaces preferences with preferences read from another Preferences object.
void	putBoolean(String key, boolean value) Adds or replaces preference.
void	putColor(String key, Color value) Adds or replaces preference.
void	putDouble(String key, double value) Adds or replaces preference.
void	putDoubles(String key, double[] value) Adds or replaces preference.
void	putFont(String key, Font value) Adds or replaces preference.
void	putInt(String key, int value) Adds or replaces preference.
void	putInts(String key, int[] value) Adds or replaces preference.
void	putLong(String key, long value) Adds or replaces preference.
void	putPaper(String key, Paper paper) Adds or replaces preference for the format of the paper used when printing documents.
void	putRectangle(String key, Rectangle value) Adds or replaces preference.
void	putString(String key, String value) Adds or replaces preference.
void	putStrings(String key, String[] value) Adds or replaces preference.
void	putURL(String key, URL value) Adds or replaces preference.
void	putURLEntry(String key, URL urlKey, URL urlValue, int maxEntries) Considers that the specified preference contains a map which maps an URL to another URL; adds or replaces in this map the value corresponding to specified key.
void	putURLs(String key, URL[] urls) Adds or replaces preference.
void	remove(String key) Removes specified preference.
void	removeAll() Removes all preferences.
boolean	save(File file, String header) Saves this Preferences object to specified Java properties file.
static void	save(Properties props, File file, String header) Helper method: saves specified properties to specified file.
static void	setUserPreferences(Preferences prefs) Installs the Preferences object containing application-wide user preferences.

Methods inherited from class java.lang.Object

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

Field Detail

properties

public final Properties properties

The Properties object being wrapped by this Preferences object.

Constructor Detail

Preferences

public Preferences()

Constructs an empty Preferences object.

Preferences

public Preferences(Properties properties)

Constructs a Preferences object acting a a wrapper for specified Properties object.

Parameters:

properties - wrapped Properties object. May be null in which case a Properties object is created.

Method Detail

putString

public void putString(String key,
                      String value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getString

public String getString(String key,
                        String fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found

Returns:

specified preference if found; returns fallback otherwise

putBoolean

public void putBoolean(String key,
                       boolean value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getBoolean

public boolean getBoolean(String key,
                          boolean fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as a boolean

Returns:

specified preference if found and valid; returns fallback otherwise

putInt

public void putInt(String key,
                   int value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getInt

public int getInt(String key,
                  int min,
                  int max,
                  int fallback)

Returns specified preference.

Parameters:

key - the name of the preference

min - minimum allowed value for the preference

max - maximum allowed value for the preference

fallback - value returned if specified preference is not found or cannot be parsed as an int or is less than min or is greater than max

Returns:

specified preference if found and valid; returns fallback otherwise

getInt

public int getInt(String key,
                  int fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as an int

Returns:

specified preference if found and valid; returns fallback otherwise

putLong

public void putLong(String key,
                    long value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getLong

public long getLong(String key,
                    long min,
                    long max,
                    long fallback)

Returns specified preference.

Parameters:

key - the name of the preference

min - minimum allowed value for the preference

max - maximum allowed value for the preference

fallback - value returned if specified preference is not found or cannot be parsed as an long or is less than min or is greater than max

Returns:

specified preference if found and valid; returns fallback otherwise

getLong

public long getLong(String key,
                    long fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as an long

Returns:

specified preference if found and valid; returns fallback otherwise

putDouble

public void putDouble(String key,
                      double value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getDouble

public double getDouble(String key,
                        double min,
                        double max,
                        double fallback)

Returns specified preference.

Parameters:

key - the name of the preference

min - minimum allowed value for the preference

max - maximum allowed value for the preference

fallback - value returned if specified preference is not found or cannot be parsed as a double or is less than min or is greater than max

Returns:

specified preference if found and valid; returns fallback otherwise

getDouble

public double getDouble(String key,
                        double fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as a double

Returns:

specified preference if found and valid; returns fallback otherwise

putStrings

public void putStrings(String key,
                       String[] value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getStrings

public String[] getStrings(String key,
                           String[] fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found

Returns:

specified preference if found; returns fallback otherwise

putInts

public void putInts(String key,
                    int[] value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getInts

public int[] getInts(String key,
                     int[] fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as an array of ints

Returns:

specified preference if found and valid; returns fallback otherwise

putDoubles

public void putDoubles(String key,
                       double[] value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getDoubles

public double[] getDoubles(String key,
                           double[] fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as an array of doubles

Returns:

specified preference if found and valid; returns fallback otherwise

putURL

public void putURL(String key,
                   URL value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getURL

public URL getURL(String key,
                  URL fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as an URL

Returns:

specified preference if found and valid; returns fallback otherwise

putURLs

public void putURLs(String key,
                    URL[] urls)

Adds or replaces preference.

Parameters:

key - the name of the preference

urls - the value of the preference

getURLs

public URL[] getURLs(String key,
                     URL[] fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as an array of URLs

Returns:

specified preference if found and valid; returns fallback otherwise

putURLEntry

public void putURLEntry(String key,
                        URL urlKey,
                        URL urlValue,
                        int maxEntries)

Considers that the specified preference contains a map which maps an URL to another URL; adds or replaces in this map the value corresponding to specified key.

Parameters:

key - the name of the preference

urlKey - the key for which an entry is to be added or replaced in the map

urlValue - the value of urlKey. May be null in case the map entry corresponding to urlKey is removed.

maxEntries - capacity of the map (in terms of entries, not in terms of URLs). If this capacity is exceeded, the oldest entries (that is, the first added ones) are automatically removed.

See Also:

getURLEntry(java.lang.String, java.net.URL, java.net.URL), putURLs(java.lang.String, java.net.URL[]), getURLs(java.lang.String, java.net.URL[])

getURLEntry

public URL getURLEntry(String key,
                       URL urlKey,
                       URL fallback)

Considers that the specified preference contains a map which maps an URL to another URL; returns the value corresponding to specified key.

Parameters:

key - the name of the preference

urlKey - the searched key

fallback - returned value when urlKey is not found in the map

Returns:

value corresponding to urlKey if any; fallback otherwise

See Also:

putURLEntry(java.lang.String, java.net.URL, java.net.URL, int), putURLs(java.lang.String, java.net.URL[]), getURLs(java.lang.String, java.net.URL[])

putFont

public void putFont(String key,
                    Font value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getFont

public Font getFont(String key,
                    Font fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as a Font

Returns:

specified preference if found and valid; returns fallback otherwise

putColor

public void putColor(String key,
                     Color value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getColor

public Color getColor(String key,
                      Color fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as a Color

Returns:

specified preference if found and valid; returns fallback otherwise

putRectangle

public void putRectangle(String key,
                         Rectangle value)

Adds or replaces preference.

Parameters:

key - the name of the preference

value - the value of the preference

getRectangle

public Rectangle getRectangle(String key,
                              Rectangle fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as a Rectangle

Returns:

specified preference if found and valid; returns fallback otherwise

putPaper

public void putPaper(String key,
                     Paper paper)

Adds or replaces preference for the format of the paper used when printing documents.

Parameters:

key - the name of the preference

paper - the value of the preference

getPaper

public Paper getPaper(String key,
                      Paper fallback)

Returns specified preference.

Parameters:

key - the name of the preference

fallback - value returned if specified preference is not found or cannot be parsed as a Paper

Returns:

specified preference if found and valid; returns fallback otherwise

newPaper

public static final Paper newPaper(double paperW,
                                   double paperH,
                                   double x,
                                   double y,
                                   double width,
                                   double height)

Helper function: returns a new Paper initialized using specified paper size and specified imageable area.

remove

public void remove(String key)

Removes specified preference.

Parameters:

key - the name of the preference

removeAll

public void removeAll()

Removes all preferences.

getAll

public String[] getAll()

Returns all preferences in the form of a list of key/value pairs. This list may be empty but cannot be null.

putAll

public void putAll(Preferences other)

Adds or replaces preferences with preferences read from another Preferences object.

Parameters:

other - the source Preferences object

load

public boolean load(File file)

Merges the contents of specified Java properties file to this Preferences object.

Invoke removeAll() if you need to reset this Preferences object to the contents of specified file.

Parameters:

file - the file to be loaded

Returns:

true if the file has been sucessfully loaded; false otherwise

See Also:

load(URL), save(java.io.File, java.lang.String)

load

public boolean load(URL url)

Merges the contents of specified Java properties file to this Preferences object.

Parameters:

url - the location of the file to be loaded

Returns:

true if the file has been sucessfully loaded; false otherwise

See Also:

load(File), save(java.io.File, java.lang.String)

load

public static void load(URL url,
                        Properties props)
                 throws IOException

Helper method: adds to specified properties the contents of specified URL.

Parameters:

url - the location of the file to be loaded

props - the properties to be updated

Throws:

IOException - if for any reason, the properties have not been sucessfully updated

save

public boolean save(File file,
                    String header)

Saves this Preferences object to specified Java properties file.

Parameters:

file - the save file

header - optional header for the save file; may be null

Returns:

true if the properties have been sucessfully updated; false otherwise

See Also:

load(File), load(URL)

save

public static void save(Properties props,
                        File file,
                        String header)
                 throws IOException

Helper method: saves specified properties to specified file.

Parameters:

props - the properties to be saved

file - the save file

header - optional header for the save file; may be null

Throws:

IOException - if for any reason, the properties have not been sucessfully saved

setUserPreferences

public static final void setUserPreferences(Preferences prefs)

Installs the Preferences object containing application-wide user preferences.

See Also:

getUserPreferences()

getUserPreferences

public static final Preferences getUserPreferences()

Returns the Preferences object containing application-wide user preferences.

Creates and installs one if setUserPreferences(com.xmlmind.util.Preferences) has never been invoked or has been set to null.