Changes to Preferences API Since Original JSR
Changes to Preferences API Since Original JSR
There have been many changes to this API since the original JSR (JSR-10).
This list is not complete, but it should give the reader a good idea of the
Copyright 2000 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, California 94303 U.S.A. All rights reserved.
- Added support for per-system preferences.
- Eliminated forClass method. We we unable to come up with compelling
guidelines as to when it is appropriate to use forClass in preference to
forPackage, so we opted to eliminate the former.
- Added support for long, float and double and byte array preferences.
- Specified that getBoolean was case-insensitive.
- Restricted maximum size of a preference value to 8K characters. This
implicitly restricts byte array values to 6K bytes (because of the nominal
RFC 2045 Base64 encoding).
- Changed the name of the method fullName to absolutePath,
for improved consistency with File.
- Made it mandatory that once a node has been successfully removed,
attempting any operation on the corresponding Preferences object will fail
with an IllegalStateOperation, with the exception of the name and
absolutePath methods. (These two methods are useful from within a
NodeChangeEvent, once the node has been removed.)
- Eliminated use of java.beans.PropertyChangeListener in favor of
new class PreferenceChangeListener. Added corresponding event class
(PreferenceChangeEvent), and renamed add- and remove- listener methods
- Added a type-safe convenience method to each change event returning the
"source" as a Preferences Object. For
PreferenceChangeEvent, it's getNode. For
NodeChangeEvent, it's getParent.
- Replaced NodeChangeEvent's getNodeName method with a
getChild method, which returns a Preferences object (rather
than a string name).
- Disallowed the empty String ("") as node name for nodes other than
the root node. (This was already implicit in the spec but needed to be made
- Clarified the circumstances under which the methods in
Preferences throw a NullPointerException.
- Clarified that it is possible to use the API even when the backing store
- Clarified that an implementation is free to persist the results before
flush is called.
- Made it mandatory that the refresh method flushes pending updates
to prevent uncommitted changes from being lost. The resulting call is
essentially, a "sync", so we renamed it.
- Eliminated Preferences's no-args constructor and init method
(whose only use was to allow serializable Preferences subclasses).
- Clarified that keys method does return non-overridden stored
- Eliminated restriction that multiple retrievals of the same node
must return Preferences objects that are identical object references.
- Greatly expanded SPI and moved all of its methods to a subclass
(AbstractPreferences). Skeletal implementation automatically takes
care of locking, generation of IllegalStateException,
IllegalArgumentException, and many similar things.
- Moved some implementors' notes from Preferences to
AbstractPreferences, and eliminated others.
- Replaced use of IOException with (new)
- Changed return values of put(String, String) and
remove(String) methods not to give you old value, so that they can be
used when the backing store is not available. (This may also improve
- As a consequence of previous change, modified
PreferenceChangeEvent not to provide oldValue. (It's
possible to emulate the old behavior if you really want to.)
- Modified keys(), children(), nodeExists(String), removeNode(String),
clear() to throw BackingStoreException. For the first four, this is
necessary; they cannot, in general, get the specified return value if the
repository is unavailable. (For clear(), it is as much a convenience
for implementers as anything else.)
- Added spec for toString.
- Added clarification that it is not necessary to do a flush
prior to JVM termination.
- Added PreferencesFactory interface to enable support of multiple
user preference trees in a single VM.
- Changed package name to java.util.prefs
- Added XML-based import/export facility.
- Wrote "proof-of-concept" implementation (SimplePreferences) based
on import/export facility. (Not really an API change.)
- Modified the protocol whereby removeChild is called by
removeNode: now it is called for each node in the subtree, in
- Replaced removeNode(String) with removeNode(). There was no compelling
reason to pass in the string, and it was ungainly.
- Renamed children method to childrenNames and changed its
behavior to return an array containing the names of this nodes children
instead of the nodes themselves. This improves performance.
- Modified AbstractPreferences.childrenSpi to return the names
of the children, rather than the children themselves. This pushes the
translation work "up the hierarchy" out of the individual preferences
implementations and into AbstractPreferences.
- Added a new (Throwable) constructor to
BackingStoreException, as it will typically be a "chained exception."
- Modified AbstractPreferences.removeNodeSpi() to throw
BackingStoreException, as removeNode throws this exception.
- Removed newNode param from AbstractPreferences constructor.
Replaced it with protected field, which subclass constructor is obligated to
set if appropriate.
- DTD for exported form: modified root and node to require a map, and
modified map to contain entry* instead of entry+. This is cleaner, and
results in much cleaner XML support code. Also modified preferences to
require a root.
- Change name of node conventionally associated with programs in the
unnamed package from "" to "".
- Replaced line number support in InvalidPreferencesFormatException with
nested exception ("cause") support.
- Change AbstractPreferences.get implementation so that if
getSpi(String) throws an exception, it is caught, and the default
is returned from get(String).
- Wrote a discussion on the correct exception behavior of the
SPI calls in AbstractPreferences.
- Described locking behavior of AbstractPreferences.isRemoved.
- Modified sync spec to allow call on removed node.
- Added automatic change notification to
AbstractPreferences.node(String) implementation description.
- Numerous minor API clarifications.