A table of preference settings, mapping named properties to values. Property
names are non-empty strings; property values can be either booleans,
non-null strings, or values of one of the primitive number types.
The table consists of two, sparse, layers: the lower layer holds default values
for properties, and the upper layer holds explicitly set values for properties.
Normal retrieval looks for an explicitly set value for the given property in
the upper layer; if there is nothing for that property in the upper layer, it
next looks for a default value for the given property in the lower layer; if
there is nothing for that property in the lower layer, it returns a standard
default-default value. The default-default values for the primitive types are
"" (the empty string)
Internally, all properties values (in both layers) are stored as strings.
Standard conversions to and from numeric and boolean types are performed on
The typical usage is to establish the defaults for all known properties
and then restore previously stored values for properties whose values
were explicitly set. The existing settings can be changed and new properties
can be set (
setValue). If the values specified is the same as
the default value, the explicit setting is deleted from the top layer.
It is also possible to reset a property value back to the default value
setToDefault. After the properties have been modified,
the properties with explicit settings are written to disk. The default values
are never saved. This two-tiered approach
to saving and restoring property setting minimizes the number of properties
that need to be persisted; indeed, the normal starting state does not require
storing any properties at all. It also makes it easy to use different
default settings in different environments while maintaining just those
property settings the user has adjusted.
A property change event is reported whenever a property's value actually
changes (either through
Note, however, that manipulating default values (with
does not cause any events to be reported.
Clients may instantiate this class.
The implementation is based on a pair of internal
java.util.Properties objects, one holding explicitly set values
setValue), the other holding the default values
store methods persist the non-default property values to
streams (the default values are not saved).
If a client sets a default value to be equivalent to the default-default for that
type, the value is still known to the preference store as having a default value.
That is, the name will still be returned in the result of the