Preferences (Tensegrity API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.tensegrity.generic.util.prefs
Interface Preferences

public interface Preferences

A Preferences object is useful when it comes to managing application-wide configuration settings and making them persistent. Upon instantiation, these configuration settings are loaded from an existing preferences.xml file located in the user.dir directory. The user preferences are merged into the defaults in a way that only valid settings will be taken over. So if the defaults change (which are shipped with the application) and a setting or a possible value of a setting is removed the setting will be removed from the user preferences as well.

A default preference file contains the set of all settings that exist in the application and provides a structure to categorize them for a better usability. Using these defaults the configuration settings can be restored across application restarts. In doing so, you will have runtime access to a read-only Preference object, helpful in situations where you do not have access to the file system, such as in an applet.

To use preferences within your application follow these steps:

Create a new / copy an existing "preferences.xml".(The Skeleton Framework contains an example file).
Instantiate your preferences with a call to the static method PreferenceFactory.createPreferences(String, Class, String) of class PreferenceFactory.
Register PreferenceListener to get notified about changes.
On application exit save your settings with a call to the method flush()

An example preferences.xml file:

 <list>
 
  <!-- a first tab: GUI related -->
  <set name="prefs.tab.gui">
   <set name="prefs.grp.common">
    <attribute name="prefs.common.language" value="Deutsch">
     <constraint><![CDATA[(value in ('Deutsch' | 'English'))]]></constraint>
    </attribute>
   </set>
   <set name="prefs.grp.surface">
    <attribute name="prefs.surface.style" value="SDI">
     <constraint><![CDATA[(value in ('SDI' | 'MDI'))]]></constraint>
    </attribute>
    <attribute name="prefs.surface.showtooltips" type="Boolean" value="true"/>
   </set>
  </set>
 
  <!-- a second tab: files and folders -->
  <set name="prefs.tab.paths">
   <set name="prefs.grp.paths">
    <attribute name="prefs.path.templates" 
               type="com.tensegrity.gui.template.DirectoryLocationAttribute" 
               value=""/>
    <attribute name="prefs.path.lastdir" 
               type="com.tensegrity.gui.template.DirectoryLocationAttribute" 
               value=""/>
   </set>
   <set name="prefs.grp.filemenu">            
    <attribute name="prefs.files.listsize" type="Integer" value="10"/>           
   </set>
  </set>

  <!-- this third group is a hidden one -> not shown in dialog -->
  <set name="prefs.hidden.tab.window">
   <set name="prefs.window.bounds">
    <attribute name="prefs.window.pos_x" type="Integer" value="20"/>
    <attribute name="prefs.window.pos_y" type="Integer" value="40"/>
    <attribute name="prefs.window.width" type="Integer" value="600"/>
    <attribute name="prefs.window.height" type="Integer" value="400"/>
   </set>
  </set>
 
 <list>

As you can see the format of the file is the tensegrity XML format for storing Attribute structures. On the top level there are the tabs which are AttributeSets and usually represent a tab in the TabbedPane of a preference dialog, thus the name. These sets contain one or more subsets defining one category of settings. Finally on the third level of the structure there are the settings.

The names of all AttributeSets and Attributes are usually used for resolving text resources in an UIManager or AttributeEditorTranslator. This also applies to the values of an EnumConstraint. The most important names are the ones of the Attributes on the third level, because they will be used to retrieve and set the values of the settings.

You can use the text "hidden" in the name of a tab to hide it from the dialog. This is useful for generic values (e.g. window positions) that the user should not edit directly.

Version:: $Id: Preferences.java,v 1.45 2006/03/27 16:58:17 BurkhardWick Exp $
Author:: Andreas Ebbert

Method Summary
`void`	`addPreferenceChangeListener(PreferenceListener listener, java.lang.String key)` Adds the specified listener to the listeners-list.
`boolean`	`containsKey(java.lang.String key)` Returns `true` if the preferences contain the specified key.
`void`	`flush()` Saves the preferences-file.
`java.lang.String`	`get(java.lang.String key, java.lang.String def)` Returns the `String` corresponding to the given key.
`boolean`	`getBoolean(java.lang.String key, boolean def)` Returns the `boolean` value corresponding to the given key.
`double`	`getDouble(java.lang.String key, double def)` Returns the `double` value corresponding to the given key.
`float`	`getFloat(java.lang.String key, float def)` Returns the `float` value corresponding to the given key.
`int`	`getInt(java.lang.String key, int def)` Returns the `int` value corresponding to the given key.
`long`	`getLong(java.lang.String key, long def)` Returns the `long` value corresponding to the given key.
`MetricExpression`	`getMetricExpression(java.lang.String key, MetricExpression def)` Returns the `MetricExpression` value corresponding to the given key.
`java.lang.String[]`	`getValueListForAttribute(java.lang.String key)` Returns an array holding the stored values for this key.
`void`	`initializeListeners()` In most cases of using preferences the stored attributes have to get set in your application twice: At Application start up Whenever an value, for that a listener has been registered, changes.
`java.lang.String[]`	`keys()` Returns all keys specified in the preference XML-file.
`java.util.Locale`	`localeCreate(java.lang.String prefsLocale)` Creates a locale by parsing the given preferences string.
`java.lang.String`	`localeGetPreferenceString(java.util.Locale locale)` Creates a string representation of the given locale that can be stored to the preferences.
`void`	`put(java.lang.String key, java.lang.String value)` Associates the key `key` to the given `String`.
`void`	`putBoolean(java.lang.String key, boolean value)` Associates the key `key` to the given `boolean`.
`void`	`putDouble(java.lang.String key, double value)` Associates the key `key` to the given `double`.
`void`	`putFloat(java.lang.String key, float value)` Associates the key `key` to the given `float`.
`void`	`putInt(java.lang.String key, int value)` Associates the key `key` to the given `int`.
`void`	`putLong(java.lang.String key, long value)` Associates the key `key` to the given `long`.
`void`	`putMetricExpression(java.lang.String key, MetricExpression value)` Associates the key `key` to the given `MetricExpression`.
`void`	`setValueListForAttribute(java.lang.String key, java.lang.String[] values)` Associates the list of given values `values` with key `key`.

Method Detail

keys

public java.lang.String[] keys()

Returns all keys specified in the preference XML-file.

Returns:: all keys specified in the preference XML-file.
Find more information in the class documentation

containsKey

public boolean containsKey(java.lang.String key)

Returns true if the preferences contain the specified key.

Parameters:: key - the key whose presence in the preferences is to be tested.
Returns:: true if the preferences contain the specified key.
Find more information in the class documentation

get

public java.lang.String get(java.lang.String key,
                            java.lang.String def)

Returns the String corresponding to the given key. If the given key does not exist the default value is returned.

Parameters:: key - the key whose corresponding value has to be returned.; def - the value to be returned, if there is no value corresponding to the given key.
Returns:: the string mapped to the key; the default value, if there is no such mapping.
Find more information in the class documentation

put

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

Associates the key key to the given String.

Parameters:: key - the key with which the string value should be associated.; value - the value associated with the given key.
Find more information in the class documentation

getBoolean

public boolean getBoolean(java.lang.String key,
                          boolean def)

Returns the boolean value corresponding to the given key.

Parameters:: key - the key whose corresponding value has to be returned.; def - the value to be returned, if there is no value corresponding to the given key.
Returns:: the boolean corresponding to the key; the default value, if there is no such mapping.

putBoolean

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

Associates the key key to the given boolean.

Parameters:: key - the key with which the boolean value should be associated.; value - the value associated with the given key.

getDouble

public double getDouble(java.lang.String key,
                        double def)

Returns the double value corresponding to the given key.

Parameters:: key - the key whose corresponding value has to be returned.; def - the value to be returned if there is no value corresponding to the given key.
Returns:: the double corresponding to the key; the given defaultValue, if there is no such mapping.

putDouble

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

Associates the key key to the given double.

Parameters:: key - the key with which the double value should be associated.; value - the value associated with the given key.

getFloat

public float getFloat(java.lang.String key,
                      float def)

Returns the float value corresponding to the given key.

Parameters:: key - the key whose corresponding value has to be returned.; def - the value to be returned, if there is no value corresponding to the given key.
Returns:: the float corresponding to the key; the default value, if there is no such mapping.

putFloat

public void putFloat(java.lang.String key,
                     float value)

Associates the key key to the given float.

Parameters:: key - the key with which the float value should be associated.; value - the value associated with the given key.

getInt

public int getInt(java.lang.String key,
                  int def)

Returns the int value corresponding to the given key.

Parameters:: key - the key whose corresponding value has to be returned.; def - the value to be returned, if there is no value corresponding to the given key.
Returns:: the int corresponding to the key; the default value, if there is no such mapping.

putInt

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

Associates the key key to the given int.

Parameters:: key - the key with which the int value should be associated.; value - the value associated with the given key.

getMetricExpression

public MetricExpression getMetricExpression(java.lang.String key,
                                            MetricExpression def)

Returns the MetricExpression value corresponding to the given key.

Parameters:: key - the key whose corresponding value has to be returned.; def - the value to be returned, if there is no value corresponding to the given key.
Returns:: the MetricExpression corresponding to the key; the default value, if there is no such mapping.

putMetricExpression

public void putMetricExpression(java.lang.String key,
                                MetricExpression value)

Associates the key key to the given MetricExpression.

Parameters:: key - the key with which the MetricExpression value should be associated.; value - the value associated with the given key.

getLong

public long getLong(java.lang.String key,
                    long def)

Returns the long value corresponding to the given key.

Parameters:: key - the key whose corresponding value has to be returned.; def - the value to be returned, if there is no value corresponding to the given key.
Returns:: the long corresponding to the key; the given value def, if there is no such mapping.

putLong

public void putLong(java.lang.String key,
                    long value)

Associates the key key to the given long.

Parameters:: key - the key with which the long value should be associated.; value - the value associated with the given key.

getValueListForAttribute

public java.lang.String[] getValueListForAttribute(java.lang.String key)

Returns an array holding the stored values for this key. Normally every key has just one associated value. But it makes sense to allow having lists associated to keys. Imagine a list of recently opened files you want to hold persistently in the preferences object. In this case it is reasonable to have a key associated to a list of values.

Parameters:: key - the key to retrieve the list for.
Returns:: the list associated with the given key; null, if there is no list associated to the given key.
Find more information in the class documentation

setValueListForAttribute

public void setValueListForAttribute(java.lang.String key,
                                     java.lang.String[] values)

Associates the list of given values values with key key.

Parameters:: key - the key to associate the given values with.; values - the list of values.
Find more information in the class documentation

flush

public void flush()
           throws java.io.IOException

Saves the preferences-file. The default name of this file is preferences.xml and it is located in the user.dir.

Throws:: java.io.IOException - if the preference-file could not be saved.

addPreferenceChangeListener

public void addPreferenceChangeListener(PreferenceListener listener,
                                        java.lang.String key)

Adds the specified listener to the listeners-list. The listener is informed when the corresponding value for this key has been modified. You may register multiple listeners using the same key.

Parameters:: listener - the listener that wants to get informed about a change of key key.; key - the key to watch.
Find more information in the class documentation

initializeListeners

public void initializeListeners()

In most cases of using preferences the stored attributes have to get set in your application twice:

At Application start up
Whenever an value, for that a listener has been registered, changes.

So, you usually do not want to implement this setting functionality twice. To avoid this redundancy add your application specific listeners first and afterwards call this method.

Find more information in the class documentation

localeCreate

public java.util.Locale localeCreate(java.lang.String prefsLocale)

Creates a locale by parsing the given preferences string. The string must be of the format: LANGUAGE + "/" + COUNTRY

Parameters:: prefsLocale - The preference string to parse
Returns:: The corresponding locale

localeGetPreferenceString

public java.lang.String localeGetPreferenceString(java.util.Locale locale)

Creates a string representation of the given locale that can be stored to the preferences. Use localeCreate(String) to create a locale from the string again.

Parameters:: locale - The locale to create a string for
Returns:: The string representation of the given locale