DbPreferences (Tentackle 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

org.tentackle.db
Class DbPreferences

java.lang.Object
  java.util.prefs.Preferences
      org.tentackle.db.DbPreferences

public class DbPreferences
extends Preferences
extends Preferences

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:

DbPreferencesNode: the nodes representing the preferences hierarchy.
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 ModificationThread 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 (see ModificationCounter for details).

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 syncObject() and flush() if autoSync=true, because a syncObject is automatically performed "in background" by the ModificationThread. If autoSync=false, syncObject() 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
`static String`	`TX_FLUSH` transaction name for flush
`static String`	`TX_REMOVE_NODE` transaction name for remove node

Fields inherited from class java.util.prefs.Preferences
`MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH`

Constructor Summary
`protected`	`DbPreferences(boolean userMode)` Special constructor for roots (both user and system).
`protected`	`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
`String`	`absolutePath()` Returns this preference node's absolute path name.
`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.
`String[]`	`childrenNames()` Returns the names of the children of this preference node, relative to this node.
`void`	`clear()` Removes all of the preferences (key-value associations) in this preference node.
`static void`	`expireKeys(Db db, long maxSerial)` Expire the preferences keys. Invoked from the ModificationThread (registered in DbPreferencesKey)
`static void`	`expireNodes(Db db, long maxSerial)` Expires the preferences nodes. Invoked from ModificationThread (registered in DbPreferencesNode)
`void`	`exportNode(OutputStream os)` Emits on the specified output stream an XML document representing all of the preferences contained in this node (but not its descendants).
`void`	`exportSubtree(OutputStream os)` Emits an XML document representing all of the preferences contained in this node and all of its descendants.
`void`	`flush()` Forces any changes in the contents of this preference node and its descendants to the persistent store.
`String`	`get(String key, String def)` Returns the value associated with the specified key in this preference node.
`boolean`	`getBoolean(String key, boolean def)` Returns the boolean value represented by the string associated with the specified key in this preference node.
`byte[]`	`getByteArray(String key, byte[] def)` Returns the byte array value represented by the string associated with the specified key in this preference node.
`static Db`	`getDb()` Gets the database connection.
`double`	`getDouble(String key, double def)` Returns the double value represented by the string associated with the specified key in this preference node.
`float`	`getFloat(String key, float def)` Returns the float value represented by the string associated with the specified key in this preference node.
`int`	`getInt(String key, int def)` Returns the int value represented by the string associated with the specified key in this preference node.
`long`	`getLong(String key, long def)` Returns the long value represented by the string associated with the specified key in this preference node.
`static void`	`importPreferences(InputStream is)` Imports all of the preferences represented by the XML document as in Preferences.
`static void`	`initialize(Db prefDb, boolean sync)` initialize the preferences.
`static boolean`	`isAutoSync()` Determines whether the preferences are automatically sync'd to the database.
`boolean`	`isReadOnly()` Determines whether preferences are read only.
`boolean`	`isUserNode()` Returns `true` if this preference node is in the user preference tree, `false` if it's in the system preference tree.
`String[]`	`keys()` Returns all of the keys that have an associated value in this preference node.
`String`	`name()` Returns this preference node's name, relative to its parent.
`Preferences`	`node(String path)` Returns the named preference node in the same tree as this node, creating it and any of its ancestors if they do not already exist.
`boolean`	`nodeExists(String pathName)` Returns true if the named preference node exists in the same tree as this node.
`Preferences`	`parent()` Returns the parent of this preference node, or `null` if this is the root.
`void`	`put(String key, String value)` Associates the specified value with the specified key in this preference node.
`void`	`putBoolean(String key, boolean value)` Associates a string representing the specified boolean value with the specified key in this preference node.
`void`	`putByteArray(String key, byte[] value)` Associates a string representing the specified byte array with the specified key in this preference node.
`void`	`putDouble(String key, double value)` Associates a string representing the specified double value with the specified key in this preference node.
`void`	`putFloat(String key, float value)` Associates a string representing the specified float value with the specified key in this preference node.
`void`	`putInt(String key, int value)` Associates a string representing the specified int value with the specified key in this preference node.
`void`	`putLong(String key, long value)` Associates a string representing the specified long value with the specified key in this preference node.
`void`	`remove(String key)` Removes the value associated with the specified key in this preference node, if any.
`void`	`removeNode()` Removes this preference node and all of its descendants, invalidating any preferences contained in the removed nodes.
`void`	`removeNodeChangeListener(NodeChangeListener ncl)` Removes the specified `NodeChangeListener`, so it no longer receives change events.
`void`	`removePreferenceChangeListener(PreferenceChangeListener pcl)` Removes the specified preference change listener, so it no longer receives preference change events.
`static void`	`setReadOnly(boolean readOnly)` Sets the preferences to read only globally.
`void`	`sync()` Ensures that future reads from this preference node and its descendants reflect any changes that were committed to the persistent store (from any VM) prior to the `sync` invocation.
`String`	`toString()` Returns a string representation of this preferences node. if node is deleted: "<absolutePath> [deleted]" user node: "<user>:<absolutePath>" system node: "<system>:<absolutePath>"
`protected void`	`updateParentNode(DbPreferencesNode node)` Updates the serial and tableserial of a parent node.

Methods inherited from class java.util.prefs.Preferences
`systemNodeForPackage, systemRoot, userNodeForPackage, userRoot`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

TX_FLUSH

public static final String TX_FLUSH

transaction name for flush

See Also:: Constant Field Values

TX_REMOVE_NODE

public static final String TX_REMOVE_NODE

transaction name for remove node

See Also:: Constant Field Values

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

protected 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

protected 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

Method Detail

setReadOnly

public static void setReadOnly(boolean readOnly)

Sets the preferences to read only globally.

Parameters:: readOnly - true for read only, false for read/write.

isReadOnly

public boolean isReadOnly()

Determines whether preferences are read only. Note: not static to allow overriding.

Returns:: true if read only

initialize

public static void initialize(Db prefDb,
                              boolean sync)

initialize the preferences. Throws IllegalStateException if already initialized

Parameters:: prefDb - the database connection; sync - true for autoSync, else syncObject() must be invoked explicitly

getDb

public static Db getDb()

Gets the database connection.

Returns:: the db connection

isAutoSync

public static boolean isAutoSync()

Determines whether the preferences are automatically sync'd to the database.

Returns:: true if auto sync

expireKeys

public static void expireKeys(Db db,
                              long maxSerial)

Expire the preferences keys.
Invoked from the ModificationThread (registered in DbPreferencesKey)

Parameters:: db - is the Modthreads db connection; maxSerial - is the current tableserial

expireNodes

public static void expireNodes(Db db,
                               long maxSerial)

Expires the preferences nodes.
Invoked from ModificationThread (registered in DbPreferencesNode)

Parameters:: db - is the Modthreads db connection; maxSerial - is the current tableserial

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

toString

public String toString()

Returns a string representation of this preferences node.

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

Specified by:: toString in class Preferences

Returns:: a string representation of the object.

name

public String name()

Description copied from class: java.util.prefs.Preferences

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

Specified by:: name in class Preferences

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

absolutePath

public String absolutePath()

Description copied from class: java.util.prefs.Preferences

Returns this preference node's absolute path name.

Specified by:: absolutePath in class Preferences

Returns:: this preference node's absolute path name.

isUserNode

public boolean isUserNode()

Description copied from class: java.util.prefs.Preferences

Returns true if this preference node is in the user preference tree, false if it's in the system preference tree.

Specified by:: isUserNode in class Preferences

Returns:: true if this preference node is in the user preference tree, false if it's in the system preference tree.

put

public void put(String key,
                String value)

Description copied from class: java.util.prefs.Preferences

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

Specified by:: put in class Preferences

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)

