public abstract class

Preferences

extends Object
java.lang.Object
   ↳ java.util.prefs.Preferences
Known Direct Subclasses

Class Overview

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:
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 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 detemine 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.

See Also

Summary

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
Preferences()
Default constructor, for use by subclasses only.
Public Methods
abstract String absolutePath()
Gets the absolute path string of this preference node.
abstract void addNodeChangeListener(NodeChangeListener ncl)
Registers a NodeChangeListener instance for this node, which will handle NodeChangeEvents.
abstract void addPreferenceChangeListener(PreferenceChangeListener pcl)
Registers a PreferenceChangeListener instance for this node, which will handle PreferenceChangeEvents.
abstract String[] childrenNames()
Returns the names of all children of this node or an empty array if this node has no children.
abstract void clear()
Removes all preferences of this node.
abstract void exportNode(OutputStream ostream)
Exports all of the preferences of this node to a XML document using the given output stream.
abstract void exportSubtree(OutputStream ostream)
Exports all of the preferences of this node and all its descendants to a XML document using the given output stream.
abstract void flush()
Forces all pending updates to this node and its descendants to be persisted in the backing store.
abstract String get(String key, String deflt)
Gets the String value mapped to the given key or its default value if no value is mapped or no backing store is available.
abstract boolean getBoolean(String key, boolean deflt)
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.
abstract byte[] getByteArray(String key, byte[] deflt)
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.
abstract double getDouble(String key, double deflt)
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.
abstract float getFloat(String key, float deflt)
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.
abstract int getInt(String key, int deflt)
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.
abstract long getLong(String key, long deflt)
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.
static void importPreferences(InputStream istream)
Imports all the preferences from an XML document using the given input stream.
abstract boolean isUserNode()
Returns whether this is a user preference node.
abstract String[] keys()
Returns all preference keys stored in this node or an empty array if no key was found.
abstract String name()
Returns the name of this node.
abstract Preferences node(String path)
Returns the preference node with the given path name.
abstract boolean nodeExists(String path)
Returns whether the preference node with the given path name exists.
abstract Preferences parent()
Returns the parent preference node of this node or null if this node is the root node.
abstract void put(String key, String value)
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.
abstract void putBoolean(String key, boolean value)
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.
abstract void putByteArray(String key, byte[] value)
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.
abstract void putDouble(String key, double value)
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.
abstract void putFloat(String key, float value)
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.
abstract void putInt(String key, int value)
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.
abstract void putLong(String key, long value)
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.
abstract void remove(String key)
Removes the preference mapped to the given key from this node.
abstract void removeNode()
Removes this preference node with all its descendants.
abstract void removeNodeChangeListener(NodeChangeListener ncl)
Removes the given NodeChangeListener instance from this node.
abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)
Removes the given PreferenceChangeListener instance from this node.
abstract void sync()
Synchronizes the data of this preference node and its descendants with the back-end preference store.
static Preferences systemNodeForPackage(Class<?> c)
Returns the system preference node for the package of the given class.
static Preferences systemRoot()
Returns the root node of the system preference hierarchy.
abstract String toString()
Returns a string representation of this node.
static Preferences userNodeForPackage(Class<?> c)
Returns the user preference node for the package of the given class.
static Preferences userRoot()
Returns the root node of the user preference hierarchy.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int MAX_KEY_LENGTH

Since: API Level 1

Maximum size in characters allowed for a preferences key.

Constant Value: 80 (0x00000050)

public static final int MAX_NAME_LENGTH

Since: API Level 1

Maximum size in characters allowed for a preferences name.

Constant Value: 80 (0x00000050)

public static final int MAX_VALUE_LENGTH

Since: API Level 1

Maximum size in characters allowed for a preferences value.

Constant Value: 8192 (0x00002000)

Protected Constructors

protected Preferences ()

Since: API Level 1

Default constructor, for use by subclasses only.

Public Methods

public abstract String absolutePath ()

Since: API Level 1

Gets the absolute path string of this preference node.

Returns
  • the preference node's absolute path string.

public abstract void addNodeChangeListener (NodeChangeListener ncl)

