1 /*
   2  * Copyright (c) 2000, 2008, 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>
 138  * &lt;!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd"&gt;
 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>
 144  *    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
 145  *
 146  *    &lt;!-- DTD for a Preferences tree. --&gt;
 147  *
 148  *    &lt;!-- The preferences element is at the root of an XML document
 149  *         representing a Preferences tree. --&gt;
 150  *    &lt;!ELEMENT preferences (root)&gt;
 151  *
 152  *    &lt;!-- The preferences element contains an optional version attribute,
 153  *          which specifies version of DTD. --&gt;
 154  *    &lt;!ATTLIST preferences EXTERNAL_XML_VERSION CDATA "0.0" &gt
 155  *
 156  *    &lt;!-- 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). --&gt;
 158  *    &lt;!ELEMENT root (map, node*) &gt;
 159  *
 160  *    &lt;!-- Additionally, the root contains a type attribute, which
 161  *         specifies whether it's the system or user root. --&gt;
 162  *    &lt;!ATTLIST root
 163  *              type (system|user) #REQUIRED &gt;
 164  *
 165  *    &lt;!-- Each node has a map representing its preferences (if any),
 166  *         and one node for each child (if any). --&gt;
 167  *    &lt;!ELEMENT node (map, node*) &gt;
 168  *
 169  *    &lt;!-- Additionally, each node has a name attribute --&gt;
 170  *    &lt;!ATTLIST node
 171  *              name CDATA #REQUIRED &gt;
 172  *
 173  *    &lt;!-- A map represents the preferences stored at a node (if any). --&gt;
 174  *    &lt;!ELEMENT map (entry*) &gt;
 175  *
 176  *    &lt;!-- An entry represents a single preference, which is simply
 177  *          a key-value pair. --&gt;
 178  *    &lt;!ELEMENT entry EMPTY &gt;
 179  *    &lt;!ATTLIST entry
 180  *              key   CDATA #REQUIRED
 181  *              value CDATA #REQUIRED &gt;
 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 platformFactory =
 293             System.getProperty("os.name").startsWith("Windows")
 294             ? "java.util.prefs.WindowsPreferencesFactory"
 295             : "java.util.prefs.FileSystemPreferencesFactory";
 296         try {
 297             return (PreferencesFactory)
 298                 Class.forName(platformFactory, false, null).newInstance();
 299         } catch (Exception e) {
 300             throw new InternalError(
 301                 "Can't instantiate platform default Preferences factory "
 302                 + platformFactory, e);
 303         }
 304     }
 305 
 306     /**
 307      * Maximum length of string allowed as a key (80 characters).
 308      */
 309     public static final int MAX_KEY_LENGTH = 80;
 310 
 311     /**
 312      * Maximum length of string allowed as a value (8192 characters).
 313      */
 314     public static final int MAX_VALUE_LENGTH = 8*1024;
 315 
 316     /**
 317      * Maximum length of a node name (80 characters).
 318      */
 319     public static final int MAX_NAME_LENGTH = 80;
 320 
 321     /**
 322      * Returns the preference node from the calling user's preference tree
 323      * that is associated (by convention) with the specified class's package.
 324      * The convention is as follows: the absolute path name of the node is the
 325      * fully qualified package name, preceded by a slash (<tt>'/'</tt>), and
 326      * with each period (<tt>'.'</tt>) replaced by a slash.  For example the
 327      * absolute path name of the node associated with the class
 328      * <tt>com.acme.widget.Foo</tt> is <tt>/com/acme/widget</tt>.
 329      *
 330      * <p>This convention does not apply to the unnamed package, whose
 331      * associated preference node is <tt>&lt;unnamed&gt;</tt>.  This node
 332      * is not intended for long term use, but for convenience in the early
 333      * development of programs that do not yet belong to a package, and
 334      * for "throwaway" programs.  <i>Valuable data should not be stored
 335      * at this node as it is shared by all programs that use it.</i>
 336      *
 337      * <p>A class <tt>Foo</tt> wishing to access preferences pertaining to its
 338      * package can obtain a preference node as follows: <pre>
 339      *    static Preferences prefs = Preferences.userNodeForPackage(Foo.class);
 340      * </pre>
 341      * This idiom obviates the need for using a string to describe the
 342      * preferences node and decreases the likelihood of a run-time failure.
 343      * (If the class name is misspelled, it will typically result in a
 344      * compile-time error.)
 345      *
 346      * <p>Invoking this method will result in the creation of the returned
 347      * node and its ancestors if they do not already exist.  If the returned
 348      * node did not exist prior to this call, this node and any ancestors that
 349      * were created by this call are not guaranteed to become permanent until
 350      * the <tt>flush</tt> method is called on the returned node (or one of its
 351      * ancestors or descendants).
 352      *
 353      * @param c the class for whose package a user preference node is desired.
 354      * @return the user preference node associated with the package of which
 355      *         <tt>c</tt> is a member.
 356      * @throws NullPointerException if <tt>c</tt> is <tt>null</tt>.
 357      * @throws SecurityException if a security manager is present and
 358      *         it denies <tt>RuntimePermission("preferences")</tt>.
 359      * @see    RuntimePermission
 360      */
 361     public static Preferences userNodeForPackage(Class<?> c) {
 362         return userRoot().node(nodeName(c));
 363     }
 364 
 365     /**
 366      * Returns the preference node from the system preference tree that is
 367      * associated (by convention) with the specified class's package.  The
 368      * convention is as follows: the absolute path name of the node is the
 369      * fully qualified package name, preceded by a slash (<tt>'/'</tt>), and
 370      * with each period (<tt>'.'</tt>) replaced by a slash.  For example the
 371      * absolute path name of the node associated with the class
 372      * <tt>com.acme.widget.Foo</tt> is <tt>/com/acme/widget</tt>.
 373      *
 374      * <p>This convention does not apply to the unnamed package, whose
 375      * associated preference node is <tt>&lt;unnamed&gt;</tt>.  This node
 376      * is not intended for long term use, but for convenience in the early
 377      * development of programs that do not yet belong to a package, and
 378      * for "throwaway" programs.  <i>Valuable data should not be stored
 379      * at this node as it is shared by all programs that use it.</i>
 380      *
 381      * <p>A class <tt>Foo</tt> wishing to access preferences pertaining to its
 382      * package can obtain a preference node as follows: <pre>
 383      *  static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);
 384      * </pre>
 385      * This idiom obviates the need for using a string to describe the
 386      * preferences node and decreases the likelihood of a run-time failure.
 387      * (If the class name is misspelled, it will typically result in a
 388      * compile-time error.)
 389      *
 390      * <p>Invoking this method will result in the creation of the returned
 391      * node and its ancestors if they do not already exist.  If the returned
 392      * node did not exist prior to this call, this node and any ancestors that
 393      * were created by this call are not guaranteed to become permanent until
 394      * the <tt>flush</tt> method is called on the returned node (or one of its
 395      * ancestors or descendants).
 396      *
 397      * @param c the class for whose package a system preference node is desired.
 398      * @return the system preference node associated with the package of which
 399      *         <tt>c</tt> is a member.
 400      * @throws NullPointerException if <tt>c</tt> is <tt>null</tt>.
 401      * @throws SecurityException if a security manager is present and
 402      *         it denies <tt>RuntimePermission("preferences")</tt>.
 403      * @see    RuntimePermission
 404      */
 405     public static Preferences systemNodeForPackage(Class<?> c) {
 406         return systemRoot().node(nodeName(c));
 407     }
 408 
 409     /**
 410      * Returns the absolute path name of the node corresponding to the package
 411      * of the specified object.
 412      *
 413      * @throws IllegalArgumentException if the package has node preferences
 414      *         node associated with it.
 415      */
 416     private static String nodeName(Class<?> c) {
 417         if (c.isArray())
 418             throw new IllegalArgumentException(
 419                 "Arrays have no associated preferences node.");
 420         String className = c.getName();
 421         int pkgEndIndex = className.lastIndexOf('.');
 422         if (pkgEndIndex < 0)
 423             return "/<unnamed>";
 424         String packageName = className.substring(0, pkgEndIndex);
 425         return "/" + packageName.replace('.', '/');
 426     }
 427 
 428     /**
 429      * This permission object represents the permission required to get
 430      * access to the user or system root (which in turn allows for all
 431      * other operations).
 432      */
 433     private static Permission prefsPerm = new RuntimePermission("preferences");
 434 
 435     /**
 436      * Returns the root preference node for the calling user.
 437      *
 438      * @return the root preference node for the calling user.
 439      * @throws SecurityException If a security manager is present and
 440      *         it denies <tt>RuntimePermission("preferences")</tt>.
 441      * @see    RuntimePermission
 442      */
 443     public static Preferences userRoot() {
 444         SecurityManager security = System.getSecurityManager();
 445         if (security != null)
 446             security.checkPermission(prefsPerm);
 447 
 448         return factory.userRoot();
 449     }
 450 
 451     /**
 452      * Returns the root preference node for the system.
 453      *
 454      * @return the root preference node for the system.
 455      * @throws SecurityException If a security manager is present and
 456      *         it denies <tt>RuntimePermission("preferences")</tt>.
 457      * @see    RuntimePermission
 458      */
 459     public static Preferences systemRoot() {
 460         SecurityManager security = System.getSecurityManager();
 461         if (security != null)
 462             security.checkPermission(prefsPerm);
 463 
 464         return factory.systemRoot();
 465     }
 466 
 467     /**
 468      * Sole constructor. (For invocation by subclass constructors, typically
 469      * implicit.)
 470      */
 471     protected Preferences() {
 472     }
 473 
 474     /**
 475      * Associates the specified value with the specified key in this
 476      * preference node.
 477      *
 478      * @param key key with which the specified value is to be associated.
 479      * @param value value to be associated with the specified key.
 480      * @throws NullPointerException if key or value is <tt>null</tt>.
 481      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
 482      *       <tt>MAX_KEY_LENGTH</tt> or if <tt>value.length</tt> exceeds
 483      *       <tt>MAX_VALUE_LENGTH</tt>.
 484      * @throws IllegalStateException if this node (or an ancestor) has been
 485      *         removed with the {@link #removeNode()} method.
 486      */
 487     public abstract void put(String key, String value);
 488 
 489     /**
 490      * Returns the value associated with the specified key in this preference
 491      * node.  Returns the specified default if there is no value associated
 492      * with the key, or the backing store is inaccessible.
 493      *
 494      * <p>Some implementations may store default values in their backing
 495      * stores.  If there is no value associated with the specified key
 496      * but there is such a <i>stored default</i>, it is returned in
 497      * preference to the specified default.
 498      *
 499      * @param key key whose associated value is to be returned.
 500      * @param def the value to be returned in the event that this
 501      *        preference node has no value associated with <tt>key</tt>.
 502      * @return the value associated with <tt>key</tt>, or <tt>def</tt>
 503      *         if no value is associated with <tt>key</tt>, or the backing
 504      *         store is inaccessible.
 505      * @throws IllegalStateException if this node (or an ancestor) has been
 506      *         removed with the {@link #removeNode()} method.
 507      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.  (A
 508      *         <tt>null</tt> value for <tt>def</tt> <i>is</i> permitted.)
 509      */
 510     public abstract String get(String key, String def);
 511 
 512     /**
 513      * Removes the value associated with the specified key in this preference
 514      * node, if any.
 515      *
 516      * <p>If this implementation supports <i>stored defaults</i>, and there is
 517      * such a default for the specified preference, the stored default will be
 518      * "exposed" by this call, in the sense that it will be returned
 519      * by a succeeding call to <tt>get</tt>.
 520      *
 521      * @param key key whose mapping is to be removed from the preference node.
 522      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
 523      * @throws IllegalStateException if this node (or an ancestor) has been
 524      *         removed with the {@link #removeNode()} method.
 525      */
 526     public abstract void remove(String key);
 527 
 528     /**
 529      * Removes all of the preferences (key-value associations) in this
 530      * preference node.  This call has no effect on any descendants
 531      * of this node.
 532      *
 533      * <p>If this implementation supports <i>stored defaults</i>, and this
 534      * node in the preferences hierarchy contains any such defaults,
 535      * the stored defaults will be "exposed" by this call, in the sense that
 536      * they will be returned by succeeding calls to <tt>get</tt>.
 537      *
 538      * @throws BackingStoreException if this operation cannot be completed
 539      *         due to a failure in the backing store, or inability to
 540      *         communicate with it.
 541      * @throws IllegalStateException if this node (or an ancestor) has been
 542      *         removed with the {@link #removeNode()} method.
 543      * @see #removeNode()
 544      */
 545     public abstract void clear() throws BackingStoreException;
 546 
 547     /**
 548      * Associates a string representing the specified int value with the
 549      * specified key in this preference node.  The associated string is the
 550      * one that would be returned if the int value were passed to
 551      * {@link Integer#toString(int)}.  This method is intended for use in
 552      * conjunction with {@link #getInt}.
 553      *
 554      * @param key key with which the string form of value is to be associated.
 555      * @param value value whose string form is to be associated with key.
 556      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
 557      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
 558      *         <tt>MAX_KEY_LENGTH</tt>.
 559      * @throws IllegalStateException if this node (or an ancestor) has been
 560      *         removed with the {@link #removeNode()} method.
 561      * @see #getInt(String,int)
 562      */
 563     public abstract void putInt(String key, int value);
 564 
 565     /**
 566      * Returns the int value represented by the string associated with the
 567      * specified key in this preference node.  The string is converted to
 568      * an integer as by {@link Integer#parseInt(String)}.  Returns the
 569      * specified default if there is no value associated with the key,
 570      * the backing store is inaccessible, or if
 571      * <tt>Integer.parseInt(String)</tt> would throw a {@link
 572      * NumberFormatException} if the associated value were passed.  This
 573      * method is intended for use in conjunction with {@link #putInt}.
 574      *
 575      * <p>If the implementation supports <i>stored defaults</i> and such a
 576      * default exists, is accessible, and could be converted to an int
 577      * with <tt>Integer.parseInt</tt>, this int is returned in preference to
 578      * the specified default.
 579      *
 580      * @param key key whose associated value is to be returned as an int.
 581      * @param def the value to be returned in the event that this
 582      *        preference node has no value associated with <tt>key</tt>
 583      *        or the associated value cannot be interpreted as an int,
 584      *        or the backing store is inaccessible.
 585      * @return the int value represented by the string associated with
 586      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
 587      *         associated value does not exist or cannot be interpreted as
 588      *         an int.
 589      * @throws IllegalStateException if this node (or an ancestor) has been
 590      *         removed with the {@link #removeNode()} method.
 591      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
 592      * @see #putInt(String,int)
 593      * @see #get(String,String)
 594      */
 595     public abstract int getInt(String key, int def);
 596 
 597     /**
 598      * Associates a string representing the specified long value with the
 599      * specified key in this preference node.  The associated string is the
 600      * one that would be returned if the long value were passed to
 601      * {@link Long#toString(long)}.  This method is intended for use in
 602      * conjunction with {@link #getLong}.
 603      *
 604      * @param key key with which the string form of value is to be associated.
 605      * @param value value whose string form is to be associated with key.
 606      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
 607      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
 608      *         <tt>MAX_KEY_LENGTH</tt>.
 609      * @throws IllegalStateException if this node (or an ancestor) has been
 610      *         removed with the {@link #removeNode()} method.
 611      * @see #getLong(String,long)
 612      */
 613     public abstract void putLong(String key, long value);
 614 
 615     /**
 616      * Returns the long value represented by the string associated with the
 617      * specified key in this preference node.  The string is converted to
 618      * a long as by {@link Long#parseLong(String)}.  Returns the
 619      * specified default if there is no value associated with the key,
 620      * the backing store is inaccessible, or if
 621      * <tt>Long.parseLong(String)</tt> would throw a {@link
 622      * NumberFormatException} if the associated value were passed.  This
 623      * method is intended for use in conjunction with {@link #putLong}.
 624      *
 625      * <p>If the implementation supports <i>stored defaults</i> and such a
 626      * default exists, is accessible, and could be converted to a long
 627      * with <tt>Long.parseLong</tt>, this long is returned in preference to
 628      * the specified default.
 629      *
 630      * @param key key whose associated value is to be returned as a long.
 631      * @param def the value to be returned in the event that this
 632      *        preference node has no value associated with <tt>key</tt>
 633      *        or the associated value cannot be interpreted as a long,
 634      *        or the backing store is inaccessible.
 635      * @return the long value represented by the string associated with
 636      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
 637      *         associated value does not exist or cannot be interpreted as
 638      *         a long.
 639      * @throws IllegalStateException if this node (or an ancestor) has been
 640      *         removed with the {@link #removeNode()} method.
 641      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
 642      * @see #putLong(String,long)
 643      * @see #get(String,String)
 644      */
 645     public abstract long getLong(String key, long def);
 646 
 647     /**
 648      * Associates a string representing the specified boolean value with the
 649      * specified key in this preference node.  The associated string is
 650      * <tt>"true"</tt> if the value is true, and <tt>"false"</tt> if it is
 651      * false.  This method is intended for use in conjunction with
 652      * {@link #getBoolean}.
 653      *
 654      * @param key key with which the string form of value is to be associated.
 655      * @param value value whose string form is to be associated with key.
 656      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
 657      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
 658      *         <tt>MAX_KEY_LENGTH</tt>.
 659      * @throws IllegalStateException if this node (or an ancestor) has been
 660      *         removed with the {@link #removeNode()} method.
 661      * @see #getBoolean(String,boolean)
 662      * @see #get(String,String)
 663      */
 664     public abstract void putBoolean(String key, boolean value);
 665 
 666     /**
 667      * Returns the boolean value represented by the string associated with the
 668      * specified key in this preference node.  Valid strings
 669      * are <tt>"true"</tt>, which represents true, and <tt>"false"</tt>, which
 670      * represents false.  Case is ignored, so, for example, <tt>"TRUE"</tt>
 671      * and <tt>"False"</tt> are also valid.  This method is intended for use in
 672      * conjunction with {@link #putBoolean}.
 673      *
 674      * <p>Returns the specified default if there is no value
 675      * associated with the key, the backing store is inaccessible, or if the
 676      * associated value is something other than <tt>"true"</tt> or
 677      * <tt>"false"</tt>, ignoring case.
 678      *
 679      * <p>If the implementation supports <i>stored defaults</i> and such a
 680      * default exists and is accessible, it is used in preference to the
 681      * specified default, unless the stored default is something other than
 682      * <tt>"true"</tt> or <tt>"false"</tt>, ignoring case, in which case the
 683      * specified default is used.
 684      *
 685      * @param key key whose associated value is to be returned as a boolean.
 686      * @param def the value to be returned in the event that this
 687      *        preference node has no value associated with <tt>key</tt>
 688      *        or the associated value cannot be interpreted as a boolean,
 689      *        or the backing store is inaccessible.
 690      * @return the boolean value represented by the string associated with
 691      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
 692      *         associated value does not exist or cannot be interpreted as
 693      *         a boolean.
 694      * @throws IllegalStateException if this node (or an ancestor) has been
 695      *         removed with the {@link #removeNode()} method.
 696      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
 697      * @see #get(String,String)
 698      * @see #putBoolean(String,boolean)
 699      */
 700     public abstract boolean getBoolean(String key, boolean def);
 701 
 702     /**
 703      * Associates a string representing the specified float value with the
 704      * specified key in this preference node.  The associated string is the
 705      * one that would be returned if the float value were passed to
 706      * {@link Float#toString(float)}.  This method is intended for use in
 707      * conjunction with {@link #getFloat}.
 708      *
 709      * @param key key with which the string form of value is to be associated.
 710      * @param value value whose string form is to be associated with key.
 711      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
 712      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
 713      *         <tt>MAX_KEY_LENGTH</tt>.
 714      * @throws IllegalStateException if this node (or an ancestor) has been
 715      *         removed with the {@link #removeNode()} method.
 716      * @see #getFloat(String,float)
 717      */
 718     public abstract void putFloat(String key, float value);
 719 
 720     /**
 721      * Returns the float value represented by the string associated with the
 722      * specified key in this preference node.  The string is converted to an
 723      * integer as by {@link Float#parseFloat(String)}.  Returns the specified
 724      * default if there is no value associated with the key, the backing store
 725      * is inaccessible, or if <tt>Float.parseFloat(String)</tt> would throw a
 726      * {@link NumberFormatException} if the associated value were passed.
 727      * This method is intended for use in conjunction with {@link #putFloat}.
 728      *
 729      * <p>If the implementation supports <i>stored defaults</i> and such a
 730      * default exists, is accessible, and could be converted to a float
 731      * with <tt>Float.parseFloat</tt>, this float is returned in preference to
 732      * the specified default.
 733      *
 734      * @param key key whose associated value is to be returned as a float.
 735      * @param def the value to be returned in the event that this
 736      *        preference node has no value associated with <tt>key</tt>
 737      *        or the associated value cannot be interpreted as a float,
 738      *        or the backing store is inaccessible.
 739      * @return the float value represented by the string associated with
 740      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
 741      *         associated value does not exist or cannot be interpreted as
 742      *         a float.
 743      * @throws IllegalStateException if this node (or an ancestor) has been
 744      *         removed with the {@link #removeNode()} method.
 745      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
 746      * @see #putFloat(String,float)
 747      * @see #get(String,String)
 748      */
 749     public abstract float getFloat(String key, float def);
 750 
 751     /**
 752      * Associates a string representing the specified double value with the
 753      * specified key in this preference node.  The associated string is the
 754      * one that would be returned if the double value were passed to
 755      * {@link Double#toString(double)}.  This method is intended for use in
 756      * conjunction with {@link #getDouble}.
 757      *
 758      * @param key key with which the string form of value is to be associated.
 759      * @param value value whose string form is to be associated with key.
 760      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
 761      * @throws IllegalArgumentException if <tt>key.length()</tt> exceeds
 762      *         <tt>MAX_KEY_LENGTH</tt>.
 763      * @throws IllegalStateException if this node (or an ancestor) has been
 764      *         removed with the {@link #removeNode()} method.
 765      * @see #getDouble(String,double)
 766      */
 767     public abstract void putDouble(String key, double value);
 768 
 769     /**
 770      * Returns the double value represented by the string associated with the
 771      * specified key in this preference node.  The string is converted to an
 772      * integer as by {@link Double#parseDouble(String)}.  Returns the specified
 773      * default if there is no value associated with the key, the backing store
 774      * is inaccessible, or if <tt>Double.parseDouble(String)</tt> would throw a
 775      * {@link NumberFormatException} if the associated value were passed.
 776      * This method is intended for use in conjunction with {@link #putDouble}.
 777      *
 778      * <p>If the implementation supports <i>stored defaults</i> and such a
 779      * default exists, is accessible, and could be converted to a double
 780      * with <tt>Double.parseDouble</tt>, this double is returned in preference
 781      * to the specified default.
 782      *
 783      * @param key key whose associated value is to be returned as a double.
 784      * @param def the value to be returned in the event that this
 785      *        preference node has no value associated with <tt>key</tt>
 786      *        or the associated value cannot be interpreted as a double,
 787      *        or the backing store is inaccessible.
 788      * @return the double value represented by the string associated with
 789      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
 790      *         associated value does not exist or cannot be interpreted as
 791      *         a double.
 792      * @throws IllegalStateException if this node (or an ancestor) has been
 793      *         removed with the {@link #removeNode()} method.
 794      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.
 795      * @see #putDouble(String,double)
 796      * @see #get(String,String)
 797      */
 798     public abstract double getDouble(String key, double def);
 799 
 800     /**
 801      * Associates a string representing the specified byte array with the
 802      * specified key in this preference node.  The associated string is
 803      * the <i>Base64</i> encoding of the byte array, as defined in <a
 804      * href=http://www.ietf.org/rfc/rfc2045.txt>RFC 2045</a>, Section 6.8,
 805      * with one minor change: the string will consist solely of characters
 806      * from the <i>Base64 Alphabet</i>; it will not contain any newline
 807      * characters.  Note that the maximum length of the byte array is limited
 808      * to three quarters of <tt>MAX_VALUE_LENGTH</tt> so that the length
 809      * of the Base64 encoded String does not exceed <tt>MAX_VALUE_LENGTH</tt>.
 810      * This method is intended for use in conjunction with
 811      * {@link #getByteArray}.
 812      *
 813      * @param key key with which the string form of value is to be associated.
 814      * @param value value whose string form is to be associated with key.
 815      * @throws NullPointerException if key or value is <tt>null</tt>.
 816      * @throws IllegalArgumentException if key.length() exceeds MAX_KEY_LENGTH
 817      *         or if value.length exceeds MAX_VALUE_LENGTH*3/4.
 818      * @throws IllegalStateException if this node (or an ancestor) has been
 819      *         removed with the {@link #removeNode()} method.
 820      * @see #getByteArray(String,byte[])
 821      * @see #get(String,String)
 822      */
 823     public abstract void putByteArray(String key, byte[] value);
 824 
 825     /**
 826      * Returns the byte array value represented by the string associated with
 827      * the specified key in this preference node.  Valid strings are
 828      * <i>Base64</i> encoded binary data, as defined in <a
 829      * href=http://www.ietf.org/rfc/rfc2045.txt>RFC 2045</a>, Section 6.8,
 830      * with one minor change: the string must consist solely of characters
 831      * from the <i>Base64 Alphabet</i>; no newline characters or
 832      * extraneous characters are permitted.  This method is intended for use
 833      * in conjunction with {@link #putByteArray}.
 834      *
 835      * <p>Returns the specified default if there is no value
 836      * associated with the key, the backing store is inaccessible, or if the
 837      * associated value is not a valid Base64 encoded byte array
 838      * (as defined above).
 839      *
 840      * <p>If the implementation supports <i>stored defaults</i> and such a
 841      * default exists and is accessible, it is used in preference to the
 842      * specified default, unless the stored default is not a valid Base64
 843      * encoded byte array (as defined above), in which case the
 844      * specified default is used.
 845      *
 846      * @param key key whose associated value is to be returned as a byte array.
 847      * @param def the value to be returned in the event that this
 848      *        preference node has no value associated with <tt>key</tt>
 849      *        or the associated value cannot be interpreted as a byte array,
 850      *        or the backing store is inaccessible.
 851      * @return the byte array value represented by the string associated with
 852      *         <tt>key</tt> in this preference node, or <tt>def</tt> if the
 853      *         associated value does not exist or cannot be interpreted as
 854      *         a byte array.
 855      * @throws IllegalStateException if this node (or an ancestor) has been
 856      *         removed with the {@link #removeNode()} method.
 857      * @throws NullPointerException if <tt>key</tt> is <tt>null</tt>.  (A
 858      *         <tt>null</tt> value for <tt>def</tt> <i>is</i> permitted.)
 859      * @see #get(String,String)
 860      * @see #putByteArray(String,byte[])
 861      */
 862     public abstract byte[] getByteArray(String key, byte[] def);
 863 
 864     /**
 865      * Returns all of the keys that have an associated value in this
 866      * preference node.  (The returned array will be of size zero if
 867      * this node has no preferences.)
 868      *
 869      * <p>If the implementation supports <i>stored defaults</i> and there
 870      * are any such defaults at this node that have not been overridden,
 871      * by explicit preferences, the defaults are returned in the array in
 872      * addition to any explicit preferences.
 873      *
 874      * @return an array of the keys that have an associated value in this
 875      *         preference node.
 876      * @throws BackingStoreException if this operation cannot be completed
 877      *         due to a failure in the backing store, or inability to
 878      *         communicate with it.
 879      * @throws IllegalStateException if this node (or an ancestor) has been
 880      *         removed with the {@link #removeNode()} method.
 881      */
 882     public abstract String[] keys() throws BackingStoreException;
 883 
 884     /**
 885      * Returns the names of the children of this preference node, relative to
 886      * this node.  (The returned array will be of size zero if this node has
 887      * no children.)
 888      *
 889      * @return the names of the children of this preference node.
 890      * @throws BackingStoreException if this operation cannot be completed
 891      *         due to a failure in the backing store, or inability to
 892      *         communicate with it.
 893      * @throws IllegalStateException if this node (or an ancestor) has been
 894      *         removed with the {@link #removeNode()} method.
 895      */
 896     public abstract String[] childrenNames() throws BackingStoreException;
 897 
 898     /**
 899      * Returns the parent of this preference node, or <tt>null</tt> if this is
 900      * the root.
 901      *
 902      * @return the parent of this preference node.
 903      * @throws IllegalStateException if this node (or an ancestor) has been
 904      *         removed with the {@link #removeNode()} method.
 905      */
 906     public abstract Preferences parent();
 907 
 908     /**
 909      * Returns the named preference node in the same tree as this node,
 910      * creating it and any of its ancestors if they do not already exist.
 911      * Accepts a relative or absolute path name.  Relative path names
 912      * (which do not begin with the slash character <tt>('/')</tt>) are
 913      * interpreted relative to this preference node.
 914      *
 915      * <p>If the returned node did not exist prior to this call, this node and
 916      * any ancestors that were created by this call are not guaranteed
 917      * to become permanent until the <tt>flush</tt> method is called on
 918      * the returned node (or one of its ancestors or descendants).
 919      *
 920      * @param pathName the path name of the preference node to return.
 921      * @return the specified preference node.
 922      * @throws IllegalArgumentException if the path name is invalid (i.e.,
 923      *         it contains multiple consecutive slash characters, or ends
 924      *         with a slash character and is more than one character long).
 925      * @throws NullPointerException if path name is <tt>null</tt>.
 926      * @throws IllegalStateException if this node (or an ancestor) has been
 927      *         removed with the {@link #removeNode()} method.
 928      * @see #flush()
 929      */
 930     public abstract Preferences node(String pathName);
 931 
 932     /**
 933      * Returns true if the named preference node exists in the same tree
 934      * as this node.  Relative path names (which do not begin with the slash
 935      * character <tt>('/')</tt>) are interpreted relative to this preference
 936      * node.
 937      *
 938      * <p>If this node (or an ancestor) has already been removed with the
 939      * {@link #removeNode()} method, it <i>is</i> legal to invoke this method,
 940      * but only with the path name <tt>""</tt>; the invocation will return
 941      * <tt>false</tt>.  Thus, the idiom <tt>p.nodeExists("")</tt> may be
 942      * used to test whether <tt>p</tt> has been removed.
 943      *
 944      * @param pathName the path name of the node whose existence
 945      *        is to be checked.
 946      * @return true if the specified node exists.
 947      * @throws BackingStoreException if this operation cannot be completed
 948      *         due to a failure in the backing store, or inability to
 949      *         communicate with it.
 950      * @throws IllegalArgumentException if the path name is invalid (i.e.,
 951      *         it contains multiple consecutive slash characters, or ends
 952      *         with a slash character and is more than one character long).
 953      * @throws NullPointerException if path name is <tt>null</tt>.
 954      * @throws IllegalStateException if this node (or an ancestor) has been
 955      *         removed with the {@link #removeNode()} method and
 956      *         <tt>pathName</tt> is not the empty string (<tt>""</tt>).
 957      */
 958     public abstract boolean nodeExists(String pathName)
 959         throws BackingStoreException;
 960 
 961     /**
 962      * Removes this preference node and all of its descendants, invalidating
 963      * any preferences contained in the removed nodes.  Once a node has been
 964      * removed, attempting any method other than {@link #name()},
 965      * {@link #absolutePath()}, {@link #isUserNode()}, {@link #flush()} or
 966      * {@link #node(String) nodeExists("")} on the corresponding
 967      * <tt>Preferences</tt> instance will fail with an
 968      * <tt>IllegalStateException</tt>.  (The methods defined on {@link Object}
 969      * can still be invoked on a node after it has been removed; they will not
 970      * throw <tt>IllegalStateException</tt>.)
 971      *
 972      * <p>The removal is not guaranteed to be persistent until the
 973      * <tt>flush</tt> method is called on this node (or an ancestor).
 974      *
 975      * <p>If this implementation supports <i>stored defaults</i>, removing a
 976      * node exposes any stored defaults at or below this node.  Thus, a
 977      * subsequent call to <tt>nodeExists</tt> on this node's path name may
 978      * return <tt>true</tt>, and a subsequent call to <tt>node</tt> on this
 979      * path name may return a (different) <tt>Preferences</tt> instance
 980      * representing a non-empty collection of preferences and/or children.
 981      *
 982      * @throws BackingStoreException if this operation cannot be completed
 983      *         due to a failure in the backing store, or inability to
 984      *         communicate with it.
 985      * @throws IllegalStateException if this node (or an ancestor) has already
 986      *         been removed with the {@link #removeNode()} method.
 987      * @throws UnsupportedOperationException if this method is invoked on
 988      *         the root node.
 989      * @see #flush()
 990      */
 991     public abstract void removeNode() throws BackingStoreException;
 992 
 993     /**
 994      * Returns this preference node's name, relative to its parent.
 995      *
 996      * @return this preference node's name, relative to its parent.
 997      */
 998     public abstract String name();
 999 