Description copied from class: java.util.prefs.Preferences

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

Some implementations may store default values in their backing stores. If there is no value associated with the specified key but there is such a stored default, it is returned in preference to the specified default.

Specified by:: get in class Preferences

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, or the backing store is inaccessible.

remove

public void remove(String key)

Description copied from class: java.util.prefs.Preferences

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

If this implementation supports stored defaults, and there is such a default for the specified preference, the stored default will be "exposed" by this call, in the sense that it will be returned by a succeeding call to get.

Specified by:: remove in class Preferences

Parameters:: key - key whose mapping is to be removed from the preference node.

clear

public void clear()
           throws BackingStoreException

Description copied from class: java.util.prefs.Preferences

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

If this implementation supports stored defaults, and this node in the preferences hierarchy contains any such defaults, the stored defaults will be "exposed" by this call, in the sense that they will be returned by succeeding calls to get.

Specified by:: clear in class Preferences

Throws:: BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
See Also:: Preferences.removeNode()

sync

public void sync()
          throws BackingStoreException

Description copied from class: java.util.prefs.Preferences

Ensures that future reads from this preference 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 preference node and its descendants to the persistent store, as if the flush method had been invoked on this node.

Specified by:: sync in class Preferences

Throws:: BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
See Also:: Preferences.flush()

flush

public void flush()
           throws BackingStoreException

Description copied from class: java.util.prefs.Preferences

Forces any changes in the contents of this preference 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 preference value changes in ancestors are not guaranteed to be made persistent.

If this method is invoked on a node that has been removed with the Preferences.removeNode() method, flushSpi() is invoked on this node, but not on others.

Specified by:: flush in class Preferences

Throws:: BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
See Also:: Preferences.sync()

putInt

public void putInt(String key,
                   int value)

Description copied from class: java.util.prefs.Preferences

Associates a string representing the specified int value with the specified key in this preference 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 Preferences.getInt(java.lang.String, int).

Specified by:: putInt in class Preferences

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:: Preferences.getInt(String,int)

getInt

public int getInt(String key,
                  int def)

Description copied from class: java.util.prefs.Preferences

Returns the int value represented by the string associated with the specified key in this preference node. The string is converted to an integer 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 Preferences.putInt(java.lang.String, int).

If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to an int with Integer.parseInt, this int is returned in preference to the specified default.

Specified by:: getInt in class Preferences

Parameters:: key - key whose associated value is to be returned as an int.; def - the value to be returned in the event that this preference 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 associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as an int.
See Also:: Preferences.putInt(String,int), Preferences.get(String,String)

putLong

public void putLong(String key,
                    long value)

Description copied from class: java.util.prefs.Preferences

Associates a string representing the specified long value with the specified key in this preference node. The associated string 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 Preferences.getLong(java.lang.String, long).

Specified by:: putLong in class Preferences

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:: Preferences.getLong(String,long)

getLong

public long getLong(String key,
                    long def)

Description copied from class: java.util.prefs.Preferences

Returns the long value represented by the string associated with the specified key in this preference node. The string 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 Preferences.putLong(java.lang.String, long).

If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to a long with Long.parseLong, this long is returned in preference to the specified default.

Specified by:: getLong in class Preferences

Parameters:: key - key whose associated value is to be returned as a long.; def - the value to be returned in the event that this preference node has no value associated with key or the associated value cannot be interpreted as a long, or the backing store is inaccessible.
Returns:: the long value represented by the string associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as a long.
See Also:: Preferences.putLong(String,long), Preferences.get(String,String)

putBoolean

public void putBoolean(String key,
                       boolean value)

Description copied from class: java.util.prefs.Preferences

Associates a string representing the specified boolean value with the specified key in this preference 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 Preferences.getBoolean(java.lang.String, boolean).

Specified by:: putBoolean in class Preferences

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:: Preferences.getBoolean(String,boolean), Preferences.get(String,String)

getBoolean

public boolean getBoolean(String key,
                          boolean def)

Description copied from class: java.util.prefs.Preferences

Returns the boolean value represented by the string associated with the specified key in this preference 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 Preferences.putBoolean(java.lang.String, boolean).

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.

If the implementation supports stored defaults and such a default exists and is accessible, it is used in preference to the specified default, unless the stored default is something other than "true" or "false", ignoring case, in which case the specified default is used.

Specified by:: getBoolean in class Preferences

Parameters:: key - key whose associated value is to be returned as a boolean.; def - the value to be returned in the event that this preference 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 associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as a boolean.
See Also:: Preferences.get(String,String), Preferences.putBoolean(String,boolean)

putFloat

public void putFloat(String key,
                     float value)

Description copied from class: java.util.prefs.Preferences

Associates a string representing the specified float value with the specified key in this preference node. The associated string 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 Preferences.getFloat(java.lang.String, float).

Specified by:: putFloat in class Preferences

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:: Preferences.getFloat(String,float)

getFloat

public float getFloat(String key,
                      float def)

Description copied from class: java.util.prefs.Preferences

Returns the float value represented by the string associated with the specified key in this preference node. The string is converted to an integer 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 Preferences.putFloat(java.lang.String, float).

If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to a float with Float.parseFloat, this float is returned in preference to the specified default.

Specified by:: getFloat in class Preferences

Parameters:: key - key whose associated value is to be returned as a float.; def - the value to be returned in the event that this preference node has no value associated with key or the associated value cannot be interpreted as a float, or the backing store is inaccessible.
Returns:: the float value represented by the string associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as a float.
See Also:: Preferences.putFloat(String,float), Preferences.get(String,String)

putDouble