Since: API Level 1

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.

Parameters
ncl the listener to be registered.
Throws
NullPointerException if the given listener is null.
IllegalStateException if this node has been removed.

public abstract void addPreferenceChangeListener (PreferenceChangeListener pcl)

Since: API Level 1

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.

Parameters
pcl the listener to be registered.
Throws
NullPointerException if the given listener is null.
IllegalStateException if this node has been removed.

public abstract String[] childrenNames ()

Since: API Level 1

Returns the names of all children of this node or an empty array if this node has no children.

Returns
  • the names of all children of this node.
Throws
BackingStoreException if backing store is unavailable or causes an operation failure.
IllegalStateException if this node has been removed.

public abstract void clear ()

Since: API Level 1

Removes all preferences of this node.

Throws
BackingStoreException if backing store is unavailable or causes an operation failure.
IllegalStateException if this node has been removed.

public abstract void exportNode (OutputStream ostream)

Since: API Level 1

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.

Parameters
ostream the output stream to write the XML-formatted data to.
Throws
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.

public abstract void exportSubtree (OutputStream ostream)

Since: API Level 1

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.

Parameters
ostream the output stream to write the XML-formatted data to.
Throws
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.

public abstract void flush ()

Since: API Level 1

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.

Throws
BackingStoreException if the backing store is unavailable or causes an operation failure.

public abstract String get (String key, String deflt)

Since: API Level 1

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.

Parameters
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.
Returns
  • the preference value mapped to the given key.
Throws
IllegalStateException if this node has been removed.
NullPointerException if the parameter key is null.

public abstract boolean getBoolean (String key, boolean deflt)

Since: API Level 1

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.

Parameters
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.
Returns
  • the boolean value mapped to the given key.
Throws
IllegalStateException if this node has been removed.
NullPointerException if the parameter key is null.

public abstract byte[] getByteArray (String key, byte[] deflt)

Since: API Level 1

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.

Parameters
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.
Returns
  • the byte array value mapped to the given key.
Throws
IllegalStateException if this node has been removed.
NullPointerException if the parameter key is null.

public abstract double getDouble (String key, double deflt)

Since: API Level 1

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.

Parameters
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.
Returns
  • the double value mapped to the given key.
Throws
IllegalStateException if this node has been removed.
NullPointerException if the parameter key is null.

public abstract float getFloat (String key, float deflt)

Since: API Level 1

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.

Parameters
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.
Returns
  • the float value mapped to the given key.
Throws
IllegalStateException if this node has been removed.
NullPointerException if the parameter key is null.

public abstract int getInt (String key, int deflt)

Since: API Level 1

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.

Parameters
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.
Returns
  • the integer value mapped to the given key.
Throws
IllegalStateException if this node has been removed.
NullPointerException if the parameter key is null.

public abstract long getLong (String key, long deflt)

Since: API Level 1

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.

Parameters
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.
Returns
  • the long value mapped to the given key.
Throws
IllegalStateException if this node has been removed.
NullPointerException if the parameter key is null.

public static void importPreferences (InputStream istream)

Since: API Level 1

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.

Parameters
istream the input stream to read the data from.
Throws
InvalidPreferencesFormatException if the data read from the given input stream is not from a valid XML document.
IOException if an error occurs while importing.
SecurityException if RuntimePermission("preferences") is denied by a SecurityManager.

public abstract boolean isUserNode ()

Since: API Level 1

Returns whether this is a user preference node.

Returns
  • true, if this is a user preference node, false if this is a system preference node.

public abstract String[] keys ()

Since: API Level 1

Returns all preference keys stored in this node or an empty array if no key was found.

Returns
  • the list of all preference keys of this node.
Throws
BackingStoreException if the backing store is unavailable or causes an operation failure.
IllegalStateException if this node has been removed.

public abstract String name ()

Since: API Level 1

Returns the name of this node.

Returns
  • the name of this node.

public abstract Preferences node (String path)

Since: API Level 1

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.

Parameters
path the path name of the requested preference node.
Returns
  • the requested preference node.
