1 *java.util.prefs.Preferences* *Preferences* A node in a hierarchical collection
3 public abstract class Preferences
4 extends |java.lang.Object|
6 |java.util.prefs.Preferences_Description|
7 |java.util.prefs.Preferences_Fields|
8 |java.util.prefs.Preferences_Constructors|
9 |java.util.prefs.Preferences_Methods|
11 ================================================================================
13 *java.util.prefs.Preferences_Fields*
14 |int_java.util.prefs.Preferences.MAX_KEY_LENGTH|
15 |int_java.util.prefs.Preferences.MAX_NAME_LENGTH|
16 |int_java.util.prefs.Preferences.MAX_VALUE_LENGTH|
18 *java.util.prefs.Preferences_Constructors*
19 |java.util.prefs.Preferences()|Sole constructor.
21 *java.util.prefs.Preferences_Methods*
22 |java.util.prefs.Preferences.absolutePath()|Returns this preference node's abso
23 |java.util.prefs.Preferences.addNodeChangeListener(NodeChangeListener)|Register
24 |java.util.prefs.Preferences.addPreferenceChangeListener(PreferenceChangeListener)|
25 |java.util.prefs.Preferences.childrenNames()|Returns the names of the children
26 |java.util.prefs.Preferences.clear()|Removes all of the preferences (key-value
27 |java.util.prefs.Preferences.exportNode(OutputStream)|Emits on the specified ou
28 |java.util.prefs.Preferences.exportSubtree(OutputStream)|Emits an XML document
29 |java.util.prefs.Preferences.flush()|Forces any changes in the contents of this
30 |java.util.prefs.Preferences.get(String,String)|Returns the value associated wi
31 |java.util.prefs.Preferences.getBoolean(String,boolean)|Returns the boolean val
32 |java.util.prefs.Preferences.getByteArray(String,byte[])|Returns the byte array
33 |java.util.prefs.Preferences.getDouble(String,double)|Returns the double value
34 |java.util.prefs.Preferences.getFloat(String,float)|Returns the float value rep
35 |java.util.prefs.Preferences.getInt(String,int)|Returns the int value represent
36 |java.util.prefs.Preferences.getLong(String,long)|Returns the long value repres
37 |java.util.prefs.Preferences.importPreferences(InputStream)|Imports all of the
38 |java.util.prefs.Preferences.isUserNode()|Returns true if this preference node
39 |java.util.prefs.Preferences.keys()|Returns all of the keys that have an associ
40 |java.util.prefs.Preferences.name()|Returns this preference node's name, relati
41 |java.util.prefs.Preferences.node(String)|Returns the named preference node in
42 |java.util.prefs.Preferences.nodeExists(String)|Returns true if the named prefe
43 |java.util.prefs.Preferences.parent()|Returns the parent of this preference nod
44 |java.util.prefs.Preferences.put(String,String)|Associates the specified value
45 |java.util.prefs.Preferences.putBoolean(String,boolean)|Associates a string rep
46 |java.util.prefs.Preferences.putByteArray(String,byte[])|Associates a string re
47 |java.util.prefs.Preferences.putDouble(String,double)|Associates a string repre
48 |java.util.prefs.Preferences.putFloat(String,float)|Associates a string represe
49 |java.util.prefs.Preferences.putInt(String,int)|Associates a string representin
50 |java.util.prefs.Preferences.putLong(String,long)|Associates a string represent
51 |java.util.prefs.Preferences.remove(String)|Removes the value associated with t
52 |java.util.prefs.Preferences.removeNode()|Removes this preference node and all
53 |java.util.prefs.Preferences.removeNodeChangeListener(NodeChangeListener)|Remov
54 |java.util.prefs.Preferences.removePreferenceChangeListener(PreferenceChangeListener)|
55 |java.util.prefs.Preferences.sync()|Ensures that future reads from this prefere
56 |java.util.prefs.Preferences.systemNodeForPackage(Class)|Returns the preference
57 |java.util.prefs.Preferences.systemRoot()|Returns the root preference node for
58 |java.util.prefs.Preferences.toString()|Returns a string representation of this
59 |java.util.prefs.Preferences.userNodeForPackage(Class)|Returns the preference n
60 |java.util.prefs.Preferences.userRoot()|Returns the root preference node for th
62 *java.util.prefs.Preferences_Description*
64 A node in a hierarchical collection of preference data. This class allows
65 applications to store and retrieve user and system preference and configuration
66 data. This data is stored persistently in an implementation-dependent backing
67 store. Typical implementations include flat files, OS-specific registries,
68 directory servers and SQL databases. The user of this class needn't be
69 concerned with details of the backing store.
71 There are two separate trees of preference nodes, one for user preferences and
72 one for system preferences. Each user has a separate user preference tree, and
73 all users in a given system share the same system preference tree. The precise
74 description of "user" and "system" will vary from implementation to
75 implementation. Typical information stored in the user preference tree might
76 include font choice, color choice, or preferred window location and size for a
77 particular application. Typical information stored in the system preference
78 tree might include installation configuration data for an application.
80 Nodes in a preference tree are named in a similar fashion to directories in a
81 hierarchical file system. Every node in a preference tree has a node name
82 (which is not necessarily unique), a unique absolute path name, and a path name
83 relative to each ancestor including itself.
85 The root node has a node name of the empty string (""). Every other node has an
86 arbitrary node name, specified at the time it is created. The only restrictions
87 on this name are that it cannot be the empty string, and it cannot contain the
88 slash character ('/').
90 The root node has an absolute path name of "/". Children of the root node have
91 absolute path names of "/" + <node name>. All other nodes have absolute path
92 names of <parent's absolute path name> + "/" + <node name>. Note that all
93 absolute path names begin with the slash character.
95 A node n's path name relative to its ancestor a is simply the string that must
96 be appended to a's absolute path name in order to form n's absolute path name,
97 with the initial slash character (if present) removed. Note that:
99 No relative path names begin with the slash character. Every node's path name
100 relative to itself is the empty string. Every node's path name relative to its
101 parent is its node name (except for the root node, which does not have a
102 parent). Every node's path name relative to the root is its absolute path name
103 with the initial slash character removed.
107 No path name contains multiple consecutive slash characters. No path name with
108 the exception of the root's absolute path name ends in the slash character. Any
109 string that conforms to these two rules is a valid path name.
111 All of the methods that modify preferences data are permitted to operate
112 asynchronously; they may return immediately, and changes will eventually
113 propagate to the persistent backing store with an implementation-dependent
114 delay. The flush method may be used to synchronously force updates to the
115 backing store. Normal termination of the Java Virtual Machine will not result
116 in the loss of pending updates -- an explicit flush invocation is not required
117 upon termination to ensure that pending updates are made persistent.
119 All of the methods that read preferences from a Preferences object require the
120 invoker to provide a default value. The default value is returned if no value
121 has been previously set or if the backing store is unavailable. The intent is
122 to allow applications to operate, albeit with slightly degraded functionality,
123 even if the backing store becomes unavailable. Several methods, like flush,
124 have semantics that prevent them from operating if the backing store is
125 unavailable. Ordinary applications should have no need to invoke any of these
126 methods, which can be identified by the fact that they are declared to throw
127 (|java.util.prefs.BackingStoreException|) .
129 The methods in this class may be invoked concurrently by multiple threads in a
130 single JVM without the need for external synchronization, and the results will
131 be equivalent to some serial execution. If this class is used concurrently by
132 multiple JVMs that store their preference data in the same backing store, the
133 data store will not be corrupted, but no other guarantees are made concerning
134 the consistency of the preference data.
136 This class contains an export/import facility, allowing preferences to be
137 "exported" to an XML document, and XML documents representing preferences to be
138 "imported" back into the system. This facility may be used to back up all or
139 part of a preference tree, and subsequently restore from the backup.
141 The XML document has the following DOCTYPE declaration:
143 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
145 Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is not
146 accessed when exporting or importing preferences; it merely serves as a string
147 to uniquely identify the DTD, which is:
149 <?xml version="1.0" encoding="UTF-8"?>
151 <!-- DTD for a Preferences tree. -->
153 <!-- The preferences element is at the root of an XML document representing a
154 Preferences tree. --> <!ELEMENT preferences (root)>
156 <!-- The preferences element contains an optional version attribute, which
157 specifies version of DTD. --> <!ATTLIST preferences EXTERNAL_XML_VERSION CDATA
160 <!-- The root element has a map representing the root's preferences (if any),
161 and one node for each child of the root (if any). --> <!ELEMENT root (map,
164 <!-- Additionally, the root contains a type attribute, which specifies whether
165 it's the system or user root. --> <!ATTLIST root type (system|user) #REQUIRED >
167 <!-- Each node has a map representing its preferences (if any), and one node
168 for each child (if any). --> <!ELEMENT node (map, node*) >
170 <!-- Additionally, each node has a name attribute --> <!ATTLIST node name CDATA
173 <!-- A map represents the preferences stored at a node (if any). --> <!ELEMENT
176 <!-- An entry represents a single preference, which is simply a key-value pair.
177 --> <!ELEMENT entry EMPTY > <!ATTLIST entry key CDATA #REQUIRED value CDATA
180 Every Preferences implementation must have an associated
181 (|java.util.prefs.PreferencesFactory|) implementation. Every J2SE
182 implementation must provide some means of specifying which PreferencesFactory
183 implementation is used to generate the root preferences nodes. This allows the
184 administrator to replace the default preferences implementation with an
185 alternative implementation.
187 Implementation note: In Sun's JRE, the PreferencesFactory implementation is
192 If the system property java.util.prefs.PreferencesFactory is defined, then it
193 is taken to be the fully-qualified name of a class implementing the
194 PreferencesFactory interface. The class is loaded and instantiated; if this
195 process fails then an unspecified error is thrown.
197 If a PreferencesFactory implementation class file has been installed in a jar
198 file that is visible to the system class loader(|java.lang.ClassLoader|) , and
199 that jar file contains a provider-configuration file named
200 java.util.prefs.PreferencesFactory in the resource directory META-INF/services,
201 then the first class name specified in that file is taken. If more than one
202 such jar file is provided, the first one found will be used. The class is
203 loaded and instantiated; if this process fails then an unspecified error is
206 Finally, if neither the above-mentioned system property nor an extension jar
207 file is provided, then the system-wide default PreferencesFactory
208 implementation for the underlying platform is loaded and instantiated.
213 *int_java.util.prefs.Preferences.MAX_KEY_LENGTH*
215 A node in a hierarchical collection of preference data. This class allows
216 applications to store and retrieve user and system preference and configuration
217 data. This data is stored persistently in an implementation-dependent backing
218 store. Typical implementations include flat files, OS-specific registries,
219 directory servers and SQL databases. The user of this class needn't be
220 concerned with details of the backing store.
222 There are two separate trees of preference nodes, one for user preferences and
223 one for system preferences. Each user has a separate user preference tree, and
224 all users in a given system share the same system preference tree. The precise
225 description of "user" and "system" will vary from implementation to
226 implementation. Typical information stored in the user preference tree might
227 include font choice, color choice, or preferred window location and size for a
228 particular application. Typical information stored in the system preference
229 tree might include installation configuration data for an application.
231 Nodes in a preference tree are named in a similar fashion to directories in a
232 hierarchical file system. Every node in a preference tree has a node name
233 (which is not necessarily unique), a unique absolute path name, and a path name
234 relative to each ancestor including itself.
236 The root node has a node name of the empty string (""). Every other node has an
237 arbitrary node name, specified at the time it is created. The only restrictions
238 on this name are that it cannot be the empty string, and it cannot contain the
239 slash character ('/').
241 The root node has an absolute path name of "/". Children of the root node have
242 absolute path names of "/" + <node name>. All other nodes have absolute path
243 names of <parent's absolute path name> + "/" + <node name>. Note that all
244 absolute path names begin with the slash character.
246 A node n's path name relative to its ancestor a is simply the string that must
247 be appended to a's absolute path name in order to form n's absolute path name,
248 with the initial slash character (if present) removed. Note that:
250 No relative path names begin with the slash character. Every node's path name
251 relative to itself is the empty string. Every node's path name relative to its
252 parent is its node name (except for the root node, which does not have a
253 parent). Every node's path name relative to the root is its absolute path name
254 with the initial slash character removed.
258 No path name contains multiple consecutive slash characters. No path name with
259 the exception of the root's absolute path name ends in the slash character. Any
260 string that conforms to these two rules is a valid path name.
262 All of the methods that modify preferences data are permitted to operate
263 asynchronously; they may return immediately, and changes will eventually
264 propagate to the persistent backing store with an implementation-dependent
265 delay. The flush method may be used to synchronously force updates to the
266 backing store. Normal termination of the Java Virtual Machine will not result
267 in the loss of pending updates -- an explicit flush invocation is not required
268 upon termination to ensure that pending updates are made persistent.
270 All of the methods that read preferences from a Preferences object require the
271 invoker to provide a default value. The default value is returned if no value
272 has been previously set or if the backing store is unavailable. The intent is
273 to allow applications to operate, albeit with slightly degraded functionality,
274 even if the backing store becomes unavailable. Several methods, like flush,
275 have semantics that prevent them from operating if the backing store is
276 unavailable. Ordinary applications should have no need to invoke any of these
277 methods, which can be identified by the fact that they are declared to throw
278 (|java.util.prefs.BackingStoreException|) .
280 The methods in this class may be invoked concurrently by multiple threads in a
281 single JVM without the need for external synchronization, and the results will
282 be equivalent to some serial execution. If this class is used concurrently by
283 multiple JVMs that store their preference data in the same backing store, the
284 data store will not be corrupted, but no other guarantees are made concerning
285 the consistency of the preference data.
287 This class contains an export/import facility, allowing preferences to be
288 "exported" to an XML document, and XML documents representing preferences to be
289 "imported" back into the system. This facility may be used to back up all or
290 part of a preference tree, and subsequently restore from the backup.
292 The XML document has the following DOCTYPE declaration:
294 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
296 Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is not
297 accessed when exporting or importing preferences; it merely serves as a string
298 to uniquely identify the DTD, which is:
300 <?xml version="1.0" encoding="UTF-8"?>
302 <!-- DTD for a Preferences tree. -->
304 <!-- The preferences element is at the root of an XML document representing a
305 Preferences tree. --> <!ELEMENT preferences (root)>
307 <!-- The preferences element contains an optional version attribute, which
308 specifies version of DTD. --> <!ATTLIST preferences EXTERNAL_XML_VERSION CDATA
311 <!-- The root element has a map representing the root's preferences (if any),
312 and one node for each child of the root (if any). --> <!ELEMENT root (map,
315 <!-- Additionally, the root contains a type attribute, which specifies whether
316 it's the system or user root. --> <!ATTLIST root type (system|user) #REQUIRED >
318 <!-- Each node has a map representing its preferences (if any), and one node
319 for each child (if any). --> <!ELEMENT node (map, node*) >
321 <!-- Additionally, each node has a name attribute --> <!ATTLIST node name CDATA
324 <!-- A map represents the preferences stored at a node (if any). --> <!ELEMENT
327 <!-- An entry represents a single preference, which is simply a key-value pair.
328 --> <!ELEMENT entry EMPTY > <!ATTLIST entry key CDATA #REQUIRED value CDATA
331 Every Preferences implementation must have an associated
332 (|java.util.prefs.PreferencesFactory|) implementation. Every J2SE
333 implementation must provide some means of specifying which PreferencesFactory
334 implementation is used to generate the root preferences nodes. This allows the
335 administrator to replace the default preferences implementation with an
336 alternative implementation.
338 Implementation note: In Sun's JRE, the PreferencesFactory implementation is
343 If the system property java.util.prefs.PreferencesFactory is defined, then it
344 is taken to be the fully-qualified name of a class implementing the
345 PreferencesFactory interface. The class is loaded and instantiated; if this
346 process fails then an unspecified error is thrown.
348 If a PreferencesFactory implementation class file has been installed in a jar
349 file that is visible to the system class loader(|java.lang.ClassLoader|) , and
350 that jar file contains a provider-configuration file named
351 java.util.prefs.PreferencesFactory in the resource directory META-INF/services,
352 then the first class name specified in that file is taken. If more than one
353 such jar file is provided, the first one found will be used. The class is
354 loaded and instantiated; if this process fails then an unspecified error is
357 Finally, if neither the above-mentioned system property nor an extension jar
358 file is provided, then the system-wide default PreferencesFactory
359 implementation for the underlying platform is loaded and instantiated.
364 *int_java.util.prefs.Preferences.MAX_NAME_LENGTH*
366 A node in a hierarchical collection of preference data. This class allows
367 applications to store and retrieve user and system preference and configuration
368 data. This data is stored persistently in an implementation-dependent backing
369 store. Typical implementations include flat files, OS-specific registries,
370 directory servers and SQL databases. The user of this class needn't be
371 concerned with details of the backing store.
373 There are two separate trees of preference nodes, one for user preferences and
374 one for system preferences. Each user has a separate user preference tree, and
375 all users in a given system share the same system preference tree. The precise
376 description of "user" and "system" will vary from implementation to
377 implementation. Typical information stored in the user preference tree might
378 include font choice, color choice, or preferred window location and size for a
379 particular application. Typical information stored in the system preference
380 tree might include installation configuration data for an application.
382 Nodes in a preference tree are named in a similar fashion to directories in a
383 hierarchical file system. Every node in a preference tree has a node name
384 (which is not necessarily unique), a unique absolute path name, and a path name
385 relative to each ancestor including itself.
387 The root node has a node name of the empty string (""). Every other node has an
388 arbitrary node name, specified at the time it is created. The only restrictions
389 on this name are that it cannot be the empty string, and it cannot contain the
390 slash character ('/').
392 The root node has an absolute path name of "/". Children of the root node have
393 absolute path names of "/" + <node name>. All other nodes have absolute path
394 names of <parent's absolute path name> + "/" + <node name>. Note that all
395 absolute path names begin with the slash character.
397 A node n's path name relative to its ancestor a is simply the string that must
398 be appended to a's absolute path name in order to form n's absolute path name,
399 with the initial slash character (if present) removed. Note that:
401 No relative path names begin with the slash character. Every node's path name
402 relative to itself is the empty string. Every node's path name relative to its
403 parent is its node name (except for the root node, which does not have a
404 parent). Every node's path name relative to the root is its absolute path name
405 with the initial slash character removed.
409 No path name contains multiple consecutive slash characters. No path name with
410 the exception of the root's absolute path name ends in the slash character. Any
411 string that conforms to these two rules is a valid path name.
413 All of the methods that modify preferences data are permitted to operate
414 asynchronously; they may return immediately, and changes will eventually
415 propagate to the persistent backing store with an implementation-dependent
416 delay. The flush method may be used to synchronously force updates to the
417 backing store. Normal termination of the Java Virtual Machine will not result
418 in the loss of pending updates -- an explicit flush invocation is not required
419 upon termination to ensure that pending updates are made persistent.
421 All of the methods that read preferences from a Preferences object require the
422 invoker to provide a default value. The default value is returned if no value
423 has been previously set or if the backing store is unavailable. The intent is
424 to allow applications to operate, albeit with slightly degraded functionality,
425 even if the backing store becomes unavailable. Several methods, like flush,
426 have semantics that prevent them from operating if the backing store is
427 unavailable. Ordinary applications should have no need to invoke any of these
428 methods, which can be identified by the fact that they are declared to throw
429 (|java.util.prefs.BackingStoreException|) .
431 The methods in this class may be invoked concurrently by multiple threads in a
432 single JVM without the need for external synchronization, and the results will
433 be equivalent to some serial execution. If this class is used concurrently by
434 multiple JVMs that store their preference data in the same backing store, the
435 data store will not be corrupted, but no other guarantees are made concerning
436 the consistency of the preference data.
438 This class contains an export/import facility, allowing preferences to be
439 "exported" to an XML document, and XML documents representing preferences to be
440 "imported" back into the system. This facility may be used to back up all or
441 part of a preference tree, and subsequently restore from the backup.
443 The XML document has the following DOCTYPE declaration:
445 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
447 Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is not
448 accessed when exporting or importing preferences; it merely serves as a string
449 to uniquely identify the DTD, which is:
451 <?xml version="1.0" encoding="UTF-8"?>
453 <!-- DTD for a Preferences tree. -->
455 <!-- The preferences element is at the root of an XML document representing a
456 Preferences tree. --> <!ELEMENT preferences (root)>
458 <!-- The preferences element contains an optional version attribute, which
459 specifies version of DTD. --> <!ATTLIST preferences EXTERNAL_XML_VERSION CDATA
462 <!-- The root element has a map representing the root's preferences (if any),
463 and one node for each child of the root (if any). --> <!ELEMENT root (map,
466 <!-- Additionally, the root contains a type attribute, which specifies whether
467 it's the system or user root. --> <!ATTLIST root type (system|user) #REQUIRED >
469 <!-- Each node has a map representing its preferences (if any), and one node
470 for each child (if any). --> <!ELEMENT node (map, node*) >
472 <!-- Additionally, each node has a name attribute --> <!ATTLIST node name CDATA
475 <!-- A map represents the preferences stored at a node (if any). --> <!ELEMENT
478 <!-- An entry represents a single preference, which is simply a key-value pair.
479 --> <!ELEMENT entry EMPTY > <!ATTLIST entry key CDATA #REQUIRED value CDATA
482 Every Preferences implementation must have an associated
483 (|java.util.prefs.PreferencesFactory|) implementation. Every J2SE
484 implementation must provide some means of specifying which PreferencesFactory
485 implementation is used to generate the root preferences nodes. This allows the
486 administrator to replace the default preferences implementation with an
487 alternative implementation.
489 Implementation note: In Sun's JRE, the PreferencesFactory implementation is
494 If the system property java.util.prefs.PreferencesFactory is defined, then it
495 is taken to be the fully-qualified name of a class implementing the
496 PreferencesFactory interface. The class is loaded and instantiated; if this
497 process fails then an unspecified error is thrown.
499 If a PreferencesFactory implementation class file has been installed in a jar
500 file that is visible to the system class loader(|java.lang.ClassLoader|) , and
501 that jar file contains a provider-configuration file named
502 java.util.prefs.PreferencesFactory in the resource directory META-INF/services,
503 then the first class name specified in that file is taken. If more than one
504 such jar file is provided, the first one found will be used. The class is
505 loaded and instantiated; if this process fails then an unspecified error is
508 Finally, if neither the above-mentioned system property nor an extension jar
509 file is provided, then the system-wide default PreferencesFactory
510 implementation for the underlying platform is loaded and instantiated.
515 *int_java.util.prefs.Preferences.MAX_VALUE_LENGTH*
517 A node in a hierarchical collection of preference data. This class allows
518 applications to store and retrieve user and system preference and configuration
519 data. This data is stored persistently in an implementation-dependent backing
520 store. Typical implementations include flat files, OS-specific registries,
521 directory servers and SQL databases. The user of this class needn't be
522 concerned with details of the backing store.
524 There are two separate trees of preference nodes, one for user preferences and
525 one for system preferences. Each user has a separate user preference tree, and
526 all users in a given system share the same system preference tree. The precise
527 description of "user" and "system" will vary from implementation to
528 implementation. Typical information stored in the user preference tree might
529 include font choice, color choice, or preferred window location and size for a
530 particular application. Typical information stored in the system preference
531 tree might include installation configuration data for an application.
533 Nodes in a preference tree are named in a similar fashion to directories in a
534 hierarchical file system. Every node in a preference tree has a node name
535 (which is not necessarily unique), a unique absolute path name, and a path name
536 relative to each ancestor including itself.
538 The root node has a node name of the empty string (""). Every other node has an
539 arbitrary node name, specified at the time it is created. The only restrictions
540 on this name are that it cannot be the empty string, and it cannot contain the
541 slash character ('/').
543 The root node has an absolute path name of "/". Children of the root node have
544 absolute path names of "/" + <node name>. All other nodes have absolute path
545 names of <parent's absolute path name> + "/" + <node name>. Note that all
546 absolute path names begin with the slash character.
548 A node n's path name relative to its ancestor a is simply the string that must
549 be appended to a's absolute path name in order to form n's absolute path name,
550 with the initial slash character (if present) removed. Note that:
552 No relative path names begin with the slash character. Every node's path name
553 relative to itself is the empty string. Every node's path name relative to its
554 parent is its node name (except for the root node, which does not have a
555 parent). Every node's path name relative to the root is its absolute path name
556 with the initial slash character removed.
560 No path name contains multiple consecutive slash characters. No path name with
561 the exception of the root's absolute path name ends in the slash character. Any
562 string that conforms to these two rules is a valid path name.
564 All of the methods that modify preferences data are permitted to operate
565 asynchronously; they may return immediately, and changes will eventually
566 propagate to the persistent backing store with an implementation-dependent
567 delay. The flush method may be used to synchronously force updates to the
568 backing store. Normal termination of the Java Virtual Machine will not result
569 in the loss of pending updates -- an explicit flush invocation is not required
570 upon termination to ensure that pending updates are made persistent.
572 All of the methods that read preferences from a Preferences object require the
573 invoker to provide a default value. The default value is returned if no value
574 has been previously set or if the backing store is unavailable. The intent is
575 to allow applications to operate, albeit with slightly degraded functionality,
576 even if the backing store becomes unavailable. Several methods, like flush,
577 have semantics that prevent them from operating if the backing store is
578 unavailable. Ordinary applications should have no need to invoke any of these
579 methods, which can be identified by the fact that they are declared to throw
580 (|java.util.prefs.BackingStoreException|) .
582 The methods in this class may be invoked concurrently by multiple threads in a
583 single JVM without the need for external synchronization, and the results will
584 be equivalent to some serial execution. If this class is used concurrently by
585 multiple JVMs that store their preference data in the same backing store, the
586 data store will not be corrupted, but no other guarantees are made concerning
587 the consistency of the preference data.
589 This class contains an export/import facility, allowing preferences to be
590 "exported" to an XML document, and XML documents representing preferences to be
591 "imported" back into the system. This facility may be used to back up all or
592 part of a preference tree, and subsequently restore from the backup.
594 The XML document has the following DOCTYPE declaration:
596 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
598 Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is not
599 accessed when exporting or importing preferences; it merely serves as a string
600 to uniquely identify the DTD, which is:
602 <?xml version="1.0" encoding="UTF-8"?>
604 <!-- DTD for a Preferences tree. -->
606 <!-- The preferences element is at the root of an XML document representing a
607 Preferences tree. --> <!ELEMENT preferences (root)>
609 <!-- The preferences element contains an optional version attribute, which
610 specifies version of DTD. --> <!ATTLIST preferences EXTERNAL_XML_VERSION CDATA
613 <!-- The root element has a map representing the root's preferences (if any),
614 and one node for each child of the root (if any). --> <!ELEMENT root (map,
617 <!-- Additionally, the root contains a type attribute, which specifies whether
618 it's the system or user root. --> <!ATTLIST root type (system|user) #REQUIRED >
620 <!-- Each node has a map representing its preferences (if any), and one node
621 for each child (if any). --> <!ELEMENT node (map, node*) >
623 <!-- Additionally, each node has a name attribute --> <!ATTLIST node name CDATA
626 <!-- A map represents the preferences stored at a node (if any). --> <!ELEMENT
629 <!-- An entry represents a single preference, which is simply a key-value pair.
630 --> <!ELEMENT entry EMPTY > <!ATTLIST entry key CDATA #REQUIRED value CDATA
633 Every Preferences implementation must have an associated
634 (|java.util.prefs.PreferencesFactory|) implementation. Every J2SE
635 implementation must provide some means of specifying which PreferencesFactory
636 implementation is used to generate the root preferences nodes. This allows the
637 administrator to replace the default preferences implementation with an
638 alternative implementation.
640 Implementation note: In Sun's JRE, the PreferencesFactory implementation is
645 If the system property java.util.prefs.PreferencesFactory is defined, then it
646 is taken to be the fully-qualified name of a class implementing the
647 PreferencesFactory interface. The class is loaded and instantiated; if this
648 process fails then an unspecified error is thrown.
650 If a PreferencesFactory implementation class file has been installed in a jar
651 file that is visible to the system class loader(|java.lang.ClassLoader|) , and
652 that jar file contains a provider-configuration file named
653 java.util.prefs.PreferencesFactory in the resource directory META-INF/services,
654 then the first class name specified in that file is taken. If more than one
655 such jar file is provided, the first one found will be used. The class is
656 loaded and instantiated; if this process fails then an unspecified error is
659 Finally, if neither the above-mentioned system property nor an extension jar
660 file is provided, then the system-wide default PreferencesFactory
661 implementation for the underlying platform is loaded and instantiated.
667 *java.util.prefs.Preferences()*
669 protected Preferences()
671 Sole constructor. (For invocation by subclass constructors, typically
675 *java.util.prefs.Preferences.absolutePath()*
677 public abstract |java.lang.String| absolutePath()
679 Returns this preference node's absolute path name.
682 Returns: this preference node's absolute path name.
683 *java.util.prefs.Preferences.addNodeChangeListener(NodeChangeListener)*
685 public abstract void addNodeChangeListener(java.util.prefs.NodeChangeListener ncl)
687 Registers the specified listener to receive node change events for this node. A
688 node change event is generated when a child node is added to or removed from
689 this node. (A single (|java.util.prefs.Preferences|) invocation results in
690 multiple node change events, one for every node in the subtree rooted at the
693 Events are only guaranteed for changes made within the same JVM as the
694 registered listener, though some implementations may generate events for
695 changes made outside this JVM. Events may be generated before the changes have
696 become permanent. Events are not generated when indirect descendants of this
697 node are added or removed; a caller desiring such events must register with
700 Few guarantees can be made regarding node creation. Because nodes are created
701 implicitly upon access, it may not be feasible for an implementation to
702 determine whether a child node existed in the backing store prior to access
703 (for example, because the backing store is unreachable or cached information is
704 out of date). Under these circumstances, implementations are neither required
705 to generate node change events nor prohibited from doing so.
707 ncl - The NodeChangeListener to add.
709 *java.util.prefs.Preferences.addPreferenceChangeListener(PreferenceChangeListener)*
711 public abstract void addPreferenceChangeListener(java.util.prefs.PreferenceChangeListener pcl)
713 Registers the specified listener to receive preference change events for this
714 preference node. A preference change event is generated when a preference is
715 added to this node, removed from this node, or when the value associated with a
716 preference is changed. (Preference change events are not generated by the
717 (|java.util.prefs.Preferences|) method, which generates a node change event.
718 Preference change events are generated by the clear method.)
720 Events are only guaranteed for changes made within the same JVM as the
721 registered listener, though some implementations may generate events for
722 changes made outside this JVM. Events may be generated before the changes have
723 been made persistent. Events are not generated when preferences are modified in
724 descendants of this node; a caller desiring such events must register with each
727 pcl - The preference change listener to add.
729 *java.util.prefs.Preferences.childrenNames()*
731 public abstract |java.lang.String| childrenNames()
732 throws |java.util.prefs.BackingStoreException|
734 Returns the names of the children of this preference node, relative to this
735 node. (The returned array will be of size zero if this node has no children.)
738 Returns: the names of the children of this preference node.
739 *java.util.prefs.Preferences.clear()*
741 public abstract void clear()
742 throws |java.util.prefs.BackingStoreException|
744 Removes all of the preferences (key-value associations) in this preference
745 node. This call has no effect on any descendants of this node.
747 If this implementation supports stored defaults, and this node in the
748 preferences hierarchy contains any such defaults, the stored defaults will be
749 "exposed" by this call, in the sense that they will be returned by succeeding
753 *java.util.prefs.Preferences.exportNode(OutputStream)*
755 public abstract void exportNode(java.io.OutputStream os)
756 throws |java.util.prefs.BackingStoreException|
757 |java.io.IOException|
759 Emits on the specified output stream an XML document representing all of the
760 preferences contained in this node (but not its descendants). This XML document
761 is, in effect, an offline backup of the node.
763 The XML document will have the following DOCTYPE declaration:
765 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
767 The UTF-8 character encoding will be used.
769 This method is an exception to the general rule that the results of
770 concurrently executing multiple methods in this class yields results equivalent
771 to some serial execution. If the preferences at this node are modified
772 concurrently with an invocation of this method, the exported preferences
773 comprise a "fuzzy snapshot" of the preferences contained in the node; some of
774 the concurrent modifications may be reflected in the exported data while others
777 os - the output stream on which to emit the XML document.
779 *java.util.prefs.Preferences.exportSubtree(OutputStream)*
781 public abstract void exportSubtree(java.io.OutputStream os)
782 throws |java.util.prefs.BackingStoreException|
783 |java.io.IOException|
785 Emits an XML document representing all of the preferences contained in this
786 node and all of its descendants. This XML document is, in effect, an offline
787 backup of the subtree rooted at the node.
789 The XML document will have the following DOCTYPE declaration:
791 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
793 The UTF-8 character encoding will be used.
795 This method is an exception to the general rule that the results of
796 concurrently executing multiple methods in this class yields results equivalent
797 to some serial execution. If the preferences or nodes in the subtree rooted at
798 this node are modified concurrently with an invocation of this method, the
799 exported preferences comprise a "fuzzy snapshot" of the subtree; some of the
800 concurrent modifications may be reflected in the exported data while others may
803 os - the output stream on which to emit the XML document.
805 *java.util.prefs.Preferences.flush()*
807 public abstract void flush()
808 throws |java.util.prefs.BackingStoreException|
810 Forces any changes in the contents of this preference node and its descendants
811 to the persistent store. Once this method returns successfully, it is safe to
812 assume that all changes made in the subtree rooted at this node prior to the
813 method invocation have become permanent.
815 Implementations are free to flush changes into the persistent store at any
816 time. They do not need to wait for this method to be called.
818 When a flush occurs on a newly created node, it is made persistent, as are any
819 ancestors (and descendants) that have yet to be made persistent. Note however
820 that any preference value changes in ancestors are not guaranteed to be made
823 If this method is invoked on a node that has been removed with the
824 (|java.util.prefs.Preferences|) method, flushSpi() is invoked on this node, but
828 *java.util.prefs.Preferences.get(String,String)*
830 public abstract |java.lang.String| get(
831 java.lang.String key,
832 java.lang.String def)
834 Returns the value associated with the specified key in this preference node.
835 Returns the specified default if there is no value associated with the key, or
836 the backing store is inaccessible.
838 Some implementations may store default values in their backing stores. If there
839 is no value associated with the specified key but there is such a stored
840 default, it is returned in preference to the specified default.
842 key - key whose associated value is to be returned.
843 def - the value to be returned in the event that this preference node has no value
846 Returns: the value associated with key, or def if no value is associated with key, or
847 the backing store is inaccessible.
848 *java.util.prefs.Preferences.getBoolean(String,boolean)*
850 public abstract boolean getBoolean(
851 java.lang.String key,
854 Returns the boolean value represented by the string associated with the
855 specified key in this preference node. Valid strings are "true", which
856 represents true, and "false", which represents false. Case is ignored, so, for
857 example, "TRUE" and "False" are also valid. This method is intended for use in
858 conjunction with (|java.util.prefs.Preferences|) .
860 Returns the specified default if there is no value associated with the key, the
861 backing store is inaccessible, or if the associated value is something other
862 than "true" or "false", ignoring case.
864 If the implementation supports stored defaults and such a default exists and is
865 accessible, it is used in preference to the specified default, unless the
866 stored default is something other than "true" or "false", ignoring case, in
867 which case the specified default is used.
869 key - key whose associated value is to be returned as a boolean.
870 def - the value to be returned in the event that this preference node has no value
871 associated with key or the associated value cannot be interpreted as a
872 boolean, or the backing store is inaccessible.
874 Returns: the boolean value represented by the string associated with key in this
875 preference node, or def if the associated value does not exist or
876 cannot be interpreted as a boolean.
877 *java.util.prefs.Preferences.getByteArray(String,byte[])*
879 public abstract byte getByteArray(
880 java.lang.String key,
883 Returns the byte array value represented by the string associated with the
884 specified key in this preference node. Valid strings are Base64 encoded binary
885 data, as defined in RFC 2045, Section 6.8, with one minor change: the string
886 must consist solely of characters from the Base64 Alphabet; no newline
887 characters or extraneous characters are permitted. This method is intended for
888 use in conjunction with (|java.util.prefs.Preferences|) .
890 Returns the specified default if there is no value associated with the key, the
891 backing store is inaccessible, or if the associated value is not a valid Base64
892 encoded byte array (as defined above).
894 If the implementation supports stored defaults and such a default exists and is
895 accessible, it is used in preference to the specified default, unless the
896 stored default is not a valid Base64 encoded byte array (as defined above), in
897 which case the specified default is used.
899 key - key whose associated value is to be returned as a byte array.
900 def - the value to be returned in the event that this preference node has no value
901 associated with key or the associated value cannot be interpreted as a
902 byte array, or the backing store is inaccessible.
904 Returns: the byte array value represented by the string associated with key in this
905 preference node, or def if the associated value does not exist or
906 cannot be interpreted as a byte array.
907 *java.util.prefs.Preferences.getDouble(String,double)*
909 public abstract double getDouble(
910 java.lang.String key,
913 Returns the double value represented by the string associated with the
914 specified key in this preference node. The string is converted to an integer as
915 by (|java.lang.Double|) . Returns the specified default if there is no value
916 associated with the key, the backing store is inaccessible, or if
917 Double.parseDouble(String) would throw a (|java.lang.NumberFormatException|) if
918 the associated value were passed. This method is intended for use in
919 conjunction with (|java.util.prefs.Preferences|) .
921 If the implementation supports stored defaults and such a default exists, is
922 accessible, and could be converted to a double with Double.parseDouble, this
923 double is returned in preference to the specified default.
925 key - key whose associated value is to be returned as a double.
926 def - the value to be returned in the event that this preference node has no value
927 associated with key or the associated value cannot be interpreted as a
928 double, or the backing store is inaccessible.
930 Returns: the double value represented by the string associated with key in this
931 preference node, or def if the associated value does not exist or
932 cannot be interpreted as a double.
933 *java.util.prefs.Preferences.getFloat(String,float)*
935 public abstract float getFloat(
936 java.lang.String key,
939 Returns the float value represented by the string associated with the specified
940 key in this preference node. The string is converted to an integer as by
941 (|java.lang.Float|) . Returns the specified default if there is no value
942 associated with the key, the backing store is inaccessible, or if
943 Float.parseFloat(String) would throw a (|java.lang.NumberFormatException|) if
944 the associated value were passed. This method is intended for use in
945 conjunction with (|java.util.prefs.Preferences|) .
947 If the implementation supports stored defaults and such a default exists, is
948 accessible, and could be converted to a float with Float.parseFloat, this float
949 is returned in preference to the specified default.
951 key - key whose associated value is to be returned as a float.
952 def - the value to be returned in the event that this preference node has no value
953 associated with key or the associated value cannot be interpreted as a
954 float, or the backing store is inaccessible.
956 Returns: the float value represented by the string associated with key in this
957 preference node, or def if the associated value does not exist or
958 cannot be interpreted as a float.
959 *java.util.prefs.Preferences.getInt(String,int)*
961 public abstract int getInt(
962 java.lang.String key,
965 Returns the int value represented by the string associated with the specified
966 key in this preference node. The string is converted to an integer as by
967 (|java.lang.Integer|) . Returns the specified default if there is no value
968 associated with the key, the backing store is inaccessible, or if
969 Integer.parseInt(String) would throw a (|java.lang.NumberFormatException|) if
970 the associated value were passed. This method is intended for use in
971 conjunction with (|java.util.prefs.Preferences|) .
973 If the implementation supports stored defaults and such a default exists, is
974 accessible, and could be converted to an int with Integer.parseInt, this int is
975 returned in preference to the specified default.
977 key - key whose associated value is to be returned as an int.
978 def - the value to be returned in the event that this preference node has no value
979 associated with key or the associated value cannot be interpreted as an
980 int, or the backing store is inaccessible.
982 Returns: the int value represented by the string associated with key in this preference
983 node, or def if the associated value does not exist or cannot be
984 interpreted as an int.
985 *java.util.prefs.Preferences.getLong(String,long)*
987 public abstract long getLong(
988 java.lang.String key,
991 Returns the long value represented by the string associated with the specified
992 key in this preference node. The string is converted to a long as by
993 (|java.lang.Long|) . Returns the specified default if there is no value
994 associated with the key, the backing store is inaccessible, or if
995 Long.parseLong(String) would throw a (|java.lang.NumberFormatException|) if the
996 associated value were passed. This method is intended for use in conjunction
997 with (|java.util.prefs.Preferences|) .
999 If the implementation supports stored defaults and such a default exists, is
1000 accessible, and could be converted to a long with Long.parseLong, this long is
1001 returned in preference to the specified default.
1003 key - key whose associated value is to be returned as a long.
1004 def - the value to be returned in the event that this preference node has no value
1005 associated with key or the associated value cannot be interpreted as a
1006 long, or the backing store is inaccessible.
1008 Returns: the long value represented by the string associated with key in this preference
1009 node, or def if the associated value does not exist or cannot be
1010 interpreted as a long.
1011 *java.util.prefs.Preferences.importPreferences(InputStream)*
1013 public static void importPreferences(java.io.InputStream is)
1014 throws |java.util.prefs.InvalidPreferencesFormatException|
1015 |java.io.IOException|
1017 Imports all of the preferences represented by the XML document on the specified
1018 input stream. The document may represent user preferences or system
1019 preferences. If it represents user preferences, the preferences will be
1020 imported into the calling user's preference tree (even if they originally came
1021 from a different user's preference tree). If any of the preferences described
1022 by the document inhabit preference nodes that do not exist, the nodes will be
1025 The XML document must have the following DOCTYPE declaration:
1027 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
1029 (This method is designed for use in conjunction with
1030 (|java.util.prefs.Preferences|) and (|java.util.prefs.Preferences|) .
1032 This method is an exception to the general rule that the results of
1033 concurrently executing multiple methods in this class yields results equivalent
1034 to some serial execution. The method behaves as if implemented on top of the
1035 other public methods in this class, notably (|java.util.prefs.Preferences|) and
1036 (|java.util.prefs.Preferences|) .
1038 is - the input stream from which to read the XML document.
1040 *java.util.prefs.Preferences.isUserNode()*
1042 public abstract boolean isUserNode()
1044 Returns true if this preference node is in the user preference tree, false if
1045 it's in the system preference tree.
1048 Returns: true if this preference node is in the user preference tree, false if it's in
1049 the system preference tree.
1050 *java.util.prefs.Preferences.keys()*
1052 public abstract |java.lang.String| keys()
1053 throws |java.util.prefs.BackingStoreException|
1055 Returns all of the keys that have an associated value in this preference node.
1056 (The returned array will be of size zero if this node has no preferences.)
1058 If the implementation supports stored defaults and there are any such defaults
1059 at this node that have not been overridden, by explicit preferences, the
1060 defaults are returned in the array in addition to any explicit preferences.
1063 Returns: an array of the keys that have an associated value in this preference node.
1064 *java.util.prefs.Preferences.name()*
1066 public abstract |java.lang.String| name()
1068 Returns this preference node's name, relative to its parent.
1071 Returns: this preference node's name, relative to its parent.
1072 *java.util.prefs.Preferences.node(String)*
1074 public abstract |java.util.prefs.Preferences| node(java.lang.String pathName)
1076 Returns the named preference node in the same tree as this node, creating it
1077 and any of its ancestors if they do not already exist. Accepts a relative or
1078 absolute path name. Relative path names (which do not begin with the slash
1079 character ('/')) are interpreted relative to this preference node.
1081 If the returned node did not exist prior to this call, this node and any
1082 ancestors that were created by this call are not guaranteed to become permanent
1083 until the flush method is called on the returned node (or one of its ancestors
1086 pathName - the path name of the preference node to return.
1088 Returns: the specified preference node.
1089 *java.util.prefs.Preferences.nodeExists(String)*
1091 public abstract boolean nodeExists(java.lang.String pathName)
1092 throws |java.util.prefs.BackingStoreException|
1094 Returns true if the named preference node exists in the same tree as this node.
1095 Relative path names (which do not begin with the slash character ('/')) are
1096 interpreted relative to this preference node.
1098 If this node (or an ancestor) has already been removed with the
1099 (|java.util.prefs.Preferences|) method, it is legal to invoke this method, but
1100 only with the path name ""; the invocation will return false. Thus, the idiom
1101 p.nodeExists("") may be used to test whether p has been removed.
1103 pathName - the path name of the node whose existence is to be checked.
1105 Returns: true if the specified node exists.
1106 *java.util.prefs.Preferences.parent()*
1108 public abstract |java.util.prefs.Preferences| parent()
1110 Returns the parent of this preference node, or null if this is the root.
1113 Returns: the parent of this preference node.
1114 *java.util.prefs.Preferences.put(String,String)*
1116 public abstract void put(
1117 java.lang.String key,
1118 java.lang.String value)
1120 Associates the specified value with the specified key in this preference node.
1122 key - key with which the specified value is to be associated.
1123 value - value to be associated with the specified key.
1125 *java.util.prefs.Preferences.putBoolean(String,boolean)*
1127 public abstract void putBoolean(
1128 java.lang.String key,
1131 Associates a string representing the specified boolean value with the specified
1132 key in this preference node. The associated string is "true" if the value is
1133 true, and "false" if it is false. This method is intended for use in
1134 conjunction with (|java.util.prefs.Preferences|) .
1136 key - key with which the string form of value is to be associated.
1137 value - value whose string form is to be associated with key.
1139 *java.util.prefs.Preferences.putByteArray(String,byte[])*
1141 public abstract void putByteArray(
1142 java.lang.String key,
1145 Associates a string representing the specified byte array with the specified
1146 key in this preference node. The associated string is the Base64 encoding of
1147 the byte array, as defined in RFC 2045, Section 6.8, with one minor change: the
1148 string will consist solely of characters from the Base64 Alphabet; it will not
1149 contain any newline characters. Note that the maximum length of the byte array
1150 is limited to three quarters of MAX_VALUE_LENGTH so that the length of the
1151 Base64 encoded String does not exceed MAX_VALUE_LENGTH. This method is intended
1152 for use in conjunction with (|java.util.prefs.Preferences|) .
1154 key - key with which the string form of value is to be associated.
1155 value - value whose string form is to be associated with key.
1157 *java.util.prefs.Preferences.putDouble(String,double)*
1159 public abstract void putDouble(
1160 java.lang.String key,
1163 Associates a string representing the specified double value with the specified
1164 key in this preference node. The associated string is the one that would be
1165 returned if the double value were passed to (|java.lang.Double|) . This method
1166 is intended for use in conjunction with (|java.util.prefs.Preferences|) .
1168 key - key with which the string form of value is to be associated.
1169 value - value whose string form is to be associated with key.
1171 *java.util.prefs.Preferences.putFloat(String,float)*
1173 public abstract void putFloat(
1174 java.lang.String key,
1177 Associates a string representing the specified float value with the specified
1178 key in this preference node. The associated string is the one that would be
1179 returned if the float value were passed to (|java.lang.Float|) . This method is
1180 intended for use in conjunction with (|java.util.prefs.Preferences|) .
1182 key - key with which the string form of value is to be associated.
1183 value - value whose string form is to be associated with key.
1185 *java.util.prefs.Preferences.putInt(String,int)*
1187 public abstract void putInt(
1188 java.lang.String key,
1191 Associates a string representing the specified int value with the specified key
1192 in this preference node. The associated string is the one that would be
1193 returned if the int value were passed to (|java.lang.Integer|) . This method is
1194 intended for use in conjunction with (|java.util.prefs.Preferences|) .
1196 key - key with which the string form of value is to be associated.
1197 value - value whose string form is to be associated with key.
1199 *java.util.prefs.Preferences.putLong(String,long)*
1201 public abstract void putLong(
1202 java.lang.String key,
1205 Associates a string representing the specified long value with the specified
1206 key in this preference node. The associated string is the one that would be
1207 returned if the long value were passed to (|java.lang.Long|) . This method is
1208 intended for use in conjunction with (|java.util.prefs.Preferences|) .
1210 key - key with which the string form of value is to be associated.
1211 value - value whose string form is to be associated with key.
1213 *java.util.prefs.Preferences.remove(String)*
1215 public abstract void remove(java.lang.String key)
1217 Removes the value associated with the specified key in this preference node, if
1220 If this implementation supports stored defaults, and there is such a default
1221 for the specified preference, the stored default will be "exposed" by this
1222 call, in the sense that it will be returned by a succeeding call to get.
1224 key - key whose mapping is to be removed from the preference node.
1226 *java.util.prefs.Preferences.removeNode()*
1228 public abstract void removeNode()
1229 throws |java.util.prefs.BackingStoreException|
1231 Removes this preference node and all of its descendants, invalidating any
1232 preferences contained in the removed nodes. Once a node has been removed,
1233 attempting any method other than (|java.util.prefs.Preferences|) ,
1234 (|java.util.prefs.Preferences|) , (|java.util.prefs.Preferences|) ,
1235 (|java.util.prefs.Preferences|) or
1236 nodeExists("")(|java.util.prefs.Preferences|) on the corresponding Preferences
1237 instance will fail with an IllegalStateException. (The methods defined on
1238 (|java.lang.Object|) can still be invoked on a node after it has been removed;
1239 they will not throw IllegalStateException.)
1241 The removal is not guaranteed to be persistent until the flush method is called
1242 on this node (or an ancestor).
1244 If this implementation supports stored defaults, removing a node exposes any
1245 stored defaults at or below this node. Thus, a subsequent call to nodeExists on
1246 this node's path name may return true, and a subsequent call to node on this
1247 path name may return a (different) Preferences instance representing a
1248 non-empty collection of preferences and/or children.
1251 *java.util.prefs.Preferences.removeNodeChangeListener(NodeChangeListener)*
1253 public abstract void removeNodeChangeListener(java.util.prefs.NodeChangeListener ncl)
1255 Removes the specified NodeChangeListener, so it no longer receives change
1258 ncl - The NodeChangeListener to remove.
1260 *java.util.prefs.Preferences.removePreferenceChangeListener(PreferenceChangeListener)*
1262 public abstract void removePreferenceChangeListener(java.util.prefs.PreferenceChangeListener pcl)
1264 Removes the specified preference change listener, so it no longer receives
1265 preference change events.
1267 pcl - The preference change listener to remove.
1269 *java.util.prefs.Preferences.sync()*
1271 public abstract void sync()
1272 throws |java.util.prefs.BackingStoreException|
1274 Ensures that future reads from this preference node and its descendants reflect
1275 any changes that were committed to the persistent store (from any VM) prior to
1276 the sync invocation. As a side-effect, forces any changes in the contents of
1277 this preference node and its descendants to the persistent store, as if the
1278 flush method had been invoked on this node.
1281 *java.util.prefs.Preferences.systemNodeForPackage(Class)*
1283 public static |java.util.prefs.Preferences| systemNodeForPackage(java.lang.Class c)
1285 Returns the preference node from the system preference tree that is associated
1286 (by convention) with the specified class's package. The convention is as
1287 follows: the absolute path name of the node is the fully qualified package
1288 name, preceded by a slash ('/'), and with each period ('.') replaced by a
1289 slash. For example the absolute path name of the node associated with the class
1290 com.acme.widget is /com/acme/widget.
1292 This convention does not apply to the unnamed package, whose associated
1293 preference node is <unnamed>. This node is not intended for long term use, but
1294 for convenience in the early development of programs that do not yet belong to
1295 a package, and for "throwaway" programs. Valuable data should not be stored at
1296 this node as it is shared by all programs that use it.
1298 A class Foo wishing to access preferences pertaining to its package can obtain
1299 a preference node as follows:
1301 static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);
1303 This idiom obviates the need for using a string to describe the preferences
1304 node and decreases the likelihood of a run-time failure. (If the class name is
1305 misspelled, it will typically result in a compile-time error.)
1307 Invoking this method will result in the creation of the returned node and its
1308 ancestors if they do not already exist. If the returned node did not exist
1309 prior to this call, this node and any ancestors that were created by this call
1310 are not guaranteed to become permanent until the flush method is called on the
1311 returned node (or one of its ancestors or descendants).
1313 c - the class for whose package a system preference node is desired.
1315 Returns: the system preference node associated with the package of which c is a member.
1316 *java.util.prefs.Preferences.systemRoot()*
1318 public static |java.util.prefs.Preferences| systemRoot()
1320 Returns the root preference node for the system.
1323 Returns: the root preference node for the system.
1324 *java.util.prefs.Preferences.toString()*
1326 public abstract |java.lang.String| toString()
1328 Returns a string representation of this preferences node, as if computed by the
1329 expression:(this.isUserNode() ? "User" : "System") + " Preference Node: " +
1330 this.absolutePath().
1333 *java.util.prefs.Preferences.userNodeForPackage(Class)*
1335 public static |java.util.prefs.Preferences| userNodeForPackage(java.lang.Class c)
1337 Returns the preference node from the calling user's preference tree that is
1338 associated (by convention) with the specified class's package. The convention
1339 is as follows: the absolute path name of the node is the fully qualified
1340 package name, preceded by a slash ('/'), and with each period ('.') replaced by
1341 a slash. For example the absolute path name of the node associated with the
1342 class com.acme.widget is /com/acme/widget.
1344 This convention does not apply to the unnamed package, whose associated
1345 preference node is <unnamed>. This node is not intended for long term use, but
1346 for convenience in the early development of programs that do not yet belong to
1347 a package, and for "throwaway" programs. Valuable data should not be stored at
1348 this node as it is shared by all programs that use it.
1350 A class Foo wishing to access preferences pertaining to its package can obtain
1351 a preference node as follows:
1353 static Preferences prefs = Preferences.userNodeForPackage(Foo.class);
1355 This idiom obviates the need for using a string to describe the preferences
1356 node and decreases the likelihood of a run-time failure. (If the class name is
1357 misspelled, it will typically result in a compile-time error.)
1359 Invoking this method will result in the creation of the returned node and its
1360 ancestors if they do not already exist. If the returned node did not exist
1361 prior to this call, this node and any ancestors that were created by this call
1362 are not guaranteed to become permanent until the flush method is called on the
1363 returned node (or one of its ancestors or descendants).
1365 c - the class for whose package a user preference node is desired.
1367 Returns: the user preference node associated with the package of which c is a member.
1368 *java.util.prefs.Preferences.userRoot()*
1370 public static |java.util.prefs.Preferences| userRoot()
1372 Returns the root preference node for the calling user.
1375 Returns: the root preference node for the calling user.