public void putDouble(String key,
                      double value)

Description copied from class: java.util.prefs.Preferences

Associates a string representing the specified double value with the specified key in this preference node. The associated string 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 Preferences.getDouble(java.lang.String, double).

Specified by:: putDouble in class Preferences

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:: Preferences.getDouble(String,double)

getDouble

public double getDouble(String key,
                        double def)

Description copied from class: java.util.prefs.Preferences

Returns the double value represented by the string associated with the specified key in this preference node. The string is converted to an integer 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 Preferences.putDouble(java.lang.String, double).

If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to a double with Double.parseDouble, this double is returned in preference to the specified default.

Specified by:: getDouble in class Preferences

Parameters:: key - key whose associated value is to be returned as a double.; def - the value to be returned in the event that this preference node has no value associated with key or the associated value cannot be interpreted as a double, or the backing store is inaccessible.
Returns:: the double value represented by the string associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as a double.
See Also:: Preferences.putDouble(String,double), Preferences.get(String,String)

putByteArray

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

Description copied from class: java.util.prefs.Preferences

Associates a string representing the specified byte array with the specified key in this preference node. The associated string is the Base64 encoding of the byte array, 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. Note that the maximum length of the byte array is limited to three quarters of MAX_VALUE_LENGTH so that the length of the Base64 encoded String does not exceed MAX_VALUE_LENGTH. This method is intended for use in conjunction with Preferences.getByteArray(java.lang.String, byte[]).

Specified by:: putByteArray in class Preferences

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:: Preferences.getByteArray(String,byte[]), Preferences.get(String,String)

getByteArray

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

Description copied from class: java.util.prefs.Preferences

Returns the byte array value represented by the string associated with the specified key in this preference node. Valid strings 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 Preferences.putByteArray(java.lang.String, byte[]).

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).

If the implementation supports stored defaults and such a default exists and is accessible, it is used in preference to the specified default, unless the stored default is not a valid Base64 encoded byte array (as defined above), in which case the specified default is used.

Specified by:: getByteArray in class Preferences

Parameters:: key - key whose associated value is to be returned as a byte array.; def - the value to be returned in the event that this preference node has no value associated with key or the associated value cannot be interpreted as a byte array, or the backing store is inaccessible.
Returns:: the byte array value represented by the string associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as a byte array.
See Also:: Preferences.get(String,String), Preferences.putByteArray(String,byte[])

keys

public String[] keys()
              throws BackingStoreException

Description copied from class: java.util.prefs.Preferences

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

If the implementation supports stored defaults and there are any such defaults at this node that have not been overridden, by explicit preferences, the defaults are returned in the array in addition to any explicit preferences.

Specified by:: keys in class Preferences

Returns:: an array of the keys that have an associated value in this preference 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

Description copied from class: java.util.prefs.Preferences

Returns the names of the children of this preference node, relative to this node. (The returned array will be of size zero if this node has no children.)

Specified by:: childrenNames in class Preferences

Returns:: the names of the children of this preference 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 Preferences parent()

Description copied from class: java.util.prefs.Preferences

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

Specified by:: parent in class Preferences

Returns:: the parent of this preference node.

node

public Preferences node(String path)

Description copied from class: java.util.prefs.Preferences

Returns the named preference node in the same tree as this node, creating it and any of its ancestors if they do not already exist. Accepts a relative or absolute path name. Relative path names (which do not begin with the slash character ('/')) are interpreted relative to this preference node.

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 permanent until the flush method is called on the returned node (or one of its ancestors or descendants).

Specified by:: node in class Preferences

Parameters:: path - the path name of the preference node to return.
Returns:: the specified preference node.
See Also:: Preferences.flush()

nodeExists

public boolean nodeExists(String pathName)
                   throws BackingStoreException

Returns true if the named preference node exists in the same tree as this node. Relative path names (which do not begin with the slash character ('/')) are interpreted relative to this preference node.

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

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 class Preferences

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

Description copied from class: java.util.prefs.Preferences

Removes this preference node and all of its descendants, invalidating any preferences contained in the removed nodes. Once a node has been removed, attempting any method other than Preferences.name(), Preferences.absolutePath(), Preferences.isUserNode(), Preferences.flush() 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 this node (or an ancestor).

If this implementation supports stored defaults, removing a node exposes any stored defaults at or below this node. Thus, a subsequent call to nodeExists on this node's path name may return true, and a subsequent call to node on this path name may return a (different) Preferences instance representing a non-empty collection of preferences and/or children.

