org.tentackle.persist

Class DbPreferences

java.lang.Object

java.util.prefs.Preferences

org.tentackle.persist.DbPreferences

All Implemented Interfaces:

PersistedPreferences

public class DbPreferences
extends Preferences
implements PersistedPreferences

Database backend for the Preferences API.
Tentackle preferences are stored in a database rather than a file(unix) or registry(windows). The persistent classes are:

1. DbPreferencesNode: the nodes representing the preferences hierarchy.
2. DbPreferencesKey: the key/value pairs corresponding to the nodes.

Unlike the default JDK-backends, tentackle preferences are synchronized between JVMs, i.e. a (flushed) change in one JVM will show up in all other JVMs. As a consequence, NodeChangeEvents and PreferenceChangeEvents work across JVM-boundaries. The synchronization is based on the ModificationTracker by use of the tableSerial. Notice that events in the local JVM are enqueued at the time of change (i.e. put(), remove(), node() or removeNode()) while other JVMs will become aware of the changes only after the changes are flush()ed to persistent storage. The underlying mechanism works as follows:

• a key is modified: the corresponding key is updated to the db and all other JVMs will identify this by its tableSerial. If the corresponding key is already loaded in other JVMs, it is reloaded from the db and the optional PreferenceChangeListeners invoked for its node.
• a key is added or removed: the key is deleted from or added to the db and its node is updated allowing other JVMs to detect the node by its tableSerial and to update its keys. If PreferenceChangeListeners are registered, an Event will be triggered.
• a node is added or removed: the node is inserted into or removed from the db and its parent is updated to allow detection by its tableserial. NodeChangeEvents are triggered accordingly. The fact that "some" nodes have been deleted is detected by gaps in the retrieved tableSerials.

Compared to AbstractPreferences (which we can not simply extend due to various design issues), the DbPreferences differ slightly in the following aspects:

• PreferenceChangeEvents are only triggered if there really is a change. Thus, invoking put() without an effective change will *not* trigger an event.
• there is only little difference between sync() and flush() if autoSync=true, because a sync is automatically performed "in background" by the ModificationThread. If autoSync=false, sync() has to be invoked explicitly to reflect changes made by other JVMs. AutoSync is the recommended mode for most applications.
• nodeExists() only returns true, if the node is persistent (regardless whether we accessed it yet or created by another JVM). However, the semantics of nodeExists("") remain, i.e. "return true if not deleted". Thus, nodeExists("") == false just means that the node has been removed by removeNode(), either by the current or another JVM. However, true does *NOT* mean, that the node exists, i.e. is persistent in the database. It just means, that it has not been removed.

Author:

harald

Field Summary

Fields inherited from class java.util.prefs.Preferences

MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH

Constructor Summary

Constructors

Constructor and Description
DbPreferences(boolean userMode) Special constructor for roots (both user and system).
DbPreferences(DbPreferences parent, DbPreferencesNode node) Constructs DbPreferences from a DbPreferencesNode.
DbPreferences(DbPreferences parent, String name) Creates a preference node with the specified parent and the specified name relative to its parent.

Method Summary

Modifier and Type	Method and Description
String	absolutePath()
void	addNodeChangeListener(NodeChangeListener ncl) Registers the specified listener to receive node change events for this node.
void	addPreferenceChangeListener(PreferenceChangeListener pcl) Registers the specified listener to receive preference change events for this preference node.
boolean	areNodeListenersRegistered()
boolean	arePreferenceListenersRegistered() Returns whether reference listeners are registered.
String[]	childrenNames()
void	clear()
void	exportNode(OutputStream os)
void	exportSubtree(OutputStream os)
void	flush()
String	get(String key, String def)
String	getAbsolutePath() Gets the absolute path.
boolean	getBoolean(String key, boolean def)
byte[]	getByteArray(String key, byte[] def)
Set<Long>	getChildIds() Gets the child IDs.
Map<String,DbPreferences>	getChildPrefs() Gets the child preferences.
double	getDouble(String key, double def)
float	getFloat(String key, float def)
int	getInt(String key, int def)
Map<String,DbPreferencesKey>	getKeys() Gets the persistence key/value pairs.
long	getLong(String key, long def)
String	getName() Gets the name.
DbPreferencesNode	getNode() Gets the persistence node.
DbPreferences	getParent() Gets the persistence parent.
DbPreferences	getRoot() Gets the root node.
boolean	isUserMode() Returns whether user-scope or system.
boolean	isUserNode()
String[]	keys()
String	name()
DbPreferences	node(String path)
boolean	nodeExists(String pathName)
DbPreferences	parent()
void	put(String key, String value)
void	putBoolean(String key, boolean value)
void	putByteArray(String key, byte[] value)
void	putDouble(String key, double value)
void	putFloat(String key, float value)
void	putInt(String key, int value)
void	putLong(String key, long value)
void	remove(String key)
void	removeNode()
void	removeNodeChangeListener(NodeChangeListener ncl)
void	removePreferenceChangeListener(PreferenceChangeListener pcl)
void	sync()
String	toString() Returns the string represenation of this node.
protected void	updateParentNode(DbPreferencesNode node) Updates the serial and tableserial of a parent node.

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 org.tentackle.prefs.PersistedPreferences

