rs.baselib.prefs

Class AbstractPreferences

java.lang.Object

rs.baselib.prefs.AbstractPreferences

All Implemented Interfaces:

IPropertyChangeProvider, IPreferences

Direct Known Subclasses:

Preferences

public abstract class AbstractPreferences
extends Object
implements IPreferences, IPropertyChangeProvider

Abstract implementation of a preference node. All modifications are performed synchronously.

Author:

ralph

Field Summary

Fields inherited from interface rs.baselib.prefs.IPreferences

CHILD_ADDED, CHILD_REMOVED, VALUES_CLEARED

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
String	absolutePath() Returns this node's absolute path name.
protected void	addNode(AbstractPreferences child) Adds the given node.
void	addPropertyChangeListener(PropertyChangeListener listener) Add a change listener.
void	addPropertyChangeListener(String propertyName, PropertyChangeListener listener) Add a change listener.
String[]	childrenNames() Returns the names of the children of this node.
void	clear() Removes all of the properties (key-value associations) in this node.
protected abstract AbstractPreferences	createNode(AbstractPreferences parent, String name) Subclasses must implement this to return a new child node.
protected abstract Lock	createReadLock() Creates the appropriate read lock object.
protected abstract Lock	createWriteLock() Creates the appropriate write lock object.
protected boolean	firePropertyChange(PropertyChangeEvent event) Fires a change event.
protected boolean	firePropertyChange(String propertyName, Object oldValue, Object newValue) Fires an event if property changed.
void	flush() Forces any changes in the contents of this node and its descendants to the persistent store.
String	get(String key, String def) Returns the value associated with the specified key in this node.
boolean	getBoolean(String key, boolean def) Returns the boolean value represented by the String object associated with the specified key in this node.
byte[]	getByteArray(String key, byte[] def) Returns the byte[] value represented by the String object associated with the specified key in this node.
double	getDouble(String key, double def) Returns the double value represented by the String object associated with the specified key in this node.
float	getFloat(String key, float def) Returns the float value represented by the String object associated with the specified key in this node.
int	getInt(String key, int def) Returns the int value represented by the String object associated with the specified key in this node.
long	getLong(String key, long def) Returns the long value represented by the String object associated with the specified key in this node.
protected abstract AbstractPreferencesService	getPreferencesService() Returns the preferences service.
Lock	getReadLock() Returns the readLock.
protected AbstractPreferences	getRootNode() Returns the root node of this node.
Lock	getWriteLock() Returns the writeLock.
protected boolean	isAbsolute(String pathName) Returns true when the given pathname is absolute to root node of this node.
protected boolean	isRelative(String pathName) Returns true when the given pathname is relative to this node.
protected boolean	isRootNode() Returns true when this is a root node.
String[]	keys() Returns all of the keys that have an associated value in this node.
String	name() Returns this node's name, relative to its parent.
IPreferences	node(String pathName) Returns a named Preferences object (node), creating it and any of its ancestors if they do not already exist.
boolean	nodeExists(String pathName) Returns true if the named node exists.
IPreferences	parent() Returns the parent of this node, or null if this is the root.
void	put(String key, String value) Associates the specified value with the specified key in this node.
void	putBoolean(String key, boolean value) Associates a String object representing the specified boolean value with the specified key in this node.
void	putByteArray(String key, byte[] value) Associates a String object representing the specified byte[] with the specified key in this node.
void	putDouble(String key, double value) Associates a String object representing the specified double value with the specified key in this node.
void	putFloat(String key, float value) Associates a String object representing the specified float value with the specified key in this node.
void	putInt(String key, int value) Associates a String object representing the specified int value with the specified key in this node.
void	putLong(String key, long value) Associates a String object representing the specified long value with the specified key in this node.
protected void	readLock() Aquires a read lock.
protected void	readUnlock() Releases a read lock.
void	remove(String key) Removes the value associated with the specified key in this node, if any.
void	removeNode() Removes this node and all of its descendants, invalidating any properties contained in the removed nodes.
protected void	removeNode(AbstractPreferences child) Removes the given node.
void	removePropertyChangeListener(PropertyChangeListener listener) Remove a change listener.
void	removePropertyChangeListener(String propertyName, PropertyChangeListener listener) Remove a change listener.
void	sync() Ensures that future reads from this node and its descendants reflect any changes that were committed to the persistent store (from any VM) prior to the sync invocation.
protected void	writeLock() Aquires a write lock.
protected void	writeUnlock() Releases a write lock.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractPreferences

