public abstract class AbstractPreferences extends Preferences
Modifier and Type | Field and Description |
---|---|
protected Object |
lock
Object used to lock this preference node.
|
protected boolean |
newNode
Set to true in the contructor if the node did not exist in the backing
store when this preference node object was created.
|
MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH
Modifier | Constructor and Description |
---|---|
protected |
AbstractPreferences(AbstractPreferences parent,
String name)
Creates a new AbstractPreferences node with the given parent and name.
|
Modifier and Type | Method and Description |
---|---|
String |
absolutePath()
Returns the absolute path name of this preference node.
|
void |
addNodeChangeListener(NodeChangeListener listener)
Add a listener which is notified when a sub-node of this node
is added or removed.
|
void |
addPreferenceChangeListener(PreferenceChangeListener listener)
Add a listener which is notified when a value in this node
is added, changed, or removed.
|
protected AbstractPreferences[] |
cachedChildren()
Returns all known unremoved children of this node.
|
String[] |
childrenNames()
Returns all the direct sub nodes of this preferences node.
|
protected abstract String[] |
childrenNamesSpi()
Returns the names of the sub nodes of this preference node.
|
protected abstract AbstractPreferences |
childSpi(String name)
Returns a child note with the given name.
|
void |
clear()
Removes all entries from this preferences node.
|
void |
exportNode(OutputStream os)
Export this node, but not its descendants, as XML to the
indicated output stream.
|
void |
exportSubtree(OutputStream os)
Export this node and all its descendants as XML to the
indicated output stream.
|
void |
flush()
Writes all preference changes on this and any subnode that have not
yet been written to the backing store.
|
protected abstract void |
flushSpi()
Writes all entries of this preferences node that have not yet been
written to the backing store and possibly creates this node in the
backing store, if it does not yet exist.
|
String |
get(String key,
String defaultVal)
Returns the value associated with the key in this preferences node.
|
boolean |
getBoolean(String key,
boolean defaultVal)
Convenience method for getting the given entry as a boolean.
|
byte[] |
getByteArray(String key,
byte[] defaultVal)
Convenience method for getting the given entry as a byte array.
|
protected AbstractPreferences |
getChild(String name)
Returns the child sub node if it exists in the backing store or null
if it does not exist.
|
double |
getDouble(String key,
double defaultVal)
Convenience method for getting the given entry as a double.
|
float |
getFloat(String key,
float defaultVal)
Convenience method for getting the given entry as a float.
|
int |
getInt(String key,
int defaultVal)
Convenience method for getting the given entry as an integer.
|
long |
getLong(String key,
long defaultVal)
Convenience method for getting the given entry as a long.
|
protected abstract String |
getSpi(String key)
Returns the value associated with the key in this preferences node or
null when the key does not exist in this preferences node.
|
protected boolean |
isRemoved()
Returns true if this node has been removed with the
removeNode() method, false otherwise. |
boolean |
isUserNode()
Returns true if this node comes from the user preferences tree, false
if it comes from the system preferences tree.
|
String[] |
keys()
Returns an (possibly empty) array with all the keys of the preference
entries of this node.
|
protected abstract String[] |
keysSpi()
Returns an (possibly empty) array with all the keys of the preference
entries of this node.
|
String |
name()
Returns the name of this preferences node.
|
Preferences |
node(String path)
Returns a sub node of this preferences node if the given path is
relative (does not start with a '/') or a sub node of the root
if the path is absolute (does start with a '/').
|
boolean |
nodeExists(String path)
Returns true if the node that the path points to exists in memory or
in the backing store.
|
Preferences |
parent()
Returns the parent preferences node of this node or null if this is
the root of the preferences tree.
|
void |
put(String key,
String value)
Sets the value of the given preferences entry for this node.
|
void |
putBoolean(String key,
boolean value)
Convenience method for setting the given entry as a boolean.
|
void |
putByteArray(String key,
byte[] value)
Convenience method for setting the given entry as an array of bytes.
|
void |
putDouble(String key,
double value)
Convenience method for setting the given entry as a double.
|
void |
putFloat(String key,
float value)
Convenience method for setting the given entry as a float.
|
void |
putInt(String key,
int value)
Convenience method for setting the given entry as an integer.
|
void |
putLong(String key,
long value)
Convenience method for setting the given entry as a long.
|
protected abstract void |
putSpi(String key,
String value)
Sets the value of the given preferences entry for this node.
|
void |
remove(String key)
Removes the preferences entry from this preferences node.
|
void |
removeNode()
Removes this and all subnodes from the backing store and clears all
entries.
|
void |
removeNodeChangeListener(NodeChangeListener listener)
Remove the indicated node change listener from the list of
listeners to notify.
|
protected abstract void |
removeNodeSpi()
Clears this node from this VM and removes it from the backing store.
|
void |
removePreferenceChangeListener(PreferenceChangeListener listener)
Remove the indicated preference change listener from the list of
listeners to notify.
|
protected abstract void |
removeSpi(String key)
Removes the given key entry from this preferences node.
|
void |
sync()
Writes and reads all preference changes to and from this and any
subnodes.
|
protected abstract void |
syncSpi()
Writes all entries of this preferences node that have not yet been
written to the backing store and reads any entries that have changed
in the backing store but that are not yet visible in this VM.
|
String |
toString()
Returns the String given by
(isUserNode() ? |
importPreferences, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot
protected final Object lock
protected boolean newNode
protected AbstractPreferences(AbstractPreferences parent, String name)
parent
- the parent of this node or null when this is the root nodename
- the name of this node, can not be null, only 80 characters
maximum, must be empty when parent is null and cannot
contain any '/' charactersIllegalArgumentException
- when name is null, greater then 80
characters, not the empty string but parent is null or
contains a '/' characterpublic String absolutePath()
absolutePath
in class Preferences
public boolean isUserNode()
isUserNode
in class Preferences
public String name()
name
in class Preferences
public String toString()
(isUserNode() ? "User":"System") + " Preference Node: " + absolutePath()
toString
in class Preferences
Object.getClass()
,
Object.hashCode()
,
Class.getName()
,
Integer.toHexString(int)
protected final AbstractPreferences[] cachedChildren()
public String[] childrenNames() throws BackingStoreException
This implementation locks this node, checks if the node has not yet
been removed and throws an IllegalStateException
when it
has been. Then it creates a new TreeSet
and adds any
already cached child nodes names. To get any uncached names it calls
childrenNamesSpi()
and adds the result to the set. Finally
it calls toArray()
on the created set. When the call to
childrenNamesSpi
thows an BackingStoreException
this method will not catch that exception but propagate the exception
to the caller.
childrenNames
in class Preferences
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- when this node has been removedpublic Preferences node(String path)
This method first locks this node and checks if the node has not been
removed, if it has been removed it throws an exception. Then if the
path is relative (does not start with a '/') it checks if the path is
legal (does not end with a '/' and has no consecutive '/' characters).
Then it recursively gets a name from the path, gets the child node
from the child-cache of this node or calls the childSpi()
method to create a new child sub node. This is done recursively on the
newly created sub node with the rest of the path till the path is empty.
If the path is absolute (starts with a '/') the lock on this node is
droped and this method is called on the root of the preferences tree
with as argument the complete path minus the first '/'.
node
in class Preferences
IllegalStateException
- if this node has been removedIllegalArgumentException
- if the path contains two or more
consecutive '/' characters, ends with a '/' charactor and is not the
string "/" (indicating the root node) or any name on the path is more
than 80 characters longpublic boolean nodeExists(String path) throws BackingStoreException
nodeExists
in class Preferences
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removed
and the path is not the empty string (indicating this node)IllegalArgumentException
- if the path contains two or more
consecutive '/' characters, ends with a '/' charactor and is not the
string "/" (indicating the root node) or any name on the path is more
then 80 characters longprotected AbstractPreferences getChild(String name) throws BackingStoreException
nodeExists()
when a child node name can not be found in the cache.
Gets the lock on this node, calls childrenNamesSpi()
to
get an array of all (possibly uncached) children and compares the
given name with the names in the array. If the name is found in the
array childSpi()
is called to get an instance, otherwise
null is returned.
BackingStoreException
- when the backing store cannot be
reachedprotected boolean isRemoved()
removeNode()
method, false otherwise.
Gets the lock on this node and then returns a boolean field set by
removeNode
methods.
public Preferences parent()
Gets the lock on this node, checks that the node has not been removed and returns the parent given to the constructor.
parent
in class Preferences
IllegalStateException
- if this node has been removedpublic void exportNode(OutputStream os) throws BackingStoreException, IOException
Preferences
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
exportNode
in class Preferences
os
- the output stream to which the XML is sentBackingStoreException
- if preference data cannot be readIOException
- if an error occurs while writing the XMLpublic void exportSubtree(OutputStream os) throws BackingStoreException, IOException
Preferences
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
exportSubtree
in class Preferences
os
- the output stream to which the XML is sentBackingStoreException
- if preference data cannot be readIOException
- if an error occurs while writing the XMLpublic String[] keys() throws BackingStoreException
This method locks this node and checks if the node has not been
removed, if it has been removed it throws an exception, then it returns
the result of calling keysSpi()
.
keys
in class Preferences
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removedpublic String get(String key, String defaultVal)
Checks that key is not null and not larger then 80 characters,
locks this node, and checks that the node has not been removed.
Then it calls keySpi()
and returns
the result of that method or the given default value if it returned
null or throwed an exception.
get
in class Preferences
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic boolean getBoolean(String key, boolean defaultVal)
getBoolean
in class Preferences
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic byte[] getByteArray(String key, byte[] defaultVal)
getByteArray
in class Preferences
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic double getDouble(String key, double defaultVal)
Double.parseDouble()
then that double is returned,
otherwise the given default double value is returned.getDouble
in class Preferences
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic float getFloat(String key, float defaultVal)
Float.parseFloat()
then that float is returned,
otherwise the given default float value is returned.getFloat
in class Preferences
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic int getInt(String key, int defaultVal)
Integer.parseInt()
then that integer is returned,
otherwise the given default integer value is returned.getInt
in class Preferences
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic long getLong(String key, long defaultVal)
Long.parseLong()
then that long is returned,
otherwise the given default long value is returned.getLong
in class Preferences
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic void put(String key, String value)
The result will be immediately visible in this VM, but may not be immediately written to the backing store.
Checks that key and value are valid, locks this node, and checks that
the node has not been removed. Then it calls putSpi()
.
put
in class Preferences
NullPointerException
- if either key or value are nullIllegalArgumentException
- if either key or value are to largeIllegalStateException
- when this node has been removedpublic void putBoolean(String key, boolean value)
Boolean.toString(value)
and then stored in the preference entry as that string.putBoolean
in class Preferences
NullPointerException
- if key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void putByteArray(String key, byte[] value)
Note that a byte array encoded as a Base64 string will be about 1.3 times larger then the original length of the byte array, which means that the byte array may not be larger about 6 KB.
putByteArray
in class Preferences
NullPointerException
- if either key or value are nullIllegalArgumentException
- if either key or value are to largeIllegalStateException
- when this node has been removedpublic void putDouble(String key, double value)
Double.toString(double)
and then stored in the preference entry as that string.putDouble
in class Preferences
NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void putFloat(String key, float value)
Float.toString(float)
and then stored in the preference entry as that string.putFloat
in class Preferences
NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void putInt(String key, int value)
Integer.toString(int)
and then stored in the preference entry as that string.putInt
in class Preferences
NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void putLong(String key, long value)
Long.toString(long)
and then stored in the preference entry as that string.putLong
in class Preferences
NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void remove(String key)
The result will be immediately visible in this VM, but may not be immediately written to the backing store.
This implementation checks that the key is not larger then 80
characters, gets the lock of this node, checks that the node has
not been removed and calls removeSpi
with the given key.
remove
in class Preferences
NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void clear() throws BackingStoreException
The result will be immediately visible in this VM, but may not be immediatly written to the backing store.
This implementation locks this node, checks that the node has not been
removed and calls keys()
to get a complete array of keys
for this node. For every key found removeSpi()
is called.
clear
in class Preferences
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removedpublic void flush() throws BackingStoreException
sync()
method to actually see the changes to the backing
store.
Locks this node, calls the flushSpi()
method, gets all
the (cached - already existing in this VM) subnodes and then calls
flushSpi()
on every subnode with this node unlocked and
only that particular subnode locked.
flush
in class Preferences
BackingStoreException
- when the backing store cannot be
reachedpublic void sync() throws BackingStoreException
Checks that this node is not removed, locks this node, calls the
syncSpi()
method, gets all the subnodes and then calls
syncSpi()
on every subnode with this node unlocked and
only that particular subnode locked.
sync
in class Preferences
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removedpublic void removeNode() throws BackingStoreException
InvalidStateException
),
even when a new node with the same path name is created this instance
will not be usable again.
Checks that this is not a root node. If not it locks the parent node,
then locks this node and checks that the node has not yet been removed.
Then it makes sure that all subnodes of this node are in the child cache,
by calling childSpi()
on any children not yet in the cache.
Then for all children it locks the subnode and removes it. After all
subnodes have been purged the child cache is cleared, this nodes removed
flag is set and any listeners are called. Finally this node is removed
from the child cache of the parent node.
removeNode
in class Preferences
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has already been removedUnsupportedOperationException
- if this is a root nodepublic void addNodeChangeListener(NodeChangeListener listener)
addNodeChangeListener
in class Preferences
listener
- the listener to addpublic void addPreferenceChangeListener(PreferenceChangeListener listener)
addPreferenceChangeListener
in class Preferences
listener
- the listener to addpublic void removeNodeChangeListener(NodeChangeListener listener)
removeNodeChangeListener
in class Preferences
listener
- the listener to removepublic void removePreferenceChangeListener(PreferenceChangeListener listener)
removePreferenceChangeListener
in class Preferences
listener
- the listener to removeprotected abstract String[] childrenNamesSpi() throws BackingStoreException
Called by childrenNames()
with this node locked.
BackingStoreException
protected abstract AbstractPreferences childSpi(String name)
node()
method (indirectly
through the getNode()
helper method) with this node locked
if a sub node with this name does not already exist in the child cache.
If the child node did not aleady exist in the backing store the boolean
field newNode
of the returned node should be set.
Note that this method should even return a non-null child node if the
backing store is not available since it may not throw a
BackingStoreException
.
protected abstract String[] keysSpi() throws BackingStoreException
Called by keys()
with this node locked if this node has
not been removed. May throw an exception when the backing store cannot
be accessed.
BackingStoreException
- when the backing store cannot be
reachedprotected abstract String getSpi(String key)
Called by key()
with this node locked after checking that
key is valid, not null and that the node has not been removed.
key()
will catch any exceptions that this method throws.
protected abstract void putSpi(String key, String value)
flush()
or sync()
can signal the failure.
Called by put()
with this node locked after checking that
key and value are valid and non-null.
protected abstract void removeSpi(String key)
flush()
or sync()
can signal the failure.
Called by remove()
with this node locked after checking
that the key is valid and non-null.
protected abstract void flushSpi() throws BackingStoreException
isRemoved()
.
Called (indirectly) by flush()
with this node locked.
BackingStoreException
protected abstract void syncSpi() throws BackingStoreException
isRemoved()
.
Called (indirectly) by sync()
with this node locked.
BackingStoreException
protected abstract void removeNodeSpi() throws BackingStoreException
Called (indirectly) by removeNode()
with this node locked
after all the sub nodes of this node have already been removed.
BackingStoreException