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 {@link * 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: *
{@code
*
* }
* Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is
* not accessed when exporting or importing preferences; it merely
* serves as a string to uniquely identify the DTD, which is:
* {@code
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
* }
*
* Every Preferences implementation must have an associated {@link
* PreferencesFactory} implementation. Every Java(TM) SE 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 located as follows: * *
If the system property * java.util.prefs.PreferencesFactory is defined, then it is * taken to be the fully-qualified name of a class implementing the * PreferencesFactory interface. The class is loaded and * instantiated; if this process fails then an unspecified error is * thrown.
If a PreferencesFactory implementation class file * has been installed in a jar file that is visible to the * {@link java.lang.ClassLoader#getSystemClassLoader system class loader}, * and that jar file contains a provider-configuration file named * java.util.prefs.PreferencesFactory in the resource * directory META-INF/services, then the first class name * specified in that file is taken. If more than one such jar file is * provided, the first one found will be used. The class is loaded * and instantiated; if this process fails then an unspecified error * is thrown.
Finally, if neither the above-mentioned system property nor * an extension jar file is provided, then the system-wide default * PreferencesFactory implementation for the underlying * platform is loaded and instantiated.
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 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). * * @param c the class for whose package a user preference node is desired. * @return the user preference node associated with the package of which * c is a member. * @throws NullPointerException if c is null. * @throws SecurityException if a security manager is present and * it denies RuntimePermission("preferences"). * @see RuntimePermission */ public static Preferences userNodeForPackage(Class c) { return userRoot().node(nodeName(c)); } /** * WARNING: On Android, the Preference nodes * corresponding to the "system" and "user" preferences are stored in sections * of the file system that are inaccessible to apps. Further, allowing apps to set * "system wide" preferences is contrary to android's security model. * * Returns the preference node from the system preference tree that is * associated (by convention) with the specified class's package. The * convention is as follows: the absolute path name of the node is the * fully qualified package name, preceded by a slash ('/'), and * with each period ('.') replaced by a slash. For example the * absolute path name of the node associated with the class * com.acme.widget.Foo is /com/acme/widget. * *
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 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).
*
* @param c the class for whose package a system preference node is desired.
* @return the system preference node associated with the package of which
* c is a member.
* @throws NullPointerException if c is null.
* @throws SecurityException if a security manager is present and
* it denies RuntimePermission("preferences").
* @see RuntimePermission
*/
public static Preferences systemNodeForPackage(Class c) {
return systemRoot().node(nodeName(c));
}
/**
* Returns the absolute path name of the node corresponding to the package
* of the specified object.
*
* @throws IllegalArgumentException if the package has node preferences
* node associated with it.
*/
private static String nodeName(Class c) {
if (c.isArray())
throw new IllegalArgumentException(
"Arrays have no associated preferences node.");
String className = c.getName();
int pkgEndIndex = className.lastIndexOf('.');
if (pkgEndIndex < 0)
return "/ 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.
*
* @param key key whose associated value is to be returned.
* @param def the value to be returned in the event that this
* preference node has no value associated with key.
* @return the value associated with key, or def
* if no value is associated with key, or the backing
* store is inaccessible.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @throws NullPointerException if key is null. (A
* null value for def is permitted.)
*/
public abstract String get(String key, String def);
/**
* Removes the value associated with the specified key in this preference
* node, if any.
*
* 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.
*
* @param key key whose mapping is to be removed from the preference node.
* @throws NullPointerException if key is null.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
*/
public abstract void remove(String key);
/**
* Removes all of the preferences (key-value associations) in this
* preference node. This call has no effect on any descendants
* of this node.
*
* 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.
*
* @throws BackingStoreException if this operation cannot be completed
* due to a failure in the backing store, or inability to
* communicate with it.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #removeNode()
*/
public abstract void clear() throws BackingStoreException;
/**
* Associates a string representing the specified int value with the
* specified key in this preference node. The associated string is the
* one that would be returned if the int value were passed to
* {@link Integer#toString(int)}. This method is intended for use in
* conjunction with {@link #getInt}.
*
* @param key key with which the string form of value is to be associated.
* @param value value whose string form is to be associated with key.
* @throws NullPointerException if key is null.
* @throws IllegalArgumentException if key.length() exceeds
* MAX_KEY_LENGTH.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #getInt(String,int)
*/
public abstract void putInt(String key, int value);
/**
* Returns the int value represented by the string associated with the
* specified key in this preference node. The string is converted to
* an integer as by {@link 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 {@link
* NumberFormatException} if the associated value were passed. This
* method is intended for use in conjunction with {@link #putInt}.
*
* 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.
*
* @param key key whose associated value is to be returned as an int.
* @param 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.
* @return the int value represented by the string associated with
* key in this preference node, or def if the
* associated value does not exist or cannot be interpreted as
* an int.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @throws NullPointerException if key is null.
* @see #putInt(String,int)
* @see #get(String,String)
*/
public abstract int getInt(String key, int def);
/**
* Associates a string representing the specified long value with the
* specified key in this preference node. The associated string is the
* one that would be returned if the long value were passed to
* {@link Long#toString(long)}. This method is intended for use in
* conjunction with {@link #getLong}.
*
* @param key key with which the string form of value is to be associated.
* @param value value whose string form is to be associated with key.
* @throws NullPointerException if key is null.
* @throws IllegalArgumentException if key.length() exceeds
* MAX_KEY_LENGTH.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #getLong(String,long)
*/
public abstract void putLong(String key, long value);
/**
* Returns the long value represented by the string associated with the
* specified key in this preference node. The string is converted to
* a long as by {@link 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 {@link
* NumberFormatException} if the associated value were passed. This
* method is intended for use in conjunction with {@link #putLong}.
*
* 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.
*
* @param key key whose associated value is to be returned as a long.
* @param 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.
* @return the long value represented by the string associated with
* key in this preference node, or def if the
* associated value does not exist or cannot be interpreted as
* a long.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @throws NullPointerException if key is null.
* @see #putLong(String,long)
* @see #get(String,String)
*/
public abstract long getLong(String key, long def);
/**
* Associates a string representing the specified boolean value with the
* specified key in this preference node. The associated string is
* "true" if the value is true, and "false" if it is
* false. This method is intended for use in conjunction with
* {@link #getBoolean}.
*
* @param key key with which the string form of value is to be associated.
* @param value value whose string form is to be associated with key.
* @throws NullPointerException if key is null.
* @throws IllegalArgumentException if key.length() exceeds
* MAX_KEY_LENGTH.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #getBoolean(String,boolean)
* @see #get(String,String)
*/
public abstract void putBoolean(String key, boolean value);
/**
* Returns the boolean value represented by the string associated with the
* specified key in this preference node. Valid strings
* are "true", which represents true, and "false", which
* represents false. Case is ignored, so, for example, "TRUE"
* and "False" are also valid. This method is intended for use in
* conjunction with {@link #putBoolean}.
*
* 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.
*
* @param key key whose associated value is to be returned as a boolean.
* @param 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.
* @return the boolean value represented by the string associated with
* key in this preference node, or def if the
* associated value does not exist or cannot be interpreted as
* a boolean.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @throws NullPointerException if key is null.
* @see #get(String,String)
* @see #putBoolean(String,boolean)
*/
public abstract boolean getBoolean(String key, boolean def);
/**
* Associates a string representing the specified float value with the
* specified key in this preference node. The associated string is the
* one that would be returned if the float value were passed to
* {@link Float#toString(float)}. This method is intended for use in
* conjunction with {@link #getFloat}.
*
* @param key key with which the string form of value is to be associated.
* @param value value whose string form is to be associated with key.
* @throws NullPointerException if key is null.
* @throws IllegalArgumentException if key.length() exceeds
* MAX_KEY_LENGTH.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #getFloat(String,float)
*/
public abstract void putFloat(String key, float value);
/**
* Returns the float value represented by the string associated with the
* specified key in this preference node. The string is converted to an
* integer as by {@link 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
* {@link NumberFormatException} if the associated value were passed.
* This method is intended for use in conjunction with {@link #putFloat}.
*
* 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.
*
* @param key key whose associated value is to be returned as a float.
* @param 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.
* @return the float value represented by the string associated with
* key in this preference node, or def if the
* associated value does not exist or cannot be interpreted as
* a float.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @throws NullPointerException if key is null.
* @see #putFloat(String,float)
* @see #get(String,String)
*/
public abstract float getFloat(String key, float def);
/**
* Associates a string representing the specified double value with the
* specified key in this preference node. The associated string is the
* one that would be returned if the double value were passed to
* {@link Double#toString(double)}. This method is intended for use in
* conjunction with {@link #getDouble}.
*
* @param key key with which the string form of value is to be associated.
* @param value value whose string form is to be associated with key.
* @throws NullPointerException if key is null.
* @throws IllegalArgumentException if key.length() exceeds
* MAX_KEY_LENGTH.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #getDouble(String,double)
*/
public abstract void putDouble(String key, double value);
/**
* Returns the double value represented by the string associated with the
* specified key in this preference node. The string is converted to an
* integer as by {@link 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
* {@link NumberFormatException} if the associated value were passed.
* This method is intended for use in conjunction with {@link #putDouble}.
*
* 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.
*
* @param key key whose associated value is to be returned as a double.
* @param 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.
* @return the double value represented by the string associated with
* key in this preference node, or def if the
* associated value does not exist or cannot be interpreted as
* a double.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @throws NullPointerException if key is null.
* @see #putDouble(String,double)
* @see #get(String,String)
*/
public abstract double getDouble(String key, double def);
/**
* Associates a string representing the specified byte array with the
* specified key in this preference node. The associated string is
* the Base64 encoding of the byte array, as defined in RFC 2045, Section 6.8,
* with one minor change: the string will consist solely of characters
* from the Base64 Alphabet; it will not contain any newline
* characters. Note that the maximum length of the byte array is limited
* to three quarters of MAX_VALUE_LENGTH so that the length
* of the Base64 encoded String does not exceed MAX_VALUE_LENGTH.
* This method is intended for use in conjunction with
* {@link #getByteArray}.
*
* @param key key with which the string form of value is to be associated.
* @param value value whose string form is to be associated with key.
* @throws NullPointerException if key or value is null.
* @throws IllegalArgumentException if key.length() exceeds MAX_KEY_LENGTH
* or if value.length exceeds MAX_VALUE_LENGTH*3/4.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #getByteArray(String,byte[])
* @see #get(String,String)
*/
public abstract void putByteArray(String key, byte[] value);
/**
* Returns the byte array value represented by the string associated with
* the specified key in this preference node. Valid strings are
* Base64 encoded binary data, as defined in RFC 2045, Section 6.8,
* with one minor change: the string must consist solely of characters
* from the Base64 Alphabet; no newline characters or
* extraneous characters are permitted. This method is intended for use
* in conjunction with {@link #putByteArray}.
*
* 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.
*
* @param key key whose associated value is to be returned as a byte array.
* @param 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.
* @return the byte array value represented by the string associated with
* key in this preference node, or def if the
* associated value does not exist or cannot be interpreted as
* a byte array.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @throws NullPointerException if key is null. (A
* null value for def is permitted.)
* @see #get(String,String)
* @see #putByteArray(String,byte[])
*/
public abstract byte[] getByteArray(String key, byte[] def);
/**
* Returns all of the keys that have an associated value in this
* preference node. (The returned array will be of size zero if
* this node has no preferences.)
*
* 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.
*
* @return an array of the keys that have an associated value in this
* preference node.
* @throws BackingStoreException if this operation cannot be completed
* due to a failure in the backing store, or inability to
* communicate with it.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
*/
public abstract String[] keys() throws BackingStoreException;
/**
* Returns the names of the children of this preference node, relative to
* this node. (The returned array will be of size zero if this node has
* no children.)
*
* @return the names of the children of this preference node.
* @throws BackingStoreException if this operation cannot be completed
* due to a failure in the backing store, or inability to
* communicate with it.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
*/
public abstract String[] childrenNames() throws BackingStoreException;
/**
* Returns the parent of this preference node, or null if this is
* the root.
*
* @return the parent of this preference node.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
*/
public abstract Preferences parent();
/**
* 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.
* Accepts a relative or absolute path name. Relative path names
* (which do not begin with the slash character ('/')) are
* interpreted relative to this preference node.
*
* 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).
*
* @param pathName the path name of the preference node to return.
* @return the specified preference node.
* @throws 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).
* @throws NullPointerException if path name is null.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #flush()
*/
public abstract Preferences node(String pathName);
/**
* Returns true if the named preference node exists in the same tree
* as this node. Relative path names (which do not begin with the slash
* character ('/')) are interpreted relative to this preference
* node.
*
* If this node (or an ancestor) has already been removed with the
* {@link #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.
*
* @param pathName the path name of the node whose existence
* is to be checked.
* @return true if the specified node exists.
* @throws BackingStoreException if this operation cannot be completed
* due to a failure in the backing store, or inability to
* communicate with it.
* @throws 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).
* @throws NullPointerException if path name is null.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method and
* pathName is not the empty string ("").
*/
public abstract boolean nodeExists(String pathName)
throws BackingStoreException;
/**
* Removes this preference node and all of its descendants, invalidating
* any preferences contained in the removed nodes. Once a node has been
* removed, attempting any method other than {@link #name()},
* {@link #absolutePath()}, {@link #isUserNode()}, {@link #flush()} or
* {@link #node(String) nodeExists("")} on the corresponding
* Preferences instance will fail with an
* IllegalStateException. (The methods defined on {@link 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 return a (different) Preferences instance
* representing a non-empty collection of preferences and/or children.
*
* @throws BackingStoreException if this operation cannot be completed
* due to a failure in the backing store, or inability to
* communicate with it.
* @throws IllegalStateException if this node (or an ancestor) has already
* been removed with the {@link #removeNode()} method.
* @throws UnsupportedOperationException if this method is invoked on
* the root node.
* @see #flush()
*/
public abstract void removeNode() throws BackingStoreException;
/**
* Returns this preference node's name, relative to its parent.
*
* @return this preference node's name, relative to its parent.
*/
public abstract String name();
/**
* Returns this preference node's absolute path name.
*
* @return this preference node's absolute path name.
*/
public abstract String absolutePath();
/**
* Returns true if this preference node is in the user
* preference tree, false if it's in the system preference tree.
*
* @return true if this preference node is in the user
* preference tree, false if it's in the system
* preference tree.
*/
public abstract boolean isUserNode();
/**
* Returns a string representation of this preferences node,
* as if computed by the expression:(this.isUserNode() ? "User" :
* "System") + " Preference Node: " + this.absolutePath().
*/
public abstract String toString();
/**
* Forces any changes in the contents of this preference node and its
* descendants to the persistent store. Once this method returns
* successfully, it is safe to assume that all changes made in the
* subtree rooted at this node prior to the method invocation have become
* permanent.
*
* 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.
*
* If this method is invoked on a node that has been removed with
* the {@link #removeNode()} method, flushSpi() is invoked on this node,
* but not on others.
*
* @throws BackingStoreException if this operation cannot be completed
* due to a failure in the backing store, or inability to
* communicate with it.
* @see #sync()
*/
public abstract void flush() throws BackingStoreException;
/**
* 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. As a
* side-effect, forces any changes in the contents of this preference node
* and its descendants to the persistent store, as if the flush
* method had been invoked on this node.
*
* @throws BackingStoreException if this operation cannot be completed
* due to a failure in the backing store, or inability to
* communicate with it.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #flush()
*/
public abstract void sync() throws BackingStoreException;
/**
* Registers the specified listener to receive preference change
* events for this preference node. A preference change event is
* generated when a preference is added to this node, removed from this
* node, or when the value associated with a preference is changed.
* (Preference change events are not generated by the {@link
* #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.
*
* @param pcl The preference change listener to add.
* @throws NullPointerException if pcl is null.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #removePreferenceChangeListener(PreferenceChangeListener)
* @see #addNodeChangeListener(NodeChangeListener)
*/
public abstract void addPreferenceChangeListener(
PreferenceChangeListener pcl);
/**
* Removes the specified preference change listener, so it no longer
* receives preference change events.
*
* @param pcl The preference change listener to remove.
* @throws IllegalArgumentException if pcl was not a registered
* preference change listener on this node.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #addPreferenceChangeListener(PreferenceChangeListener)
*/
public abstract void removePreferenceChangeListener(
PreferenceChangeListener pcl);
/**
* Registers the specified listener to receive node change events
* for this node. A node change event is generated when a child node is
* added to or removed from this node. (A single {@link #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.
*
* @param ncl The NodeChangeListener to add.
* @throws NullPointerException if ncl is null.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #removeNodeChangeListener(NodeChangeListener)
* @see #addPreferenceChangeListener(PreferenceChangeListener)
*/
public abstract void addNodeChangeListener(NodeChangeListener ncl);
/**
* Removes the specified NodeChangeListener, so it no longer
* receives change events.
*
* @param ncl The NodeChangeListener to remove.
* @throws IllegalArgumentException if ncl was not a registered
* NodeChangeListener on this node.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #addNodeChangeListener(NodeChangeListener)
*/
public abstract void removeNodeChangeListener(NodeChangeListener ncl);
/**
* Emits on the specified output stream an XML document representing all
* of the preferences contained in this node (but not its descendants).
* This XML document is, in effect, an offline backup of the node.
*
* The XML document will have the following DOCTYPE declaration:
* 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.
*
* @param os the output stream on which to emit the XML document.
* @throws IOException if writing to the specified output stream
* results in an IOException.
* @throws BackingStoreException if preference data cannot be read from
* backing store.
* @see #importPreferences(InputStream)
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
*/
public abstract void exportNode(OutputStream os)
throws IOException, BackingStoreException;
/**
* Emits an XML document representing all of the preferences contained
* in this node and all of its descendants. This XML document is, in
* effect, an offline backup of the subtree rooted at the node.
*
* The XML document will have the following DOCTYPE declaration:
* 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.
*
* @param os the output stream on which to emit the XML document.
* @throws IOException if writing to the specified output stream
* results in an IOException.
* @throws BackingStoreException if preference data cannot be read from
* backing store.
* @throws IllegalStateException if this node (or an ancestor) has been
* removed with the {@link #removeNode()} method.
* @see #importPreferences(InputStream)
* @see #exportNode(OutputStream)
*/
public abstract void exportSubtree(OutputStream os)
throws IOException, BackingStoreException;
/**
* Imports all of the preferences represented by the XML document on the
* specified input stream. The document may represent user preferences or
* system preferences. If it represents user preferences, the preferences
* will be imported into the calling user's preference tree (even if they
* originally came from a different user's preference tree). If any of
* the preferences described by the document inhabit preference nodes that
* do not exist, the nodes will be created.
*
* The XML document must have the following DOCTYPE declaration:
* 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 {@link #node(String)} and {@link #put(String, String)}.
*
* @param is the input stream from which to read the XML document.
* @throws IOException if reading from the specified input stream
* results in an IOException.
* @throws InvalidPreferencesFormatException Data on input stream does not
* constitute a valid XML document with the mandated document type.
* @throws SecurityException If a security manager is present and
* it denies RuntimePermission("preferences").
* @see RuntimePermission
*/
public static void importPreferences(InputStream is)
throws IOException, InvalidPreferencesFormatException
{
XmlSupport.importPreferences(is);
}
}
{@code
*
* }
* The UTF-8 character encoding will be used.
*
* {@code
*
* }
* The UTF-8 character encoding will be used.
*
* {@code
*
* }
* (This method is designed for use in conjunction with
* {@link #exportNode(OutputStream)} and
* {@link #exportSubtree(OutputStream)}.
*
*