1000     /**
1001      * Returns this preference node's absolute path name.
1002      *
1003      * @return this preference node's absolute path name.
1004      */
1005     public abstract String absolutePath();
1006 
1007     /**
1008      * Returns <tt>true</tt> if this preference node is in the user
1009      * preference tree, <tt>false</tt> if it's in the system preference tree.
1010      *
1011      * @return <tt>true</tt> if this preference node is in the user
1012      *         preference tree, <tt>false</tt> if it's in the system
1013      *         preference tree.
1014      */
1015     public abstract boolean isUserNode();
1016 
1017     /**
1018      * Returns a string representation of this preferences node,
1019      * as if computed by the expression:<tt>(this.isUserNode() ? "User" :
1020      * "System") + " Preference Node: " + this.absolutePath()</tt>.
1021      */
1022     public abstract String toString();
1023 
1024     /**
1025      * Forces any changes in the contents of this preference node and its
1026      * descendants to the persistent store.  Once this method returns
1027      * successfully, it is safe to assume that all changes made in the
1028      * subtree rooted at this node prior to the method invocation have become
1029      * permanent.
1030      *
1031      * <p>Implementations are free to flush changes into the persistent store
1032      * at any time.  They do not need to wait for this method to be called.
1033      *
1034      * <p>When a flush occurs on a newly created node, it is made persistent,
1035      * as are any ancestors (and descendants) that have yet to be made
1036      * persistent.  Note however that any preference value changes in
1037      * ancestors are <i>not</i> guaranteed to be made persistent.
1038      *
1039      * <p> If this method is invoked on a node that has been removed with
1040      * the {@link #removeNode()} method, flushSpi() is invoked on this node,
1041      * but not on others.
1042      *
1043      * @throws BackingStoreException if this operation cannot be completed
1044      *         due to a failure in the backing store, or inability to
1045      *         communicate with it.
1046      * @see    #sync()
1047      */
1048     public abstract void flush() throws BackingStoreException;
1049 
1050     /**
1051      * Ensures that future reads from this preference node and its
1052      * descendants reflect any changes that were committed to the persistent
1053      * store (from any VM) prior to the <tt>sync</tt> invocation.  As a
1054      * side-effect, forces any changes in the contents of this preference node
1055      * and its descendants to the persistent store, as if the <tt>flush</tt>
1056      * method had been invoked on this node.
1057      *
1058      * @throws BackingStoreException if this operation cannot be completed
1059      *         due to a failure in the backing store, or inability to
1060      *         communicate with it.
1061      * @throws IllegalStateException if this node (or an ancestor) has been
1062      *         removed with the {@link #removeNode()} method.
1063      * @see    #flush()
1064      */
1065     public abstract void sync() throws BackingStoreException;
1066 
1067     /**
1068      * Registers the specified listener to receive <i>preference change
1069      * events</i> for this preference node.  A preference change event is
1070      * generated when a preference is added to this node, removed from this
1071      * node, or when the value associated with a preference is changed.
1072      * (Preference change events are <i>not</i> generated by the {@link
1073      * #removeNode()} method, which generates a <i>node change event</i>.
1074      * Preference change events <i>are</i> generated by the <tt>clear</tt>
1075      * method.)
1076      *
1077      * <p>Events are only guaranteed for changes made within the same JVM
1078      * as the registered listener, though some implementations may generate
1079      * events for changes made outside this JVM.  Events may be generated
1080      * before the changes have been made persistent.  Events are not generated
1081      * when preferences are modified in descendants of this node; a caller
1082      * desiring such events must register with each descendant.
1083      *
1084      * @param pcl The preference change listener to add.
1085      * @throws NullPointerException if <tt>pcl</tt> is null.
1086      * @throws IllegalStateException if this node (or an ancestor) has been
1087      *         removed with the {@link #removeNode()} method.
1088      * @see #removePreferenceChangeListener(PreferenceChangeListener)
1089      * @see #addNodeChangeListener(NodeChangeListener)
1090      */
1091     public abstract void addPreferenceChangeListener(
1092         PreferenceChangeListener pcl);
1093 
1094     /**
1095      * Removes the specified preference change listener, so it no longer
1096      * receives preference change events.
1097      *
1098      * @param pcl The preference change listener to remove.
1099      * @throws IllegalArgumentException if <tt>pcl</tt> was not a registered
1100      *         preference change listener on this node.
1101      * @throws IllegalStateException if this node (or an ancestor) has been
1102      *         removed with the {@link #removeNode()} method.
1103      * @see #addPreferenceChangeListener(PreferenceChangeListener)
1104      */
1105     public abstract void removePreferenceChangeListener(
1106         PreferenceChangeListener pcl);
1107 
1108     /**
1109      * Registers the specified listener to receive <i>node change events</i>
1110      * for this node.  A node change event is generated when a child node is
1111      * added to or removed from this node.  (A single {@link #removeNode()}
1112      * invocation results in multiple <i>node change events</i>, one for every
1113      * node in the subtree rooted at the removed node.)
1114      *
1115      * <p>Events are only guaranteed for changes made within the same JVM
1116      * as the registered listener, though some implementations may generate
1117      * events for changes made outside this JVM.  Events may be generated
1118      * before the changes have become permanent.  Events are not generated
1119      * when indirect descendants of this node are added or removed; a
1120      * caller desiring such events must register with each descendant.
1121      *
1122      * <p>Few guarantees can be made regarding node creation.  Because nodes
1123      * are created implicitly upon access, it may not be feasible for an
1124      * implementation to determine whether a child node existed in the backing
1125      * store prior to access (for example, because the backing store is
1126      * unreachable or cached information is out of date).  Under these
1127      * circumstances, implementations are neither required to generate node
1128      * change events nor prohibited from doing so.
1129      *
1130      * @param ncl The <tt>NodeChangeListener</tt> to add.
1131      * @throws NullPointerException if <tt>ncl</tt> is null.
1132      * @throws IllegalStateException if this node (or an ancestor) has been
1133      *         removed with the {@link #removeNode()} method.
1134      * @see #removeNodeChangeListener(NodeChangeListener)
1135      * @see #addPreferenceChangeListener(PreferenceChangeListener)
1136      */
1137     public abstract void addNodeChangeListener(NodeChangeListener ncl);
1138 
1139     /**
1140      * Removes the specified <tt>NodeChangeListener</tt>, so it no longer
1141      * receives change events.
1142      *
1143      * @param ncl The <tt>NodeChangeListener</tt> to remove.
1144      * @throws IllegalArgumentException if <tt>ncl</tt> was not a registered
1145      *         <tt>NodeChangeListener</tt> on this node.
1146      * @throws IllegalStateException if this node (or an ancestor) has been
1147      *         removed with the {@link #removeNode()} method.
1148      * @see #addNodeChangeListener(NodeChangeListener)
1149      */
1150     public abstract void removeNodeChangeListener(NodeChangeListener ncl);
1151 
1152     /**
1153      * Emits on the specified output stream an XML document representing all
1154      * of the preferences contained in this node (but not its descendants).
1155      * This XML document is, in effect, an offline backup of the node.
1156      *
1157      * <p>The XML document will have the following DOCTYPE declaration:
1158      * <pre>
1159      * &lt;!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd"&gt;
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      * at this node are modified concurrently with an invocation of this
1167      * method, the exported preferences comprise a "fuzzy snapshot" of the
1168      * preferences contained in the node; 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      * @see    #importPreferences(InputStream)
1177      * @throws IllegalStateException if this node (or an ancestor) has been
1178      *         removed with the {@link #removeNode()} method.
1179      */
1180     public abstract void exportNode(OutputStream os)
1181         throws IOException, BackingStoreException;
1182 
1183     /**
1184      * Emits an XML document representing all of the preferences contained
1185      * in this node and all of its descendants.  This XML document is, in
1186      * effect, an offline backup of the subtree rooted at the node.
1187      *
1188      * <p>The XML document will have the following DOCTYPE declaration:
1189      * <pre>
1190      * &lt;!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd"&gt;
1191      * </pre>
1192      * The UTF-8 character encoding will be used.
1193      *
1194      * <p>This method is an exception to the general rule that the results of
1195      * concurrently executing multiple methods in this class yields
1196      * results equivalent to some serial execution.  If the preferences
1197      * or nodes in the subtree rooted at this node are modified concurrently
1198      * with an invocation of this method, the exported preferences comprise a
1199      * "fuzzy snapshot" of the subtree; some of the concurrent modifications
1200      * may be reflected in the exported data while others may not.
1201      *
1202      * @param os the output stream on which to emit the XML document.
1203      * @throws IOException if writing to the specified output stream
1204      *         results in an <tt>IOException</tt>.
1205      * @throws BackingStoreException if preference data cannot be read from
1206      *         backing store.
1207      * @throws IllegalStateException if this node (or an ancestor) has been
1208      *         removed with the {@link #removeNode()} method.
1209      * @see    #importPreferences(InputStream)
1210      * @see    #exportNode(OutputStream)
1211      */
1212     public abstract void exportSubtree(OutputStream os)
1213         throws IOException, BackingStoreException;
1214 
1215     /**
1216      * Imports all of the preferences represented by the XML document on the
1217      * specified input stream.  The document may represent user preferences or
1218      * system preferences.  If it represents user preferences, the preferences
1219      * will be imported into the calling user's preference tree (even if they
1220      * originally came from a different user's preference tree).  If any of
1221      * the preferences described by the document inhabit preference nodes that
1222      * do not exist, the nodes will be created.
1223      *
1224      * <p>The XML document must have the following DOCTYPE declaration:
1225      * <pre>
1226      * &lt;!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd"&gt;
1227      * </pre>
1228      * (This method is designed for use in conjunction with
1229      * {@link #exportNode(OutputStream)} and
1230      * {@link #exportSubtree(OutputStream)}.
1231      *
1232      * <p>This method is an exception to the general rule that the results of
1233      * concurrently executing multiple methods in this class yields
1234      * results equivalent to some serial execution.  The method behaves
1235      * as if implemented on top of the other public methods in this class,
1236      * notably {@link #node(String)} and {@link #put(String, String)}.
1237      *
1238      * @param is the input stream from which to read the XML document.
1239      * @throws IOException if reading from the specified input stream
1240      *         results in an <tt>IOException</tt>.
1241      * @throws InvalidPreferencesFormatException Data on input stream does not
1242      *         constitute a valid XML document with the mandated document type.
1243      * @throws SecurityException If a security manager is present and
1244      *         it denies <tt>RuntimePermission("preferences")</tt>.
1245      * @see    RuntimePermission
1246      */
1247     public static void importPreferences(InputStream is)
1248         throws IOException, InvalidPreferencesFormatException
1249     {
1250         XmlSupport.importPreferences(is);
1251     }
1252 }