| java.lang.Object | |
| ↳ | java.util.prefs.Preferences |
 Known Direct Subclasses
|
An instance of the class Preferences represents one node in a
preference tree, which provides a mechanism to store and access configuration
data in a hierarchical way. Two hierarchy trees are maintained, one for
system preferences shared by all users and the other for user preferences
specific to the user. Preferences hierarchy trees and data are stored
in an implementation-dependent back-end.
Every node has one name and one unique absolute path following the same notational conventions as directories in a file system. The root node's name is "", and other node name strings cannot contain the slash character and cannot be empty. The root node's absolute path is "/", and all other nodes' absolute paths are constructed in the standard way: <parent's absolute path> + "/" + <node's name>. Since the set of nodes forms a tree with the root node at its base, all absolute paths start with the slash character. Every node has one relative path to each of its ancestors. The relative path doesn't start with slash: it equals the node's absolute path with leading substring removed corresponding to the ancestor's absolute path and a slash.
Modification to preferences data may be asynchronous, which means that
preference update method calls may return immediately instead of blocking.
The flush() and sync() methods force the back-end to
synchronously perform all pending updates, but the implementation is
permitted to perform the modifications on the underlying back-end data
at any time between the moment the request is made and the moment the
flush() or sync() method returns. Please note that if the JVM
exits normally, the implementation must assure all modifications are
persisted implicitly.
When invoking a method that retrieves preferences, the user must provide
a default value. The default value is returned when the preferences cannot
be found or the back-end is unavailable. Some other methods will throw
BackingStoreException when the back-end is unavailable.
Preferences can be exported to and imported from an XML files. These documents must have an XML DOCTYPE declaration:
Developers
There must be a concrete PreferencesFactory type for every concrete
Preferences type developed. Every J2SE implementation must provide a
default implementation for every supported platform, and must also provide a
means of replacing the default implementation. This implementation uses the
system property java.util.prefs.PreferencesFactory to determine which
preferences implementation to use.
The methods of this class are thread-safe. If multiple JVMs are using the same back-end concurrently, the back-end won't be corrupted, but no other behavior guarantees are made.
| Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| int | MAX_KEY_LENGTH | Maximum size in characters allowed for a preferences key. | |||||||||
| int | MAX_NAME_LENGTH | Maximum size in characters allowed for a preferences name. | |||||||||
| int | MAX_VALUE_LENGTH | Maximum size in characters allowed for a preferences value. | |||||||||
| Protected Constructors | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Default constructor, for use by subclasses only.
| |||||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Gets the absolute path string of this preference node.
| |||||||||||
Registers a
NodeChangeListener instance for this node, which will
handle NodeChangeEvents.
| |||||||||||
Registers a
PreferenceChangeListener instance for this node,
which will handle PreferenceChangeEvents.
| |||||||||||
Returns the names of all children of this node or an empty array if this
node has no children.
| |||||||||||
Removes all preferences of this node.
| |||||||||||
Exports all of the preferences of this node to a XML document using the
given output stream.
| |||||||||||
Exports all of the preferences of this node and all its descendants to a
XML document using the given output stream.
| |||||||||||
Forces all pending updates to this node and its descendants to be
persisted in the backing store.
| |||||||||||
Gets the
String value mapped to the given key or its default
value if no value is mapped or no backing store is available.
| |||||||||||
Gets the
boolean value mapped to the given key or its default
value if no value is mapped, if the backing store is unavailable, or if
the value is invalid.
| |||||||||||
Gets the
byte array value mapped to the given key or its default
value if no value is mapped, if the backing store is unavailable, or if
the value is an invalid string.
| |||||||||||
Gets the
double value mapped to the given key or its default
value if no value is mapped, if the backing store is unavailable, or if
the value is an invalid string.
| |||||||||||
Gets the
float value mapped to the given key or its default value
if no value is mapped, if the backing store is unavailable, or if the
value is an invalid string.
| |||||||||||
Gets the
int value mapped to the given key or its default value
if no value is mapped, if the backing store is unavailable, or if the
value is an invalid string.
| |||||||||||
Gets the
long value mapped to the given key or its default value
if no value is mapped, if the backing store is unavailable, or if the
value is an invalid string.
| |||||||||||
Imports all the preferences from an XML document using the given input
stream.
| |||||||||||
Returns whether this is a user preference node.
| |||||||||||
Returns all preference keys stored in this node or an empty array if no
key was found.
| |||||||||||
Returns the name of this node.
| |||||||||||
Returns the preference node with the given path name.
| |||||||||||
Returns whether the preference node with the given path name exists.
| |||||||||||
Returns the parent preference node of this node or
null if this
node is the root node.
| |||||||||||
Adds a new preference to this node using the given key and value or
updates the value if a preference with the given key already exists.
| |||||||||||
Adds a new preference with a
boolean value to this node using the
given key and value or updates the value if a preference with the given
key already exists.
| |||||||||||
Adds a new preference to this node using the given key and the string
form of the given value or updates the value if a preference with the
given key already exists.
| |||||||||||
Adds a new preference to this node using the given key and
double
value or updates the value if a preference with the
given key already exists.
| |||||||||||
Adds a new preference to this node using the given key and
float
value or updates the value if a preference with the
given key already exists.
| |||||||||||
Adds a new preference to this node using the given key and
int
value or updates the value if a preference with the
given key already exists.
| |||||||||||
Adds a new preference to this node using the given key and
long
value or updates the value if a preference with the
given key already exists.
| |||||||||||
Removes the preference mapped to the given key from this node.
| |||||||||||
Removes this preference node with all its descendants.
| |||||||||||
Removes the given
NodeChangeListener instance from this node.
| |||||||||||
Removes the given
PreferenceChangeListener instance from this
node.
| |||||||||||
Synchronizes the data of this preference node and its descendants with
the back-end preference store.
| |||||||||||
Legacy code; do not use.
| |||||||||||
Legacy code; do not use.
| |||||||||||
Returns a string representation of this node.
| |||||||||||
Legacy code; do not use.
| |||||||||||
Legacy code; do not use.
| |||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
From class
java.lang.Object
| |||||||||||
Maximum size in characters allowed for a preferences key.
Maximum size in characters allowed for a preferences name.
Maximum size in characters allowed for a preferences value.
Gets the absolute path string of this preference node.
Registers a NodeChangeListener instance for this node, which will
handle NodeChangeEvents. NodeChangeEvents will be fired
when a child node has been added to or removed from this node.
| ncl | the listener to be registered. |
|---|
| NullPointerException | if the given listener is null. |
|---|---|
| IllegalStateException | if this node has been removed. |
Registers a PreferenceChangeListener instance for this node,
which will handle PreferenceChangeEvents. PreferenceChangeEvents will be fired when a preference has been added
to, removed from, or updated for this node.
| pcl | the listener to be registered. |
|---|
| NullPointerException | if the given listener is null. |
|---|---|
| IllegalStateException | if this node has been removed. |
Returns the names of all children of this node or an empty array if this node has no children.
| BackingStoreException | if backing store is unavailable or causes an operation failure. |
|---|---|
| IllegalStateException | if this node has been removed. |
Removes all preferences of this node.
| BackingStoreException | if backing store is unavailable or causes an operation failure. |
|---|---|
| IllegalStateException | if this node has been removed. |
Exports all of the preferences of this node to a XML document using the given output stream.
This XML document uses the UTF-8 encoding and is written according to the DTD in its DOCTYPE declaration, which is the following:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">Please note that (unlike the methods of this class that don't concern serialization), this call is not thread-safe.
| ostream | the output stream to write the XML-formatted data to. |
|---|
| IOException | if an error occurs while exporting. |
|---|---|
| BackingStoreException | if the backing store is unavailable or causes an operation failure. |
| IllegalStateException | if this node has been removed. |
Exports all of the preferences of this node and all its descendants to a XML document using the given output stream.
This XML document uses the UTF-8 encoding and is written according to the DTD in its DOCTYPE declaration, which is the following:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">Please note that (unlike the methods of this class that don't concern serialization), this call is not thread-safe.
| ostream | the output stream to write the XML-formatted data to. |
|---|
| IOException | if an error occurs while exporting. |
|---|---|
| BackingStoreException | if the backing store is unavailable or causes an operation failure. |
| IllegalStateException | if this node has been removed. |
Forces all pending updates to this node and its descendants to be persisted in the backing store.
If this node has been removed, the invocation of this method only flushes this node, not its descendants.
| BackingStoreException | if the backing store is unavailable or causes an operation failure. |
|---|
Gets the String value mapped to the given key or its default
value if no value is mapped or no backing store is available.
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.
| key | the preference key. |
|---|---|
| deflt | the default value, which will be returned if no value is mapped to the given key or no backing store is available. |
| IllegalStateException | if this node has been removed. |
|---|---|
| NullPointerException | if the parameter key is null.
|
Gets the boolean value mapped to the given key or its default
value if no value is mapped, if the backing store is unavailable, or if
the value is invalid.
The only valid values are the String "true", which represents
true and "false", which represents false, ignoring case.
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.
| key | the preference key. |
|---|---|
| deflt | the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid. |
| IllegalStateException | if this node has been removed. |
|---|---|
| NullPointerException | if the parameter key is null.
|
Gets the byte array value mapped to the given key or its default
value if no value is mapped, if the backing store is unavailable, or if
the value is an invalid string.
To be valid, the value string must be 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.
| key | the preference key. |
|---|---|
| deflt | the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid. |
| IllegalStateException | if this node has been removed. |
|---|---|
| NullPointerException | if the parameter key is null.
|
Gets the double value mapped to the given key or its default
value if no value is mapped, if the backing store is unavailable, or if
the value is an invalid string.
To be valid, the value string must be a string that can be converted to a
double 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.
| key | the preference key. |
|---|---|
| deflt | the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid. |
| IllegalStateException | if this node has been removed. |
|---|---|
| NullPointerException | if the parameter key is null.
|
Gets the float value mapped to the given key or its default value
if no value is mapped, if the backing store is unavailable, or if the
value is an invalid string.
To be valid, the value string must be a string that can be converted to a
float 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.
| key | the preference key. |
|---|---|
| deflt | the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid. |
| IllegalStateException | if this node has been removed. |
|---|---|
| NullPointerException | if the parameter key is null.
|
Gets the int value mapped to the given key or its default value
if no value is mapped, if the backing store is unavailable, or if the
value is an invalid string.
To be valid, the value string must be a string that can be converted to
an int 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.
| key | the preference key. |
|---|---|
| deflt | the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid. |
| IllegalStateException | if this node has been removed. |
|---|---|
| NullPointerException | if the parameter key is null.
|
Gets the long value mapped to the given key or its default value
if no value is mapped, if the backing store is unavailable, or if the
value is an invalid string.
To be valid, the value string must be a string that can be converted to a
long 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.
| key | the preference key. |
|---|---|
| deflt | the default value, which will be returned if no value is mapped to the given key, if the backing store is unavailable, or if the value is invalid. |
| IllegalStateException | if this node has been removed. |
|---|---|
| NullPointerException | if the parameter key is null.
|
Imports all the preferences from an XML document using the given input stream.
This XML document uses the UTF-8 encoding and must be written according to the DTD in its DOCTYPE declaration, which must be the following:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">Please note that (unlike the methods of this class that don't concern serialization), this call is not thread-safe.
| istream | the input stream to read the data from. |
|---|
| InvalidPreferencesFormatException | if the data read from the given input stream is not from a valid XML document. |
|---|---|
| IOException | if an error occurs while importing. |
Returns whether this is a user preference node.
true, if this is a user preference node, false if
this is a system preference node.
Returns all preference keys stored in this node or an empty array if no key was found.
| BackingStoreException | if the backing store is unavailable or causes an operation failure. |
|---|---|
| IllegalStateException | if this node has been removed. |
Returns the name of this node.
Returns the preference node with the given path name. The path name can be relative or absolute. The requested node 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 a slash, otherwise it will be treated as an absolute path.
| path | the path name of the requested preference node. |
|---|
| IllegalStateException | if this node has been removed. |
|---|---|
| IllegalArgumentException | if the path name is invalid. |
| NullPointerException | if the given path is null.
|
Returns whether the preference node with the given path name exists. The path is treated as relative to this node if it doesn't start with a slash, otherwise it is treated as an absolute path.
Please note that if this node has been removed, an invocation of this
node will throw an IllegalStateException unless the given path is
an empty string, which will return false.
| path | the path name of the preference node to query. |
|---|
true, if the queried preference node exists, false
otherwise.| IllegalStateException | if this node has been removed and the path is not an empty string. |
|---|---|
| IllegalArgumentException | if the path name is invalid. |
| NullPointerException | if the given path is null. |
| BackingStoreException | if the backing store is unavailable or causes an operation failure. |
Returns the parent preference node of this node or null if this
node is the root node.
| IllegalStateException | if this node has been removed. |
|---|
Adds a new preference to this node using the given key and value or updates the value if a preference with the given key already exists.
| key | the preference key to be added or updated. |
|---|---|
| value | the preference value for the given key. |
| NullPointerException | if the given key or value is null. |
|---|---|
| IllegalArgumentException | if the given key's length is bigger than MAX_KEY_LENGTH or the value's length is bigger than MAX_VALUE_LENGTH. |
| IllegalStateException | if this node has been removed. |
Adds a new preference with a boolean value to this node using the
given key and value or updates the value if a preference with the given
key already exists.
| key | the preference key to be added or updated. |
|---|---|
| value | the preference boolean value for the given key. |
| NullPointerException | if the given key is null. |
|---|---|
| IllegalArgumentException | if the given key's length is bigger than MAX_KEY_LENGTH. |
| IllegalStateException | if this node has been removed. |
Adds a new preference to this node using the given key and the string form of the given value or updates the value if a preference with the given key already exists.
The string form of the value is the Base64-encoded binary data of the given byte array. The Base64 encoding is as defined in RFC 2045, section 6.8.
| key | the preference key to be added or updated. |
|---|---|
| value | the preference value for the given key. |
| NullPointerException | if the given key or value is null. |
|---|---|
| IllegalArgumentException | if the given key's length is bigger than MAX_KEY_LENGTH or value's length is bigger than three
quarters of MAX_KEY_LENGTH. |
| IllegalStateException | if this node has been removed. |
Adds a new preference to this node using the given key and double
value or updates the value if a preference with the
given key already exists.
The value is stored in its string form, which is the result of invoking
Double.toString(double).
| key | the preference key to be added or updated. |
|---|---|
| value | the preference value for the given key. |
| NullPointerException | if the given key is null. |
|---|---|
| IllegalArgumentException | if the given key's length is bigger than MAX_KEY_LENGTH. |
| IllegalStateException | if this node has been removed. |
Adds a new preference to this node using the given key and float
value or updates the value if a preference with the
given key already exists.
The value is stored in its string form, which is the result of invoking
Float.toString(float).
| key | the preference key to be added or updated. |
|---|---|
| value | the preference value for the given key. |
| NullPointerException | if the given key is null. |
|---|---|
| IllegalArgumentException | if the given key's length is bigger than MAX_KEY_LENGTH. |
| IllegalStateException | if this node has been removed. |
Adds a new preference to this node using the given key and int
value or updates the value if a preference with the
given key already exists.
The value is stored in its string form, which is the result of invoking
Integer.toString(int).
| key | the preference key to be added or updated. |
|---|---|
| value | the preference value for the given key. |
| NullPointerException | if the given key is null. |
|---|---|
| IllegalArgumentException | if the given key's length is bigger than MAX_KEY_LENGTH. |
| IllegalStateException | if this node has been removed. |
Adds a new preference to this node using the given key and long
value or updates the value if a preference with the
given key already exists.
The value is stored in its string form, which is the result of invoking
Long.toString(long).
| key | the preference key to be added or updated. |
|---|---|
| value | the preference value for the given key. |
| NullPointerException | if the given key is null. |
|---|---|
| IllegalArgumentException | if the given key's length is bigger than MAX_KEY_LENGTH. |
| IllegalStateException | if this node has been removed. |
Removes the preference mapped to the given key from this node.
| key | the key of the preference to be removed. |
|---|
| NullPointerException | if the given key is null. |
|---|---|
| IllegalStateException | if this node has been removed. |
Removes this preference node with all its descendants. The removal won't
necessarily be persisted until the method flush() is invoked.
| BackingStoreException | if the backing store is unavailable or causes an operation failure. |
|---|---|
| IllegalStateException | if this node has been removed. |
| UnsupportedOperationException | if this is a root node. |
Removes the given NodeChangeListener instance from this node.
| ncl | the listener to be removed. |
|---|
| IllegalArgumentException | if the given listener is null. |
|---|---|
| IllegalStateException | if this node has been removed. |
Removes the given PreferenceChangeListener instance from this
node.
| pcl | the listener to be removed. |
|---|
| IllegalArgumentException | if the given listener is null. |
|---|---|
| IllegalStateException | if this node has been removed. |
Synchronizes the data of this preference node and its descendants with the back-end preference store. Any changes found in the back-end data should be reflected in this node and its descendants, and at the same time any local changes to this node and descendants should be persisted.
| BackingStoreException | if the backing store is unavailable or causes an operation failure. |
|---|---|
| IllegalStateException | if this node has been removed. |
Legacy code; do not use. On Android, the Preference nodes
corresponding to the "system" and "user" preferences are stored in sections
of the file system that are inaccessible to apps. Further, allowing apps to set
"system wide" preferences is contrary to android's security model.
Returns the system preference node for the package of the given class.
The absolute path of the returned node is one slash followed by the given
class's full package name, replacing each period character ('.') with
a slash. For example, the absolute path of the preference associated with
the class Object would be "/java/lang". As a special case, the unnamed
package is associated with a preference node "/<unnamed>". This
method will create the node and its ancestors as needed. Any nodes created
by this method won't necessarily be persisted until the method flush() is invoked.
| c | the given class. |
|---|
| NullPointerException | if the given class is null.
|
|---|
Legacy code; do not use. On Android, the Preference nodes corresponding to the "system" and "user" preferences are stored in sections of the file system that are inaccessible to apps. Further, allowing apps to set "system wide" preferences is contrary to android's security model. Returns the root node of the system preference hierarchy.
Returns a string representation of this node. The format is "User/System Preference Node: " followed by this node's absolute path.
Legacy code; do not use. On Android, the Preference nodes corresponding to the "system" and "user" preferences are stored in sections of the file system that are inaccessible to apps. Further, allowing apps to set "system wide" preferences is contrary to android's security model.
Returns the user preference node for the package of the given class.
The absolute path of the returned node is one slash followed by the given
class's full package name, replacing each period character ('.') with
a slash. For example, the absolute path of the preference associated with
the class Object would be "/java/lang". As a special case, the unnamed
package is associated with a preference node "/<unnamed>". This
method will create the node and its ancestors as needed. Any nodes created
by this method won't necessarily be persisted until the method flush() is invoked.
| NullPointerException | if the given class is null.
|
|---|
Legacy code; do not use. On Android, the Preference nodes corresponding to the "system" and "user" preferences are stored in sections of the file system that are inaccessible to apps. Further, allowing apps to set "system wide" preferences is contrary to android's security model. Returns the root node of the user preference hierarchy.