This class provides a skeletal implementation of the Preferences
class, greatly easing the task of implementing it.

This class is for Preferences implementers only.
Normal users of the Preferences facility should have no need to
consult this documentation.  The Preferences documentation
should suffice.

Implementors must override the nine abstract service-provider interface
(SPI) methods: getSpi(String), putSpi(String,String),
removeSpi(String), childSpi(String), removeNodeSpi(), keysSpi(), childrenNamesSpi(), syncSpi() and flushSpi().  All of the concrete methods specify
precisely how they are implemented atop these SPI methods.  The implementor
may, at his discretion, override one or more of the concrete methods if the
default implementation is unsatisfactory for any reason, such as
performance.

The SPI methods fall into three groups concerning exception
behavior. The getSpi method should never throw exceptions, but it
doesn't really matter, as any exception thrown by this method will be
intercepted by get(String,String), which will return the specified
default value to the caller.  The removeNodeSpi, keysSpi,
childrenNamesSpi, syncSpi and flushSpi methods are specified
to throw BackingStoreException, and the implementation is required
to throw this checked exception if it is unable to perform the operation.
The exception propagates outward, causing the corresponding API method
to fail.

The remaining SPI methods putSpi(String,String), removeSpi(String) and childSpi(String) have more complicated
exception behavior.  They are not specified to throw
BackingStoreException, as they can generally obey their contracts
even if the backing store is unavailable.  This is true because they return
no information and their effects are not required to become permanent until
a subsequent call to Preferences.flush() or
Preferences.sync(). Generally speaking, these SPI methods should not
throw exceptions.  In some implementations, there may be circumstances
under which these calls cannot even enqueue the requested operation for
later processing.  Even under these circumstances it is generally better to
simply ignore the invocation and return, rather than throwing an
exception.  Under these circumstances, however, all subsequent invocations
of flush() and sync should return false, as
returning true would imply that all previous operations had
successfully been made permanent.

There is one circumstance under which putSpi, removeSpi and
childSpi should throw an exception: if the caller lacks
sufficient privileges on the underlying operating system to perform the
requested operation.  This will, for instance, occur on most systems
if a non-privileged user attempts to modify system preferences.
(The required privileges will vary from implementation to
implementation.  On some implementations, they are the right to modify the
contents of some directory in the file system; on others they are the right
to modify contents of some key in a registry.)  Under any of these
circumstances, it would generally be undesirable to let the program
continue executing as if these operations would become permanent at a later
time.  While implementations are not required to throw an exception under
these circumstances, they are encouraged to do so.  A SecurityException would be appropriate.

Most of the SPI methods require the implementation to read or write
information at a preferences node.  The implementor should beware of the
fact that another VM may have concurrently deleted this node from the
backing store.  It is the implementation's responsibility to recreate the
node if it has been deleted.

Implementation note: In Sun's default Preferences
implementations, the user's identity is inherited from the underlying
operating system and does not change for the lifetime of the virtual
machine.  It is recognized that server-side Preferences
implementations may have the user identity change from request to request,
implicitly passed to Preferences methods via the use of a
static ThreadLocal instance.  Authors of such implementations are
strongly encouraged to determine the user at the time preferences
are accessed (for example by the get(String,String) or put(String,String) method) rather than permanently associating a user
with each Preferences instance.  The latter behavior conflicts
with normal Preferences usage and would lead to great confusion.

Thrown to indicate that a preferences operation could not complete because
of a failure in the backing store, or a failure to contact the backing
store.

Thrown to indicate that an operation could not complete because
the input did not conform to the appropriate XML document type
for a collection of preferences, as per the Preferences
specification.

An event emitted by a Preferences node to indicate that
a child of that node has been added or removed.

Note, that although NodeChangeEvent inherits Serializable interface from
java.util.EventObject, it is not intended to be Serializable. Appropriate
serialization methods are implemented to throw NotSerializableException.

A listener for receiving preference node change events.

An event emitted by a Preferences node to indicate that
a preference has been added, removed or has had its value changed.

Note, that although PreferenceChangeEvent inherits Serializable interface
from EventObject, it is not intended to be Serializable. Appropriate
serialization methods are implemented to throw NotSerializableException.

A listener for receiving preference change events.

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:

No relative path names begin with the slash character.
Every node's path name relative to itself is the empty string.
Every node's path name relative to its parent is its node name (except
for the root node, which does not have a parent).
Every node's path name relative to the root is its absolute path name
with the initial slash character removed.


Note finally that:

No path name contains multiple consecutive slash characters.
No path name with the exception of the root's absolute path name
ends in the slash character.
Any string that conforms to these two rules is a valid path name.


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 preferences; 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 Java(TM) SE 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 located as follows:



If the system property
java.util.prefs.PreferencesFactory is defined, then it is
taken to be the fully-qualified name of a class implementing the
PreferencesFactory interface.  The class is loaded and
instantiated; if this process fails then an unspecified error is
thrown.

 If a PreferencesFactory implementation class file
has been installed in a jar file that is visible to the
system class loader,
and that jar file contains a provider-configuration file named
java.util.prefs.PreferencesFactory in the resource
directory META-INF/services, then the first class name
specified in that file is taken.  If more than one such jar file is
provided, the first one found will be used.  The class is loaded
and instantiated; if this process fails then an unspecified error
is thrown.

Finally, if neither the above-mentioned system property nor
an extension jar file is provided, then the system-wide default
PreferencesFactory implementation for the underlying
platform is loaded and instantiated.

A factory object that generates Preferences objects.  Providers of
new Preferences implementations should provide corresponding
PreferencesFactory implementations so that the new
Preferences implementation can be installed in place of the
platform-specific default implementation.

This class is for Preferences implementers only.
Normal users of the Preferences facility should have no need to
consult this documentation.