systemNodeForPackage, systemRoot, userNodeForPackage, userRoot

Constructor Detail

DbPreferences

public DbPreferences(DbPreferences parent,
                     String name)

Creates a preference node with the specified parent and the specified name relative to its parent. Don't use this constructor for root-nodes!

Parameters:

parent - the parent of this preference node

name - the name of this preference node, relative to its parent

Throws:

IllegalArgumentException - if name contains a slash ('/'), or parent is null and name isn't "".

DbPreferences

public DbPreferences(boolean userMode)

Special constructor for roots (both user and system). This constructor will only be called twice by the static intializer. Package scope!

Parameters:

userMode - true if user mode, else system mode

DbPreferences

public DbPreferences(DbPreferences parent,
                     DbPreferencesNode node)
              throws BackingStoreException

Constructs DbPreferences from a DbPreferencesNode. Only used from loadNodes(). Package scope!

Parameters:

parent - the parent preferences

node - the node

Throws:

BackingStoreException - if creation failed

Method Detail

getNode

public DbPreferencesNode getNode()

Gets the persistence node.

Returns:

the node

getParent

public DbPreferences getParent()

Gets the persistence parent.

Returns:

the parent

getName

public String getName()

Gets the name.

Returns:

the name

getAbsolutePath

public String getAbsolutePath()

Gets the absolute path.

Returns:

the path

isUserMode

public boolean isUserMode()

Returns whether user-scope or system.

Returns:

true if user, else system

getRoot

public DbPreferences getRoot()

Gets the root node.

Returns:

the root node

getChildPrefs

public Map<String,DbPreferences> getChildPrefs()

Gets the child preferences.

Returns:

the child preferences

getChildIds

public Set<Long> getChildIds()

Gets the child IDs.

Returns:

the child IDs

getKeys

public Map<String,DbPreferencesKey> getKeys()

Gets the persistence key/value pairs.

Returns:

the keys

updateParentNode

protected void updateParentNode(DbPreferencesNode node)
                         throws BackingStoreException

Updates the serial and tableserial of a parent node. The method is invoked whenever a key or child node is added or removed.

Parameters:

node - the parent node to update

Throws:

BackingStoreException - if update failed

areNodeListenersRegistered

public boolean areNodeListenersRegistered()

Returns:

true if any node listeners are registered on this node

arePreferenceListenersRegistered

public boolean arePreferenceListenersRegistered()

Returns whether reference listeners are registered.

Returns:

true if any preferences listeners are registered on this node

toString

public String toString()

Returns the string represenation of this node.

• if node is deleted: "<absolutePath> [deleted]"
• user node: "<user>:<absolutePath>"
• system node: "<system>:<absolutePath>"

Specified by:

toString in class Preferences

Returns:

the string

name

public String name()

Specified by:

name in interface PersistedPreferences

Specified by:

name in class Preferences

absolutePath

public String absolutePath()

Specified by:

absolutePath in interface PersistedPreferences

Specified by:

absolutePath in class Preferences

isUserNode

public boolean isUserNode()

Specified by:

isUserNode in interface PersistedPreferences

Specified by:

isUserNode in class Preferences

put

public void put(String key,
                String value)

Specified by:

put in interface PersistedPreferences

Specified by:

put in class Preferences

get

public String get(String key,
                  String def)

Specified by:

get in interface PersistedPreferences

Specified by:

get in class Preferences

remove

public void remove(String key)

Specified by:

remove in interface PersistedPreferences

Specified by:

remove in class Preferences

clear

public void clear()
           throws BackingStoreException

Specified by:

clear in interface PersistedPreferences

Specified by:

clear in class Preferences

Throws:

BackingStoreException

sync

public void sync()
          throws BackingStoreException

Specified by:

sync in interface PersistedPreferences

Specified by:

sync in class Preferences

Throws:

BackingStoreException

flush

public void flush()
           throws BackingStoreException

Specified by:

flush in interface PersistedPreferences

Specified by:

flush in class Preferences

Throws:

BackingStoreException

putInt

public void putInt(String key,
                   int value)

Specified by:

putInt in interface PersistedPreferences

Specified by:

putInt in class Preferences

getInt

public int getInt(String key,
                  int def)

Specified by:

getInt in interface PersistedPreferences

Specified by:

getInt in class Preferences

putLong

public void putLong(String key,
                    long value)

Specified by:

putLong in interface PersistedPreferences

Specified by:

putLong in class Preferences

getLong

public long getLong(String key,
                    long def)

Specified by:

getLong in interface PersistedPreferences

Specified by:

getLong in class Preferences

putBoolean

public void putBoolean(String key,
                       boolean value)

Specified by:

putBoolean in interface PersistedPreferences

Specified by:

putBoolean in class Preferences

getBoolean

public boolean getBoolean(String key,
                          boolean def)

Specified by:

getBoolean in interface PersistedPreferences