public AbstractPreferences()

Constructor. Creates a root node.

AbstractPreferences

public AbstractPreferences(AbstractPreferences parent,
                   String name)

Constructor.

Parameters:

parent - the parent of this node

Method Detail

createReadLock

protected abstract Lock createReadLock()

Creates the appropriate read lock object.

Returns:

the read lock object

createWriteLock

protected abstract Lock createWriteLock()

Creates the appropriate write lock object.

Returns:

the write lock object

getReadLock

public Lock getReadLock()

Returns the readLock.

Returns:

the readLock

readLock

protected void readLock()

Aquires a read lock.

readUnlock

protected void readUnlock()

Releases a read lock.

getWriteLock

public Lock getWriteLock()

Returns the writeLock.

Returns:

the writeLock

writeLock

protected void writeLock()

Aquires a write lock.

writeUnlock

protected void writeUnlock()

Releases a write lock.

createNode

protected abstract AbstractPreferences createNode(AbstractPreferences parent,
                             String name)

Subclasses must implement this to return a new child node.

Parameters:

parent - the parent to be used

name - the name to be used

Returns:

the new node

addNode

protected void addNode(AbstractPreferences child)

Adds the given node. The scheduling policy will define whether this task is executed immediately or performed by a background task (which requires a flush() call to access the node later).

Parameters:

child - child to be added

removeNode

protected void removeNode(AbstractPreferences child)

Removes the given node. The scheduling policy will define whether this task is executed immediately or performed by a background task (which requires a flush() to see the result).

Parameters:

child - child to be removed

put

public void put(String key,
       String value)

Associates the specified value with the specified key in this node.

Specified by:

put in interface IPreferences

Parameters:

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

value - value to be associated with the specified key.

get

public String get(String key,
         String def)

Returns the value associated with the specified key in this node. Returns the specified default if there is no value associated with the key, or the backing store is inaccessible.

Specified by:

get in interface IPreferences

Parameters:

key - key whose associated value is to be returned.

def - the value to be returned in the event that this node has no value associated with key or the backing store is inaccessible.

Returns:

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

remove

public void remove(String key)

Removes the value associated with the specified key in this node, if any.

Specified by:

remove in interface IPreferences

Parameters:

key - key whose mapping is to be removed from this node.

See Also:

IPreferences.get(String,String)

clear

public void clear()
           throws BackingStoreException

Removes all of the properties (key-value associations) in this node. This call has no effect on any descendants of this node.

Specified by:

clear in interface IPreferences

Throws:

BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

See Also:

IPreferences.remove(String)

putInt

public void putInt(String key,
          int value)

Associates a String object representing the specified int value with the specified key in this node. The associated string is the one that would be returned if the int value were passed to Integer.toString(int). This method is intended for use in conjunction with IPreferences.getInt(java.lang.String, int) method.

Implementor's note: it is not necessary that the property value be represented by a String object in the backing store. If the backing store supports integer values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as an int (with getInt or a String (with get) type.

Specified by:

putInt in interface IPreferences

Parameters:

key - key with which the string form of value is to be associated.

value - value whose string form is to be associated with key.

See Also:

IPreferences.getInt(String,int)

getInt

public int getInt(String key,
         int def)

Returns the int value represented by the String object associated with the specified key in this node. The String object is converted to an int as by Integer.parseInt(String). Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if Integer.parseInt(String) would throw a NumberFormatException if the associated value were passed. This method is intended for use in conjunction with the IPreferences.putInt(java.lang.String, int) method.

Specified by:

getInt in interface IPreferences

Parameters:

key - key whose associated value is to be returned as an int.

def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as an int or the backing store is inaccessible.

Returns:

the int value represented by the String object associated with key in this node, or def if the associated value does not exist or cannot be interpreted as an int type.

See Also:

IPreferences.putInt(String,int), IPreferences.get(String,String)

putLong

public void putLong(String key,
           long value)

Associates a String object representing the specified long value with the specified key in this node. The associated String object is the one that would be returned if the long value were passed to Long.toString(long). This method is intended for use in conjunction with the IPreferences.getLong(java.lang.String, long) method.

Implementor's note: it is not necessary that the value be represented by a String type in the backing store. If the backing store supports long values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as a long (with getLong or a String (with get) type.

Specified by:

putLong in interface IPreferences

