Managing User Preferences

API
Using the Preferences Manager

API

YASL provides a ready-made mechanism for managing user preferences. The preferences are stored in a properties file which is typically located in a sub-folder in the user's home directory. The preferences manager handles loading and storing the preferences file but the application controls the name and location of the file. The manager has convenience methods for storing and setting the frame's size and position as well as convenience methods for storing and retrieving preferences of types other than String. Classes that implement the PreferencesListener interface (from org.yasl.arch.prefs) can be added to the manager as listeners that will be notified whenever a preference has been changed.

The methods from the PreferencesManager interface (from org.yasl.arch.prefs) are listed below. The interface is implemented by PreferencesManagerImpl (from org.yasl.arch.impl.prefs) which can be initialized with a map of default preferences and values for the folder and filename to which preferences will be saved.

Constants

/**
 * Preference key for application width.
 */
public static final String PREF_APP_WIDTH = "yasl.pref.app.width";

/**
 * Preference key for application height.
 */
public static final String PREF_APP_HEIGHT = "yasl.pref.app.height";

/**
 * Preference key for application x position.
 */
public static final String PREF_APP_POS_X = "yasl.pref.app.pos.x";

/**
 * Preference key for application y position.
 */
public static final String PREF_APP_POS_Y = "yasl.pref.app.pos.y";

Loading and Saving Properties

/**
 * Saves the preferences to the properties file specified.
 * The header value will be placed at the top of the file as a comment.
 *
 * @param prefFile File
 * @param header String
 */
public void savePreferences(File prefFile, String header)
        throws FileNotFoundException, IOException;

/**
 * Saves the preferences to the properties file specified.
 *
 * @param prefFile File
 */
public void savePreferences(File prefFile)
        throws FileNotFoundException, IOException;

/**
 * Populate the preferences from the specified properties file.
 *
 * @param prefFile File
 */
public void loadPreferences(File prefFile)
        throws FileNotFoundException, IOException;

/**
 * Utility method for creating a file object using the user's home
 * folder.
 * 
 * If the folder does not exist, it will be created.
 *
 * @param folder String -- The name of the folder that will hold app
 * config files in the user's home directory.
 * @param filename String -- The name of the file to hold user preferences.
 * @return File
 */
public File getPreferenceFile(String folder, String filename)
        throws IOException;

/**
 * Utility method for creating a file object using the user's home
 * folder.
 * 
 * If the folder does not exist, it will be created.
 * 
 * This method will use the default folder and default filename.
 *
 * @return File
 */
public File getPreferenceFile()
     throws IOException;

/**
 * Returns the default name of the folder that will hold app
 * config files in the user's home directory.
 *
 * @return String
 */
public String getDefaultPrefsFolder();

/**
 * Returns the default name of the file to hold user preferences.
 *
 * @return String
 */
public String getDefaultPrefsFilename();

/**
 * Returns the value to be placed at the top of the
 * preferences file as a comment.
 *
 * This method may return null if the default header
 * has not been set.
 *
 * @return String
 */
public String getDefaultPreferencesHeader();

/**
 * Sets the value to be placed at the top of the preferences
 * file as a comment.
 *
 * @return String
*/
public void setDefaultPreferencesHeader(String header);

Frame Size and Location Methods

/**
 * Saves the frame size in the preferences.
 *
 * @param frame JFrame
 */
public void saveFrameSize(JFrame frame);

/**
 * Sets the size of the frame based on the values set
 * in the preferences.
 *
 * @param frame JFrame
 */
public void setFrameSize(JFrame frame);

/**
 * Saves the frame location in the preferences.
 *
 * @param frame JFrame
 */
public void saveFrameLocation(JFrame frame);

/**
 * Sets the size of the location of the frame based on the
 * values set in the preferences.
 *
 * @param frame JFrame
 */
public void setFrameLocation(JFrame frame);

Generic Preference Methods

/**
 * Returns true if the key is mapped in the preferences.
 *
 * @return boolean
 */
public boolean isPreferenceAvailable(String key);

/**
 * Returns list of the preference keys.
 *
 * @return List
 */
public List getPreferenceKeys();

/**
 * Returns the value associated with the key.
 *
 * If the key does not exist, the returned value is null.
 *
 * @param key String
 * @return String
 */
public String getPreference(String key);

/**
 * Returns the value associated with the key.
 *
 * If the key does not exist, the returned value is the defaultValue.
 *
 * @param key String
 * @param defaultValue String
 * @return String
 */
public String getPreference(String key, String defaultValue);

/**
 * Sets the value to be associated with the passed key.
 *
 * The value cannot be null.
 *
 * @param key String
 * @param value Object
 */
public void setPreference(String key, Object value);

Typed Preference Methods

/**
 * Convenience method for transforming a value to an int.
 * 
 * If the key does not exist, 0 is returned.
 *
 * @param key String
 * @return int
 */
public int getIntValue(String key);

/**
 * Convenience method for setting an int value.
 *
 * @param key String
 * @param value int
 */
public void setIntValue(String key, int value);

/**
 * Convenience method for transforming a value to a float.
 * 
 * If the key does not exist, 0 is returned.
 *
 * @param key String
 * @return float
 */
public float getFloatValue(String key);

