ucar.util.prefs

Class PreferencesExt

java.lang.Object

java.util.prefs.Preferences

java.util.prefs.AbstractPreferences

ucar.util.prefs.PreferencesExt

All Implemented Interfaces:

PersistenceManager

public class PreferencesExt
extends AbstractPreferences
implements PersistenceManager

An extension of java.util.prefs.Preferences (jdk 1.4) that provides a platform-independent implementation using XML files as backing store.

To save Java beans, use putBean() and putBeanCollection(). This uses reflection to get/set properties that have simple single-valued accessor methods of primitive and String type.

For arbitrary objects, use putBeanObject(), which uses the XMLEncode/XMLDecode API (jdk 1.4). To obtain a PreferencesExt object, instantiate an XMLStore object and call XMLStore.getPreferences().

Author:

John Caron

See Also:

XMLStore, Preferences

Field Summary

Fields inherited from class java.util.prefs.AbstractPreferences

lock, newNode

Fields inherited from class java.util.prefs.Preferences

MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH

Constructor Summary

Constructors

Constructor and Description
PreferencesExt(PreferencesExt parent, String name) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected String[]	childrenNamesSpi() Implements AbstractPreferences childrenNamesSpi() method.
protected Collection	childrenNamesSpi(String nodePath)
protected AbstractPreferences	childSpi(String name)
protected void	flushSpi() Empty, never used implementation of AbstractPreferences.flushSpi().
Object	getBean(String key, Object def) Get the object that has the specified key.
List	getList(String key, List def) Get an arrayList.
Object	getObject(String key)
protected String	getSpi(String keyName)
boolean	isUserNode() return true unless this is the systemRoot node
protected String[]	keysSpi()
protected Collection	keysSpi(String nodePath)
void	putBean(String key, Object newValue) Stores an object using simple bean properties.
void	putBeanCollection(String key, Collection newValue) Stores a Collection of beans.
void	putBeanObject(String key, Object newValue) Stores an object using XMLEncoder/XMLDecoder.
void	putList(String key, List newValue) Stores the value with this key, if the exact key and value are not already in the storedDefaults (using equals() to test for equality).
void	putObject(String keyName, Object value)
protected void	putSpi(String key, String newValue)
protected void	removeNodeSpi()
protected void	removeSpi(String key) removes key/value if exists, no effect on storedDefaults Remove the association (if any) for the specified key at this preference node.
static void	setSystemRoot(PreferencesExt prefs) Set the system root you get when you call Preferences.systemRoot().
static void	setUserRoot(PreferencesExt prefs) Set the user root you get when you call Preferences.userRoot().
protected void	syncSpi()

Methods inherited from class java.util.prefs.AbstractPreferences

absolutePath, addNodeChangeListener, addPreferenceChangeListener, cachedChildren, childrenNames, clear, exportNode, exportSubtree, flush, get, getBoolean, getByteArray, getChild, getDouble, getFloat, getInt, getLong, isRemoved, keys, name, node, nodeExists, parent, put, putBoolean, putByteArray, putDouble, putFloat, putInt, putLong, remove, removeNode, removeNodeChangeListener, removePreferenceChangeListener, sync, toString

Methods inherited from class java.util.prefs.Preferences

importPreferences, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ucar.util.prefs.PersistenceManager

addPreferenceChangeListener, get, getBoolean, getDouble, getInt, getLong, put, putBoolean, putDouble, putInt, putLong

Constructor Detail

PreferencesExt

public PreferencesExt(PreferencesExt parent,
              String name)

Constructor. Usually you get a PreferencesExt object from XMLStore.getPrefs(), rather than constructing one directly. For the root node, parent = null and name = "".

Method Detail

setUserRoot

public static void setUserRoot(PreferencesExt prefs)

Set the user root you get when you call Preferences.userRoot().

setSystemRoot

public static void setSystemRoot(PreferencesExt prefs)

Set the system root you get when you call Preferences.systemRoot().

isUserNode

public boolean isUserNode()

return true unless this is the systemRoot node

Overrides:

isUserNode in class AbstractPreferences

getBean

public Object getBean(String key,
             Object def)

Get the object that has the specified key. This returns the object itself, not a copy, so if you change the bean and call store.save(), any changes to the object will be saved, even without calling putBean(). If you want to change the object without saving the changes, you must make a copy of the object yourself.

