java.lang.Object | ||
java.util.prefs.Preferences |
Preferences
instance represents one node in preferences tree,
which provide a mechanisms to store and access configuration data in a
hierarchical way. Two hierarchy tree is maintained, one for system
preferences shared by all users, and the other for user preferences which is
specific for each user. Preferences hierarchy tree and data is stored
precisely in implementation-dependent backend, and user doesn't need to care
about the details.
Every node has one name and one unique absolute path in a similar way with directories in file system. The root node's name is "", and other nodes' name string cannot contains slash and cannot be empty. The root node's absolute path is "/", and other nodes' absolute path equals <parent's absolute path> + "/" + <node's name>. All absolute paths start with slash. Every node has one relative path to one of its ancestor. Relative path doesn't start with slash, and equals to absolute path when following after ancestor's absolute path and a slash.
The modification to preferences data may be asynchronous, which means they may don't block and may returns immediately, implementation can feel free to the modifications to the backend in any time until the flush() or sync() method is invoked, these two methods force synchronized updates to backend. Please note that if JVM exit normally, the implementation must assure all modifications are persisted implicitly.
User invoking methods that retrieve preferences must provide default value,
default value is returned when preferences cannot be found or backend is
unavailable. Some other methods will throw BackingStoreException
when backend is unavailable.
Preferences can be export to/import from XML files, the XML document must have the following DOCTYPE declaration:
This system URI is not really accessed by network, it is only a identification string. Visit the DTD location to see the actual format permitted.
There has to be a concrete PreferencesFactory
type for every
concrete Preferences
type developed. Every J2SE implementation
must provide a default implementation for every supported platform, and the
default implementation can be replaced in some way. This implementation uses
system property java.util.prefs.PreferencesFactory to dictate the preferences
implementation.
Methods of this class is thread-safe. If multi JVMs using same backend concurrently, the backend won't be corrupted, but no other guarantees is made.
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 |
Preferences() | ||||||
Default constructor, for use by subclasses only. |
abstract | String | absolutePath() | ||||
Get this preference node's absolute path string. | ||||||
abstract | void | addNodeChangeListener(NodeChangeListener ncl) | ||||
Register an NodeChangeListener instance for this node, which
will receive NodeChangeEvent . |
||||||
abstract | void | addPreferenceChangeListener(PreferenceChangeListener pcl) | ||||
Register an PreferenceChangeListener instance for this node, which
will receive PreferenceChangeEvent . |
||||||
abstract | String[] | childrenNames() | ||||
Return names of all children of this node, or empty string if this node has no children. | ||||||
abstract | void | clear() | ||||
Remove all preferences of this node. | ||||||
abstract | void | exportNode(OutputStream ostream) | ||||
Export all preferences of this node to the given output stream in XML document. | ||||||
abstract | void | exportSubtree(OutputStream ostream) | ||||
Export all preferences of this node and its all descendants to the given output stream in XML document. | ||||||
abstract | void | flush() | ||||
Force the updates to this node and its descendants to the backing store. | ||||||
abstract | String | get(String key, String deflt) | ||||
Return the string value mapped to the given key, or default value if no value is mapped or backing store is unavailable. | ||||||
abstract | 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. | ||||||
abstract | 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. | ||||||
abstract | 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. | ||||||
abstract | 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. | ||||||
abstract | 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. | ||||||
abstract | 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. | ||||||
static | void | importPreferences(InputStream istream) | ||||
Import all preferences from the given input stream in XML document. | ||||||
abstract | boolean | isUserNode() | ||||
Return true if this is a user preferences, false if this is a system preferences | ||||||
abstract | String[] | keys() | ||||
Return all preferences keys stored in this node, or empty array if no key is found. | ||||||
abstract | String | name() | ||||
Return name of this node. | ||||||
abstract | Preferences | node(String path) | ||||
Return the preferences node with the given path name. | ||||||
abstract | boolean | nodeExists(String path) | ||||
Return the preferences node with the given path name. | ||||||
abstract | Preferences | parent() | ||||
Return the parent preferences node of this node, or null if this node is root. | ||||||
abstract | 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. | ||||||
abstract | 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. | ||||||
abstract | 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. | ||||||
abstract | 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. | ||||||
abstract | 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. | ||||||
abstract | 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. | ||||||
abstract | 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. | ||||||
abstract | void | remove(String key) | ||||
Remove the preferences mapped to the given key from this node. | ||||||
abstract | void | removeNode() | ||||
Remove this preferences node and its all descendants. | ||||||
abstract | void | removeNodeChangeListener(NodeChangeListener ncl) | ||||
Remove the given NodeChangeListener instance from this node. |
||||||
abstract | void | removePreferenceChangeListener(PreferenceChangeListener pcl) | ||||
Remove the given PreferenceChangeListener instance from this node. |
||||||
abstract | void | sync() | ||||
Synchronize this preferences node and its descendants' data with the back end preferences store. | ||||||
static | Preferences | systemNodeForPackage(Class<?> c) | ||||
Return the system preference node for the package of given class. | ||||||
static | Preferences | systemRoot() | ||||
Return the root node for system preference hierarchy. | ||||||
abstract | String | toString() | ||||
Return a string description of this node. | ||||||
static | Preferences | userNodeForPackage(Class<?> c) | ||||
Return the user preference node for the package of given class. | ||||||
static | Preferences | userRoot() | ||||
Return the root node for user preference hierarchy. |
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.
ncl | the given listener to be registered |
---|
NullPointerException | if the given listener is null |
---|---|
IllegalStateException | if this node has been removed |
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.
pcl | the given listener to be registered |
---|
NullPointerException | if the given listener is null |
---|---|
IllegalStateException | if this node has been removed |
BackingStoreException | if backing store is unavailable or causes operation failure |
---|---|
IllegalStateException | if this node has been removed |
BackingStoreException | if backing store is unavailable or causes operation failure |
---|---|
IllegalStateException | if this node has been removed |
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.
ostream | the output stream to export the XML |
---|
IOException | if export operation caused an IOException |
---|---|
BackingStoreException | if backing store is unavailable or causes operation failure |
IllegalStateException | if this node has been removed |
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.
ostream | the output stream to export the XML |
---|
IOException | if export operation caused an IOException |
---|---|
BackingStoreException | if backing store is unavailable or causes operation failure |
IllegalStateException | if this node has been removed |
If this node has been removed, then the invocation of this method only flush this node without descendants.
BackingStoreException | if backing store is unavailable or causes operation failure |
---|
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 backing store unavailable |
IllegalStateException | if this node has been removed |
---|---|
NullPointerException | if parameter key is null |
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.
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 |
IllegalStateException | if this node has been removed |
---|---|
NullPointerException | if parameter key is null |
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.
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 |
IllegalStateException | if this node has been removed |
---|---|
NullPointerException | if parameter key is null |
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.
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 |
IllegalStateException | if this node has been removed |
---|---|
NullPointerException | if parameter key is null |
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.
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 |
IllegalStateException | if this node has been removed |
---|---|
NullPointerException | if parameter key is null |
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.
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 |
IllegalStateException | if this node has been removed |
---|---|
NullPointerException | if parameter key is null |
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.
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 |
IllegalStateException | if this node has been removed |
---|---|
NullPointerException | if parameter key is null |
This XML document has the following DOCTYPE declaration:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">* Please note that this node is not thread-safe, which is an exception of this class.
istream | the given input stream to read data |
---|
InvalidPreferencesFormatException | if the data read from given input stream is not valid XML document |
---|---|
IOException | if import operation caused an IOException |
SecurityException | if RuntimePermission("preferences") is denied
by a SecurityManager
|
BackingStoreException | if backing store is unavailable or causes operation failure |
---|---|
IllegalStateException | if this node has been removed |
The path is treated as relative to this node if it doesn't start with slash, or as absolute otherwise.
path | the path name of dictated preferences |
---|
IllegalStateException | if this node has been removed. |
---|---|
IllegalArgumentException | if the path name is invalid. |
NullPointerException | if given path is null. |
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.
path | the path name of dictated preferences |
---|
IllegalStateException | if this node has been removed and the path is not empty string. |
---|---|
IllegalArgumentException | if the path name is invalid. |
NullPointerException | if given path is null. |
BackingStoreException | if backing store is unavailable or causes operation failure |
IllegalStateException | if this node has been removed |
---|
key | the preferences key to be added or be updated |
---|---|
value | the preferences 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 |
key | the preferences key to be added or be updated |
---|---|
value | the preferences 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 |
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.
key | the preferences key to be added or be updated |
---|---|
value | the preferences 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 |
The string form of given value is the result of invoking Double.toString(double)
key | the preferences key to be added or be updated |
---|---|
value | the preferences 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 |
The string form of given value is the result of invoking Float.toString(float)
key | the preferences key to be added or be updated |
---|---|
value | the preferences 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 |
The string form of given value is the result of invoking Integer.toString(int)
key | the preferences key to be added or be updated |
---|---|
value | the preferences 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 |
The string form of given value is the result of invoking Long.toString(long)
key | the preferences key to be added or be updated |
---|---|
value | the preferences 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 |
key | the given preferences key to removed |
---|
NullPointerException | if the given key is null |
---|---|
IllegalStateException | if this node has been removed |
flush()
method is invoked.
BackingStoreException | if backing store is unavailable or causes operation failure |
---|---|
IllegalStateException | if this node has been removed |
UnsupportedOperationException | if this is a root node |
NodeChangeListener
instance from this node.
ncl | the given listener to be removed |
---|
IllegalArgumentException | if the given listener |
---|---|
IllegalStateException | if this node has been removed |
PreferenceChangeListener
instance from this node.
pcl | the given listener to be removed |
---|
IllegalArgumentException | if the given listener |
---|---|
IllegalStateException | if this node has been removed |
BackingStoreException | if backing store is unavailable or causes operation failure |
---|---|
IllegalStateException | if this node has been removed |
Object
has absolute path like "/java/lang". As a special case, the unnamed
package is associated with preference node "/".
This method will create node and its ancestors if needed, and the new
created nodes maybe won't be persisted until the flush()
is invoked.
Parameters
c
the given class
Returns
- the system preference node for the package of given class.
Throws
NullPointerException
if the given class is null
SecurityException
if RuntimePermission("preferences")
is denied
by a SecurityManager
SecurityException | if RuntimePermission("preferences") is denied
by a SecurityManager
|
---|
Object
has absolute path like "/java/lang". As a special case, the unnamed
package is associated with preference node "/".
This method will create node and its ancestors if needed, and the new
created nodes maybe won't be persisted until the flush()
is invoked.
Parameters
c
the given class
Returns
- the user preference node for the package of given class.
Throws
NullPointerException
if the given class is null
SecurityException
if RuntimePermission("preferences")
is denied
by a SecurityManager
SecurityException | if RuntimePermission("preferences") is denied
by a SecurityManager
|
---|
Copyright 2007 Google Inc. | Build 0.9_r1-98467 - 14 Aug 2008 18:56 |