Java in a Nutshell, 5th Edition [Electronic resources] نسخه متنی

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 ( );
}

Subclasses

AbstractPreferences

Passed To

NodeChangeEvent.NodeChangeEvent( ),
PreferenceChangeEvent.PreferenceChangeEvent( )

Returned By

AbstractPreferences.{node( ), parent(
)}, NodeChangeEvent.{getChild( ),
getParent( )},
PreferenceChangeEvent.getNode( ),
PreferencesFactory.{systemRoot( ),
userRoot( )}