Throws
IllegalStateException if this node has been removed.
IllegalArgumentException if the path name is invalid.
NullPointerException if the given path is null.

public abstract boolean nodeExists (String path)

Since: API Level 1

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.

Parameters
path the path name of the preference node to query.
Returns
  • true, if the queried preference node exists, false otherwise.
Throws
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.

public abstract Preferences parent ()

Since: API Level 1

Returns the parent preference node of this node or null if this node is the root node.

Returns
  • the parent preference node of this node.
Throws
IllegalStateException if this node has been removed.

public abstract void put (String key, String value)

Since: API Level 1

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.

Parameters
key the preference key to be added or updated.
value the preference value for the given key.
Throws
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.

public abstract void putBoolean (String key, boolean value)

Since: API Level 1

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.

Parameters
key the preference key to be added or updated.
value the preference boolean value for the given key.
Throws
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.

public abstract void putByteArray (String key, byte[] value)

Since: API Level 1

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.

Parameters
key the preference key to be added or updated.
value the preference value for the given key.
Throws
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.

public abstract void putDouble (String key, double value)

Since: API Level 1

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).

Parameters
key the preference key to be added or updated.
value the preference value for the given key.
Throws
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.

public abstract void putFloat (String key, float value)

Since: API Level 1

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).

Parameters
key the preference key to be added or updated.
value the preference value for the given key.
Throws
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.

public abstract void putInt (String key, int value)

Since: API Level 1

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).

Parameters
key the preference key to be added or updated.
value the preference value for the given key.
Throws
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.

public abstract void putLong (String key, long value)

Since: API Level 1

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).

Parameters
key the preference key to be added or updated.
value the preference value for the given key.
Throws
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.

public abstract void remove (String key)

Since: API Level 1

Removes the preference mapped to the given key from this node.

Parameters
key the key of the preference to be removed.
Throws
NullPointerException if the given key is null.
IllegalStateException if this node has been removed.

public abstract void removeNode ()

Since: API Level 1

Removes this preference node with all its descendants. The removal won't necessarily be persisted until the method flush() is invoked.

Throws
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.

public abstract void removeNodeChangeListener (NodeChangeListener ncl)

Since: API Level 1

Removes the given NodeChangeListener instance from this node.

Parameters
ncl the listener to be removed.
Throws
IllegalArgumentException if the given listener is null.
IllegalStateException if this node has been removed.

public abstract void removePreferenceChangeListener (PreferenceChangeListener pcl)

Since: API Level 1

Removes the given PreferenceChangeListener instance from this node.

Parameters
pcl the listener to be removed.
Throws
IllegalArgumentException if the given listener is null.
IllegalStateException if this node has been removed.

public abstract void sync ()

Since: API Level 1

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.

Throws
BackingStoreException if the backing store is unavailable or causes an operation failure.
IllegalStateException if this node has been removed.

public static Preferences systemNodeForPackage (Class<?> c)

Since: API Level 1

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.

Parameters
c the given class.
Returns
  • the system preference node for the package of the given class.
Throws
NullPointerException if the given class is null.
SecurityException if the RuntimePermission("preferences") is denied by a SecurityManager.

public static Preferences systemRoot ()

Since: API Level 1

Returns the root node of the system preference hierarchy.

Returns
  • the system preference hierarchy root node.
Throws
SecurityException if the RuntimePermission("preferences") is denied by a SecurityManager.

public abstract String toString ()

Since: API Level 1

Returns a string representation of this node. The format is "User/System Preference Node: " followed by this node's absolute path.

Returns
  • the string representation of this node.

public static Preferences userNodeForPackage (Class<?> c)

Since: API Level 1

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.

Parameters
c the given class.
Returns
  • the user preference node for the package of the given class.
Throws
NullPointerException if the given class is null.
SecurityException if the RuntimePermission("preferences") is denied by a SecurityManager.

public static Preferences userRoot ()

Since: API Level 1

Returns the root node of the user preference hierarchy.

Returns
  • the user preference hierarchy root node.
Throws
SecurityException if the RuntimePermission("preferences") is denied by a SecurityManager.