/**
 * Convenience method for setting float values.
 *
 * @param key String
 * @param value float
 */
public void setFloatValue(String key, float value);

/**
 * Convenience method for transforming a value to a double.
 *
 * If the key does not exist, 0 is returned.
 *
 * @param key String
 * @return double
 */
public double getDoubleValue(String key);

/**
 * Convenience method for setting double preferences.
 *
 * @param key String
 * @param value double
 */
public void setDoubleValue(String key, double value);

/**
 * Convenience method for transforming a value to a boolean.
 * 
 * If the key does not exist, false is returned.
 *
 * @param key String
 * @return boolean
 */
public boolean getBooleanValue(String key);

/**
 * Convenience method for setting a boolean preference.
 *
 * @param key String
 * @param value boolean
 */
public void setBooleanValue(String key, boolean value);

/**
 * Convenience method for transforming a value to a Color.
 * 
 * The color should be encoded in the following format:
 * R,G,B. For example: 23,44,8
 * 
 * If the key does not exist, null is returned.
 *
 * @param key String
 * @return Color
 */
public Color getColorValue(String key);

/**
 * Convenience method for setting a Color preference.
 *
 * @param key String
 * @param colorValue Color
 */
public void setColorValue(String key, Color colorValue);

Change Listener Methods

/**
 * Adds a preferences listener to the manager. The listener will be
 * notified when a preference changes.
 *
 * @param listener PreferencesListener
 */
public void addPreferencesChangeListener(PreferencesListener listener);

/**
 * Removes a preferences listener from the manager.
 *
 * @param listener PreferencesListener
 */
public void removePreferencesChangeListener(PreferencesListener listener);

Using the Preferences Manager

The preferences manager is stored in the singletons map using the key YASLApplication.KEY_PREFERENCES_MANAGER. The typical usage flow for the preferences manager is listed below:

Preferences manager is created and stored through xml configuration. (See sample.)
Preferences manager is accessed from the application start action. Preferences are loaded from the preferences file at this point. (See sample.)
Application accesses preferences manager to check or store preferences at various points in the application.
Preferences manager is accessed from the application exit action. Preferences are saved to the preferences file at this point. (See sample.)

The sample code below is drawn from the Hello World Application.

XML Config for Preferences Manager

<yaslConfig>
  <property key="bundleName" value="org.yasl.helloworld.resources.helloWorldGuiStrings"/>
  <property key="prefsFolder" value="yasl_hello_world"/>
  <property key="prefsFilename" value="hello_world_prefs.properties"/>
...

  <singletonsConfig>
...
    <!-- default preferences -->
    <map key="default_prefs" keyType="temporary">
      <mapEntry mapKey="yasl.pref.app.width" mapValue="500"/>
      <mapEntry mapKey="yasl.pref.app.height" mapValue="350"/>
      <mapEntry mapKey="yasl.pref.app.pos.x" mapValue="100"/>
      <mapEntry mapKey="yasl.pref.app.pos.y" mapValue="100"/>
    </map>
    <!-- preferences manager -->
    <singleton class="org.yasl.arch.impl.prefs.PreferencesManagerImpl" key="yasl_preferences_manager">
      <argKeyedObject keyType="temporary" key="default_prefs"/>
      <argPrimitive type="String" value="$prefsFolder"/>
      <argPrimitive type="String" value="$prefsFilename"/>
    </singleton>
    <!-- set header for prefs manager -->
    <methodCall keyType="singletons" key="yasl_preferences_manager" method="setDefaultPreferencesHeader">
      <argRBString bundle="$bundleName" key="app.user.prefs.header"/>
    </methodCall>
  </singletonsConfig>

Preferences Manager in the Start Action

protected void performAction(ActionEvent e)
        throws Exception {
    YASLSwingApplication swingApp = getYASLSwingApplication();
    // load preferences if pref manager is defined
    if (swingApp.isSingletonMapped(YASLApplication.KEY_PREFERENCES_MANAGER)) {
        PreferencesManager prefManager =
                (PreferencesManager)swingApp.getSingleton(
                        YASLApplication.KEY_PREFERENCES_MANAGER);
        File prefFile = prefManager.getPreferenceFile();
        prefManager.loadPreferences(prefFile);
        // set app width, height, and position
        JFrame frame = swingApp.getJFrame();
        prefManager.setFrameSize(frame);
        prefManager.setFrameLocation(frame);
    }
}

Preferences Manager in the Exit Action

protected void performAction(ActionEvent e)
        throws Exception {
    YASLSwingApplication swingApp = getYASLSwingApplication();
    // get and set preferences if prefs manager is defined
    if (swingApp.isSingletonMapped(YASLApplication.KEY_PREFERENCES_MANAGER)) {
        PreferencesManager prefManager =
                (PreferencesManager)swingApp.getSingleton(
                        YASLApplication.KEY_PREFERENCES_MANAGER);
        JFrame frame = swingApp.getJFrame();
        // save size of app frame
        prefManager.saveFrameSize(frame);
        // save location of frame
        prefManager.saveFrameLocation(frame);
        // save preferences
        File prefFile = prefManager.getPreferenceFile();
        prefManager.savePreferences(prefFile);
    }
    // stop application
    System.exit(0);
}

Yet Another Swing Library

Swing Application Framework and Components

Documentation: