org.ocd.prefs.file
Class FilePreferences

java.lang.Object
  |
  +--org.ocd.prefs.util.Preferences
        |
        +--org.ocd.prefs.util.AbstractPreferences
              |
              +--org.ocd.prefs.file.FilePreferences

public class FilePreferences

extends AbstractPreferences

Since:

$Date: 2002/03/29 08:01:16 $

Version:

$Revision: 1.2 $

Author:

$Author: ocd_dino $, ocd_dino - ocd_dino@users.sourceforge.net (initial author)

Field Summary

static java.lang.String

PROPERTIES_FILE

Fields inherited from class org.ocd.prefs.util.AbstractPreferences

lock, newNode

Fields inherited from class org.ocd.prefs.util.Preferences

MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH

Constructor Summary

FilePreferences(java.io.File pPrefDir)
Creates new FilePreferences

FilePreferences(FilePreferences parent, java.lang.String name)
Creates new FilePreferences

Method Summary

protected java.lang.String[]	childrenNamesSpi() Returns the names of the children of this preference node.
protected AbstractPreferences	childSpi(java.lang.String name) Returns the named child of this preference node, creating it if it does not already exist.
protected void	flushSpi() This method is invoked with this node locked.
protected java.io.File	getNodeDir()
protected java.lang.String	getSpi(java.lang.String key) Return the value associated with the specified key at this preference node, or null if there is no association for this key, or the association cannot be determined at this time.
protected java.lang.String[]	keysSpi() Returns all of the keys that have an associated value in this preference node.
protected java.util.Properties	loadProperties()
protected void	putSpi(java.lang.String key, java.lang.String value) Put the given key-value association into this preference node.
protected void	removeNodeSpi() Removes this preference node, invalidating it and any preferences that it contains.
protected void	removeSpi(java.lang.String key) Remove the association (if any) for the specified key at this preference node.
protected void	syncSpi() This method is invoked with this node locked.

Methods inherited from class org.ocd.prefs.util.AbstractPreferences

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

Methods inherited from class org.ocd.prefs.util.Preferences

setFactory, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTIES_FILE

public static final java.lang.String PROPERTIES_FILE

Constructor Detail

FilePreferences

public FilePreferences(java.io.File pPrefDir)

Creates new FilePreferences

FilePreferences

public FilePreferences(FilePreferences parent,
                       java.lang.String name)

Creates new FilePreferences

Method Detail

getNodeDir

protected java.io.File getNodeDir()

loadProperties

protected java.util.Properties loadProperties()

putSpi

protected void putSpi(java.lang.String key,
                      java.lang.String value)

Put the given key-value association into this preference node. It is guaranteed that key and value are non-null and of legal length. Also, it is guaranteed that this node has not been removed. (The implementor needn't check for any of these things.)

This method is invoked with the lock on this node held.

Overrides:

putSpi in class AbstractPreferences

getSpi

protected java.lang.String getSpi(java.lang.String key)

Return the value associated with the specified key at this preference node, or null if there is no association for this key, or the association cannot be determined at this time. It is guaranteed that key is non-null. Also, it is guaranteed that this node has not been removed. (The implementor needn't check for either of these things.)

Generally speaking, this method should not throw an exception under any circumstances. If, however, if it does throw an exception, the exception will be intercepted and treated as a null return value.

This method is invoked with the lock on this node held.

Overrides:

getSpi in class AbstractPreferences

Returns:

the value associated with the specified key at this preference node, or null if there is no association for this key, or the association cannot be determined at this time.

syncSpi

protected void syncSpi()
                throws BackingStoreException

This method is invoked with this node locked. The contract of this method is to synchronize any cached preferences stored at this node with any stored in the backing store. (It is perfectly possible that this node does not exist on the backing store, either because it has been deleted by another VM, or because it has not yet been created.) Note that this method should not synchronize the preferences in any subnodes of this node. If the backing store naturally syncs an entire subtree at once, the implementer is encouraged to override sync(), rather than merely overriding this method.

If this node throws a BackingStoreException, the exception will propagate out beyond the enclosing AbstractPreferences.sync() invocation.

Overrides:

syncSpi in class AbstractPreferences

Throws:

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

removeNodeSpi

protected void removeNodeSpi()
                      throws BackingStoreException

Removes this preference node, invalidating it and any preferences that it contains. The named child will have no descendants at the time this invocation is made (i.e., the Preferences.removeNode() method invokes this method repeatedly in a bottom-up fashion, removing each of a node's descendants before removing the node itself).

This method is invoked with the lock held on this node and its parent (and all ancestors that are being removed as a result of a single invocation to Preferences.removeNode()).

The removal of a node needn't become persistent until the flush method is invoked on this node (or an ancestor).

If this node throws a BackingStoreException, the exception will propagate out beyond the enclosing AbstractPreferences.removeNode() invocation.

Overrides:

removeNodeSpi in class AbstractPreferences

Throws:

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

childSpi

protected AbstractPreferences childSpi(java.lang.String name)

Returns the named child of this preference node, creating it if it does not already exist. It is guaranteed that name is non-null, non-empty, does not contain the slash character ('/'), and is no longer than Preferences.MAX_NAME_LENGTH characters. Also, it is guaranteed that this node has not been removed. (The implementor needn't check for any of these things.)

Finally, it is guaranteed that the named node has not been returned by a previous invocation of this method or AbstractPreferences.getChild(String) after the last time that it was removed. In other words, a cached value will always be used in preference to invoking this method. Subclasses need not maintain their own cache of previously returned children.

The implementer must ensure that the returned node has not been removed. If a like-named child of this node was previously removed, the implementer must return a newly constructed AbstractPreferences node; once removed, an AbstractPreferences node cannot be "resuscitated."

If this method causes a node to be created, this node is not guaranteed to be persistent until the flush method is invoked on this node or one of its ancestors (or descendants).

This method is invoked with the lock on this node held.

Overrides:

childSpi in class AbstractPreferences

Parameters:

name - The name of the child node to return, relative to this preference node.

Returns:

The named child node.

flushSpi

protected void flushSpi()
                 throws BackingStoreException

This method is invoked with this node locked. The contract of this method is to synchronize any cached preferences stored at this node with any stored in the backing store. (It is perfectly possible that this node does not exist on the backing store, either because it has been deleted by another VM, or because it has not yet been created.) Note that this method should not flush the preferences in any subnodes of this node. If the backing store naturally syncs an entire subtree at once, the implementer is encouraged to override flush(), rather than merely overriding this method.

If this node throws a BackingStoreException, the exception will propagate out beyond the enclosing AbstractPreferences.flush() invocation.

Overrides:

flushSpi in class AbstractPreferences

Throws:

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

removeSpi

protected void removeSpi(java.lang.String key)

Remove the association (if any) for the specified key at this preference node. It is guaranteed that key is non-null. Also, it is guaranteed that this node has not been removed. (The implementor needn't check for either of these things.)

This method is invoked with the lock on this node held.

Overrides:

removeSpi in class AbstractPreferences

childrenNamesSpi

protected java.lang.String[] childrenNamesSpi()
                                       throws BackingStoreException

Returns the names of the children of this preference node. (The returned array will be of size zero if this node has no children.) This method need not return the names of any nodes already cached, but may do so without harm.

This method is invoked with the lock on this node held.

If this node throws a BackingStoreException, the exception will propagate out beyond the enclosing AbstractPreferences.childrenNames() invocation.

Overrides:

childrenNamesSpi in class AbstractPreferences

Returns:

an array containing 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.

keysSpi

protected java.lang.String[] keysSpi()
                              throws BackingStoreException

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.) It is guaranteed that this node has not been removed.

This method is invoked with the lock on this node held.

If this node throws a BackingStoreException, the exception will propagate out beyond the enclosing AbstractPreferences.keys() invocation.

Overrides:

keysSpi in class AbstractPreferences

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.