Specified by:: removeNode in class Preferences

Throws:: BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
See Also:: Preferences.flush()

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()/syncObject().

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)

Description copied from class: java.util.prefs.Preferences

Removes the specified preference change listener, so it no longer receives preference change events.

Specified by:: removePreferenceChangeListener in class Preferences

Parameters:: pcl - The preference change listener to remove.
See Also:: Preferences.addPreferenceChangeListener(PreferenceChangeListener)

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.)

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 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)

Description copied from class: java.util.prefs.Preferences

Removes the specified NodeChangeListener, so it no longer receives change events.

Specified by:: removeNodeChangeListener in class Preferences

Parameters:: ncl - The NodeChangeListener to remove.
See Also:: Preferences.addNodeChangeListener(NodeChangeListener)

exportNode

public void exportNode(OutputStream os)
                throws IOException,
                       BackingStoreException

Description copied from class: java.util.prefs.Preferences

Emits on the specified output stream an XML document representing all of the preferences contained in this node (but not its descendants). This XML document is, in effect, an offline backup of the node.

The XML document will have the following DOCTYPE declaration:

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">

The UTF-8 character encoding will be used.

This method is an exception to the general rule that the results of concurrently executing multiple methods in this class yields results equivalent to some serial execution. If the preferences at this node are modified concurrently with an invocation of this method, the exported preferences comprise a "fuzzy snapshot" of the preferences contained in the node; some of the concurrent modifications may be reflected in the exported data while others may not.

Specified by:: exportNode in class Preferences

Parameters:: os - the output stream on which to emit the XML document.
Throws:: IOException - if writing to the specified output stream results in an IOException.; BackingStoreException - if preference data cannot be read from backing store.
See Also:: Preferences.importPreferences(InputStream)

exportSubtree

public void exportSubtree(OutputStream os)
                   throws IOException,
                          BackingStoreException

Description copied from class: java.util.prefs.Preferences

Emits an XML document representing all of the preferences contained in this node and all of its descendants. This XML document is, in effect, an offline backup of the subtree rooted at the node.

The XML document will have the following DOCTYPE declaration:

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">

The UTF-8 character encoding will be used.

This method is an exception to the general rule that the results of concurrently executing multiple methods in this class yields results equivalent to some serial execution. If the preferences or nodes in the subtree rooted at this node are modified concurrently with an invocation of this method, the exported preferences comprise a "fuzzy snapshot" of the subtree; some of the concurrent modifications may be reflected in the exported data while others may not.

Specified by:: exportSubtree in class Preferences

Parameters:: os - the output stream on which to emit the XML document.
Throws:: IOException - if writing to the specified output stream results in an IOException.; BackingStoreException - if preference data cannot be read from backing store.
See Also:: Preferences.importPreferences(InputStream), Preferences.exportNode(OutputStream)

importPreferences

public static void importPreferences(InputStream is)
                              throws IOException,
                                     InvalidPreferencesFormatException

Imports all of the preferences represented by the XML document as in Preferences.

CAUTION: As in Preferences this method is static, i.e. this one does *NOT* override Preferences.importPreferences()! YOU MUST INVOKE DbPreferences.importPreferences() directly!!! This is due to the design by Sun. Sun's implementation of Preferences.importPreferences() should better invoke a method in PreferencesFactory according to the property "java.util.prefs.PreferencesFactory". Instead it invokes (package scoped) XmlSupport :-(

Parameters:: is - the input stream from which to read the XML document.
Throws:: IOException - if reading from the specified output stream results in an IOException.; InvalidPreferencesFormatException - Data on input stream does not constitute a valid XML document with the mandated document type.; SecurityException - If a security manager is present and it denies RuntimePermission("preferences").
See Also:: RuntimePermission

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.tentackle.db Class DbPreferences

TX_FLUSH

TX_REMOVE_NODE

DbPreferences

DbPreferences

DbPreferences

setReadOnly

isReadOnly

initialize

getDb

isAutoSync

expireKeys

expireNodes

updateParentNode

toString

name

absolutePath

isUserNode

put

get

remove

clear

sync

flush

putInt

getInt

putLong

getLong

putBoolean

getBoolean

putFloat

getFloat

putDouble

getDouble

putByteArray

getByteArray

keys

childrenNames

parent

node

nodeExists

removeNode

addPreferenceChangeListener

removePreferenceChangeListener

addNodeChangeListener

removeNodeChangeListener

exportNode

exportSubtree

importPreferences

org.tentackle.db
Class DbPreferences