|
JavaTM 2 Platform Std. Ed. v1.4.1 |
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
java.lang.Object | +--java.util.prefs.Preferences
A node in a hierarchical collection of preference data. This class allows applications to store and retrieve user and system preference and configuration data. This data is stored persistently in an implementation-dependent backing store. Typical implementations include flat files, OS-specific registries, directory servers and SQL databases. The user of this class needn't be concerned with details of the backing store.
There are two separate trees of preference nodes, one for user preferences and one for system preferences. Each user has a separate user preference tree, and all users in a given system share the same system preference tree. The precise description of "user" and "system" will vary from implementation to implementation. Typical information stored in the user preference tree might include font choice, color choice, or preferred window location and size for a particular application. Typical information stored in the system preference tree might include installation configuration data for an application.
Nodes in a preference tree are named in a similar fashion to directories in a hierarchical file system. Every node in a preference tree has a node name (which is not necessarily unique), a unique absolute path name, and a path name relative to each ancestor including itself.
The root node has a node name of the empty string (""). Every other node has an arbitrary node name, specified at the time it is created. The only restrictions on this name are that it cannot be the empty string, and it cannot contain the slash character ('/').
The root node has an absolute path name of "/". Children of the root node have absolute path names of "/" + <node name>. All other nodes have absolute path names of <parent's absolute path name> + "/" + <node name>. Note that all absolute path names begin with the slash character.
A node n's path name relative to its ancestor a is simply the string that must be appended to a's absolute path name in order to form n's absolute path name, with the initial slash character (if present) removed. Note that:
Note finally that:
All of the methods that modify preferences data are permitted to operate asynchronously; they may return immediately, and changes will eventually propagate to the persistent backing store with an implementation-dependent delay. The flush method may be used to synchronously force updates to the backing store. Normal termination of the Java Virtual Machine will not result in the loss of pending updates -- an explicit flush invocation is not required upon termination to ensure that pending updates are made persistent.
All of the methods that read preferences from a Preferences
object require the invoker to provide a default value. The default value is
returned if no value has been previously set or if the backing store is
unavailable. The intent is to allow applications to operate, albeit
with slightly degraded functionality, even if the backing store becomes
unavailable. Several methods, like flush, have semantics that
prevent them from operating if the backing store is unavailable. Ordinary
applications should have no need to invoke any of these methods, which can
be identified by the fact that they are declared to throw BackingStoreException.
The methods in this class may be invoked concurrently by multiple threads in a single JVM without the need for external synchronization, and the results will be equivalent to some serial execution. If this class is used concurrently by multiple JVMs that store their preference data in the same backing store, the data store will not be corrupted, but no other guarantees are made concerning the consistency of the preference data.
This class contains an export/import facility, allowing preferences to be "exported" to an XML document, and XML documents representing preferences to be "imported" back into the system. This facility may be used to back up all or part of a preference tree, and subsequently restore from the backup.
The XML document has the following DOCTYPE declaration:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is not accessed when exporting or importing prefereneces; it merely serves as a string to uniquely identify the DTD, which is:
<?xml version="1.0" encoding="UTF-8"?>
<!-- DTD for a Preferences tree. -->
<!-- The preferences element is at the root of an XML document
representing a Preferences tree. -->
<!ELEMENT preferences (root)>
<!-- The preferences element contains an optional version attribute,
which specifies version of DTD. -->
<!ATTLIST preferences EXTERNAL_XML_VERSION CDATA "0.0" >
<!-- The root element has a map representing the root's preferences
(if any), and one node for each child of the root (if any). -->
<!ELEMENT root (map, node*) >
<!-- Additionally, the root contains a type attribute, which
specifies whether it's the system or user root. -->
<!ATTLIST root
type (system|user) #REQUIRED >
<!-- Each node has a map representing its preferences (if any),
and one node for each child (if any). -->
<!ELEMENT node (map, node*) >
<!-- Additionally, each node has a name attribute -->
<!ATTLIST node
name CDATA #REQUIRED >
<!-- A map represents the preferences stored at a node (if any). -->
<!ELEMENT map (entry*) >
<!-- An entry represents a single preference, which is simply
a key-value pair. -->
<!ELEMENT entry EMPTY >
<!ATTLIST entry
key CDATA #REQUIRED
value CDATA #REQUIRED >
Every Preferences implementation must have an associated PreferencesFactory implementation. Every J2SE implementation must provide
some means of specifying which PreferencesFactory implementation
is used to generate the root preferences nodes. This allows the
administrator to replace the default preferences implementation with an
alternative implementation.
Implementation note: In Sun's JRE, the PreferencesFactory implementation is specified using the system property java.util.prefs.PreferencesFactory, which must be set to the fully qualified name of a class implementing the PreferencesFactory.
| Field Summary | |
static int |
MAX_KEY_LENGTH
Maximum length of string allowed as a key (80 characters). |
static int |
MAX_NAME_LENGTH
Maximum length of a node name (80 characters). |
static int |
MAX_VALUE_LENGTH
Maximum length of string allowed as a value (8192 characters). |
| Constructor Summary | |
protected |
Preferences()
Sole constructor. |
| Method Summary | |
abstract String |
absolutePath()
Returns this preference node's absolute path name. |
abstract void |
addNodeChangeListener(NodeChangeListener ncl)
Registers the specified listener to receive node change events for this node. |
abstract void |
addPreferenceChangeListener(PreferenceChangeListener pcl)
Registers the specified listener to receive preference change events for this preference node. |
abstract String[] |
childrenNames()
Returns the names of the children of this preference node, relative to this node. |
abstract void |
clear()
Removes all of the preferences (key-value associations) in this preference node. |
abstract void |
exportNode(OutputStream os)
Emits on the specified output stream an XML document representing all of the preferences contained in this node (but not its descendants). |
abstract void |
exportSubtree(OutputStream os)
Emits an XML document representing all of the preferences contained in this node and all of its descendants. |
abstract void |
flush()
Forces any changes in the contents of this preference node and its descendants to the persistent store. |
abstract String |
get(String key,
String def)
Returns the value associated with the specified key in this preference node. |
abstract boolean |
getBoolean(String key,
boolean def)
Returns the boolean value represented by the string associated with the specified key in this preference node. |
abstract byte[] |
getByteArray(String key,
byte[] def)
Returns the byte array value represented by the string associated with the specified key in this preference node. |
abstract double |
getDouble(String key,
double def)
Returns the double value represented by the string associated with the specified key in this preference node. |
abstract float |
getFloat(String key,
float def)
Returns the float value represented by the string associated with the specified key in this preference node. |
abstract int |
getInt(String key,
int def)
Returns the int value represented by the string associated with the specified key in this preference node. |
abstract long |
getLong(String key,
long def)
Returns the long value represented by the string associated with the specified key in this preference node. |
static void |
importPreferences(InputStream is)
Imports all of the preferences represented by the XML document on the specified input stream. |
abstract boolean |
isUserNode()
Returns true if this preference node is in the user preference tree, false if it's in the system preference tree. |
abstract String[] |
keys()
Returns all of the keys that have an associated value in this preference node. |
abstract String |
name()
Returns this preference node's name, relative to its parent. |
abstract Preferences |
node(String pathName)
Returns the named preference node in the same tree as this node, creating it and any of its ancestors if they do not already exist. |
abstract boolean |
nodeExists(String pathName)
Returns true if the named preference node exists in the same tree as this node. |
abstract Preferences |
parent()
Returns the parent of this preference node, or null if this is the root. |
abstract void |
put(String key,
String value)
Associates the specified value with the specified key in this preference node. |
abstract void |
putBoolean(String key,
boolean value)
Associates a string representing the specified boolean value with the specified key in this preference node. |
abstract void |
putByteArray(String key,
byte[] value)
Associates a string representing the specified byte array with the specified key in this preference node. |
abstract void |
putDouble(String key,
double value)
Associates a string representing the specified double value with the specified key in this preference node. |
abstract void |
putFloat(String key,
float value)
Associates a string representing the specified float value with the specified key in this preference node. |
abstract void |
putInt(String key,
int value)
Associates a string representing the specified int value with the specified key in this preference node. |
abstract void |
putLong(String key,
long value)
Associates a string representing the specified long value with the specified key in this preference node. |
abstract void |
remove(String key)
Removes the value associated with the specified key in this preference node, if any. |
abstract void |
removeNode()
Removes this preference node and all of its descendants, invalidating any preferences contained in the removed nodes. |
abstract void |
removeNodeChangeListener(NodeChangeListener ncl)
Removes the specified NodeChangeListener, so it no longer receives change events. |
abstract void |
removePreferenceChangeListener(PreferenceChangeListener pcl)
Removes the specified preference change listener, so it no longer receives preference change events. |
abstract void |
sync()
Ensures that future reads from this preference node and its descendants reflect any changes that were committed to the persistent store (from any VM) prior to the sync invocation. |
static Preferences |
systemNodeForPackage(Class c)
Returns the preference node from the system preference tree that is associated (by convention) with the specified class's package. |
static Preferences |
systemRoot()
Returns the root preference node for the system. |
abstract String |
toString()
Returns a string representation of this preferences node, as if computed by the expression:(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath(). |
static Preferences |
userNodeForPackage(Class c)
Returns the preference node from the calling user's preference tree that is associated (by convention) with the specified class's package. |
static Preferences |
userRoot()
Returns the root preference node for the calling user. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Field Detail |
public static final int MAX_KEY_LENGTH
public static final int MAX_VALUE_LENGTH
public static final int MAX_NAME_LENGTH
| Constructor Detail |
protected Preferences()
| Method Detail |
public static Preferences userNodeForPackage(Class c)
This convention does not apply to the unnamed package, whose associated preference node is <unnamed>. This node is not intended for long term use, but for convenience in the early development of programs that do not yet belong to a package, and for "throwaway" programs. Valuable data should not be stored at this node as it is shared by all programs that use it.
A class Foo wishing to access preferences pertaining to its package can obtain a preference node as follows:
static Preferences prefs = Preferences.userNodeForPackage(Foo.class);
This idiom obviates the need for using a string to describe the
preferences node and decreases the likelihood of a run-time failure.
(If the class name is is misspelled, it will typically result in a
compile-time error.)
Invoking this method will result in the creation of the returned node and its ancestors if they do not already exist. If the returned node did not exist prior to this call, this node and any ancestors that were created by this call are not guaranteed to become permanent until the flush method is called on the returned node (or one of its ancestors or descendants).
c - the class for whose package a user preference node is desired.
NullPointerException - if c is null.
SecurityException - if a security manager is present and
it denies RuntimePermission("preferences").RuntimePermissionpublic static Preferences systemNodeForPackage(Class c)
This convention does not apply to the unnamed package, whose associated preference node is <unnamed>. This node is not intended for long term use, but for convenience in the early development of programs that do not yet belong to a package, and for "throwaway" programs. Valuable data should not be stored at this node as it is shared by all programs that use it.
A class Foo wishing to access preferences pertaining to its package can obtain a preference node as follows:
static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);This idiom obviates the need for using a string to describe the preferences node and decreases the likelihood of a run-time failure. (If the class name is is misspelled, it will typically result in a compile-time error.)
Invoking this method will result in the creation of the returned node and its ancestors if they do not already exist. If the returned node did not exist prior to this call, this node and any ancestors that were created by this call are not guaranteed to become permanent until the flush method is called on the returned node (or one of its ancestors or descendants).
c - the class for whose package a system preference node is desired.
NullPointerException - if c is null.
SecurityException - if a security manager is present and
it denies RuntimePermission("preferences").RuntimePermissionpublic static Preferences userRoot()
SecurityException - If a security manager is present and
it denies RuntimePermission("preferences").RuntimePermissionpublic static Preferences systemRoot()
SecurityException - If a security manager is present and
it denies RuntimePermission("preferences").RuntimePermission
public abstract void put(String key,
String value)
key - key with which the specified value is to be associated.value - value to be associated with the specified key.
NullPointerException - if key or value is null.
IllegalArgumentException - if key.length() exceeds
MAX_KEY_LENGTH or if value.length exceeds
MAX_VALUE_LENGTH.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.
public abstract String get(String key,
String def)
Some implementations may store default values in their backing stores. If there is no value associated with the specified key but there is such a stored default, it is returned in preference to the specified default.
key - key whose associated value is to be returned.def - the value to be returned in the event that this
preference node has no value associated with key.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.
NullPointerException - if key is null. (A
null value for def is permitted.)public abstract void remove(String key)
If this implementation supports stored defaults, and there is such a default for the specified preference, the stored default will be "exposed" by this call, in the sense that it will be returned by a succeeding call to get.
key - key whose mapping is to be removed from the preference node.
NullPointerException - if key is null.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.
public abstract void clear()
throws BackingStoreException
If this implementation supports stored defaults, and this node in the preferences hierarchy contains any such defaults, the stored defaults will be "exposed" by this call, in the sense that they will be returned by succeeding calls to get.
BackingStoreException - if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.removeNode()
public abstract void putInt(String key,
int value)
Integer.toString(int). This method is intended for use in
conjunction with getInt(java.lang.String, int).
key - key with which the string form of value is to be associated.value - value whose string form is to be associated with key.
NullPointerException - if key is null.
IllegalArgumentException - if key.length() exceeds
MAX_KEY_LENGTH.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.getInt(String,int)
public abstract int getInt(String key,
int def)
Integer.parseInt(String). Returns the
specified default if there is no value associated with the key,
the backing store is inaccessible, or if
Integer.parseInt(String) would throw a NumberFormatException if the associated value were passed. This
method is intended for use in conjunction with putInt(java.lang.String, int).
If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to an int with Integer.parseInt, this int is returned in preference to the specified default.
key - key whose associated value is to be returned as an int.def - the value to be returned in the event that this
preference node has no value associated with key
or the associated value cannot be interpreted as an int,
or the backing store is inaccessible.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.
NullPointerException - if key is null.putInt(String,int),
get(String,String)
public abstract void putLong(String key,
long value)
Long.toString(long). This method is intended for use in
conjunction with getLong(java.lang.String, long).
key - key with which the string form of value is to be associated.value - value whose string form is to be associated with key.
NullPointerException - if key is null.
IllegalArgumentException - if key.length() exceeds
MAX_KEY_LENGTH.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.getLong(String,long)
public abstract long getLong(String key,
long def)
Long.parseLong(String). Returns the
specified default if there is no value associated with the key,
the backing store is inaccessible, or if
Long.parseLong(String) would throw a NumberFormatException if the associated value were passed. This
method is intended for use in conjunction with putLong(java.lang.String, long).
If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to a long with Long.parseLong, this long is returned in preference to the specified default.
key - key whose associated value is to be returned as a long.def - the value to be returned in the event that this
preference node has no value associated with key
or the associated value cannot be interpreted as a long,
or the backing store is inaccessible.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.
NullPointerException - if key is null.putLong(String,long),
get(String,String)
public abstract void putBoolean(String key,
boolean value)
getBoolean(java.lang.String, boolean).
key - key with which the string form of value is to be associated.value - value whose string form is to be associated with key.
NullPointerException - if key is null.
IllegalArgumentException - if key.length() exceeds
MAX_KEY_LENGTH.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.getBoolean(String,boolean),
get(String,String)
public abstract boolean getBoolean(String key,
boolean def)
putBoolean(java.lang.String, boolean).
Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if the associated value is something other than "true" or "false", ignoring case.
If the implementation supports stored defaults and such a default exists and is accessible, it is used in preference to the specified default, unless the stored default is something other than "true" or "false", ignoring case, in which case the specified default is used.
key - key whose associated value is to be returned as a boolean.def - the value to be returned in the event that this
preference node has no value associated with key
or the associated value cannot be interpreted as a boolean,
or the backing store is inaccessible.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.
NullPointerException - if key is null.get(String,String),
putBoolean(String,boolean)
public abstract void putFloat(String key,
float value)
Float.toString(float). This method is intended for use in
conjunction with getFloat(java.lang.String, float).
key - key with which the string form of value is to be associated.value - value whose string form is to be associated with key.
NullPointerException - if key is null.
IllegalArgumentException - if key.length() exceeds
MAX_KEY_LENGTH.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.getFloat(String,float)
public abstract float getFloat(String key,
float def)
Float.parseFloat(String). Returns the specified
default if there is no value associated with the key, the backing store
is inaccessible, or if Float.parseFloat(String) would throw a
NumberFormatException if the associated value were passed.
This method is intended for use in conjunction with putFloat(java.lang.String, float).
If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to a float with Float.parseFloat, this float is returned in preference to the specified default.
key - key whose associated value is to be returned as a float.def - the value to be returned in the event that this
preference node has no value associated with key
or the associated value cannot be interpreted as a float,
or the backing store is inaccessible.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.
NullPointerException - if key is null.putFloat(String,float),
get(String,String)
public abstract void putDouble(String key,
double value)
Double.toString(double). This method is intended for use in
conjunction with getDouble(java.lang.String, double).
key - key with which the string form of value is to be associated.value - value whose string form is to be associated with key.
NullPointerException - if key is null.
IllegalArgumentException - if key.length() exceeds
MAX_KEY_LENGTH.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.getDouble(String,double)
public abstract double getDouble(String key,
double def)
Double.parseDouble(String). Returns the specified
default if there is no value associated with the key, the backing store
is inaccessible, or if Double.parseDouble(String) would throw a
NumberFormatException if the associated value were passed.
This method is intended for use in conjunction with putDouble(java.lang.String, double).
If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to a double with Double.parseDouble, this double is returned in preference to the specified default.
key - key whose associated value is to be returned as a double.def - the value to be returned in the event that this
preference node has no value associated with key
or the associated value cannot be interpreted as a double,
or the backing store is inaccessible.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.
NullPointerException - if key is null.putDouble(String,double),
get(String,String)
public abstract void putByteArray(String key,
byte[] value)
getByteArray(java.lang.String, byte[]).
key - key with which the string form of value is to be associated.value - value whose string form is to be associated with key.
NullPointerException - if key or value is null.
IllegalArgumentException - if key.length() exceeds MAX_KEY_LENGTH
or if value.length exceeds MAX_VALUE_LENGTH*3/4.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.getByteArray(String,byte[]),
get(String,String)
public abstract byte[] getByteArray(String key,
byte[] def)
putByteArray(java.lang.String, byte[]).
Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if the associated value is not a valid Base64 encoded byte array (as defined above).
If the implementation supports stored defaults and such a default exists and is accessible, it is used in preference to the specified default, unless the stored default is not a valid Base64 encoded byte array (as defined above), in which case the specified default is used.
key - key whose associated value is to be returned as a byte array.def - the value to be returned in the event that this
preference node has no value associated with key
or the associated value cannot be interpreted as a byte array,
or the backing store is inaccessible.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.
NullPointerException - if key is null. (A
null value for def is permitted.)get(String,String),
putByteArray(String,byte[])
public abstract String[] keys()
throws BackingStoreException
If the implementation supports stored defaults and there are any such defaults at this node that have not been overridden, by explicit preferences, the defaults are returned in the array in addition to any explicit preferences.
BackingStoreException - if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.
public abstract String[] childrenNames()
throws BackingStoreException
BackingStoreException - if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.public abstract Preferences parent()
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.public abstract Preferences node(String pathName)
If the returned node did not exist prior to this call, this node and any ancestors that were created by this call are not guaranteed to become permanent until the flush method is called on the returned node (or one of its ancestors or descendants).
pathName - the path name of the preference node to return.
IllegalArgumentException - if the path name is invalid (i.e.,
it contains multiple consecutive slash characters, or ends
with a slash character and is more than one character long).
NullPointerException - if path name is null.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.flush()
public abstract boolean nodeExists(String pathName)
throws BackingStoreException
If this node (or an ancestor) has already been removed with the
removeNode() method, it is legal to invoke this method,
but only with the path name ""; the invocation will return
false. Thus, the idiom p.nodeExists("") may be
used to test whether p has been removed.
pathName - the path name of the node whose existence
is to be checked.
BackingStoreException - if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
IllegalArgumentException - if the path name is invalid (i.e.,
it contains multiple consecutive slash characters, or ends
with a slash character and is more than one character long).
NullPointerException - if path name is null.
s * @throws IllegalStateException if this node (or an ancestor) has been
removed with the removeNode() method and
pathName is not the empty string ("").
public abstract void removeNode()
throws BackingStoreException
name(),
absolutePath(), isUserNode(), flush() or
nodeExists("") on the corresponding
Preferences instance will fail with an
IllegalStateException. (The methods defined on Object
can still be invoked on a node after it has been removed; they will not
throw IllegalStateException.)
The removal is not guaranteed to be persistent until the flush method is called on this node (or an ancestor).
If this implementation supports stored defaults, removing a node exposes any stored defaults at or below this node. Thus, a subsequent call to nodeExists on this node's path name may return true, and a subsequent call to node on this path name may may return a (different) Preferences instance representing a non-empty collection of preferences and/or children.
BackingStoreException - if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
IllegalStateException - if this node (or an ancestor) has already
been removed with the removeNode() method.
UnsupportedOperationException - if this method is invoked on
the root node.flush()public abstract String name()
public abstract String absolutePath()
public abstract boolean isUserNode()
public abstract String toString()
toString in class Object
public abstract void flush()
throws BackingStoreException
Implementations are free to flush changes into the persistent store at any time. They do not need to wait for this method to be called.
When a flush occurs on a newly created node, it is made persistent, as are any ancestors (and descendants) that have yet to be made persistent. Note however that any preference value changes in ancestors are not guaranteed to be made persistent.
BackingStoreException - if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.sync()
public abstract void sync()
throws BackingStoreException
BackingStoreException - if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.flush()public abstract void addPreferenceChangeListener(PreferenceChangeListener pcl)
removeNode() method, which generates a node change event.
Preference change events are generated by the clear
method.)
Events are only guaranteed for changes made within the same JVM as the registered listener, though some implementations may generate events for changes made outside this JVM. Events may be generated before the changes have been made persistent. Events are not generated when preferences are modified in descendants of this node; a caller desiring such events must register with each descendant.
pcl - The preference change listener to add.
NullPointerException - if pcl is null.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.removePreferenceChangeListener(PreferenceChangeListener),
addNodeChangeListener(NodeChangeListener)public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)
pcl - The preference change listener to remove.
IllegalArgumentException - if pcl was not a registered
preference change listener on this node.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.addPreferenceChangeListener(PreferenceChangeListener)public abstract void addNodeChangeListener(NodeChangeListener ncl)
removeNode()
invocation results in multiple node change events, one for every
node in the subtree rooted at the removed node.)
Events are only guaranteed for changes made within the same JVM as the registered listener, though some implementations may generate events for changes made outside this JVM. Events may be generated before the changes have become permanent. Events are not generated when indirect descendants of this node are added or removed; a caller desiring such events must register with each descendant.
Few guarantees can be made regarding node creation. Because nodes are created implicitly upon access, it may not be feasible for an implementation to determine whether a child node existed in the backing store prior to access (for example, because the backing store is unreachable or cached information is out of date). Under these circumstances, implementations are neither required to generate node change events nor prohibited from doing so.
ncl - The NodeChangeListener to add.
NullPointerException - if ncl is null.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.removeNodeChangeListener(NodeChangeListener),
addPreferenceChangeListener(PreferenceChangeListener)public abstract void removeNodeChangeListener(NodeChangeListener ncl)
ncl - The NodeChangeListener to remove.
IllegalArgumentException - if ncl was not a registered
NodeChangeListener on this node.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.addNodeChangeListener(NodeChangeListener)
public abstract void exportNode(OutputStream os)
throws IOException,
BackingStoreException
The XML document will have the following DOCTYPE declaration:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">The UTF-8 character encoding will be used.
This method is an exception to the general rule that the results of concurrently executing multiple methods in this class yields results equivalent to some serial execution. If the preferences at this node are modified concurrently with an invocation of this method, the exported preferences comprise a "fuzzy snapshot" of the preferences contained in the node; some of the concurrent modifications may be reflected in the exported data while others may not.
os - the output stream on which to emit the XML document.
IOException - if writing to the specified output stream
results in an IOException.
BackingStoreException - if preference data cannot be read from
backing store.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.importPreferences(InputStream)
public abstract void exportSubtree(OutputStream os)
throws IOException,
BackingStoreException
The XML document will have the following DOCTYPE declaration:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">The UTF-8 character encoding will be used.
This method is an exception to the general rule that the results of concurrently executing multiple methods in this class yields results equivalent to some serial execution. If the preferences or nodes in the subtree rooted at this node are modified concurrently with an invocation of this method, the exported preferences comprise a "fuzzy snapshot" of the subtree; some of the concurrent modifications may be reflected in the exported data while others may not.
os - the output stream on which to emit the XML document.
IOException - if writing to the specified output stream
results in an IOException.
BackingStoreException - if preference data cannot be read from
backing store.
IllegalStateException - if this node (or an ancestor) has been
removed with the removeNode() method.importPreferences(InputStream),
exportNode(OutputStream)
public static void importPreferences(InputStream is)
throws IOException,
InvalidPreferencesFormatException
The XML document must have the following DOCTYPE declaration:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">(This method is designed for use in conjunction with
exportNode(OutputStream) and
exportSubtree(OutputStream).
This method is an exception to the general rule that the results of
concurrently executing multiple methods in this class yields
results equivalent to some serial execution. The method behaves
as if implemented on top of the other public methods in this class,
notably node(String) and put(String, String).
is - the input stream from which to read the XML document.
IOException - if reading from the specified output stream
results in an IOException.
InvalidPreferencesFormatException - Data on input stream does not
constitute a valid XML document with the mandated document type.
SecurityException - If a security manager is present and
it denies RuntimePermission("preferences").RuntimePermission
|
JavaTM 2 Platform Std. Ed. v1.4.1 |
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.