1 /*
2  * Copyright (C) 2014 The Android Open Source Project
3  * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5  *
6  * This code is free software; you can redistribute it and/or modify it
7  * under the terms of the GNU General Public License version 2 only, as
8  * published by the Free Software Foundation.  Oracle designates this
9  * particular file as subject to the "Classpath" exception as provided
10  * by Oracle in the LICENSE file that accompanied this code.
11  *
12  * This code is distributed in the hope that it will be useful, but WITHOUT
13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
15  * version 2 for more details (a copy is included in the LICENSE file that
16  * accompanied this code).
17  *
18  * You should have received a copy of the GNU General Public License version
19  * 2 along with this work; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
21  *
22  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
23  * or visit www.oracle.com if you need additional information or have any
24  * questions.
25  */
26 
27 package java.util.prefs;
28 
29 import java.io.InputStream;
30 import java.io.IOException;
31 import java.io.OutputStream;
32 import java.security.AccessController;
33 import java.security.Permission;
34 import java.security.PrivilegedAction;
35 import java.util.Iterator;
36 import java.util.ServiceLoader;
37 import java.util.ServiceConfigurationError;
38 
39 // These imports needed only as a workaround for a JavaDoc bug
40 import java.lang.RuntimePermission;
41 import java.lang.Integer;
42 import java.lang.Long;
43 import java.lang.Float;
44 import java.lang.Double;
45 
46 /**
47  * A node in a hierarchical collection of preference data.  This class
48  * allows applications to store and retrieve user and system
49  * preference and configuration data.  This data is stored
50  * persistently in an implementation-dependent backing store.  Typical
51  * implementations include flat files, OS-specific registries,
52  * directory servers and SQL databases.  The user of this class needn't
53  * be concerned with details of the backing store.
54  *
55  * <p>There are two separate trees of preference nodes, one for user
56  * preferences and one for system preferences.  Each user has a separate user
57  * preference tree, and all users in a given system share the same system
58  * preference tree.  The precise description of "user" and "system" will vary
59  * from implementation to implementation.  Typical information stored in the
60  * user preference tree might include font choice, color choice, or preferred
61  * window location and size for a particular application.  Typical information
62  * stored in the system preference tree might include installation
63  * configuration data for an application.
64  *
65  * <p>Nodes in a preference tree are named in a similar fashion to
66  * directories in a hierarchical file system.   Every node in a preference
67  * tree has a <i>node name</i> (which is not necessarily unique),
68  * a unique <i>absolute path name</i>, and a path name <i>relative</i> to each
69  * ancestor including itself.
70  *
71  * <p>The root node has a node name of the empty string ("").  Every other
72  * node has an arbitrary node name, specified at the time it is created.  The
73  * only restrictions on this name are that it cannot be the empty string, and
74  * it cannot contain the slash character ('/').
75  *
76  * <p>The root node has an absolute path name of <tt>"/"</tt>.  Children of
77  * the root node have absolute path names of <tt>"/" + </tt><i>&lt;node
78  * name&gt;</i>.  All other nodes have absolute path names of <i>&lt;parent's
79  * absolute path name&gt;</i><tt> + "/" + </tt><i>&lt;node name&gt;</i>.
80  * Note that all absolute path names begin with the slash character.
81  *
82  * <p>A node <i>n</i>'s path name relative to its ancestor <i>a</i>
83  * is simply the string that must be appended to <i>a</i>'s absolute path name
84  * in order to form <i>n</i>'s absolute path name, with the initial slash
85  * character (if present) removed.  Note that:
86  * <ul>
87  * <li>No relative path names begin with the slash character.
88  * <li>Every node's path name relative to itself is the empty string.
89  * <li>Every node's path name relative to its parent is its node name (except
90  * for the root node, which does not have a parent).
91  * <li>Every node's path name relative to the root is its absolute path name
92  * with the initial slash character removed.
93  * </ul>
94  *
95  * <p>Note finally that:
96  * <ul>
97  * <li>No path name contains multiple consecutive slash characters.
98  * <li>No path name with the exception of the root's absolute path name
99  * ends in the slash character.
100  * <li>Any string that conforms to these two rules is a valid path name.
101  * </ul>
102  *
103  * <p>All of the methods that modify preferences data are permitted to operate
104  * asynchronously; they may return immediately, and changes will eventually
105  * propagate to the persistent backing store with an implementation-dependent
106  * delay.  The <tt>flush</tt> method may be used to synchronously force
107  * updates to the backing store.  Normal termination of the Java Virtual
108  * Machine will <i>not</i> result in the loss of pending updates -- an explicit
109  * <tt>flush</tt> invocation is <i>not</i> required upon termination to ensure
110  * that pending updates are made persistent.
111  *
112  * <p>All of the methods that read preferences from a <tt>Preferences</tt>
113  * object require the invoker to provide a default value.  The default value is
114  * returned if no value has been previously set <i>or if the backing store is
115  * unavailable</i>.  The intent is to allow applications to operate, albeit
116  * with slightly degraded functionality, even if the backing store becomes
117  * unavailable.  Several methods, like <tt>flush</tt>, have semantics that
118  * prevent them from operating if the backing store is unavailable.  Ordinary
119  * applications should have no need to invoke any of these methods, which can
120  * be identified by the fact that they are declared to throw {@link
121  * BackingStoreException}.
122  *
123  * <p>The methods in this class may be invoked concurrently by multiple threads
124  * in a single JVM without the need for external synchronization, and the
125  * results will be equivalent to some serial execution.  If this class is used
126  * concurrently <i>by multiple JVMs</i> that store their preference data in
127  * the same backing store, the data store will not be corrupted, but no
128  * other guarantees are made concerning the consistency of the preference
129  * data.
130  *
131  * <p>This class contains an export/import facility, allowing preferences
132  * to be "exported" to an XML document, and XML documents representing
133  * preferences to be "imported" back into the system.  This facility
134  * may be used to back up all or part of a preference tree, and
135  * subsequently restore from the backup.
136  *
137  * <p>The XML document has the following DOCTYPE declaration:
138  * <pre>{@code
139  * <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
140  * }</pre>
141  * Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is
142  * <i>not</i> accessed when exporting or importing preferences; it merely
143  * serves as a string to uniquely identify the DTD, which is:
144  * <pre>{@code
145  *    <?xml version="1.0" encoding="UTF-8"?>
146  *
147  *    <!-- DTD for a Preferences tree. -->
148  *
149  *    <!-- The preferences element is at the root of an XML document
150  *         representing a Preferences tree. -->
151  *    <!ELEMENT preferences (root)>
152  *
153  *    <!-- The preferences element contains an optional version attribute,
154  *          which specifies version of DTD. -->
155  *    <!ATTLIST preferences EXTERNAL_XML_VERSION CDATA "0.0" >
156  *
157  *    <!-- The root element has a map representing the root's preferences
158  *         (if any), and one node for each child of the root (if any). -->
159  *    <!ELEMENT root (map, node*) >
160  *
161  *    <!-- Additionally, the root contains a type attribute, which
162  *         specifies whether it's the system or user root. -->
163  *    <!ATTLIST root
164  *              type (system|user) #REQUIRED >
165  *
166  *    <!-- Each node has a map representing its preferences (if any),
167  *         and one node for each child (if any). -->
168  *    <!ELEMENT node (map, node*) >
169  *
170  *    <!-- Additionally, each node has a name attribute -->
171  *    <!ATTLIST node
172  *              name CDATA #REQUIRED >
173  *
174  *    <!-- A map represents the preferences stored at a node (if any). -->
175  *    <!ELEMENT map (entry*) >
176  *
177  *    <!-- An entry represents a single preference, which is simply
178  *          a key-value pair. -->
179  *    <!ELEMENT entry EMPTY >
180  *    <!ATTLIST entry
181  *              key   CDATA #REQUIRED
182  *              value CDATA #REQUIRED >
183  * }</pre>
184  *
185  * Every <tt>Preferences</tt> implementation must have an associated {@link
186  * PreferencesFactory} implementation.  Every Java(TM) SE implementation must provide
187  * some means of specifying which <tt>PreferencesFactory</tt> implementation
188  * is used to generate the root preferences nodes.  This allows the
189  * administrator to replace the default preferences implementation with an
190  * alternative implementation.
191  *
192  * <p>Implementation note: In Sun's JRE, the <tt>PreferencesFactory</tt>
193  * implementation is located as follows:
194  *
195  * <ol>
196  *
197  * <li><p>If the system property
198  * <tt>java.util.prefs.PreferencesFactory</tt> is defined, then it is
199  * taken to be the fully-qualified name of a class implementing the
200  * <tt>PreferencesFactory</tt> interface.  The class is loaded and
201  * instantiated; if this process fails then an unspecified error is
202  * thrown.</p></li>
203  *
204  * <li><p> If a <tt>PreferencesFactory</tt> implementation class file
205  * has been installed in a jar file that is visible to the
206  * {@link java.lang.ClassLoader#getSystemClassLoader system class loader},
207  * and that jar file contains a provider-configuration file named
208  * <tt>java.util.prefs.PreferencesFactory</tt> in the resource
209  * directory <tt>META-INF/services</tt>, then the first class name
210  * specified in that file is taken.  If more than one such jar file is
211  * provided, the first one found will be used.  The class is loaded
212  * and instantiated; if this process fails then an unspecified error
213  * is thrown.  </p></li>
214  *
215  * <li><p>Finally, if neither the above-mentioned system property nor
216  * an extension jar file is provided, then the system-wide default
217  * <tt>PreferencesFactory</tt> implementation for the underlying
218  * platform is loaded and instantiated.</p></li>
219  *
220  * </ol>
221  *
222  * @author  Josh Bloch
223  * @since   1.4
224  */
225 public abstract class Preferences {
226 
227     // Android-changed: Not final for testing.
228     private static PreferencesFactory factory = findPreferencesFactory();
229 
230     // Android-changed: Custom implementation of findPreferencesFactory.
findPreferencesFactory()231     private static PreferencesFactory findPreferencesFactory() {
232         // Try the system property first...
233         PreferencesFactory result = ServiceLoader.loadFromSystemProperty(PreferencesFactory.class);
234         if (result != null) {
235             return result;
236         }
237         // Then use ServiceLoader for META-INF/services/...
238         for (PreferencesFactory impl : ServiceLoader.load(PreferencesFactory.class)) {
239             return impl;
240         }
241         // Finally return a default...
242         return new FileSystemPreferencesFactory();
243     }
244 
245     /**
246      * @hide for testing only.
247      */
248     // Android-changed: Allow this to be set for testing.
setPreferencesFactory(PreferencesFactory pf)249     public static PreferencesFactory setPreferencesFactory(PreferencesFactory pf) {
250         PreferencesFactory previous = factory;
251         factory = pf;
252         return previous;
253     }
254 
255     /**
256      * Maximum length of string allowed as a key (80 characters).
257      */
258     public static final int MAX_KEY_LENGTH = 80;
259 
260     /**
261      * Maximum length of string allowed as a value (8192 characters).
262      */
263     public static final int MAX_VALUE_LENGTH = 8*1024;
264 
265     /**
266      * Maximum length of a node name (80 characters).
267      */
268     public static final int MAX_NAME_LENGTH = 80;
269 
270     /**
271      * <strong>WARNING:</strong> On Android, the Preference nodes
272      * corresponding to the "system" and "user" preferences are stored in sections
273      * of the file system that are inaccessible to apps. Further, allowing apps to set
274      * "system wide" preferences is contrary to android's security model.
275      *
276      * Returns the preference node from the calling user's preference tree
277      * that is associated (by convention) with the specified class's package.
278      * The convention is as follows: the absolute path name of the node is the
279      * fully qualified package name, preceded by a slash (<tt>'/'</tt>), and
280      * with each period (<tt>'.'</tt>) replaced by a slash.  For example the
281      * absolute path name of the node associated with the class
282      * <tt>com.acme.widget.Foo</tt> is <tt>/com/acme/widget</tt>.
283      *
284      * <p>This convention does not apply to the unnamed package, whose
285      * associated preference node is <tt>&lt;unnamed&gt;</tt>.  This node
286      * is not intended for long term use, but for convenience in the early
287      * development of programs that do not yet belong to a package, and
288      * for "throwaway" programs.  <i>Valuable data should not be stored
289      * at this node as it is shared by all programs that use it.</i>
290      *
291      * <p>A class <tt>Foo</tt> wishing to access preferences pertaining to its
292      * package can obtain a preference node as follows: <pre>
293      *    static Preferences prefs = Preferences.userNodeForPackage(Foo.class);
294      * </pre>
295      * This idiom obviates the need for using a string to describe the
296      * preferences node and decreases the likelihood of a run-time failure.
297      * (If the class name is misspelled, it will typically result in a
298      * compile-time error.)
299      *
300      * <p>Invoking this method will result in the creation of the returned
301      * node and its ancestors if they do not already exist.  If the returned
302      * node did not exist prior to this call, this node and any ancestors that
303      * were created by this call are not guaranteed to become permanent until
304      * the <tt>flush</tt> method is called on the returned node (or one of its
305      * ancestors or descendants).
306      *
307      * @param c the class for whose package a user preference node is desired.
308      * @return the user preference node associated with the package of which
309      *         <tt>c</tt> is a member.
310      * @throws NullPointerException if <tt>c</tt> is <tt>null</tt>.
311      * @throws SecurityException if a security manager is present and
312      *         it denies <tt>RuntimePermission("preferences")</tt>.
313      * @see    RuntimePermission
314      */
userNodeForPackage(Class<?> c)315     public static Preferences userNodeForPackage(Class<?> c) {
316         return userRoot().node(nodeName(c));
317     }
318 
319     /**
320      * <strong>WARNING:</strong> On Android, the Preference nodes
321      * corresponding to the "system" and "user" preferences are stored in sections
322      * of the file system that are inaccessible to apps. Further, allowing apps to set
323      * "system wide" preferences is contrary to android's security model.
324      *
325      * Returns the preference node from the system preference tree that is
326      * associated (by convention) with the specified class's package.  The
327      * convention is as follows: the absolute path name of the node is the
328      * fully qualified package name, preceded by a slash (<tt>'/'</tt>), and
329      * with each period (<tt>'.'</tt>) replaced by a slash.  For example the
330      * absolute path name of the node associated with the class
331      * <tt>com.acme.widget.Foo</tt> is <tt>/com/acme/widget</tt>.
332      *
333      * <p>This convention does not apply to the unnamed package, whose
334      * associated preference node is <tt>&lt;unnamed&gt;</tt>.  This node
335      * is not intended for long term use, but for convenience in the early
336      * development of programs that do not yet belong to a package, and
337      * for "throwaway" programs.  <i>Valuable data should not be stored
338      * at this node as it is shared by all programs that use it.</i>
339      *
340      * <p>A class <tt>Foo</tt> wishing to access preferences pertaining to its
341      * package can obtain a preference node as follows: <pre>
342      *  static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);
343      * </pre>
344      * This idiom obviates the need for using a string to describe the
345      * preferences node and decreases the likelihood of a run-time failure.
346      * (If the class name is misspelled, it will typically result in a
347      * compile-time error.)
348      *
349      * <p>Invoking this method will result in the creation of the returned
350      * node and its ancestors if they do not already exist.  If the returned
351      * node did not exist prior to this call, this node and any ancestors that
352      * were created by this call are not guaranteed to become permanent until
353      * the <tt>flush</tt> method is called on the returned node (or one of its
354      * ancestors or descendants).
355      *
356      * @param c the class for whose package a system preference node is desired.
357      * @return the system preference node associated with the package of which
358      *         <tt>c</tt> is a member.
359      * @throws NullPointerException if <tt>c</tt> is <tt>null</tt>.
360      * @throws SecurityException if a security manager is present and
361      *         it denies <tt>RuntimePermission("preferences")</tt>.
362      * @see    RuntimePermission
363      */
systemNodeForPackage(Class<?> c)364     public static Preferences systemNodeForPackage(Class<?> c) {
365         return systemRoot().node(nodeName(c));
366     }
367 
368     /**
369      * Returns the absolute path name of the node corresponding to the package
370      * of the specified object.
371      *
372      * @throws IllegalArgumentException if the package has node preferences
373      *         node associated with it.
374      */
nodeName(Class<?> c)375     private static String nodeName(Class<?> c) {
376         if (c.isArray())
377             throw new IllegalArgumentException(
378                 "Arrays have no associated preferences node.");
379         String className = c.getName();
380         int pkgEndIndex = className.lastIndexOf('.');
381         if (pkgEndIndex < 0)
382             return "/<unnamed>";
383         String packageName = className.substring(0, pkgEndIndex);
384         return "/" + packageName.replace('.', '/');
385     }
386 
387     /**
388      * This permission object represents the permission required to get
389      * access to the user or system root (which in turn allows for all
390      * other operations).
391      */
392     private static Permission prefsPerm = new RuntimePermission("preferences");
393 
394     /**
395      * <strong>WARNING:</strong> On Android, the Preference nodes
396      * corresponding to the "system" and "user" preferences are stored in sections
397      * of the file system that are inaccessible to apps. Further, allowing apps to set
398      * "system wide" preferences is contrary to android's security model.
399      *
400      * Returns the root preference node for the calling user.
401      *
402      * @return the root preference node for the calling user.
403      * @throws SecurityException If a security manager is present and
404      *         it denies <tt>RuntimePermission("preferences")</tt>.
405      * @see    RuntimePermission
406      */
userRoot()407     public static Preferences userRoot() {
408         SecurityManager security = System.getSecurityManager();
409         if (security != null)
410             security.checkPermission(prefsPerm);
411 
412         return factory.userRoot();
413     }
414 
415     /**
416      * <strong>WARNING:</strong> On Android, the Preference nodes
417      * corresponding to the "system" and "user" preferences are stored in sections
418      * of the file system that are inaccessible to apps. Further, allowing apps to set
419      * "system wide" preferences is contrary to android's security model.
420      *
421      * Returns the root preference node for the system.
422      *
423      * @return the root preference node for the system.
424      * @throws SecurityException If a security manager is present and
425      *         it denies <tt>RuntimePermission("preferences")</tt>.
426      * @see    RuntimePermission
427      */
systemRoot()428     public static Preferences systemRoot() {
429         SecurityManager security = System.getSecurityManager();
430         if (security != null)
431             security.checkPermission(prefsPerm);
432 
433         return factory.systemRoot();
434     }
435 
436     /**
437      * Sole constructor. (For invocation by subclass constructors, typically
438      * implicit.)
439      */
Preferences()440     protected Preferences() {
441     }
442 
443     /**
444      * Associates the specified value with the specified key in this
445      * preference node.
446      *
447      * @param key key with which the specified value is to be associated.
448      * @param value value to be associated with the specified key.
449      * @throws NullPointerException if key or value is <tt>null</tt>.
450      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
451      *       <tt>MAX_KEY_LENGTH</tt> or if <tt>value.length</tt> exceeds
452      *       <tt>MAX_VALUE_LENGTH</tt>.
453      * @throws IllegalStateException if this node (or an ancestor) has been
454      *         removed with the {@link #removeNode()} method.
455      */
put(String key, String value)456     public abstract void put(String key, String value);
457 
458     /**
459      * Returns the value associated with the specified key in this preference
460      * node.  Returns the specified default if there is no value associated
461      * with the key, or the backing store is inaccessible.
462      *
463      * <p>Some implementations may store default values in their backing
464      * stores.  If there is no value associated with the specified key
465      * but there is such a <i>stored default</i>, it is returned in
466      * preference to the specified default.
467      *
468      * @param key key whose associated value is to be returned.
469      * @param def the value to be returned in the event that this
470      *        preference node has no value associated with <tt>key</tt>.
471      * @return the value associated with <tt>key</tt>, or <tt>def</tt>
472      *         if no value is associated with <tt>key</tt>, or the backing
473      *         store is inaccessible.
474      * @throws IllegalStateException if this node (or an ancestor) has been
475      *         removed with the {@link #removeNode()} method.
476      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.  (A
477      *         <tt>null</tt> value for <tt>def</tt> <i>is</i> permitted.)
478      */
get(String key, String def)479     public abstract String get(String key, String def);
480 
481     /**
482      * Removes the value associated with the specified key in this preference
483      * node, if any.
484      *
485      * <p>If this implementation supports <i>stored defaults</i>, and there is
486      * such a default for the specified preference, the stored default will be
487      * "exposed" by this call, in the sense that it will be returned
488      * by a succeeding call to <tt>get</tt>.
489      *
490      * @param key key whose mapping is to be removed from the preference node.
491      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
492      * @throws IllegalStateException if this node (or an ancestor) has been
493      *         removed with the {@link #removeNode()} method.
494      */
remove(String key)495     public abstract void remove(String key);
496 
497     /**
498      * Removes all of the preferences (key-value associations) in this
499      * preference node.  This call has no effect on any descendants
500      * of this node.
501      *
502      * <p>If this implementation supports <i>stored defaults</i>, and this
503      * node in the preferences hierarchy contains any such defaults,
504      * the stored defaults will be "exposed" by this call, in the sense that
505      * they will be returned by succeeding calls to <tt>get</tt>.
506      *
507      * @throws BackingStoreException if this operation cannot be completed
508      *         due to a failure in the backing store, or inability to
509      *         communicate with it.
510      * @throws IllegalStateException if this node (or an ancestor) has been
511      *         removed with the {@link #removeNode()} method.
512      * @see #removeNode()
513      */
clear()514     public abstract void clear() throws BackingStoreException;
515 
516     /**
517      * Associates a string representing the specified int value with the
518      * specified key in this preference node.  The associated string is the
519      * one that would be returned if the int value were passed to
520      * {@link Integer#toString(int)}.  This method is intended for use in
521      * conjunction with {@link #getInt}.
522      *
523      * @param key key with which the string form of value is to be associated.
524      * @param value value whose string form is to be associated with key.
525      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
526      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
527      *         <tt>MAX_KEY_LENGTH</tt>.
528      * @throws IllegalStateException if this node (or an ancestor) has been
529      *         removed with the {@link #removeNode()} method.
530      * @see #getInt(String,int)
531      */
putInt(String key, int value)532     public abstract void putInt(String key, int value);
533 
534     /**
535      * Returns the int value represented by the string associated with the
536      * specified key in this preference node.  The string is converted to
537      * an integer as by {@link Integer#parseInt(String)}.  Returns the
538      * specified default if there is no value associated with the key,
539      * the backing store is inaccessible, or if
540      * <tt>Integer.parseInt(String)</tt> would throw a {@link
541      * NumberFormatException} if the associated value were passed.  This
542      * method is intended for use in conjunction with {@link #putInt}.
543      *
544      * <p>If the implementation supports <i>stored defaults</i> and such a
545      * default exists, is accessible, and could be converted to an int
546      * with <tt>Integer.parseInt</tt>, this int is returned in preference to
547      * the specified default.
548      *
549      * @param key key whose associated value is to be returned as an int.
550      * @param def the value to be returned in the event that this
551      *        preference node has no value associated with <tt>key</tt>
552      *        or the associated value cannot be interpreted as an int,
553      *        or the backing store is inaccessible.
554      * @return the int value represented by the string associated with
555      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
556      *         associated value does not exist or cannot be interpreted as
557      *         an int.
558      * @throws IllegalStateException if this node (or an ancestor) has been
559      *         removed with the {@link #removeNode()} method.
560      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
561      * @see #putInt(String,int)
562      * @see #get(String,String)
563      */
getInt(String key, int def)564     public abstract int getInt(String key, int def);
565 
566     /**
567      * Associates a string representing the specified long value with the
568      * specified key in this preference node.  The associated string is the
569      * one that would be returned if the long value were passed to
570      * {@link Long#toString(long)}.  This method is intended for use in
571      * conjunction with {@link #getLong}.
572      *
573      * @param key key with which the string form of value is to be associated.
574      * @param value value whose string form is to be associated with key.
575      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
576      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
577      *         <tt>MAX_KEY_LENGTH</tt>.
578      * @throws IllegalStateException if this node (or an ancestor) has been
579      *         removed with the {@link #removeNode()} method.
580      * @see #getLong(String,long)
581      */
putLong(String key, long value)582     public abstract void putLong(String key, long value);
583 
584     /**
585      * Returns the long value represented by the string associated with the
586      * specified key in this preference node.  The string is converted to
587      * a long as by {@link Long#parseLong(String)}.  Returns the
588      * specified default if there is no value associated with the key,
589      * the backing store is inaccessible, or if
590      * <tt>Long.parseLong(String)</tt> would throw a {@link
591      * NumberFormatException} if the associated value were passed.  This
592      * method is intended for use in conjunction with {@link #putLong}.
593      *
594      * <p>If the implementation supports <i>stored defaults</i> and such a
595      * default exists, is accessible, and could be converted to a long
596      * with <tt>Long.parseLong</tt>, this long is returned in preference to
597      * the specified default.
598      *
599      * @param key key whose associated value is to be returned as a long.
600      * @param def the value to be returned in the event that this
601      *        preference node has no value associated with <tt>key</tt>
602      *        or the associated value cannot be interpreted as a long,
603      *        or the backing store is inaccessible.
604      * @return the long value represented by the string associated with
605      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
606      *         associated value does not exist or cannot be interpreted as
607      *         a long.
608      * @throws IllegalStateException if this node (or an ancestor) has been
609      *         removed with the {@link #removeNode()} method.
610      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
611      * @see #putLong(String,long)
612      * @see #get(String,String)
613      */
getLong(String key, long def)614     public abstract long getLong(String key, long def);
615 
616     /**
617      * Associates a string representing the specified boolean value with the
618      * specified key in this preference node.  The associated string is
619      * <tt>"true"</tt> if the value is true, and <tt>"false"</tt> if it is
620      * false.  This method is intended for use in conjunction with
621      * {@link #getBoolean}.
622      *
623      * @param key key with which the string form of value is to be associated.
624      * @param value value whose string form is to be associated with key.
625      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
626      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
627      *         <tt>MAX_KEY_LENGTH</tt>.
628      * @throws IllegalStateException if this node (or an ancestor) has been
629      *         removed with the {@link #removeNode()} method.
630      * @see #getBoolean(String,boolean)
631      * @see #get(String,String)
632      */
putBoolean(String key, boolean value)633     public abstract void putBoolean(String key, boolean value);
634 
635     /**
636      * Returns the boolean value represented by the string associated with the
637      * specified key in this preference node.  Valid strings
638      * are <tt>"true"</tt>, which represents true, and <tt>"false"</tt>, which
639      * represents false.  Case is ignored, so, for example, <tt>"TRUE"</tt>
640      * and <tt>"False"</tt> are also valid.  This method is intended for use in
641      * conjunction with {@link #putBoolean}.
642      *
643      * <p>Returns the specified default if there is no value
644      * associated with the key, the backing store is inaccessible, or if the
645      * associated value is something other than <tt>"true"</tt> or
646      * <tt>"false"</tt>, ignoring case.
647      *
648      * <p>If the implementation supports <i>stored defaults</i> and such a
649      * default exists and is accessible, it is used in preference to the
650      * specified default, unless the stored default is something other than
651      * <tt>"true"</tt> or <tt>"false"</tt>, ignoring case, in which case the
652      * specified default is used.
653      *
654      * @param key key whose associated value is to be returned as a boolean.
655      * @param def the value to be returned in the event that this
656      *        preference node has no value associated with <tt>key</tt>
657      *        or the associated value cannot be interpreted as a boolean,
658      *        or the backing store is inaccessible.
659      * @return the boolean value represented by the string associated with
660      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
661      *         associated value does not exist or cannot be interpreted as
662      *         a boolean.
663      * @throws IllegalStateException if this node (or an ancestor) has been
664      *         removed with the {@link #removeNode()} method.
665      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
666      * @see #get(String,String)
667      * @see #putBoolean(String,boolean)
668      */
getBoolean(String key, boolean def)669     public abstract boolean getBoolean(String key, boolean def);
670 
671     /**
672      * Associates a string representing the specified float value with the
673      * specified key in this preference node.  The associated string is the
674      * one that would be returned if the float value were passed to
675      * {@link Float#toString(float)}.  This method is intended for use in
676      * conjunction with {@link #getFloat}.
677      *
678      * @param key key with which the string form of value is to be associated.
679      * @param value value whose string form is to be associated with key.
680      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
681      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
682      *         <tt>MAX_KEY_LENGTH</tt>.
683      * @throws IllegalStateException if this node (or an ancestor) has been
684      *         removed with the {@link #removeNode()} method.
685      * @see #getFloat(String,float)
686      */
putFloat(String key, float value)687     public abstract void putFloat(String key, float value);
688 
689     /**
690      * Returns the float value represented by the string associated with the
691      * specified key in this preference node.  The string is converted to an
692      * integer as by {@link Float#parseFloat(String)}.  Returns the specified
693      * default if there is no value associated with the key, the backing store
694      * is inaccessible, or if <tt>Float.parseFloat(String)</tt> would throw a
695      * {@link NumberFormatException} if the associated value were passed.
696      * This method is intended for use in conjunction with {@link #putFloat}.
697      *
698      * <p>If the implementation supports <i>stored defaults</i> and such a
699      * default exists, is accessible, and could be converted to a float
700      * with <tt>Float.parseFloat</tt>, this float is returned in preference to
701      * the specified default.
702      *
703      * @param key key whose associated value is to be returned as a float.
704      * @param def the value to be returned in the event that this
705      *        preference node has no value associated with <tt>key</tt>
706      *        or the associated value cannot be interpreted as a float,
707      *        or the backing store is inaccessible.
708      * @return the float value represented by the string associated with
709      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
710      *         associated value does not exist or cannot be interpreted as
711      *         a float.
712      * @throws IllegalStateException if this node (or an ancestor) has been
713      *         removed with the {@link #removeNode()} method.
714      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
715      * @see #putFloat(String,float)
716      * @see #get(String,String)
717      */
getFloat(String key, float def)718     public abstract float getFloat(String key, float def);
719 
720     /**
721      * Associates a string representing the specified double value with the
722      * specified key in this preference node.  The associated string is the
723      * one that would be returned if the double value were passed to
724      * {@link Double#toString(double)}.  This method is intended for use in
725      * conjunction with {@link #getDouble}.
726      *
727      * @param key key with which the string form of value is to be associated.
728      * @param value value whose string form is to be associated with key.
729      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
730      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
731      *         <tt>MAX_KEY_LENGTH</tt>.
732      * @throws IllegalStateException if this node (or an ancestor) has been
733      *         removed with the {@link #removeNode()} method.
734      * @see #getDouble(String,double)
735      */
putDouble(String key, double value)736     public abstract void putDouble(String key, double value);
737 
738     /**
739      * Returns the double value represented by the string associated with the
740      * specified key in this preference node.  The string is converted to an
741      * integer as by {@link Double#parseDouble(String)}.  Returns the specified
742      * default if there is no value associated with the key, the backing store
743      * is inaccessible, or if <tt>Double.parseDouble(String)</tt> would throw a
744      * {@link NumberFormatException} if the associated value were passed.
745      * This method is intended for use in conjunction with {@link #putDouble}.
746      *
747      * <p>If the implementation supports <i>stored defaults</i> and such a
748      * default exists, is accessible, and could be converted to a double
749      * with <tt>Double.parseDouble</tt>, this double is returned in preference
750      * to the specified default.
751      *
752      * @param key key whose associated value is to be returned as a double.
753      * @param def the value to be returned in the event that this
754      *        preference node has no value associated with <tt>key</tt>
755      *        or the associated value cannot be interpreted as a double,
756      *        or the backing store is inaccessible.
757      * @return the double value represented by the string associated with
758      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
759      *         associated value does not exist or cannot be interpreted as
760      *         a double.
761      * @throws IllegalStateException if this node (or an ancestor) has been
762      *         removed with the {@link #removeNode()} method.
763      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
764      * @see #putDouble(String,double)
765      * @see #get(String,String)
766      */
getDouble(String key, double def)767     public abstract double getDouble(String key, double def);
768 
769     /**
770      * Associates a string representing the specified byte array with the
771      * specified key in this preference node.  The associated string is
772      * the <i>Base64</i> encoding of the byte array, as defined in <a
773      * href=http://www.ietf.org/rfc/rfc2045.txt>RFC 2045</a>, Section 6.8,
774      * with one minor change: the string will consist solely of characters
775      * from the <i>Base64 Alphabet</i>; it will not contain any newline
776      * characters.  Note that the maximum length of the byte array is limited
777      * to three quarters of <tt>MAX_VALUE_LENGTH</tt> so that the length
778      * of the Base64 encoded String does not exceed <tt>MAX_VALUE_LENGTH</tt>.
779      * This method is intended for use in conjunction with
780      * {@link #getByteArray}.
781      *
782      * @param key key with which the string form of value is to be associated.
783      * @param value value whose string form is to be associated with key.
784      * @throws NullPointerException if key or value is <tt>null</tt>.
785      * @throws IllegalArgumentException if key.length() exceeds MAX_KEY_LENGTH
786      *         or if value.length exceeds MAX_VALUE_LENGTH*3/4.
787      * @throws IllegalStateException if this node (or an ancestor) has been
788      *         removed with the {@link #removeNode()} method.
789      * @see #getByteArray(String,byte[])
790      * @see #get(String,String)
791      */
putByteArray(String key, byte[] value)792     public abstract void putByteArray(String key, byte[] value);
793 
794     /**
795      * Returns the byte array value represented by the string associated with
796      * the specified key in this preference node.  Valid strings are
797      * <i>Base64</i> encoded binary data, as defined in <a
798      * href=http://www.ietf.org/rfc/rfc2045.txt>RFC 2045</a>, Section 6.8,
799      * with one minor change: the string must consist solely of characters
800      * from the <i>Base64 Alphabet</i>; no newline characters or
801      * extraneous characters are permitted.  This method is intended for use
802      * in conjunction with {@link #putByteArray}.
803      *
804      * <p>Returns the specified default if there is no value
805      * associated with the key, the backing store is inaccessible, or if the
806      * associated value is not a valid Base64 encoded byte array
807      * (as defined above).
808      *
809      * <p>If the implementation supports <i>stored defaults</i> and such a
810      * default exists and is accessible, it is used in preference to the
811      * specified default, unless the stored default is not a valid Base64
812      * encoded byte array (as defined above), in which case the
813      * specified default is used.
814      *
815      * @param key key whose associated value is to be returned as a byte array.
816      * @param def the value to be returned in the event that this
817      *        preference node has no value associated with <tt>key</tt>
818      *        or the associated value cannot be interpreted as a byte array,
819      *        or the backing store is inaccessible.
820      * @return the byte array value represented by the string associated with
821      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
822      *         associated value does not exist or cannot be interpreted as
823      *         a byte array.
824      * @throws IllegalStateException if this node (or an ancestor) has been
825      *         removed with the {@link #removeNode()} method.
826      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.  (A
827      *         <tt>null</tt> value for <tt>def</tt> <i>is</i> permitted.)
828      * @see #get(String,String)
829      * @see #putByteArray(String,byte[])
830      */
getByteArray(String key, byte[] def)831     public abstract byte[] getByteArray(String key, byte[] def);
832 
833     /**
834      * Returns all of the keys that have an associated value in this
835      * preference node.  (The returned array will be of size zero if
836      * this node has no preferences.)
837      *
838      * <p>If the implementation supports <i>stored defaults</i> and there
839      * are any such defaults at this node that have not been overridden,
840      * by explicit preferences, the defaults are returned in the array in
841      * addition to any explicit preferences.
842      *
843      * @return an array of the keys that have an associated value in this
844      *         preference node.
845      * @throws BackingStoreException if this operation cannot be completed
846      *         due to a failure in the backing store, or inability to
847      *         communicate with it.
848      * @throws IllegalStateException if this node (or an ancestor) has been
849      *         removed with the {@link #removeNode()} method.
850      */
keys()851     public abstract String[] keys() throws BackingStoreException;
852 
853     /**
854      * Returns the names of the children of this preference node, relative to
855      * this node.  (The returned array will be of size zero if this node has
856      * no children.)
857      *
858      * @return the names of the children of this preference node.
859      * @throws BackingStoreException if this operation cannot be completed
860      *         due to a failure in the backing store, or inability to
861      *         communicate with it.
862      * @throws IllegalStateException if this node (or an ancestor) has been
863      *         removed with the {@link #removeNode()} method.
864      */
childrenNames()865     public abstract String[] childrenNames() throws BackingStoreException;
866 
867     /**
868      * Returns the parent of this preference node, or <tt>null</tt> if this is
869      * the root.
870      *
871      * @return the parent of this preference node.
872      * @throws IllegalStateException if this node (or an ancestor) has been
873      *         removed with the {@link #removeNode()} method.
874      */
parent()875     public abstract Preferences parent();
876 
877     /**
878      * Returns the named preference node in the same tree as this node,
879      * creating it and any of its ancestors if they do not already exist.
880      * Accepts a relative or absolute path name.  Relative path names
881      * (which do not begin with the slash character <tt>('/')</tt>) are
882      * interpreted relative to this preference node.
883      *
884      * <p>If the returned node did not exist prior to this call, this node and
885      * any ancestors that were created by this call are not guaranteed
886      * to become permanent until the <tt>flush</tt> method is called on
887      * the returned node (or one of its ancestors or descendants).
888      *
889      * @param pathName the path name of the preference node to return.
890      * @return the specified preference node.
891      * @throws IllegalArgumentException if the path name is invalid (i.e.,
892      *         it contains multiple consecutive slash characters, or ends
893      *         with a slash character and is more than one character long).
894      * @throws NullPointerException if path name is <tt>null</tt>.
895      * @throws IllegalStateException if this node (or an ancestor) has been
896      *         removed with the {@link #removeNode()} method.
897      * @see #flush()
898      */
node(String pathName)899     public abstract Preferences node(String pathName);
900 
901     /**
902      * Returns true if the named preference node exists in the same tree
903      * as this node.  Relative path names (which do not begin with the slash
904      * character <tt>('/')</tt>) are interpreted relative to this preference
905      * node.
906      *
907      * <p>If this node (or an ancestor) has already been removed with the
908      * {@link #removeNode()} method, it <i>is</i> legal to invoke this method,
909      * but only with the path name <tt>""</tt>; the invocation will return
910      * <tt>false</tt>.  Thus, the idiom <tt>p.nodeExists("")</tt> may be
911      * used to test whether <tt>p</tt> has been removed.
912      *
913      * @param pathName the path name of the node whose existence
914      *        is to be checked.
915      * @return true if the specified node exists.
916      * @throws BackingStoreException if this operation cannot be completed
917      *         due to a failure in the backing store, or inability to
918      *         communicate with it.
919      * @throws IllegalArgumentException if the path name is invalid (i.e.,
920      *         it contains multiple consecutive slash characters, or ends
921      *         with a slash character and is more than one character long).
922      * @throws NullPointerException if path name is <tt>null</tt>.
923      * @throws IllegalStateException if this node (or an ancestor) has been
924      *         removed with the {@link #removeNode()} method and
925      *         <tt>pathName</tt> is not the empty string (<tt>""</tt>).
926      */
nodeExists(String pathName)927     public abstract boolean nodeExists(String pathName)
928         throws BackingStoreException;
929 
930     /**
931      * Removes this preference node and all of its descendants, invalidating
932      * any preferences contained in the removed nodes.  Once a node has been
933      * removed, attempting any method other than {@link #name()},
934      * {@link #absolutePath()}, {@link #isUserNode()}, {@link #flush()} or
935      * {@link #node(String) nodeExists("")} on the corresponding
936      * <tt>Preferences</tt> instance will fail with an
937      * <tt>IllegalStateException</tt>.  (The methods defined on {@link Object}
938      * can still be invoked on a node after it has been removed; they will not
939      * throw <tt>IllegalStateException</tt>.)
940      *
941      * <p>The removal is not guaranteed to be persistent until the
942      * <tt>flush</tt> method is called on this node (or an ancestor).
943      *
944      * <p>If this implementation supports <i>stored defaults</i>, removing a
945      * node exposes any stored defaults at or below this node.  Thus, a
946      * subsequent call to <tt>nodeExists</tt> on this node's path name may
947      * return <tt>true</tt>, and a subsequent call to <tt>node</tt> on this
948      * path name may return a (different) <tt>Preferences</tt> instance
949      * representing a non-empty collection of preferences and/or children.
950      *
951      * @throws BackingStoreException if this operation cannot be completed
952      *         due to a failure in the backing store, or inability to
953      *         communicate with it.
954      * @throws IllegalStateException if this node (or an ancestor) has already
955      *         been removed with the {@link #removeNode()} method.
956      * @throws UnsupportedOperationException if this method is invoked on
957      *         the root node.
958      * @see #flush()
959      */
removeNode()960     public abstract void removeNode() throws BackingStoreException;
961 
962     /**
963      * Returns this preference node's name, relative to its parent.
964      *
965      * @return this preference node's name, relative to its parent.
966      */
name()967     public abstract String name();
968 
969     /**
970      * Returns this preference node's absolute path name.
971      *
972      * @return this preference node's absolute path name.
973      */
absolutePath()974     public abstract String absolutePath();
975 
976     /**
977      * Returns <tt>true</tt> if this preference node is in the user
978      * preference tree, <tt>false</tt> if it's in the system preference tree.
979      *
980      * @return <tt>true</tt> if this preference node is in the user
981      *         preference tree, <tt>false</tt> if it's in the system
982      *         preference tree.
983      */
isUserNode()984     public abstract boolean isUserNode();
985 
986     /**
987      * Returns a string representation of this preferences node,
988      * as if computed by the expression:<tt>(this.isUserNode() ? "User" :
989      * "System") + " Preference Node: " + this.absolutePath()</tt>.
990      */
toString()991     public abstract String toString();
992 
993     /**
994      * Forces any changes in the contents of this preference node and its
995      * descendants to the persistent store.  Once this method returns
996      * successfully, it is safe to assume that all changes made in the
997      * subtree rooted at this node prior to the method invocation have become
998      * permanent.
999      *
1000      * <p>Implementations are free to flush changes into the persistent store
1001      * at any time.  They do not need to wait for this method to be called.
1002      *
1003      * <p>When a flush occurs on a newly created node, it is made persistent,
1004      * as are any ancestors (and descendants) that have yet to be made
1005      * persistent.  Note however that any preference value changes in
1006      * ancestors are <i>not</i> guaranteed to be made persistent.
1007      *
1008      * <p> If this method is invoked on a node that has been removed with
1009      * the {@link #removeNode()} method, flushSpi() is invoked on this node,
1010      * but not on others.
1011      *
1012      * @throws BackingStoreException if this operation cannot be completed
1013      *         due to a failure in the backing store, or inability to
1014      *         communicate with it.
1015      * @see    #sync()
1016      */
flush()1017     public abstract void flush() throws BackingStoreException;
1018 
1019     /**
1020      * Ensures that future reads from this preference node and its
1021      * descendants reflect any changes that were committed to the persistent
1022      * store (from any VM) prior to the <tt>sync</tt> invocation.  As a
1023      * side-effect, forces any changes in the contents of this preference node
1024      * and its descendants to the persistent store, as if the <tt>flush</tt>
1025      * method had been invoked on this node.
1026      *
1027      * @throws BackingStoreException if this operation cannot be completed
1028      *         due to a failure in the backing store, or inability to
1029      *         communicate with it.
1030      * @throws IllegalStateException if this node (or an ancestor) has been
1031      *         removed with the {@link #removeNode()} method.
1032      * @see    #flush()
1033      */
sync()1034     public abstract void sync() throws BackingStoreException;
1035 
1036     /**
1037      * Registers the specified listener to receive <i>preference change
1038      * events</i> for this preference node.  A preference change event is
1039      * generated when a preference is added to this node, removed from this
1040      * node, or when the value associated with a preference is changed.
1041      * (Preference change events are <i>not</i> generated by the {@link
1042      * #removeNode()} method, which generates a <i>node change event</i>.
1043      * Preference change events <i>are</i> generated by the <tt>clear</tt>
1044      * method.)
1045      *
1046      * <p>Events are only guaranteed for changes made within the same JVM
1047      * as the registered listener, though some implementations may generate
1048      * events for changes made outside this JVM.  Events may be generated
1049      * before the changes have been made persistent.  Events are not generated
1050      * when preferences are modified in descendants of this node; a caller
1051      * desiring such events must register with each descendant.
1052      *
1053      * @param pcl The preference change listener to add.
1054      * @throws NullPointerException if <tt>pcl</tt> is null.
1055      * @throws IllegalStateException if this node (or an ancestor) has been
1056      *         removed with the {@link #removeNode()} method.
1057      * @see #removePreferenceChangeListener(PreferenceChangeListener)
1058      * @see #addNodeChangeListener(NodeChangeListener)
1059      */
addPreferenceChangeListener( PreferenceChangeListener pcl)1060     public abstract void addPreferenceChangeListener(
1061         PreferenceChangeListener pcl);
1062 
1063     /**
1064      * Removes the specified preference change listener, so it no longer
1065      * receives preference change events.
1066      *
1067      * @param pcl The preference change listener to remove.
1068      * @throws IllegalArgumentException if <tt>pcl</tt> was not a registered
1069      *         preference change listener on this node.
1070      * @throws IllegalStateException if this node (or an ancestor) has been
1071      *         removed with the {@link #removeNode()} method.
1072      * @see #addPreferenceChangeListener(PreferenceChangeListener)
1073      */
removePreferenceChangeListener( PreferenceChangeListener pcl)1074     public abstract void removePreferenceChangeListener(
1075         PreferenceChangeListener pcl);
1076 
1077     /**
1078      * Registers the specified listener to receive <i>node change events</i>
1079      * for this node.  A node change event is generated when a child node is
1080      * added to or removed from this node.  (A single {@link #removeNode()}
1081      * invocation results in multiple <i>node change events</i>, one for every
1082      * node in the subtree rooted at the removed node.)
1083      *
1084      * <p>Events are only guaranteed for changes made within the same JVM
1085      * as the registered listener, though some implementations may generate
1086      * events for changes made outside this JVM.  Events may be generated
1087      * before the changes have become permanent.  Events are not generated
1088      * when indirect descendants of this node are added or removed; a
1089      * caller desiring such events must register with each descendant.
1090      *
1091      * <p>Few guarantees can be made regarding node creation.  Because nodes
1092      * are created implicitly upon access, it may not be feasible for an
1093      * implementation to determine whether a child node existed in the backing
1094      * store prior to access (for example, because the backing store is
1095      * unreachable or cached information is out of date).  Under these
1096      * circumstances, implementations are neither required to generate node
1097      * change events nor prohibited from doing so.
1098      *
1099      * @param ncl The <tt>NodeChangeListener</tt> to add.
1100      * @throws NullPointerException if <tt>ncl</tt> is null.
1101      * @throws IllegalStateException if this node (or an ancestor) has been
1102      *         removed with the {@link #removeNode()} method.
1103      * @see #removeNodeChangeListener(NodeChangeListener)
1104      * @see #addPreferenceChangeListener(PreferenceChangeListener)
1105      */
addNodeChangeListener(NodeChangeListener ncl)1106     public abstract void addNodeChangeListener(NodeChangeListener ncl);
1107 
1108     /**
1109      * Removes the specified <tt>NodeChangeListener</tt>, so it no longer
1110      * receives change events.
1111      *
1112      * @param ncl The <tt>NodeChangeListener</tt> to remove.
1113      * @throws IllegalArgumentException if <tt>ncl</tt> was not a registered
1114      *         <tt>NodeChangeListener</tt> on this node.
1115      * @throws IllegalStateException if this node (or an ancestor) has been
1116      *         removed with the {@link #removeNode()} method.
1117      * @see #addNodeChangeListener(NodeChangeListener)
1118      */
removeNodeChangeListener(NodeChangeListener ncl)1119     public abstract void removeNodeChangeListener(NodeChangeListener ncl);
1120 
1121     /**
1122      * Emits on the specified output stream an XML document representing all
1123      * of the preferences contained in this node (but not its descendants).
1124      * This XML document is, in effect, an offline backup of the node.
1125      *
1126      * <p>The XML document will have the following DOCTYPE declaration:
1127      * <pre>{@code
1128      * <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
1129      * }</pre>
1130      * The UTF-8 character encoding will be used.
1131      *
1132      * <p>This method is an exception to the general rule that the results of
1133      * concurrently executing multiple methods in this class yields
1134      * results equivalent to some serial execution.  If the preferences
1135      * at this node are modified concurrently with an invocation of this
1136      * method, the exported preferences comprise a "fuzzy snapshot" of the
1137      * preferences contained in the node; some of the concurrent modifications
1138      * may be reflected in the exported data while others may not.
1139      *
1140      * @param os the output stream on which to emit the XML document.
1141      * @throws IOException if writing to the specified output stream
1142      *         results in an <tt>IOException</tt>.
1143      * @throws BackingStoreException if preference data cannot be read from
1144      *         backing store.
1145      * @see    #importPreferences(InputStream)
1146      * @throws IllegalStateException if this node (or an ancestor) has been
1147      *         removed with the {@link #removeNode()} method.
1148      */
exportNode(OutputStream os)1149     public abstract void exportNode(OutputStream os)
1150         throws IOException, BackingStoreException;
1151 
1152     /**
1153      * Emits an XML document representing all of the preferences contained
1154      * in this node and all of its descendants.  This XML document is, in
1155      * effect, an offline backup of the subtree rooted at the node.
1156      *
1157      * <p>The XML document will have the following DOCTYPE declaration:
1158      * <pre>{@code
1159      * <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
1160      * }</pre>
1161      * The UTF-8 character encoding will be used.
1162      *
1163      * <p>This method is an exception to the general rule that the results of
1164      * concurrently executing multiple methods in this class yields
1165      * results equivalent to some serial execution.  If the preferences
1166      * or nodes in the subtree rooted at this node are modified concurrently
1167      * with an invocation of this method, the exported preferences comprise a
1168      * "fuzzy snapshot" of the subtree; some of the concurrent modifications
1169      * may be reflected in the exported data while others may not.
1170      *
1171      * @param os the output stream on which to emit the XML document.
1172      * @throws IOException if writing to the specified output stream
1173      *         results in an <tt>IOException</tt>.
1174      * @throws BackingStoreException if preference data cannot be read from
1175      *         backing store.
1176      * @throws IllegalStateException if this node (or an ancestor) has been
1177      *         removed with the {@link #removeNode()} method.
1178      * @see    #importPreferences(InputStream)
1179      * @see    #exportNode(OutputStream)
1180      */
exportSubtree(OutputStream os)1181     public abstract void exportSubtree(OutputStream os)
1182         throws IOException, BackingStoreException;
1183 
1184     /**
1185      * Imports all of the preferences represented by the XML document on the
1186      * specified input stream.  The document may represent user preferences or
1187      * system preferences.  If it represents user preferences, the preferences
1188      * will be imported into the calling user's preference tree (even if they
1189      * originally came from a different user's preference tree).  If any of
1190      * the preferences described by the document inhabit preference nodes that
1191      * do not exist, the nodes will be created.
1192      *
1193      * <p>The XML document must have the following DOCTYPE declaration:
1194      * <pre>{@code
1195      * <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
1196      * }</pre>
1197      * (This method is designed for use in conjunction with
1198      * {@link #exportNode(OutputStream)} and
1199      * {@link #exportSubtree(OutputStream)}.
1200      *
1201      * <p>This method is an exception to the general rule that the results of
1202      * concurrently executing multiple methods in this class yields
1203      * results equivalent to some serial execution.  The method behaves
1204      * as if implemented on top of the other public methods in this class,
1205      * notably {@link #node(String)} and {@link #put(String, String)}.
1206      *
1207      * @param is the input stream from which to read the XML document.
1208      * @throws IOException if reading from the specified input stream
1209      *         results in an <tt>IOException</tt>.
1210      * @throws InvalidPreferencesFormatException Data on input stream does not
1211      *         constitute a valid XML document with the mandated document type.
1212      * @throws SecurityException If a security manager is present and
1213      *         it denies <tt>RuntimePermission("preferences")</tt>.
1214      * @see    RuntimePermission
1215      */
importPreferences(InputStream is)1216     public static void importPreferences(InputStream is)
1217         throws IOException, InvalidPreferencesFormatException
1218     {
1219         XmlSupport.importPreferences(is);
1220     }
1221 }
1222