java.util.prefs
public
abstract
class
java.util.prefs.AbstractPreferences
This class is partly implementation of Preferences
, which can be
used to simplify Preferences
provider's implementation.
This class define nine abstract SPI methods, which must be implemented by
preference provider. And provider can also override other methods of this
class. Some SPI methods will throw BackingStoreException
,
including childrenNamesSpi()
, flushSpi()
,
keysSpi()
, removeNodeSpi()
,
syncSpi()
; getSpi(String, String)
never throws any
exceptions; the last SPI methods, putSpi(String)
,
removeSpi(String)
and childSpi(String)
won't throw
BackingStoreException
, but in some implementations, they may
throw SecurityException
due to lacking the permission to access
backing end storage.
Summary
|
|
|
Value |
|
int |
MAX_KEY_LENGTH |
Maximum size in characters of preferences key
|
80 |
0x00000050 |
int |
MAX_NAME_LENGTH |
Maximum size in characters of preferences name
|
80 |
0x00000050 |
int |
MAX_VALUE_LENGTH |
Maximum size in characters of preferences value
|
8192 |
0x00002000 |
Fields
protected |
|
final |
Object |
lock |
The object used to lock this node. |
protected |
|
|
boolean |
newNode |
This field is true if this node is created while it doesn't exist in the
backing store. |
Protected Constructors
Public Methods
|
|
|
|
|
String |
absolutePath() |
|
|
|
|
|
void |
addNodeChangeListener(NodeChangeListener ncl) |
|
|
|
|
|
void |
addPreferenceChangeListener(PreferenceChangeListener pcl) |
|
|
|
|
|
String[] |
childrenNames() |
|
|
|
|
|
void |
clear() |
|
|
|
|
|
void |
exportNode(OutputStream ostream) |
|
|
|
|
|
void |
exportSubtree(OutputStream ostream) |
|
|
|
|
|
void |
flush() |
|
|
|
|
|
String |
get(String key, String deflt) |
|
|
|
|
|
boolean |
getBoolean(String key, boolean deflt) |
|
|
|
|
|
byte[] |
getByteArray(String key, byte[] deflt) |
|
|
|
|
|
double |
getDouble(String key, double deflt) |
|
|
|
|
|
float |
getFloat(String key, float deflt) |
|
|
|
|
|
int |
getInt(String key, int deflt) |
|
|
|
|
|
long |
getLong(String key, long deflt) |
|
|
|
|
|
boolean |
isUserNode() |
|
|
|
|
|
String[] |
keys() |
|
|
|
|
|
String |
name() |
|
|
|
|
|
Preferences |
node(String name) |
|
|
|
|
|
boolean |
nodeExists(String name) |
|
|
|
|
|
Preferences |
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() |
Protected Methods
absolutePath,
addNodeChangeListener,
addPreferenceChangeListener,
childrenNames,
clear,
exportNode,
exportSubtree,
flush,
get,
getBoolean,
getByteArray,
getDouble,
getFloat,
getInt,
getLong,
importPreferences,
isUserNode,
keys,
name,
node,
nodeExists,
parent,
put,
putBoolean,
putByteArray,
putDouble,
putFloat,
putInt,
putLong,
remove,
removeNode,
removeNodeChangeListener,
removePreferenceChangeListener,
sync,
systemNodeForPackage,
systemRoot,
toString,
userNodeForPackage,
userRoot
abstract |
|
|
|
|
String |
absolutePath() |
abstract |
|
|
|
|
void |
addNodeChangeListener(NodeChangeListener ncl) |
abstract |
|
|
|
|
void |
addPreferenceChangeListener(PreferenceChangeListener pcl) |
abstract |
|
|
|
|
String[] |
childrenNames() |
abstract |
|
|
|
|
void |
clear() |
abstract |
|
|
|
|
void |
exportNode(OutputStream ostream) |
abstract |
|
|
|
|
void |
exportSubtree(OutputStream ostream) |
abstract |
|
|
|
|
void |
flush() |
abstract |
|
|
|
|
String |
get(String key, String deflt) |
abstract |
|
|
|
|
boolean |
getBoolean(String key, boolean deflt) |
abstract |
|
|
|
|
byte[] |
getByteArray(String key, byte[] deflt) |
abstract |
|
|
|
|
double |
getDouble(String key, double deflt) |
abstract |
|
|
|
|
float |
getFloat(String key, float deflt) |
abstract |
|
|
|
|
int |
getInt(String key, int deflt) |
abstract |
|
|
|
|
long |
getLong(String key, long deflt) |
|
|
|
static |
|
void |
importPreferences(InputStream istream) |
abstract |
|
|
|
|
boolean |
isUserNode() |
abstract |
|
|
|
|
String[] |
keys() |
abstract |
|
|
|
|
String |
name() |
abstract |
|
|
|
|
Preferences |
node(String path) |
abstract |
|
|
|
|
boolean |
nodeExists(String path) |
abstract |
|
|
|
|
Preferences |
parent() |
abstract |
|
|
|
|
void |
put(String key, String value) |
abstract |
|
|
|
|
void |
putBoolean(String key, boolean value) |
abstract |
|
|
|
|
void |
putByteArray(String key, byte[] value) |
abstract |
|
|
|
|
void |
putDouble(String key, double value) |
abstract |
|
|
|
|
void |
putFloat(String key, float value) |
abstract |
|
|
|
|
void |
putInt(String key, int value) |
abstract |
|
|
|
|
void |
putLong(String key, long value) |
abstract |
|
|
|
|
void |
remove(String key) |
abstract |
|
|
|
|
void |
removeNode() |
abstract |
|
|
|
|
void |
removeNodeChangeListener(NodeChangeListener ncl) |
abstract |
|
|
|
|
void |
removePreferenceChangeListener(PreferenceChangeListener pcl) |
abstract |
|
|
|
|
void |
sync() |
|
|
|
static |
|
Preferences |
systemNodeForPackage(Class<?> c) |
|
|
|
static |
|
Preferences |
systemRoot() |
abstract |
|
|
|
|
String |
toString() |
|
|
|
static |
|
Preferences |
userNodeForPackage(Class<?> c) |
|
|
|
static |
|
Preferences |
userRoot() |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Fields
protected
final
Object
lock
The object used to lock this node.
protected
boolean
newNode
This field is true if this node is created while it doesn't exist in the
backing store. This field's default value is false, and it is checked when
the node creation is completed, and if it is true, the node change event
will be fired for this node's parent.
Protected Constructors
Construct a new
AbstractPreferences
instance using given
parent node and node name.
Parameters
parent
| the parent node of this node, can be null, which means this
node is root |
name
| the name of this node, can be empty(""), which means this
node is root |
Public Methods
public
String
absolutePath()
Get this preference node's absolute path string.
Returns
- this preference node's absolute path string.
public
void
addNodeChangeListener(NodeChangeListener ncl)
Register an
NodeChangeListener
instance for this node, which
will receive
NodeChangeEvent
.
NodeChangeEvent
will
be produced when direct child node is added to or removed from this node.
Parameters
ncl
| the given listener to be registered |
Register an
PreferenceChangeListener
instance for this node, which
will receive
PreferenceChangeEvent
.
PreferenceChangeEvent
will
be produced when preference is added to, removed from or updated for this node.
Parameters
pcl
| the given listener to be registered |
public
String[]
childrenNames()
Return names of all children of this node, or empty string if this node
has no children.
Returns
- names of all children of this node
public
void
clear()
Remove all preferences of this node.
public
void
exportNode(OutputStream ostream)
Export all preferences of this node to the given output stream in XML
document.
This XML document has the following DOCTYPE declaration:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
And the UTF-8 encoding will be used. Please note that this node is not
thread-safe, which is an exception of this class.
Parameters
ostream
| the output stream to export the XML |
public
void
exportSubtree(OutputStream ostream)
Export all preferences of this node and its all descendants to the given
output stream in XML document.
This XML document has the following DOCTYPE declaration:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
*
And the UTF-8 encoding will be used. Please note that this node is not
thread-safe, which is an exception of this class.
Parameters
ostream
| the output stream to export the XML |
public
void
flush()
Force the updates to this node and its descendants to the backing store.
If this node has been removed, then the invocation of this method only
flush this node without descendants.
Return the string value mapped to the given key, or default value if no
value is mapped or backing store is unavailable.
Some implementations may store default values in backing stores. In this case,
if there is no value mapped to the given key, the stored default value is
returned.
Parameters
key
| the preference key |
deflt
| the default value, which will be returned if no value is
mapped to the given key or backing store unavailable |
Returns
- the preference value mapped to the given key, or default value if
no value is mapped or backing store unavailable
public
boolean
getBoolean(String key, boolean deflt)
Return the boolean value mapped to the given key, or default value if no
value is mapped, backing store is unavailable, or the value is invalid.
The valid value is string equals "true", which represents true, or "false",
which represents false, case is ignored.
Some implementations may store default values in backing stores. In this case,
if there is no value mapped to the given key, the stored default value is
returned.
Parameters
key
| the preference key |
deflt
| the default value, which will be returned if no value is
mapped to the given key, backing store unavailable or value
is invalid |
Returns
- the boolean value mapped to the given key, or default value if
no value is mapped, backing store unavailable or value is invalid
public
byte[]
getByteArray(String key, byte[] deflt)
Return the byte array value mapped to the given key, or default value if no
value is mapped, backing store is unavailable, or the value is invalid string.
The valid value string is Base64 encoded binary data. The Base64 encoding
is as defined in RFC 2045,
section 6.8.
Some implementations may store default values in backing stores. In this case,
if there is no value mapped to the given key, the stored default value is
returned.
Parameters
key
| the preference key |
deflt
| the default value, which will be returned if no value is
mapped to the given key, backing store unavailable or value
is invalid |
Returns
- the byte array value mapped to the given key, or default value if
no value is mapped, backing store unavailable or value is invalid
public
double
getDouble(String key, double deflt)
Return the double value mapped to the given key, or default value if no
value is mapped, backing store is unavailable, or the value is invalid string.
The valid value string can be converted to double number by
Double.parseDouble(String).
Some implementations may store default values in backing stores. In this case,
if there is no value mapped to the given key, the stored default value is
returned.
Parameters
key
| the preference key |
deflt
| the default value, which will be returned if no value is
mapped to the given key, backing store unavailable or value
is invalid |
Returns
- the double value mapped to the given key, or default value if
no value is mapped, backing store unavailable or value is invalid
public
float
getFloat(String key, float deflt)
Return the float value mapped to the given key, or default value if no
value is mapped, backing store is unavailable, or the value is invalid string.
The valid value string can be converted to float number by
Float.parseFloat(String).
Some implementations may store default values in backing stores. In this case,
if there is no value mapped to the given key, the stored default value is
returned.
Parameters
key
| the preference key |
deflt
| the default value, which will be returned if no value is
mapped to the given key, backing store unavailable or value
is invalid |
Returns
- the float value mapped to the given key, or default value if
no value is mapped, backing store unavailable or value is invalid
public
int
getInt(String key, int deflt)
Return the float value mapped to the given key, or default value if no
value is mapped, backing store is unavailable, or the value is invalid string.
The valid value string can be converted to integer by
Integer.parseInt(String).
Some implementations may store default values in backing stores. In this case,
if there is no value mapped to the given key, the stored default value is
returned.
Parameters
key
| the preference key |
deflt
| the default value, which will be returned if no value is
mapped to the given key, backing store unavailable or value
is invalid |
Returns
- the integer value mapped to the given key, or default value if
no value is mapped, backing store unavailable or value is invalid
public
long
getLong(String key, long deflt)
Return the long value mapped to the given key, or default value if no
value is mapped, backing store is unavailable, or the value is invalid string.
The valid value string can be converted to long integer by
Long.parseLong(String).
Some implementations may store default values in backing stores. In this case,
if there is no value mapped to the given key, the stored default value is
returned.
Parameters
key
| the preference key |
deflt
| the default value, which will be returned if no value is
mapped to the given key, backing store unavailable or value
is invalid |
Returns
- the long value mapped to the given key, or default value if
no value is mapped, backing store unavailable or value is invalid
public
boolean
isUserNode()
Return true if this is a user preferences, false if this is a system
preferences
Returns
- true if this is a user preferences, false if this is a
system preferences
Return all preferences keys stored in this node, or empty array if no
key is found.
Returns
- all preferences keys in this node
public
String
name()
Return name of this node.
Return the preferences node with the given path name. The path name can
be relative or absolute. The dictated preferences and its ancestors will
be created if they do not exist.
The path is treated as relative to this node if it doesn't start with
slash, or as absolute otherwise.
Parameters
name
| the path name of dictated preferences |
Returns
- the dictated preferences node
public
boolean
nodeExists(String name)
Return the preferences node with the given path name. The path is treated
as relative to this node if it doesn't start with slash, or as absolute
otherwise.
Please note that if this node has been removed, invocation of this node
will throw IllegalStateException
except the given path is
empty string, which will return false.
Parameters
name
| the path name of dictated preferences |
Returns
- true if the dictated preferences node exists
Return the parent preferences node of this node, or null if this node is root.
Returns
- the parent preferences node of this node.
public
void
put(String key, String value)
Add new preferences to this node using given key and value, or update
value if preferences with given key has already existed.
Parameters
key
| the preferences key to be added or be updated |
value
| the preferences value for the given key |
public
void
putBoolean(String key, boolean value)
Add new preferences to this node using given key and string form of given
value, or update value if preferences with given key has already existed.
Parameters
key
| the preferences key to be added or be updated |
value
| the preferences value for the given key |
public
void
putByteArray(String key, byte[] value)
Add new preferences to this node using given key and string form of given
value, or update value if preferences with given key has already existed.
The string form of value is the Base64 encoded binary data of the given
byte array. The Base64 encoding is as defined in
RFC 2045, section 6.8.
Parameters
key
| the preferences key to be added or be updated |
value
| the preferences value for the given key |
public
void
putDouble(String key, double value)
Add new preferences to this node using given key and string form of given
value, or update value if preferences with given key has already existed.
The string form of given value is the result of invoking
Double.toString(double)
Parameters
key
| the preferences key to be added or be updated |
value
| the preferences value for the given key |
public
void
putFloat(String key, float value)
Add new preferences to this node using given key and string form of given
value, or update value if preferences with given key has already existed.
The string form of given value is the result of invoking
Float.toString(float)
Parameters
key
| the preferences key to be added or be updated |
value
| the preferences value for the given key |
public
void
putInt(String key, int value)
Add new preferences to this node using given key and string form of given
value, or update value if preferences with given key has already existed.
The string form of given value is the result of invoking
Integer.toString(int)
Parameters
key
| the preferences key to be added or be updated |
value
| the preferences value for the given key |
public
void
putLong(String key, long value)
Add new preferences to this node using given key and string form of given
value, or update value if preferences with given key has already existed.
The string form of given value is the result of invoking
Long.toString(long)
Parameters
key
| the preferences key to be added or be updated |
value
| the preferences value for the given key |
public
void
remove(String key)
Remove the preferences mapped to the given key from this node.
Parameters
key
| the given preferences key to removed |
public
void
removeNode()
Remove this preferences node and its all descendants. The removal maybe
won't be persisted until the
flush()
method is invoked.
public
void
removeNodeChangeListener(NodeChangeListener ncl)
Remove the given
NodeChangeListener
instance from this node.
Parameters
ncl
| the given listener to be removed |
Remove the given
PreferenceChangeListener
instance from this node.
Parameters
pcl
| the given listener to be removed |
public
void
sync()
Synchronize this preferences node and its descendants' data with the back
end preferences store. The changes of back end should be reflect by this
node and its descendants, meanwhile, the changes of this node and descendants
should be persisted.
public
String
toString()
Return a string description of this node. The format is "User/System
Preference Node: " followed by this node's absolute path.
Returns
- a string description of this node
Protected Methods
Return arrays of all cached children node.
Returns
- arrays of all cached children node.
Return the child preference node with the given name, and create new one if
it does not exist. Invoker of this method should assure that the given name
are valid as well as this node is not removed. Invocation of this method
implies that the node with given name is not cached(or, has been removed.)
If the named node has just been removed, implementation of this method must
create a new one instead of reactivated the removed one.
The new creation is not required to be persisted immediately until the flush
method is invoked.
protected
abstract
String[]
childrenNamesSpi()
Return names of this node's all children , or empty array if this node has
no child. Cached children name is not required to be returned.
Returns
- names of this node's all children
protected
abstract
void
flushSpi()
Flush changes of this node to the backing store. This method should only
flush this node, and should not include the descendant nodes. The
implementation which want to flush all nodes at once should override
flush() method.
Return the child node with given name, or null if it doesn't exist. The
given name must be valid and this node cannot be removed. Invocation of
this method implies that the node with given name is not cached(or, has
been removed.)
Parameters
name
| the given child name to be got |
Returns
- the child node with given name, or null if it doesn't exist
protected
abstract
String
getSpi(String key)
Get the preference value mapped to the given key. Invoker of this method
should assure that given key are valid as well as this node is not removed.
This method should not throw exceptions, but if it does, the invoker should
catch it and deal with it as null return value.
Parameters
key
| the given key to be searched for |
Returns
- the preference value mapped to the given key
protected
boolean
isRemoved()
Return true if and only if this node has been removed by invoking
removeNode.
Returns
- true if and only if this node has been removed by invoking
removeNode
protected
abstract
String[]
keysSpi()
Return all keys of this node's preferences, or empty array if no preference
found on this node. Invoker of this method should assure that this node is
not removed.
Returns
- all keys of this node's preferences
protected
abstract
void
putSpi(String name, String value)
Put the given key-value pair into this node. Invoker of this method should
assure that both the given values are valid as well as this node
is not removed.
Parameters
name
| the given preference key |
value
| the given preference value
|
protected
abstract
void
removeNodeSpi()
Remove this node from the preference hierarchy tree. The invoker of this
method should assure that this node has no child node, which means the
Preferences.removeNode() should invoke
this method multi-times in bottom-up pattern. The removal is not required
to be persisted at once until the it is flushed.
protected
abstract
void
removeSpi(String key)
Remove the preference with the given key. Invoker of this method
should assure that given key are valid as well as this node is not removed.
Parameters
key
| the given key to removed
|
protected
abstract
void
syncSpi()
Synchronize this node with the backing store. This method should only
synchronize this node, and should not include the descendant nodes. The
implementation which want to synchronize all nodes at once should override
sync() method.