Parameters:

key - key with which the string form of value is to be associated.

value - value whose string form is to be associated with key.

See Also:

IPreferences.getLong(String,long)

getLong

public long getLong(String key,
           long def)

Returns the long value represented by the String object associated with the specified key in this node. The String object is converted to a long as by Long.parseLong(String). Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if Long.parseLong(String) would throw a NumberFormatException if the associated value were passed. This method is intended for use in conjunction with the IPreferences.putLong(java.lang.String, long) method.

Specified by:

getLong in interface IPreferences

Parameters:

key - key whose associated value is to be returned as a long value.

def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as a long type or the backing store is inaccessible.

Returns:

the long value represented by the String object associated with key in this node, or def if the associated value does not exist or cannot be interpreted as a long type.

See Also:

IPreferences.putLong(String,long), IPreferences.get(String,String)

putBoolean

public void putBoolean(String key,
              boolean value)

Associates a String object representing the specified boolean value with the specified key in this node. The associated string is "true" if the value is true, and "false" if it is false. This method is intended for use in conjunction with the IPreferences.getBoolean(java.lang.String, boolean) method.

Implementor's note: it is not necessary that the value be represented by a string in the backing store. If the backing store supports boolean values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as a boolean (with getBoolean) or a String (with get) type.

Specified by:

putBoolean in interface IPreferences

Parameters:

key - key with which the string form of value is to be associated.

value - value whose string form is to be associated with key.

See Also:

IPreferences.getBoolean(String,boolean), IPreferences.get(String,String)

getBoolean

public boolean getBoolean(String key,
                 boolean def)

Returns the boolean value represented by the String object associated with the specified key in this node. Valid strings are "true", which represents true, and "false", which represents false. Case is ignored, so, for example, "TRUE" and "False" are also valid. This method is intended for use in conjunction with the IPreferences.putBoolean(java.lang.String, boolean) method.

Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if the associated value is something other than "true" or "false", ignoring case.

Specified by:

getBoolean in interface IPreferences

Parameters:

key - key whose associated value is to be returned as a boolean.

def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as a boolean or the backing store is inaccessible.

Returns:

the boolean value represented by the String object associated with key in this node, or null if the associated value does not exist or cannot be interpreted as a boolean.

See Also:

IPreferences.get(String,String), IPreferences.putBoolean(String,boolean)

putFloat

public void putFloat(String key,
            float value)

Associates a String object representing the specified float value with the specified key in this node. The associated String object is the one that would be returned if the float value were passed to Float.toString(float). This method is intended for use in conjunction with the IPreferences.getFloat(java.lang.String, float) method.

Implementor's note: it is not necessary that the value be represented by a string in the backing store. If the backing store supports float values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as a float (with getFloat) or a String (with get) type.

Specified by:

putFloat in interface IPreferences

Parameters:

key - key with which the string form of value is to be associated.

value - value whose string form is to be associated with key.

See Also:

IPreferences.getFloat(String,float)

getFloat

public float getFloat(String key,
             float def)

Returns the float value represented by the String object associated with the specified key in this node. The String object is converted to a float value as by Float.parseFloat(String). Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if Float.parseFloat(String) would throw a NumberFormatException if the associated value were passed. This method is intended for use in conjunction with the IPreferences.putFloat(java.lang.String, float) method.

Specified by:

getFloat in interface IPreferences

Parameters:

key - key whose associated value is to be returned as a float value.

def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as a float type or the backing store is inaccessible.

Returns:

the float value represented by the string associated with key in this node, or def if the associated value does not exist or cannot be interpreted as a float type.

See Also:

IPreferences.putFloat(String,float), IPreferences.get(String,String)

putDouble

public void putDouble(String key,
             double value)

Associates a String object representing the specified double value with the specified key in this node. The associated String object is the one that would be returned if the double value were passed to Double.toString(double). This method is intended for use in conjunction with the IPreferences.getDouble(java.lang.String, double) method

Implementor's note: it is not necessary that the value be represented by a string in the backing store. If the backing store supports double values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as a double (with getDouble) or a String (with get) type.

Specified by:

putDouble in interface IPreferences

Parameters:

key - key with which the string form of value is to be associated.

value - value whose string form is to be associated with key.

See Also:

IPreferences.getDouble(String,double)

getDouble

public double getDouble(String key,
               double def)

