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.
Parameters:
- ncl - The NodeChangeListener to add.
Throws:
- NullPointerException - if ncl is null.
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
See Also: Preferences.removeNodeChangeListener(NodeChangeListener), Preferences.addPreferenceChangeListener(PreferenceChangeListener),

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.
Parameters:
- pcl - The preference change listener to add.
Throws:
- NullPointerException - if pcl is null.
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
See Also: Preferences.removePreferenceChangeListener(PreferenceChangeListener), Preferences.addNodeChangeListener(NodeChangeListener),

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.
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
See Also: Preferences.removeNode(),

The XML document will have the following DOCTYPE declaration:

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
 

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.
Parameters:
- os - the output stream on which to emit the XML document.
Throws:
- 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 {@link #removeNode()} method.
See Also: Preferences.importPreferences(InputStream),

The XML document will have the following DOCTYPE declaration:

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
 

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.
Parameters:
- os - the output stream on which to emit the XML document.
Throws:
- 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 {@link #removeNode()} method.
See Also: Preferences.importPreferences(InputStream), Preferences.exportNode(OutputStream),

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 Preferences.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 Also: Preferences.sync(),

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.
Returns: the value associated with key, or def if no value is associated with key, or the backing store is inaccessible.
Parameters:
- 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.
Throws:
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
- NullPointerException - if key is null. (A null value for def is permitted.)

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.
Returns: 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.
Parameters:
- 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.
Throws:
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
- NullPointerException - if key is null.
See Also: Preferences.get(String,String), Preferences.putBoolean(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 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.
Returns: 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.
Parameters:
- 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.
Throws:
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
- NullPointerException - if key is null. (A null value for def is permitted.)
See Also: Preferences.get(String,String), Preferences.putByteArray(String,byte[]),

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.
Returns: 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.
Parameters:
- 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.
Throws:
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
- NullPointerException - if key is null.
See Also: Preferences.putDouble(String,double), Preferences.get(String,String),

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.
Returns: 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.
Parameters:
- 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.
Throws:
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
- NullPointerException - if key is null.
See Also: Preferences.putFloat(String,float), Preferences.get(String,String),

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.
Returns: 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.
Parameters:
- 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.
Throws:
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
- NullPointerException - if key is null.
See Also: Preferences.putInt(String,int), Preferences.get(String,String),

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.
Returns: 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.
Parameters:
- 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.
Throws:
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
- NullPointerException - if key is null.
See Also: Preferences.putLong(String,long), Preferences.get(String,String),

The XML document must have the following DOCTYPE declaration:

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
 

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 Preferences.node(String) and Preferences.put(String, String).
Parameters:
- is - the input stream from which to read the XML document.
Throws:
- IOException - if reading from the specified input 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").
See Also: RuntimePermission,

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.
Returns: 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.
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.

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).
Returns: the specified preference node.
Parameters:
- pathName - the path name of the preference node to return.
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).
- NullPointerException - if path name is null.
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
See Also: Preferences.flush(),

If this node (or an ancestor) has already been removed with the Preferences.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.
Returns: true if the specified node exists.
Parameters:
- pathName - the path name of the node whose existence is to be checked.
Throws:
- 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.
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method and pathName is not the empty string ("").

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.
Parameters:
- key - key whose mapping is to be removed from the preference node.
Throws:
- NullPointerException - if key is null.
- IllegalStateException - if this node (or an ancestor) has been removed with the {@link #removeNode()} method.

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.
- IllegalStateException - if this node (or an ancestor) has already been removed with the {@link #removeNode()} method.
- UnsupportedOperationException - if this method is invoked on the root node.
See Also: Preferences.flush(),

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

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).
Returns: the system preference node associated with the package of which c is a member.
Parameters:
- c - the class for whose package a system preference node is desired.
Throws:
- NullPointerException - if c is null.
- SecurityException - if a security manager is present and it denies RuntimePermission("preferences").
See Also: RuntimePermission,

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

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).
Returns: the user preference node associated with the package of which c is a member.
Parameters:
- c - the class for whose package a user preference node is desired.
Throws:
- NullPointerException - if c is null.
- SecurityException - if a security manager is present and it denies RuntimePermission("preferences").
See Also: RuntimePermission,