File	Doc	Category	Size	Date	Package
Preferences.java	API Doc	Java SE 5 API	59855	Fri Aug 26 14:57:28 BST 2005	java.util.prefs

Preferences

• java.lang.Object

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

<?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 >

Fields Summary
private static final PreferencesFactory	factory
public static final int	MAX_KEY_LENGTH Maximum length of string allowed as a key (80 characters).
public static final int	MAX_VALUE_LENGTH Maximum length of string allowed as a value (8192 characters).
public static final int	MAX_NAME_LENGTH Maximum length of a node name (80 characters).
private static Permission	prefsPerm This permission object represents the permission required to get access to the user or system root (which in turn allows for all other operations).

Constructors Summary
protected Preferences() Sole constructor. (For invocation by subclass constructors, typically implicit.)

Methods Summary
public abstract java.lang.String	absolutePath() Returns this preference node's absolute path name. return this preference node's absolute path name.
public abstract void	addNodeChangeListener(java.util.prefs.NodeChangeListener ncl) 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	addPreferenceChangeListener(java.util.prefs.PreferenceChangeListener pcl) 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 java.lang.String[]	childrenNames() 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 void	clear() 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	exportNode(java.io.OutputStream os) 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: <!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. 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	exportSubtree(java.io.OutputStream os) 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: <!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. 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)
private static java.util.prefs.PreferencesFactory	factory() // 1. Try user-specified system property String factoryName = AccessController.doPrivileged( new PrivilegedAction<String>() { public String run() { return System.getProperty( "java.util.prefs.PreferencesFactory");}}); if (factoryName != null) { // FIXME: This code should be run in a doPrivileged and // not use the context classloader, to avoid being // dependent on the invoking thread. // Checking AllPermission also seems wrong. try { return (PreferencesFactory) Class.forName(factoryName, false, ClassLoader.getSystemClassLoader()) .newInstance(); } catch (Exception ex) { try { // workaround for javaws, plugin, // load factory class using non-system classloader SecurityManager sm = System.getSecurityManager(); if (sm != null) { sm.checkPermission(new java.security.AllPermission()); } return (PreferencesFactory) Class.forName(factoryName, false, Thread.currentThread() .getContextClassLoader()) .newInstance(); } catch (Exception e) { InternalError error = new InternalError( "Can't instantiate Preferences factory " + factoryName); error.initCause(e); throw error; } } } return AccessController.doPrivileged( new PrivilegedAction<PreferencesFactory>() { public PreferencesFactory run() { return factory1();}});
private static java.util.prefs.PreferencesFactory	factory1() // 2. Try service provider interface Iterator i = Service.providers(PreferencesFactory.class, ClassLoader.getSystemClassLoader()); // choose first provider instance while (i.hasNext()) { try { return (PreferencesFactory) i.next(); } catch (ServiceConfigurationError sce) { if (sce.getCause() instanceof SecurityException) { // Ignore the security exception, try the next provider continue; } throw sce; } } // 3. Use platform-specific system-wide default String platformFactory = System.getProperty("os.name").startsWith("Windows") ? "java.util.prefs.WindowsPreferencesFactory" : "java.util.prefs.FileSystemPreferencesFactory"; try { return (PreferencesFactory) Class.forName(platformFactory, false, null).newInstance(); } catch (Exception e) { InternalError error = new InternalError( "Can't instantiate platform default Preferences factory " + platformFactory); error.initCause(e); throw error; }
public abstract void	flush() 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 java.lang.String	get(java.lang.String key, java.lang.String def) Returns the value associated with the specified key in this preference node. Returns the specified default if there is no value associated with the key, or the backing store is inaccessible. 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 boolean	getBoolean(java.lang.String key, boolean def) 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 byte[]	getByteArray(java.lang.String key, byte[] def) 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 double	getDouble(java.lang.String key, double def) 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 float	getFloat(java.lang.String key, float def) 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 int	getInt(java.lang.String key, int def) 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 long	getLong(java.lang.String key, long def) 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 static void	importPreferences(java.io.InputStream is) 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: <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd"> (This method is designed for use in conjunction with {@link #exportNode(OutputStream)} and {@link #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 {@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 output 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 XmlSupport.importPreferences(is);
public abstract boolean	isUserNode() 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 java.lang.String[]	keys() 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 java.lang.String	name() Returns this preference node's name, relative to its parent. return this preference node's name, relative to its parent.
public abstract java.util.prefs.Preferences	node(java.lang.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. 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 boolean	nodeExists(java.lang.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. s * @throws IllegalStateException if this node (or an ancestor) has been removed with the {@link #removeNode()} method and pathName is not the empty string ("").
private static java.lang.String	nodeName(java.lang.Class 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. if (c.isArray()) throw new IllegalArgumentException( "Arrays have no associated preferences node."); String className = c.getName(); int pkgEndIndex = className.lastIndexOf('."); if (pkgEndIndex < 0) return "/<unnamed>"; String packageName = className.substring(0, pkgEndIndex); return "/" + packageName.replace('.", '/");
public abstract java.util.prefs.Preferences	parent() 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 void	put(java.lang.String key, java.lang.String value) Associates the specified value with the specified key in this preference node. param key key with which the specified value is to be associated. param value value to be associated with the specified 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. throws IllegalStateException if this node (or an ancestor) has been removed with the {@link #removeNode()} method.
public abstract void	putBoolean(java.lang.String key, boolean value) 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	putByteArray(java.lang.String key, byte[] value) 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	putDouble(java.lang.String key, double value) 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	putFloat(java.lang.String key, float value) 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	putInt(java.lang.String key, int value) 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	putLong(java.lang.String key, long value) 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	remove(java.lang.String key) 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	removeNode() 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	removeNodeChangeListener(java.util.prefs.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	removePreferenceChangeListener(java.util.prefs.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	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. 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 static java.util.prefs.Preferences	systemNodeForPackage(java.lang.Class c) 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 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 return systemRoot().node(nodeName(c));
public static java.util.prefs.Preferences	systemRoot() Returns the root preference node for the system. return the root preference node for the system. throws SecurityException If a security manager is present and it denies RuntimePermission("preferences"). see RuntimePermission SecurityManager security = System.getSecurityManager(); if (security != null) security.checkPermission(prefsPerm); return factory.systemRoot();
public abstract java.lang.String	toString() Returns a string representation of this preferences node, as if computed by the expression:(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath().
public static java.util.prefs.Preferences	userNodeForPackage(java.lang.Class c) Returns the preference node from the calling user's 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 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.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 return userRoot().node(nodeName(c));
public static java.util.prefs.Preferences	userRoot() Returns the root preference node for the calling user. return the root preference node for the calling user. throws SecurityException If a security manager is present and it denies RuntimePermission("preferences"). see RuntimePermission SecurityManager security = System.getSecurityManager(); if (security != null) security.checkPermission(prefsPerm); return factory.userRoot();