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