Returns the double value represented by the String object associated with the specified key in this node. The String object is converted to a double value as by Double.parseDouble(String). Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if Double.parseDouble(String) would throw a NumberFormatException if the associated value were passed. This method is intended for use in conjunction with the IPreferences.putDouble(java.lang.String, double) method.

Specified by:

getDouble in interface IPreferences

Parameters:

key - key whose associated value is to be returned as a double value.

def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as a double type or the backing store is inaccessible.

Returns:

the double value represented by the String object associated with key in this node, or def if the associated value does not exist or cannot be interpreted as a double type.

See Also:

IPreferences.putDouble(String,double), IPreferences.get(String,String)

putByteArray

public void putByteArray(String key,
                byte[] value)

Associates a String object representing the specified byte[] with the specified key in this node. The associated String object the Base64 encoding of the byte[], as defined in RFC 2045 , Section 6.8, with one minor change: the string will consist solely of characters from the Base64 Alphabet ; it will not contain any newline characters. This method is intended for use in conjunction with the IPreferences.getByteArray(java.lang.String, byte[]) method.

Implementor's note: it is not necessary that the value be represented by a String type in the backing store. If the backing store supports byte[] values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as an a byte[] object (with getByteArray) or a String object (with get).

Specified by:

putByteArray in interface IPreferences

Parameters:

key - key with which the string form of value is to be associated.

value - value whose string form is to be associated with key.

See Also:

IPreferences.getByteArray(String,byte[]), IPreferences.get(String,String)

getByteArray

public byte[] getByteArray(String key,
                  byte[] def)

Returns the byte[] value represented by the String object associated with the specified key in this node. Valid String objects are Base64 encoded binary data, as defined in RFC 2045 , Section 6.8, with one minor change: the string must consist solely of characters from the Base64 Alphabet ; no newline characters or extraneous characters are permitted. This method is intended for use in conjunction with the IPreferences.putByteArray(java.lang.String, byte[]) method.

Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if the associated value is not a valid Base64 encoded byte array (as defined above).

Specified by:

getByteArray in interface IPreferences

Parameters:

key - key whose associated value is to be returned as a byte[] object.

def - the value to be returned in the event that this node has no value associated with key or the associated value cannot be interpreted as a byte[] type, or the backing store is inaccessible.

Returns:

the byte[] value represented by the String object associated with key in this node, or def if the associated value does not exist or cannot be interpreted as a byte[].

See Also:

IPreferences.get(String,String), IPreferences.putByteArray(String,byte[])

keys

public String[] keys()
              throws BackingStoreException

Returns all of the keys that have an associated value in this node. (The returned array will be of size zero if this node has no preferences and not null!)

Specified by:

keys in interface IPreferences

Returns:

an array of the keys that have an associated value in this node.

Throws:

BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

childrenNames

public String[] childrenNames()
                       throws BackingStoreException

Returns the names of the children of this node. (The returned array will be of size zero if this node has no children and not null!)

Specified by:

childrenNames in interface IPreferences

Returns:

the names of the children of this node.

Throws:

BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

parent

public IPreferences parent()

Returns the parent of this node, or null if this is the root.

Specified by:

parent in interface IPreferences

Returns:

the parent of this node.

isRelative

protected boolean isRelative(String pathName)

Returns true when the given pathname is relative to this node. This means the path does not start with a slash ('/').

Parameters:

pathName - name to be checked

Returns:

true when path name is relative to this node

isAbsolute

protected boolean isAbsolute(String pathName)

Returns true when the given pathname is absolute to root node of this node. This means the path starts with a slash ('/').

Parameters:

pathName - name to be checked

Returns:

true when path name is absolute to root node of this node

isRootNode

protected boolean isRootNode()

Returns true when this is a root node.

Returns:

true when this is a root node

getRootNode

protected AbstractPreferences getRootNode()

Returns the root node of this node.

Returns:

root node

node

public IPreferences node(String pathName)

Returns a named Preferences object (node), creating it and any of its ancestors if they do not already exist. Accepts a relative or absolute pathname. Absolute pathnames (which begin with '/') are interpreted relative to the root of this node. Relative pathnames (which begin with any character other than '/') are interpreted relative to this node itself. The empty string ("") is a valid relative pathname, referring to this node itself.

If the returned node did not exist prior to this call, this node and any ancestors that were created by this call are not guaranteed to become persistent until the flush method is called on the returned node (or one of its descendants).

Specified by:

node in interface IPreferences

Parameters:

