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 ( );
}
NodeChangeEvent.NodeChangeEvent( ),
PreferenceChangeEvent.PreferenceChangeEvent( )
AbstractPreferences.{node( ), parent(
)}, NodeChangeEvent.{getChild( ),
getParent( )},
PreferenceChangeEvent.getNode( ),
PreferencesFactory.{systemRoot( ),
userRoot( )}