Generated by
JDiff

java.util.prefs Documentation Differences

This file contains all the changes in documentation in the package java.util.prefs as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Class Preferences

A node in a hierarchical collection of preference data. This class allows applications to store and retrieve user and system preference and configuration data. This data is stored persistently in an implementation-dependent backing store. Typical implementations include flat files OS-specific registries directory servers and SQL databases. The user of this class needn't be concerned with details of the backing store.

There are two separate trees of preference nodes one for user preferences and one for system preferences. Each user has a separate user preference tree and all users in a given system share the same system preference tree. The precise description of "user" and "system" will vary from implementation to implementation. Typical information stored in the user preference tree might include font choice color choice or preferred window location and size for a particular application. Typical information stored in the system preference tree might include installation configuration data for an application.

Nodes in a preference tree are named in a similar fashion to directories in a hierarchical file system. Every node in a preference tree has a node name (which is not necessarily unique) a unique absolute path name and a path name relative to each ancestor including itself.

The root node has a node name of the empty string (""). Every other node has an arbitrary node name specified at the time it is created. The only restrictions on this name are that it cannot be the empty string and it cannot contain the slash character ('/').

The root node has an absolute path name of "/". Children of the root node have absolute path names of "/" + <node name>. All other nodes have absolute path names of <parent's absolute path name> + "/" + <node name>. Note that all absolute path names begin with the slash character.

A node n's path name relative to its ancestor a is simply the string that must be appended to a's absolute path name in order to form n's absolute path name with the initial slash character (if present) removed. Note that:

Note finally that:

All of the methods that modify preferences data are permitted to operate asynchronously; they may return immediately and changes will eventually propagate to the persistent backing store with an implementation-dependent delay. The flush method may be used to synchronously force updates to the backing store. Normal termination of the Java Virtual Machine will not result in the loss of pending updates -- an explicit flush invocation is not required upon termination to ensure that pending updates are made persistent.

All of the methods that read preferences from a Preferences object require the invoker to provide a default value. The default value is returned if no value has been previously set or if the backing store is unavailable. The intent is to allow applications to operate albeit with slightly degraded functionality even if the backing store becomes unavailable. Several methods like flush have semantics that prevent them from operating if the backing store is unavailable. Ordinary applications should have no need to invoke any of these methods which can be identified by the fact that they are declared to throw BackingStoreException

The methods in this class may be invoked concurrently by multiple threads in a single JVM without the need for external synchronization and the results will be equivalent to some serial execution. If this class is used concurrently by multiple JVMs that store their preference data in the same backing store the data store will not be corrupted but no other guarantees are made concerning the consistency of the preference data.

This class contains an export/import facility allowing preferences to be "exported" to an XML document and XML documents representing preferences to be "imported" back into the system. This facility may be used to back up all or part of a preference tree and subsequently restore from the backup.

The XML document has the following DOCTYPE declaration:

 < DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd"> 
Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is not accessed when exporting or importing prefereneces; it merely serves as a string to uniquely identify the DTD which is:
 < xml version="1.0" encoding="UTF-8" > < -- DTD for a Preferences tree. --> < -- The preferences element is at the root of an XML document representing a Preferences tree. --> < ELEMENT preferences (root)> < -- The preferences element contains an optional version attribute which specifies version of DTD. --> < ATTLIST preferences EXTERNAL_XML_VERSION CDATA "0.0" > < -- The root element has a map representing the root's preferences (if any) and one node for each child of the root (if any). --> < ELEMENT root (map node*) > < -- Additionally the root contains a type attribute which specifies whether it's the system or user root. --> < ATTLIST root type (system|user) #REQUIRED > < -- Each node has a map representing its preferences (if any) and one node for each child (if any). --> < ELEMENT node (map node*) > < -- Additionally each node has a name attribute --> < ATTLIST node name CDATA #REQUIRED > < -- A map represents the preferences stored at a node (if any). --> < ELEMENT map (entry*) > < -- An entry represents a single preference which is simply a key-value pair. --> < ELEMENT entry EMPTY > < ATTLIST entry key CDATA #REQUIRED value CDATA #REQUIRED > 
Every Preferences implementation must have an associated PreferencesFactory implementation. Every J2SE implementation must provide some means of specifying which PreferencesFactory implementation is used to generate the root preferences nodes. This allows the administrator to replace the default preferences implementation with an alternative implementation.

Implementation note: In Sun's JRE the PreferencesFactory implementation is specified using the system property java.util.prefs.PreferencesFactory which must be set to the fully qualified name of a class implementing the PreferencesFactory. @author Josh Bloch @version 1.13 1216 05/0306/0102 @since 1.4

Class Preferences, boolean nodeExists(String)

Returns true if the named preference node exists in the same tree as this node. Relative path names (which do not begin with the slash character ('/')) are interpreted relative to this preference node.

If this node (or an ancestor) has already been removed with the #removeNode() method it is legal to invoke this method but only with the path name ""; the invocation will return false. Thus the idiom p.nodeExists("") may be used to test whether p has been removed. @param pathName the path name of the node whose existence is to be checked. @return true if the specified node exists. @throws BackingStoreException if this operation cannot be completed due to a failure in the backing store or inability to communicate with it. @throws IllegalArgumentException if the path name is invalid (i.e. it contains multiple consecutive slash characters or ends with a slash character and is more than one character long). @throws NullPointerException if path name is null. s * @throws IllegalStateException if this node (or an ancestor) has been removed with the #removeNode() method and pathName is not the empty string ("").

Class Preferences, void removeNode()

Removes this preference node and all of its descendants invalidating any preferences contained in the removed nodes. Once a node has been removed attempting any method other than #name() #absolutePath() #isUserNode() #flush() or nodeExists("") on the corresponding Preferences instance will fail with an IllegalStateException. (The methods defined on Object can still be invoked on a node after it has been removed; they will not throw IllegalStateException.)

The removal is not guaranteed to be persistent until the flush method is called on this node (or an ancestor).

If this implementation supports stored defaults removing a node exposes any stored defaults at or below this node. Thus a subsequent call to nodeExists on this node's path name may return true and a subsequent call to node on this path name may may return a (different) Preferences instance representing a non-empty collection of preferences and/or children. @throws BackingStoreException if this operation cannot be completed due to a failure in the backing store or inability to communicate with it. @throws IllegalStateException if this node (or an ancestor) has already been removed with the #removeNode() method. @throws UnsupportedOperationException if this method is invoked on the root node. @see #flush()