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 as follows:

• boolean = false
• double = 0.0
• float = 0.0f
• int = 0
• long = 0L
• String = "" (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 demand.

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 using 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 setValue, setToDefault). Note, however, that manipulating default values (with setDefault) does not cause any events to be reported.

Clients may instantiate this class. This class was not designed to be subclassed.

The implementation is based on a pair of internal java.util.Properties objects, one holding explicitly set values (set using setValue), the other holding the default values (set using setDefaultValue). The load and 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 defaultPropertyNames and contains methods.