Specified by:

getBoolean in class Preferences

putFloat

public void putFloat(String key,
                     float value)

Specified by:

putFloat in interface PersistedPreferences

Specified by:

putFloat in class Preferences

getFloat

public float getFloat(String key,
                      float def)

Specified by:

getFloat in interface PersistedPreferences

Specified by:

getFloat in class Preferences

putDouble

public void putDouble(String key,
                      double value)

Specified by:

putDouble in interface PersistedPreferences

Specified by:

putDouble in class Preferences

getDouble

public double getDouble(String key,
                        double def)

Specified by:

getDouble in interface PersistedPreferences

Specified by:

getDouble in class Preferences

putByteArray

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

Specified by:

putByteArray in interface PersistedPreferences

Specified by:

putByteArray in class Preferences

getByteArray

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

Specified by:

getByteArray in interface PersistedPreferences

Specified by:

getByteArray in class Preferences

keys

public String[] keys()
              throws BackingStoreException

Specified by:

keys in interface PersistedPreferences

Specified by:

keys in class Preferences

Throws:

BackingStoreException

childrenNames

public String[] childrenNames()
                       throws BackingStoreException

Specified by:

childrenNames in interface PersistedPreferences

Specified by:

childrenNames in class Preferences

Throws:

BackingStoreException

parent

public DbPreferences parent()

Specified by:

parent in interface PersistedPreferences

Specified by:

parent in class Preferences

node

public DbPreferences node(String path)

Specified by:

node in interface PersistedPreferences

Specified by:

node in class Preferences

nodeExists

public boolean nodeExists(String pathName)
                   throws BackingStoreException

This implementation differs from AbstractPreferences because it checks the persistent storage rather than the cache, i.e. a node only created in memory but not yet written to persistent storage is considered non-existant. As a consequence it is possible to decide whether a system-preference has been overridden by a user-preference. (see CompositePreferences). Notice that "" will return true even if not written to disk to denote "not deleted" (which does not mean "saved" -- a little confusing)

Specified by:

nodeExists in interface PersistedPreferences

Specified by:

nodeExists in class Preferences

Throws:

BackingStoreException

removeNode

public void removeNode()
                throws BackingStoreException

Specified by:

removeNode in interface PersistedPreferences

Specified by:

removeNode in class Preferences

Throws:

BackingStoreException

addPreferenceChangeListener

public void addPreferenceChangeListener(PreferenceChangeListener pcl)

Registers the specified listener to receive preference change events for this preference node. A preference change event is generated when a preference is added to this node, removed from this node, or when the value associated with a preference is changed. (Preference change events are not generated by the removeNode() method, which generates a node change event. Preference change events are generated by the clear method.)

Events are generated even for changes made outside this JVM. For the local JVM events are generated before the changes have been made persistent. For all other JVMs events are generated *after* flush()/sync().

Specified by:

addPreferenceChangeListener in interface PersistedPreferences

Specified by:

addPreferenceChangeListener in class Preferences

Parameters:

pcl - The preference change listener to add.

Throws:

NullPointerException - if pcl is null.

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

See Also:

removePreferenceChangeListener(PreferenceChangeListener), addNodeChangeListener(NodeChangeListener)

removePreferenceChangeListener

public void removePreferenceChangeListener(PreferenceChangeListener pcl)

Specified by:

removePreferenceChangeListener in interface PersistedPreferences

Specified by:

removePreferenceChangeListener in class Preferences

addNodeChangeListener

public void addNodeChangeListener(NodeChangeListener ncl)

Registers the specified listener to receive node change events for this node. A node change event is generated when a child node is added to or removed from this node. (A single removeNode() invocation results in multiple node change events, one for every node in the subtree rooted at the removed node.)

Events are generated even for changes made outside this JVM. For the local JVM events are generated before the changes have been made persistent. For all other JVMs events are generated *after* flush()/sync().

Node creation will always generate an even for the local JVM. Other JVMs get that event only in case the node is created on disk (and not updated in case another JVM already created that node).

Specified by:

addNodeChangeListener in interface PersistedPreferences

Specified by:

addNodeChangeListener in class Preferences

Parameters:

ncl - The NodeChangeListener to add.

Throws:

NullPointerException - if ncl is null.

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

See Also:

removeNodeChangeListener(NodeChangeListener), addPreferenceChangeListener(PreferenceChangeListener)

removeNodeChangeListener

public void removeNodeChangeListener(NodeChangeListener ncl)

Specified by:

removeNodeChangeListener in interface PersistedPreferences

Specified by:

removeNodeChangeListener in class Preferences

exportNode

public void exportNode(OutputStream os)
                throws IOException,
                       BackingStoreException

Specified by:

exportNode in interface PersistedPreferences

Specified by:

exportNode in class Preferences

Throws:

IOException

BackingStoreException

exportSubtree

public void exportSubtree(OutputStream os)
                   throws IOException,
                          BackingStoreException

Specified by:

exportSubtree in interface PersistedPreferences

Specified by:

exportSubtree in class Preferences

Throws:

IOException

BackingStoreException