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