Parameters:

key - get the object with this key.

def - the default value to be returned in the event that this preference node has no value associated with key.

Returns:

the value associated with key, or def if no value is associated with key.

Throws:

IllegalStateException - if this node (or an ancestor) has been removed with the AbstractPreferences.removeNode() method.

NullPointerException - if key is null. (A null default is permitted.)

putBean

public void putBean(String key,
           Object newValue)

Stores an object using simple bean properties. If the exact key and value are already in the storedDefaults (using equals() to test for equality), then it is not stored.

Parameters:

key - key with which the specified value is to be associated.

newValue - store this bean.

Throws:

NullPointerException - if key or value is null.

IllegalStateException - if this node (or an ancestor) has been removed with the AbstractPreferences.removeNode() method.

putBeanCollection

public void putBeanCollection(String key,
                     Collection newValue)

Stores a Collection of beans. The beans are stored using simple bean properties. The collection of beans must all be of the same class.

Parameters:

key - key with which the specified collection is to be associated.

newValue - store this collection of beans.

Throws:

NullPointerException - if key or value is null.

IllegalStateException - if this node (or an ancestor) has been removed with the AbstractPreferences.removeNode() method.

putBeanObject

public void putBeanObject(String key,
                 Object newValue)

Stores an object using XMLEncoder/XMLDecoder. Use this for arbitrary objects. If the exact key and value are already in the storedDefaults (using equals() to test for equality), then it is not stored.

Parameters:

key - key with which the specified value is to be associated.

newValue - store this bean object.

Throws:

NullPointerException - if key or value is null.

IllegalStateException - if this node (or an ancestor) has been removed with the AbstractPreferences.removeNode() method.

getList

public List getList(String key,
           List def)

Get an arrayList. This returns a copy of the stored list.

Specified by:

getList in interface PersistenceManager

Parameters:

key - key whose associated value is to be returned.

def - the value to be returned in the event that this preference node has no value associated with key.

Returns:

the value associated with key, or def if no value is associated with key.

putList

public void putList(String key,
           List newValue)

Stores the value with this key, if the exact key and value are not already in the storedDefaults (using equals() to test for equality). "Two lists are defined to be equal if they contain the same elements in the same order."

Specified by:

putList in interface PersistenceManager

Parameters:

key - key with which the specified value is to be associated.

newValue - value to be associated with the specified key.

childrenNamesSpi

protected String[] childrenNamesSpi()

Implements AbstractPreferences childrenNamesSpi() method. Find all children nodes of this node (or of identically named nodes in storedDefaults)

Specified by:

childrenNamesSpi in class AbstractPreferences

childrenNamesSpi

protected Collection childrenNamesSpi(String nodePath)

keysSpi

protected String[] keysSpi()
                    throws BackingStoreException

Specified by:

keysSpi in class AbstractPreferences

Throws:

BackingStoreException

keysSpi

protected Collection keysSpi(String nodePath)

childSpi

protected AbstractPreferences childSpi(String name)

Specified by:

childSpi in class AbstractPreferences

flushSpi

protected void flushSpi()
                 throws BackingStoreException

Empty, never used implementation of AbstractPreferences.flushSpi().

Specified by:

flushSpi in class AbstractPreferences

Throws:

BackingStoreException

getSpi

protected String getSpi(String keyName)

Specified by:

getSpi in class AbstractPreferences

putSpi

protected void putSpi(String key,
          String newValue)

Specified by:

putSpi in class AbstractPreferences

removeNodeSpi

protected void removeNodeSpi()
                      throws BackingStoreException

Specified by:

removeNodeSpi in class AbstractPreferences

Throws:

BackingStoreException

removeSpi

protected void removeSpi(String key)

removes key/value if exists, no effect on storedDefaults Remove the association (if any) for the specified key at this preference node. It is guaranteed that key is non-null. Also, it is guaranteed that this node has not been removed. (The implementor needn't check for either of these things.) This method is invoked with the lock on this node held.

Specified by:

removeSpi in class AbstractPreferences

syncSpi

protected void syncSpi()
                throws BackingStoreException

Specified by:

syncSpi in class AbstractPreferences

Throws:

BackingStoreException

putObject

public void putObject(String keyName,
             Object value)

Specified by:

putObject in interface PersistenceManager

getObject

public Object getObject(String key)

Specified by:

getObject in interface PersistenceManager