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