pathName - the path name of the Preferences object to return.

Returns:

the specified Preferences object.

See Also:

IPreferences.flush()

nodeExists

public boolean nodeExists(String pathName)
                   throws BackingStoreException

Returns true if the named node exists. Accepts a relative or absolute pathname. Absolute pathnames (which begin with '/') are interpreted relative to the root of this node. Relative pathnames (which begin with any character other than '/') are interpreted relative to this node itself. The pathname "" is valid, and refers to this node itself.

If this node (or an ancestor) has already been removed with the IPreferences.removeNode() method, it is legal to invoke this method, but only with the pathname ""; the invocation will return false. Thus, the idiom p.nodeExists("") may be used to test whether p has been removed.

Specified by:

nodeExists in interface IPreferences

Parameters:

pathName - the path name of the node whose existence is to be checked.

Returns:

true if the specified node exists.

Throws:

BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

removeNode

public void removeNode()
                throws BackingStoreException

Removes this node and all of its descendants, invalidating any properties contained in the removed nodes. Once a node has been removed, attempting any method other than name(),absolutePath() or nodeExists("") on the corresponding Preferences instance will fail with an IllegalStateException. (The methods defined on Object can still be invoked on a node after it has been removed; they will not throw IllegalStateException.)

The removal is not guaranteed to be persistent until the flush method is called on the parent of this node.

Specified by:

removeNode in interface IPreferences

Throws:

BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

See Also:

IPreferences.flush()

name

public String name()

Returns this node's name, relative to its parent.

Specified by:

name in interface IPreferences

Returns:

this node's name, relative to its parent.

absolutePath

public String absolutePath()

Returns this node's absolute path name. Note that:

• Root node - The path name of the root node is "/".
• Slash at end - Path names other than that of the root node may not end in slash ('/').
• Unusual names -"." and ".." have no special significance in path names.
• Illegal names - The only illegal path names are those that contain multiple consecutive slashes, or that end in slash and are not the root.

Specified by:

absolutePath in interface IPreferences

Returns:

this node's absolute path name.

getPreferencesService

protected abstract AbstractPreferencesService getPreferencesService()

Returns the preferences service.

Returns:

the preferences service

flush

public void flush()
           throws BackingStoreException

Forces any changes in the contents of this node and its descendants to the persistent store.

Once this method returns successfully, it is safe to assume that all changes made in the subtree rooted at this node prior to the method invocation have become permanent.

Implementations are free to flush changes into the persistent store at any time. They do not need to wait for this method to be called.

When a flush occurs on a newly created node, it is made persistent, as are any ancestors (and descendants) that have yet to be made persistent. Note however that any properties value changes in ancestors are not guaranteed to be made persistent.

Specified by:

flush in interface IPreferences

Throws:

BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

See Also:

IPreferences.sync()

sync

public void sync()
          throws BackingStoreException

Ensures that future reads from this node and its descendants reflect any changes that were committed to the persistent store (from any VM) prior to the sync invocation. As a side-effect, forces any changes in the contents of this node and its descendants to the persistent store, as if the flush method had been invoked on this node.

Specified by:

sync in interface IPreferences

Throws:

BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

See Also:

IPreferences.flush()

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Add a change listener.

Specified by:

addPropertyChangeListener in interface IPropertyChangeProvider

Parameters:

listener - the listener to be added

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Remove a change listener.

Specified by:

removePropertyChangeListener in interface IPropertyChangeProvider

Parameters:

listener - the listener to be removed

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                             PropertyChangeListener listener)

Add a change listener.

Specified by:

addPropertyChangeListener in interface IPropertyChangeProvider

Parameters:

propertyName - the property name the listener will be registered for

listener - the listener to be added

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                PropertyChangeListener listener)

Remove a change listener.

Specified by:

removePropertyChangeListener in interface IPropertyChangeProvider

Parameters:

propertyName - the property name the listener will not listen for anymore

listener - the listener to be removed

firePropertyChange

protected boolean firePropertyChange(String propertyName,
                         Object oldValue,
                         Object newValue)

Fires an event if property changed.

Parameters:

propertyName - name of property

oldValue - old value

newValue - new value

Returns:

true when the event was fired (because values were not equal)

firePropertyChange

protected boolean firePropertyChange(PropertyChangeEvent event)

Fires a change event.

Parameters:

event - event to be fired

Returns:

true when the event was fired (because values were not equal)