/* * Copyright (C) 2014 The Android Open Source Project * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.util.prefs; import java.io.InputStream; import java.io.IOException; import java.io.OutputStream; import java.security.AccessController; import java.security.Permission; import java.security.PrivilegedAction; import java.util.Iterator; import java.util.ServiceLoader; import java.util.ServiceConfigurationError; // These imports needed only as a workaround for a JavaDoc bug import java.lang.RuntimePermission; import java.lang.Integer; import java.lang.Long; import java.lang.Float; import java.lang.Double; /** * A node in a hierarchical collection of preference data. This class * allows applications to store and retrieve user and system * preference and configuration data. This data is stored * persistently in an implementation-dependent backing store. Typical * implementations include flat files, OS-specific registries, * directory servers and SQL databases. The user of this class needn't * be concerned with details of the backing store. * *

There are two separate trees of preference nodes, one for user * preferences and one for system preferences. Each user has a separate user * preference tree, and all users in a given system share the same system * preference tree. The precise description of "user" and "system" will vary * from implementation to implementation. Typical information stored in the * user preference tree might include font choice, color choice, or preferred * window location and size for a particular application. Typical information * stored in the system preference tree might include installation * configuration data for an application. * *

Nodes in a preference tree are named in a similar fashion to * directories in a hierarchical file system. Every node in a preference * tree has a node name (which is not necessarily unique), * a unique absolute path name, and a path name relative to each * ancestor including itself. * *

The root node has a node name of the empty string (""). Every other * node has an arbitrary node name, specified at the time it is created. The * only restrictions on this name are that it cannot be the empty string, and * it cannot contain the slash character ('/'). * *

The root node has an absolute path name of "/". Children of * the root node have absolute path names of "/" + <node * name>. All other nodes have absolute path names of <parent's * absolute path name> + "/" + <node name>. * Note that all absolute path names begin with the slash character. * *

A node n's path name relative to its ancestor a * is simply the string that must be appended to a's absolute path name * in order to form n's absolute path name, with the initial slash * character (if present) removed. Note that: *

* *

Note finally that: *

* *

All of the methods that modify preferences data are permitted to operate * asynchronously; they may return immediately, and changes will eventually * propagate to the persistent backing store with an implementation-dependent * delay. The flush method may be used to synchronously force * updates to the backing store. Normal termination of the Java Virtual * Machine will not result in the loss of pending updates -- an explicit * flush invocation is not required upon termination to ensure * that pending updates are made persistent. * *

All of the methods that read preferences from a Preferences * object require the invoker to provide a default value. The default value is * returned if no value has been previously set or if the backing store is * unavailable. The intent is to allow applications to operate, albeit * with slightly degraded functionality, even if the backing store becomes * unavailable. Several methods, like flush, have semantics that * prevent them from operating if the backing store is unavailable. Ordinary * applications should have no need to invoke any of these methods, which can * be identified by the fact that they are declared to throw {@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: * *

    * *
  1. 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.

  2. * *
  3. 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.

  4. * *
  5. 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.

  6. * *
* * @author Josh Bloch * @since 1.4 */ public abstract class Preferences { // Android-changed: Not final for testing. private static PreferencesFactory factory = findPreferencesFactory(); // Android-changed: Custom implementation of findPreferencesFactory. private static PreferencesFactory findPreferencesFactory() { // Try the system property first... PreferencesFactory result = ServiceLoader.loadFromSystemProperty(PreferencesFactory.class); if (result != null) { return result; } // Then use ServiceLoader for META-INF/services/... for (PreferencesFactory impl : ServiceLoader.load(PreferencesFactory.class)) { return impl; } // Finally return a default... return new FileSystemPreferencesFactory(); } /** * @hide for testing only. */ // Android-changed: Allow this to be set for testing. public static PreferencesFactory setPreferencesFactory(PreferencesFactory pf) { PreferencesFactory previous = factory; factory = pf; return previous; } /** * Maximum length of string allowed as a key (80 characters). */ public static final int MAX_KEY_LENGTH = 80; /** * Maximum length of string allowed as a value (8192 characters). */ public static final int MAX_VALUE_LENGTH = 8*1024; /** * Maximum length of a node name (80 characters). */ public static final int MAX_NAME_LENGTH = 80; /** * 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 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.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.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 "/"; String packageName = className.substring(0, pkgEndIndex); return "/" + packageName.replace('.', '/'); } /** * This permission object represents the permission required to get * access to the user or system root (which in turn allows for all * other operations). */ private static Permission prefsPerm = new RuntimePermission("preferences"); /** * 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 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 */ public static Preferences userRoot() { SecurityManager security = System.getSecurityManager(); if (security != null) security.checkPermission(prefsPerm); return factory.userRoot(); } /** * 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 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 */ public static Preferences systemRoot() { SecurityManager security = System.getSecurityManager(); if (security != null) security.checkPermission(prefsPerm); return factory.systemRoot(); } /** * Sole constructor. (For invocation by subclass constructors, typically * implicit.) */ protected Preferences() { } /** * 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 put(String key, String value); /** * 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 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: *

{@code
     * 
     * }
* 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 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: *

{@code
     * 
     * }
* 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) */ 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: *

{@code
     * 
     * }
* (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 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); } }