A Preferences object
represents a mapping between preference names, which are
case-sensitive strings, and corresponding preference values.
get( ) allows you to query the string value of a
named preference, and put( ) allows you to set a
string value for a named preference. Although all preference values
are stored as strings, various convenience methods whose names begin
with "get" and
"put" exist to convert preference
values of type boolean byte[ ],
double, float,
int, and long to and from
strings.
The remove( ) method allows you to delete a named
preference altogether, and clear( ) deletes all
preference values stored in a Preferences object.
The keys( ) method returns an array of strings
that specify the names of all preferences in the
Preferences object.
Preference values are stored in some implementation-dependent
back-end which may be a file, a LDAP directory server, the Windows
Registry, or any other persistant "backing
store". Note that all the get( )
methods of this class require a default value to be specified. They
return this default if no value has been stored for the named
preference, or if the backing store is unavailable for any reason.
The Preferences class is completely independent of
the underlying implementation, except that it enforces an
80-character limit for preference names and
Preference node names (see below), and a
8192-character limit on preference value strings.
Preferences does not have a public construtor. To
obtain a Preferences object for use in your
application, you must must use one of the static methods described
below. Each Preferences object is a node in a
hierarchy of Preferences nodes. There are two
distinct hierarchies: one stores user-specific preferences, and one
stores system-wide preferences. All Preferences nodes (in either
hierarchy) have a unique name and use the same naming convention that
Unix filesystems use. Applications (and classes) may store their
preferences in a Preferences node with any name,
but the convention is to use a node name that corresponds to the
package name of the application or class, with all
"." characters in the package name
converted to "/" characters. For
example, the preferences node used by
java.lang.System would be
"/java/lang".
Preferences defines static methods that you can
use to obtain the Preferences objects your
application requires. Pass a Class object to
systemNodeForPackage( ) and
userNodeForPackage( ) to obtain the system and
user Preferences objects that are specific to the
package of that class. If you want a Preferences
node specific to a single class rather than to the package, you can
pass the class name to the node( ) method of the
package-specific node returned by systemNodeForPackage(
) or userNodeForPackage( ). If you want
to navigate the entire tree of preferences nodes (which most
applications never need to do) call systemRoot( )
and userRoot( ) to obtain the root node of the two
hierarchies, and then use the node( ) method to
look up child nodes of those roots.
Various Preferences methods allow you to traverse
the preferences hierarchies. parent( ) returns the
parent Preferences node. childrenNames(
) returns an array of the relative names of all children of
a Preferences node. node( )
returns a named Preferences object from the
hierarchy. If the specified node name begins with a slash, it is an
absolute name and is interpreted relative to the root of the
hierarchy. Otherwise, it is a relative name and is interpreted
relative to the Preferences object on which
node( ) was called. nodeExists(
) allows you to test whether a named node exists.
removeNode( ) allows you to delete an entire
Preferences node from the hierarchy (useful when
uninstalling an application). name( ) returns the
simple name of a Preferences node, relative to its
parent. absoutePath( ) returns the full, absolute
name of the node, relative to the root of the hierarchy. Finally,
isUserNode( ) allows you to determine whether a
Preferences object is part of the user or system
hierarchies.
Many applications will simply read their preference values once at
startup. Long-lived applications or applications that want to respond
dynamically to modifications to preferences (such as applications
that are tightly integrated with a graphical desktop) may use
addPreferenceChangeListener( ) to register a
PreferenceChangeListener to recieve notifications
of preference changes (in the form of
PreferenceChangeEvent objects). Applications that
are interested in changes to the Preferences
hierarchy itself can register a
NodeChangeListener.
put( ) and the various type-specific
put...( ) convenience methods may return
asynchonously, before the new preference value is stored persistantly
within the backing store. Call flush( ) to force
any preference changes to this Preferences node
(and any of its descendants in the hierarchy) to be stored
persistantly. (Note that it is not necessary to call flush(
) before an application terminates: all preferences will
eventually be made persistant.) More than one application (within
more than one Java virtual machine) may set preference values in the
same Preferences node at the same time. Call
sync( ) to ensure that future calls to
get( ) and its related convenience methods
retrieve current preference values set by this or other virtual
machines. Note that the flush( ) and
sync( ) operations are typically much more
expensive than get( ) and put(
) operations, and applications do not often need to use
them.
Preferences implementations ensure that all the
methods of this class are thread safe. If multiple threads or
multiple VMs write store the same preferences concurrently, their
values may overwrite one another, but the preference data will not be
corrupted. Note that, for simplicity, Preferences
does not define any way to set multiple preferences in a single
atomic transaction. If you need to ensure atomicity for multiple
preference values, define a data format that allows you to store all
the requisite values in a single string, and set and query those
values with a single call to put( ) or
get( ).
The contents of a Preferences node, or of a node
and all of its descendants may be exported as an XML file with
exportNode( ) and exportSubtree(
). The static importPreferences( )
method reads an exported XML file back into the preferences
hierarchy. These methods allow backups to be made of preference data,
and allow preferences to be transferred between systems or between
users.
Prior to Java 1.4, application preferences were sometimes managed
with the java.util.Properties object.
public abstract class Preferences {
// Protected Constructors
protected Preferences( );
// Public Constants
public static final int MAX_KEY_LENGTH; =80
public static final int MAX_NAME_LENGTH; =80
public static final int MAX_VALUE_LENGTH; =8192
// Public Class Methods
public static void importPreferences(java.io.InputStream is)
throws java.io.IOException, InvalidPreferencesFormatException;
public static Preferences systemNodeForPackage(Class<?> c);
public static Preferences systemRoot( );
public static Preferences userNodeForPackage(Class<?> c);
public static Preferences userRoot( );
// Event Registration Methods (by event name)
public abstract void addNodeChangeListener(NodeChangeListener ncl);
public abstract void removeNodeChangeListener(NodeChangeListener ncl);
public abstract void addPreferenceChangeListener(PreferenceChangeListener pcl);
public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl);
// Public Instance Methods
public abstract String absolutePath( );
public abstract String[ ] childrenNames( ) throws BackingStoreException;
public abstract void clear( ) throws BackingStoreException;
public abstract void exportNode(java.io.OutputStream os) throws java.io.IOException,
BackingStoreException;
public abstract void exportSubtree(java.io.OutputStream os) throws java.io.IOException,
BackingStoreException;
public abstract void flush( ) throws BackingStoreException;
public abstract String get(String key, String def);
public abstract boolean getBoolean(String key, boolean def);
public abstract byte[ ] getByteArray(String key, byte[ ] def);
public abstract double getDouble(String key, double def);
public abstract float getFloat(String key, float def);
public abstract int getInt(String key, int def);
public abstract long getLong(String key, long def);
public abstract boolean isUserNode( );
public abstract String[ ] keys( ) throws BackingStoreException;
public abstract String name( );
public abstract Preferences node(String pathName);
public abstract boolean nodeExists(String pathName) throws BackingStoreException;
public abstract Preferences parent( );
public abstract void put(String key, String value);
public abstract void putBoolean(String key, boolean value);
public abstract void putByteArray(String key, byte[ ] value);
public abstract void putDouble(String key, double value);
public abstract void putFloat(String key, float value);
public abstract void putInt(String key, int value);
public abstract void putLong(String key, long value);
public abstract void remove(String key);
public abstract void removeNode( ) throws BackingStoreException;
public abstract void sync( ) throws BackingStoreException;
// Public Methods Overriding Object
public abstract String toString( );
}
