com.xmlmind.util
Class Preferences

java.lang.Object
  extended by com.xmlmind.util.Preferences

public class Preferences
extends java.lang.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
 java.util.Properties properties
          The Properties object being wrapped by this Preferences object.
 
Constructor Summary
Preferences()
          Constructs an empty Preferences object.
Preferences(java.util.Properties properties)
          Constructs a Preferences object acting a a wrapper for specified Properties object.
 
Method Summary
 java.lang.String[] getAll()
          Returns all preferences in the form of a list of key/value pairs.
 boolean getBoolean(java.lang.String key, boolean fallback)
          Returns specified preference.
 java.awt.Color getColor(java.lang.String key, java.awt.Color fallback)
          Returns specified preference.
 double getDouble(java.lang.String key, double fallback)
          Returns specified preference.
 double getDouble(java.lang.String key, double min, double max, double fallback)
          Returns specified preference.
 double[] getDoubles(java.lang.String key, double[] fallback)
          Returns specified preference.
 java.awt.Font getFont(java.lang.String key, java.awt.Font fallback)
          Returns specified preference.
 int getInt(java.lang.String key, int fallback)
          Returns specified preference.
 int getInt(java.lang.String key, int min, int max, int fallback)
          Returns specified preference.
 int[] getInts(java.lang.String key, int[] fallback)
          Returns specified preference.
 long getLong(java.lang.String key, long fallback)
          Returns specified preference.
 long getLong(java.lang.String key, long min, long max, long fallback)
          Returns specified preference.
 java.awt.print.Paper getPaper(java.lang.String key, java.awt.print.Paper fallback)
          Returns specified preference.
static Preferences getPreferences()
          Returns the Preferences object containing application-wide user preferences.
 java.awt.Rectangle getRectangle(java.lang.String key, java.awt.Rectangle fallback)
          Returns specified preference.
 java.lang.String getString(java.lang.String key, java.lang.String fallback)
          Returns specified preference.
 java.lang.String[] getStrings(java.lang.String key, java.lang.String[] fallback)
          Returns specified preference.
 java.net.URL getURL(java.lang.String key, java.net.URL fallback)
          Returns specified preference.
 java.net.URL getURLEntry(java.lang.String key, java.net.URL urlKey, java.net.URL fallback)
          Considers that the specified preference contains a map which maps an URL to another URL; returns the value corresponding to specified key.
 java.net.URL[] getURLs(java.lang.String key, java.net.URL[] fallback)
          Returns specified preference.
 boolean load(java.io.File file)
          Merges the contents of specified Java properties file to this Preferences object.
 boolean load(java.net.URL url)
          Merges the contents of specified Java properties file to this Preferences object.
static void load(java.net.URL url, java.util.Properties props)
          Helper method: adds to specified properties the contents of specified URL.
static java.awt.print.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(java.lang.String key, boolean value)
          Adds or replaces preference.
 void putColor(java.lang.String key, java.awt.Color value)
          Adds or replaces preference.
 void putDouble(java.lang.String key, double value)
          Adds or replaces preference.
 void putDoubles(java.lang.String key, double[] value)
          Adds or replaces preference.
 void putFont(java.lang.String key, java.awt.Font value)
          Adds or replaces preference.
 void putInt(java.lang.String key, int value)
          Adds or replaces preference.
 void putInts(java.lang.String key, int[] value)
          Adds or replaces preference.
 void putLong(java.lang.String key, long value)
          Adds or replaces preference.
 void putPaper(java.lang.String key, java.awt.print.Paper paper)
          Adds or replaces preference for the format of the paper used when printing documents.
 void putRectangle(java.lang.String key, java.awt.Rectangle value)
          Adds or replaces preference.
 void putString(java.lang.String key, java.lang.String value)
          Adds or replaces preference.
 void putStrings(java.lang.String key, java.lang.String[] value)
          Adds or replaces preference.
 void putURL(java.lang.String key, java.net.URL value)
          Adds or replaces preference.
 void putURLEntry(java.lang.String key, java.net.URL urlKey, java.net.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(java.lang.String key, java.net.URL[] urls)
          Adds or replaces preference.
 void remove(java.lang.String key)
          Removes specified preference.
 void removeAll()
          Removes all preferences.
 boolean save(java.io.File file, java.lang.String header)
          Saves this Preferences object to specified Java properties file.
static void save(java.util.Properties props, java.io.File file, java.lang.String header)
          Helper method: saves specified properties to specified file.
static void setPreferences(Preferences prefs)
          Specifies 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 java.util.Properties properties
The Properties object being wrapped by this Preferences object.

Constructor Detail

Preferences

public Preferences()
Constructs an empty Preferences object.


Preferences

public Preferences(java.util.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(java.lang.String key,
                      java.lang.String value)
Adds or replaces preference.

Parameters:
key - the name of the preference
value - the value of the preference

getString

public java.lang.String getString(java.lang.String key,
                                  java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.String key,
                       java.lang.String[] value)
Adds or replaces preference.

Parameters:
key - the name of the preference
value - the value of the preference

getStrings

public java.lang.String[] getStrings(java.lang.String key,
                                     java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.String key,
                   java.net.URL value)
Adds or replaces preference.

Parameters:
key - the name of the preference
value - the value of the preference

getURL

public java.net.URL getURL(java.lang.String key,
                           java.net.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(java.lang.String key,
                    java.net.URL[] urls)
Adds or replaces preference.

Parameters:
key - the name of the preference
urls - the value of the preference

getURLs

public java.net.URL[] getURLs(java.lang.String key,
                              java.net.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(java.lang.String key,
                        java.net.URL urlKey,
                        java.net.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 java.net.URL getURLEntry(java.lang.String key,
                                java.net.URL urlKey,
                                java.net.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(java.lang.String key,
                    java.awt.Font value)
Adds or replaces preference.

Parameters:
key - the name of the preference
value - the value of the preference

getFont

public java.awt.Font getFont(java.lang.String key,
                             java.awt.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(java.lang.String key,
                     java.awt.Color value)
Adds or replaces preference.

Parameters:
key - the name of the preference
value - the value of the preference

getColor

public java.awt.Color getColor(java.lang.String key,
                               java.awt.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(java.lang.String key,
                         java.awt.Rectangle value)
Adds or replaces preference.

Parameters:
key - the name of the preference
value - the value of the preference

getRectangle

public java.awt.Rectangle getRectangle(java.lang.String key,
                                       java.awt.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(java.lang.String key,
                     java.awt.print.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 java.awt.print.Paper getPaper(java.lang.String key,
                                     java.awt.print.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 java.awt.print.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(java.lang.String key)
Removes specified preference.

Parameters:
key - the name of the preference

removeAll

public void removeAll()
Removes all preferences.


getAll

public java.lang.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(java.io.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(java.net.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(java.net.URL url,
                        java.util.Properties props)
                 throws java.io.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:
java.io.IOException - if for any reason, the properties have not been sucessfully updated

save

public boolean save(java.io.File file,
                    java.lang.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(java.util.Properties props,
                        java.io.File file,
                        java.lang.String header)
                 throws java.io.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:
java.io.IOException - if for any reason, the properties have not been sucessfully saved

setPreferences

public static final void setPreferences(Preferences prefs)
Specifies the Preferences object containing application-wide user preferences.

Parameters:
prefs - application-wide user preferences. May be null in which case a new, non-persistent, Preferences object will be used.
See Also:
getPreferences()

getPreferences

public static final Preferences getPreferences()
Returns the Preferences object containing application-wide user preferences.

Returns:
a non-null Preferences object
See Also:
setPreferences(com.xmlmind.util.Preferences)