java.util.prefs
Class Preferences

java.lang.Object
  java.util.prefs.Preferences

Direct Known Subclasses:

AbstractPreferences

public abstract class Preferences
extends Object

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.

Since:

1.4

See Also:

PreferencesFactory

Field Summary

static int	MAX_KEY_LENGTH Maximum size in characters of preferences key
static int	MAX_NAME_LENGTH Maximum size in characters of preferences name
static int	MAX_VALUE_LENGTH Maximum size in characters of preferences value

Constructor Summary

protected

Preferences() Default constructor, for use by subclasses only.

Method Summary

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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MAX_KEY_LENGTH

public static final int MAX_KEY_LENGTH

Maximum size in characters of preferences key

See Also:

Constant Field Values

MAX_NAME_LENGTH

public static final int MAX_NAME_LENGTH

Maximum size in characters of preferences name

See Also:

Constant Field Values

MAX_VALUE_LENGTH

public static final int MAX_VALUE_LENGTH

Maximum size in characters of preferences value

See Also:

Constant Field Values

Constructor Detail

Preferences

protected Preferences()

Default constructor, for use by subclasses only.

Method Detail

absolutePath

public abstract String absolutePath()

Get this preference node's absolute path string.

Returns:

this preference node's absolute path string.

childrenNames

public abstract String[] childrenNames()
                                throws BackingStoreException

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

Throws:

BackingStoreException - if backing store is unavailable or causes operation failure

IllegalStateException - if this node has been removed

clear

public abstract void clear()
                    throws BackingStoreException

Remove all preferences of this node.

Throws:

BackingStoreException - if backing store is unavailable or causes operation failure

IllegalStateException - if this node has been removed

exportNode

public abstract void exportNode(OutputStream ostream)
                         throws IOException,
                                BackingStoreException

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

Throws:

IOException - if export operation caused an IOException

BackingStoreException - if backing store is unavailable or causes operation failure

IllegalStateException - if this node has been removed

exportSubtree

public abstract void exportSubtree(OutputStream ostream)
                            throws IOException,
                                   BackingStoreException

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

Throws:

IOException - if export operation caused an IOException

BackingStoreException - if backing store is unavailable or causes operation failure

IllegalStateException - if this node has been removed

flush

public abstract void flush()
                    throws BackingStoreException

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.

Throws:

BackingStoreException - if backing store is unavailable or causes operation failure

get

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

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

Throws:

IllegalStateException - if this node has been removed

NullPointerException - if parameter key is null

getBoolean

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

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

Throws:

IllegalStateException - if this node has been removed

NullPointerException - if parameter key is null

getByteArray

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

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

Throws:

IllegalStateException - if this node has been removed

NullPointerException - if parameter key is null

getDouble

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

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

Throws:

IllegalStateException - if this node has been removed

NullPointerException - if parameter key is null

getFloat

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

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

Throws:

IllegalStateException - if this node has been removed

NullPointerException - if parameter key is null

getInt

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

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

Throws:

IllegalStateException - if this node has been removed

NullPointerException - if parameter key is null

getLong

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

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

Throws:

IllegalStateException - if this node has been removed

NullPointerException - if parameter key is null

importPreferences

public static void importPreferences(InputStream istream)
                              throws InvalidPreferencesFormatException,
                                     IOException

Import all preferences from the given input stream in XML document.

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.

Parameters:

istream - the given input stream to read data

Throws:

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

isUserNode

public abstract 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

keys

public abstract String[] keys()
                       throws BackingStoreException

Return all preferences keys stored in this node, or empty array if no key is found.

Returns:

all preferences keys in this node

Throws:

BackingStoreException - if backing store is unavailable or causes operation failure

IllegalStateException - if this node has been removed

name

public abstract String name()

Return name of this node.

Returns:

the name of this node

node

public abstract Preferences node(String path)

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:

path - the path name of dictated preferences

Returns:

the dictated preferences node

Throws:

IllegalStateException - if this node has been removed.

IllegalArgumentException - if the path name is invalid.

NullPointerException - if given path is null.

nodeExists

public abstract boolean nodeExists(String path)
                            throws BackingStoreException

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:

path - the path name of dictated preferences

Returns:

true if the dictated preferences node exists

Throws:

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

parent

public abstract Preferences parent()

Return the parent preferences node of this node, or null if this node is root.

Returns:

the parent preferences node of this node.

Throws:

IllegalStateException - if this node has been removed

put

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

Parameters:

key - the preferences key to be added or be updated

value - the preferences 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

putBoolean

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

Parameters:

key - the preferences key to be added or be updated

value - the preferences 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

putByteArray

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

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

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

putDouble

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

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

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

putFloat

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

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

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

putInt

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

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

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

putLong

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

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

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

remove

public abstract void remove(String key)

Remove the preferences mapped to the given key from this node.

Parameters:

key - the given preferences key to removed

Throws:

NullPointerException - if the given key is null

IllegalStateException - if this node has been removed

removeNode

public abstract void removeNode()
                         throws BackingStoreException

Remove this preferences node and its all descendants. The removal maybe won't be persisted until the flush() method is invoked.

Throws:

BackingStoreException - if backing store is unavailable or causes operation failure

IllegalStateException - if this node has been removed

UnsupportedOperationException - if this is a root node

addNodeChangeListener

public abstract 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

Throws:

NullPointerException - if the given listener is null

IllegalStateException - if this node has been removed

addPreferenceChangeListener

public abstract void addPreferenceChangeListener(PreferenceChangeListener pcl)

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

Throws:

NullPointerException - if the given listener is null

IllegalStateException - if this node has been removed

removeNodeChangeListener

public abstract void removeNodeChangeListener(NodeChangeListener ncl)

Remove the given NodeChangeListener instance from this node.

Parameters:

ncl - the given listener to be removed

Throws:

IllegalArgumentException - if the given listener

IllegalStateException - if this node has been removed

removePreferenceChangeListener

public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)

Remove the given PreferenceChangeListener instance from this node.

Parameters:

pcl - the given listener to be removed

Throws:

IllegalArgumentException - if the given listener

IllegalStateException - if this node has been removed

sync

public abstract void sync()
                   throws BackingStoreException

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.

Throws:

BackingStoreException - if backing store is unavailable or causes operation failure

IllegalStateException - if this node has been removed

systemNodeForPackage

public static Preferences systemNodeForPackage(Class<?> c)

Return the system preference node for the package of given class. The absolute path of the returned node is one slash followed by the given class's full package name with replacing each period ('.') with slash. For example, the preference's associated with class 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

systemRoot

public static Preferences systemRoot()

Return the root node for system preference hierarchy.

Returns:

the root node for system preference hierarchy

Throws:

SecurityException - if RuntimePermission("preferences") is denied by a SecurityManager

userNodeForPackage

public static Preferences userNodeForPackage(Class<?> c)

Return the user preference node for the package of given class. The absolute path of the returned node is one slash followed by the given class's full package name with replacing each period ('.') with slash. For example, the preference's associated with class 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

userRoot

public static Preferences userRoot()

Return the root node for user preference hierarchy.

Returns:

the root node for user preference hierarchy

Throws:

SecurityException - if RuntimePermission("preferences") is denied by a SecurityManager

toString

public abstract String toString()

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

Overrides:

toString in class Object

Returns:

a string description of this node