| /* | |
| * Copyright (c) 2000, 2024, 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 jdk.internal.util.OperatingSystem; | |
| import java.io.InputStream; | |
| import java.io.IOException; | |
| import java.io.OutputStream; | |
| import java.util.Iterator; | |
| import java.util.ServiceLoader; | |
| import java.util.ServiceConfigurationError; | |
| /** | |
| * 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. | |
| * | |
| * <p>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. | |
| * | |
| * <p>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 <i>node name</i> (which is not necessarily unique), | |
| * a unique <i>absolute path name</i>, and a path name <i>relative</i> to each | |
| * ancestor including itself. | |
| * | |
| * <p>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 ('/'). | |
| * | |
| * <p>The root node has an absolute path name of {@code "/"}. Children of | |
| * the root node have absolute path names of {@code "/" + }<i><node | |
| * name></i>. All other nodes have absolute path names of <i><parent's | |
| * absolute path name></i>{@code + "/" + }<i><node name></i>. | |
| * Note that all absolute path names begin with the slash character. | |
| * | |
| * <p>A node <i>n</i>'s path name relative to its ancestor <i>a</i> | |
| * is simply the string that must be appended to <i>a</i>'s absolute path name | |
| * in order to form <i>n</i>'s absolute path name, with the initial slash | |
| * character (if present) removed. Note that: | |
| * <ul> | |
| * <li>No relative path names begin with the slash character. | |
| * <li>Every node's path name relative to itself is the empty string. | |
| * <li>Every node's path name relative to its parent is its node name (except | |
| * for the root node, which does not have a parent). | |
| * <li>Every node's path name relative to the root is its absolute path name | |
| * with the initial slash character removed. | |
| * </ul> | |
| * | |
| * <p>Note finally that: | |
| * <ul> | |
| * <li>No path name contains multiple consecutive slash characters. | |
| * <li>No path name with the exception of the root's absolute path name | |
| * ends in the slash character. | |
| * <li>Any string that conforms to these two rules is a valid path name. | |
| * </ul> | |
| * | |
| * <p>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 {@code flush} method may be used to synchronously force | |
| * updates to the backing store. Normal termination of the Java Virtual | |
| * Machine will <i>not</i> result in the loss of pending updates -- an explicit | |
| * {@code flush} invocation is <i>not</i> required upon termination to ensure | |
| * that pending updates are made persistent. | |
| * | |
| * <p>All of the methods that read preferences from a {@code Preferences} | |
| * object require the invoker to provide a default value. The default value is | |
| * returned if no value has been previously set <i>or if the backing store is | |
| * unavailable</i>. The intent is to allow applications to operate, albeit | |
| * with slightly degraded functionality, even if the backing store becomes | |
| * unavailable. Several methods, like {@code 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}. | |
| * | |
| * <p>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 <i>by multiple JVMs</i> 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. | |
| * | |
| * <p>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. | |
| * | |
| * <p>The XML document has the following DOCTYPE declaration: | |
| * <pre>{@code | |
| * <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd"> | |
| * }</pre> | |
| * Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is | |
| * <i>not</i> accessed when exporting or importing preferences; it merely | |
| * serves as a string to uniquely identify the DTD, which is: | |
| * <pre>{@code | |
| * <?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 > | |
| * }</pre> | |
| * | |
| * Every {@code Preferences} implementation must have an associated {@link | |
| * PreferencesFactory} implementation. Every Java(TM) SE implementation must provide | |
| * some means of specifying which {@code PreferencesFactory} implementation | |
| * is used to generate the root preferences nodes. This allows the | |
| * administrator to replace the default preferences implementation with an | |
| * alternative implementation. | |
| * | |
| * @implNote | |
| * The {@code PreferencesFactory} implementation is located as follows: | |
| * | |
| * <ol> | |
| * | |
| * <li><p>If the system property | |
| * {@systemProperty java.util.prefs.PreferencesFactory} is defined, then it is | |
| * taken to be the fully-qualified name of a class implementing the | |
| * {@code PreferencesFactory} interface. The class is loaded and | |
| * instantiated; if this process fails then an unspecified error is | |
| * thrown.</p></li> | |
| * | |
| * <li><p> If a {@code 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 | |
| * {@code java.util.prefs.PreferencesFactory} in the resource | |
| * directory {@code 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. </p></li> | |
| * | |
| * <li><p>Finally, if neither the above-mentioned system property nor | |
| * an extension jar file is provided, then the system-wide default | |
| * {@code PreferencesFactory} implementation for the underlying | |
| * platform is loaded and instantiated.</p></li> | |
| * | |
| * </ol> | |
| * | |
| * @author Josh Bloch | |
| * @since 1.4 | |
| */ | |
| public abstract class Preferences { | |
| private static final PreferencesFactory factory = factory(); | |
| private static PreferencesFactory factory() { | |
| // 1. Try user-specified system property | |
| String factoryName = System.getProperty("java.util.prefs.PreferencesFactory"); | |
| if (factoryName != null) { | |
| try { | |
| @SuppressWarnings("deprecation") | |
| Object result =Class.forName(factoryName, false, | |
| ClassLoader.getSystemClassLoader()) | |
| .newInstance(); | |
| return (PreferencesFactory)result; | |
| } catch (Exception ex) { | |
| try { | |
| // workaround for javaws, plugin, | |
| // load factory class using non-system classloader | |
| @SuppressWarnings("deprecation") | |
| Object result = Class.forName(factoryName, false, | |
| Thread.currentThread() | |
| .getContextClassLoader()) | |
| .newInstance(); | |
| return (PreferencesFactory) result; | |
| } catch (Exception e) { | |
| throw new InternalError( | |
| "Can't instantiate Preferences factory " | |
| + factoryName, e); | |
| } | |
| } | |
| } | |
| // 2. Try service provider interface | |
| Iterator<PreferencesFactory> itr = ServiceLoader | |
| .load(PreferencesFactory.class, ClassLoader.getSystemClassLoader()) | |
| .iterator(); | |
| // choose first provider instance | |
| while (itr.hasNext()) { | |
| try { | |
| return itr.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 = switch (OperatingSystem.current()) { | |
| case WINDOWS -> "java.util.prefs.WindowsPreferencesFactory"; | |
| case MACOS -> "java.util.prefs.MacOSXPreferencesFactory"; | |
| default -> "java.util.prefs.FileSystemPreferencesFactory"; | |
| }; | |
| try { | |
| @SuppressWarnings("deprecation") | |
| Object result = Class.forName(platformFactory, false, | |
| Preferences.class.getClassLoader()).newInstance(); | |
| return (PreferencesFactory) result; | |
| } catch (Exception e) { | |
| throw new InternalError( | |
| "Can't instantiate platform default Preferences factory " | |
| + platformFactory, e); | |
| } | |
| } | |
| /** | |
| * 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; | |
| /** | |
| * 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 ({@code '/'}), and | |
| * with each period ({@code '.'}) replaced by a slash. For example the | |
| * absolute path name of the node associated with the class | |
| * {@code com.acme.widget.Foo} is {@code /com/acme/widget}. | |
| * | |
| * <p>This convention does not apply to the unnamed package, whose | |
| * associated preference node is {@code <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. <i>Valuable data should not be stored | |
| * at this node as it is shared by all programs that use it.</i> | |
| * | |
| * <p>A class {@code Foo} wishing to access preferences pertaining to its | |
| * package can obtain a preference node as follows: <pre> | |
| * static Preferences prefs = Preferences.userNodeForPackage(Foo.class); | |
| * </pre> | |
| * 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.) | |
| * | |
| * <p>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 {@code 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 | |
| * {@code c} is a member. | |
| * @throws NullPointerException if {@code c} is {@code null}. | |
| */ | |
| public static Preferences userNodeForPackage(Class<?> c) { | |
| return userRoot().node(nodeName(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 ({@code '/'}), and | |
| * with each period ({@code '.'}) replaced by a slash. For example the | |
| * absolute path name of the node associated with the class | |
| * {@code com.acme.widget.Foo} is {@code /com/acme/widget}. | |
| * | |
| * <p>This convention does not apply to the unnamed package, whose | |
| * associated preference node is {@code <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. <i>Valuable data should not be stored | |
| * at this node as it is shared by all programs that use it.</i> | |
| * | |
| * <p>A class {@code Foo} wishing to access preferences pertaining to its | |
| * package can obtain a preference node as follows: <pre> | |
| * static Preferences prefs = Preferences.systemNodeForPackage(Foo.class); | |
| * </pre> | |
| * 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.) | |
| * | |
| * <p>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 {@code 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 | |
| * {@code c} is a member. | |
| * @throws NullPointerException if {@code c} is {@code null}. | |
| */ | |
| 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 "/<unnamed>"; | |
| String packageName = className.substring(0, pkgEndIndex); | |
| return "/" + packageName.replace('.', '/'); | |
| } | |
| /** | |
| * Returns the root preference node for the calling user. | |
| * | |
| * @return the root preference node for the calling user. | |
| */ | |
| public static Preferences userRoot() { | |
| return factory.userRoot(); | |
| } | |
| /** | |
| * Returns the root preference node for the system. | |
| * | |
| * @return the root preference node for the system. | |
| */ | |
| public static Preferences systemRoot() { | |
| 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 {@code null}. | |
| * @throws IllegalArgumentException if {@code key.length()} exceeds | |
| * {@code MAX_KEY_LENGTH} or if {@code value.length} exceeds | |
| * {@code MAX_VALUE_LENGTH}. | |
| * @throws IllegalStateException if this node (or an ancestor) has been | |
| * removed with the {@link #removeNode()} method. | |
| * @throws IllegalArgumentException if either key or value contain | |
| * the null control character, code point U+0000. | |
| */ | |
| 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. | |
| * | |
| * <p>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 <i>stored default</i>, 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 {@code key}. | |
| * @return the value associated with {@code key}, or {@code def} | |
| * if no value is associated with {@code 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 {@code key} is {@code null}. (A | |
| * {@code null} value for {@code def} <i>is</i> permitted.) | |
| * @throws IllegalArgumentException if key contains the null control | |
| * character, code point U+0000. | |
| */ | |
| public abstract String get(String key, String def); | |
| /** | |
| * Removes the value associated with the specified key in this preference | |
| * node, if any. | |
| * | |
| * <p>If this implementation supports <i>stored defaults</i>, 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 {@code get}. | |
| * | |
| * @param key key whose mapping is to be removed from the preference node. | |
| * @throws NullPointerException if {@code key} is {@code null}. | |
| * @throws IllegalStateException if this node (or an ancestor) has been | |
| * removed with the {@link #removeNode()} method. | |
| * @throws IllegalArgumentException if key contains the null control | |
| * character, code point U+0000. | |
| */ | |
| 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. | |
| * | |
| * <p>If this implementation supports <i>stored defaults</i>, 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 {@code 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 {@code key} is {@code null}. | |
| * @throws IllegalArgumentException if {@code key.length()} exceeds | |
| * {@code MAX_KEY_LENGTH}. | |
| * @throws IllegalStateException if this node (or an ancestor) has been | |
| * removed with the {@link #removeNode()} method. | |
| * @throws IllegalArgumentException if key contains | |
| * the null control character, code point U+0000. | |
| * @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 | |
| * {@code 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}. | |
| * | |
| * <p>If the implementation supports <i>stored defaults</i> and such a | |
| * default exists, is accessible, and could be converted to an int | |
| * with {@code 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 {@code 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 | |
| * {@code key} in this preference node, or {@code 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 {@code key} is {@code null}. | |
| * @throws IllegalArgumentException if key contains the null control | |
| * character, code point U+0000. | |
| * @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 {@code key} is {@code null}. | |
| * @throws IllegalArgumentException if {@code key.length()} exceeds | |
| * {@code MAX_KEY_LENGTH}. | |
| * @throws IllegalStateException if this node (or an ancestor) has been | |
| * removed with the {@link #removeNode()} method. | |
| * @throws IllegalArgumentException if key contains | |
| * the null control character, code point U+0000. | |
| * @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 | |
| * {@code 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}. | |
| * | |
| * <p>If the implementation supports <i>stored defaults</i> and such a | |
| * default exists, is accessible, and could be converted to a long | |
| * with {@code 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 {@code 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 | |
| * {@code key} in this preference node, or {@code 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 {@code key} is {@code null}. | |
| * @throws IllegalArgumentException if key contains the null control | |
| * character, code point U+0000. | |
| * @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 | |
| * {@code "true"} if the value is true, and {@code "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 {@code key} is {@code null}. | |
| * @throws IllegalArgumentException if {@code key.length()} exceeds | |
| * {@code MAX_KEY_LENGTH}. | |
| * @throws IllegalStateException if this node (or an ancestor) has been | |
| * removed with the {@link #removeNode()} method. | |
| * @throws IllegalArgumentException if key contains | |
| * the null control character, code point U+0000. | |
| * @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 {@code "true"}, which represents true, and {@code "false"}, which | |
| * represents false. Case is ignored, so, for example, {@code "TRUE"} | |
| * and {@code "False"} are also valid. This method is intended for use in | |
| * conjunction with {@link #putBoolean}. | |
| * | |
| * <p>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 {@code "true"} or | |
| * {@code "false"}, ignoring case. | |
| * | |
| * <p>If the implementation supports <i>stored defaults</i> 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 | |
| * {@code "true"} or {@code "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 {@code 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 | |
| * {@code key} in this preference node, or {@code 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 {@code key} is {@code null}. | |
| * @throws IllegalArgumentException if key contains the null control | |
| * character, code point U+0000. | |
| * @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 {@code key} is {@code null}. | |
| * @throws IllegalArgumentException if {@code key.length()} exceeds | |
| * {@code MAX_KEY_LENGTH}. | |
| * @throws IllegalStateException if this node (or an ancestor) has been | |
| * removed with the {@link #removeNode()} method. | |
| * @throws IllegalArgumentException if key contains | |
| * the null control character, code point U+0000. | |
| * @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 {@code 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}. | |
| * | |
| * <p>If the implementation supports <i>stored defaults</i> and such a | |
| * default exists, is accessible, and could be converted to a float | |
| * with {@code 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 {@code 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 | |
| * {@code key} in this preference node, or {@code 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 {@code key} is {@code null}. | |
| * @throws IllegalArgumentException if key contains the null control | |
| * character, code point U+0000. | |
| * @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 {@code key} is {@code null}. | |
| * @throws IllegalArgumentException if {@code key.length()} exceeds | |
| * {@code MAX_KEY_LENGTH}. | |
| * @throws IllegalStateException if this node (or an ancestor) has been | |
| * removed with the {@link #removeNode()} method. | |
| * @throws IllegalArgumentException if key contains | |
| * the null control character, code point U+0000. | |
| * @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 {@code 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}. | |
| * | |
| * <p>If the implementation supports <i>stored defaults</i> and such a | |
| * default exists, is accessible, and could be converted to a double | |
| * with {@code 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 {@code 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 | |
| * {@code key} in this preference node, or {@code 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 {@code key} is {@code null}. | |
| * @throws IllegalArgumentException if key contains the null control | |
| * character, code point U+0000. | |
| * @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 <i>Base64</i> encoding of the byte array, as defined in <a | |
| * href=http://www.ietf.org/rfc/rfc2045.txt>RFC 2045</a>, Section 6.8, | |
| * with one minor change: the string will consist solely of characters | |
| * from the <i>Base64 Alphabet</i>; it will not contain any newline | |
| * characters. Note that the maximum length of the byte array is limited | |
| * to three quarters of {@code MAX_VALUE_LENGTH} so that the length | |
| * of the Base64 encoded String does not exceed {@code 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 {@code 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. | |
| * @throws IllegalArgumentException if key contains | |
| * the null control character, code point U+0000. | |
| * @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 | |
| * <i>Base64</i> encoded binary data, as defined in <a | |
| * href=http://www.ietf.org/rfc/rfc2045.txt>RFC 2045</a>, Section 6.8, | |
| * with one minor change: the string must consist solely of characters | |
| * from the <i>Base64 Alphabet</i>; no newline characters or | |
| * extraneous characters are permitted. This method is intended for use | |
| * in conjunction with {@link #putByteArray}. | |
| * | |
| * <p>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). | |
| * | |
| * <p>If the implementation supports <i>stored defaults</i> 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 {@code 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 | |
| * {@code key} in this preference node, or {@code 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 {@code key} is {@code null}. (A | |
| * {@code null} value for {@code def} <i>is</i> permitted.) | |
| * @throws IllegalArgumentException if key contains the null control | |
| * character, code point U+0000. | |
| * @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.) | |
| * | |
| * <p>If the implementation supports <i>stored defaults</i> 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 {@code 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 {@code ('/')}) are | |
| * interpreted relative to this preference node. | |
| * | |
| * <p>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 {@code 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 {@code 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 {@code ('/')}) are interpreted relative to this preference | |
| * node. | |
| * | |
| * <p>If this node (or an ancestor) has already been removed with the | |
| * {@link #removeNode()} method, it <i>is</i> legal to invoke this method, | |
| * but only with the path name {@code ""}; the invocation will return | |
| * {@code false}. Thus, the idiom {@code p.nodeExists("")} may be | |
| * used to test whether {@code 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 {@code null}. | |
| * @throws IllegalStateException if this node (or an ancestor) has been | |
| * removed with the {@link #removeNode()} method and | |
| * {@code pathName} is not the empty string ({@code ""}). | |
| */ | |
| 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 | |
| * {@code Preferences} instance will fail with an | |
| * {@code IllegalStateException}. (The methods defined on {@link Object} | |
| * can still be invoked on a node after it has been removed; they will not | |
| * throw {@code IllegalStateException}.) | |
| * | |
| * <p>The removal is not guaranteed to be persistent until the | |
| * {@code flush} method is called on this node (or an ancestor). | |
| * | |
| * <p>If this implementation supports <i>stored defaults</i>, removing a | |
| * node exposes any stored defaults at or below this node. Thus, a | |
| * subsequent call to {@code nodeExists} on this node's path name may | |
| * return {@code true}, and a subsequent call to {@code node} on this | |
| * path name may return a (different) {@code 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 {@code true} if this preference node is in the user | |
| * preference tree, {@code false} if it's in the system preference tree. | |
| * | |
| * @return {@code true} if this preference node is in the user | |
| * preference tree, {@code 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:{@code (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. | |
| * | |
| * <p>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. | |
| * | |
| * <p>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 <i>not</i> guaranteed to be made persistent. | |
| * | |
| * <p> 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 {@code 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 {@code 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 <i>preference change | |
| * events</i> 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 <i>not</i> generated by the {@link | |
| * #removeNode()} method, which generates a <i>node change event</i>. | |
| * Preference change events <i>are</i> generated by the {@code clear} | |
| * method.) | |
| * | |
| * <p>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 {@code 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 {@code 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 <i>node change events</i> | |
| * 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 <i>node change events</i>, one for every | |
| * node in the subtree rooted at the removed node.) | |
| * | |
| * <p>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. | |
| * | |
| * <p>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 {@code NodeChangeListener} to add. | |
| * @throws NullPointerException if {@code 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 {@code NodeChangeListener}, so it no longer | |
| * receives change events. | |
| * | |
| * @param ncl The {@code NodeChangeListener} to remove. | |
| * @throws IllegalArgumentException if {@code ncl} was not a registered | |
| * {@code 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. | |
| * | |
| * <p>The XML document will have the following DOCTYPE declaration: | |
| * <pre>{@code | |
| * <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd"> | |
| * }</pre> | |
| * The UTF-8 character encoding will be used. | |
| * | |
| * <p>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 {@code 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. | |
| * | |
| * <p>The XML document will have the following DOCTYPE declaration: | |
| * <pre>{@code | |
| * <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd"> | |
| * }</pre> | |
| * The UTF-8 character encoding will be used. | |
| * | |
| * <p>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 {@code 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. | |
| * | |
| * <p>The XML document must have the following DOCTYPE declaration: | |
| * <pre>{@code | |
| * <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd"> | |
| * }</pre> | |
| * (This method is designed for use in conjunction with | |
| * {@link #exportNode(OutputStream)} and | |
| * {@link #exportSubtree(OutputStream)}. | |
| * | |
| * <p>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 {@code IOException}. | |
| * @throws InvalidPreferencesFormatException Data on input stream does not | |
| * constitute a valid XML document with the mandated document type. | |
| */ | |
| public static void importPreferences(InputStream is) | |
| throws IOException, InvalidPreferencesFormatException | |
| { | |
| XmlSupport.importPreferences(is); | |
| } | |
| } |