Merge git+ssh://davetron5000@repo.or.cz/srv/git/vimdoclet
[vimdoclet.git] / sample / java.util.prefs.Preferences.txt
blob99c62718868f4fe0de55ffb64fdf1131cfde6493
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. 
105 Note finally that: 
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 
158 "0.0" 
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, 
162 node*) > 
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 
171 #REQUIRED > 
173 <!-- A map represents the preferences stored at a node (if any). --> <!ELEMENT 
174 map (entry*) > 
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 
178 #REQUIRED > 
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 
188 located as follows: 
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 
204 thrown. 
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. 
256 Note finally that: 
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 
309 "0.0" 
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, 
313 node*) > 
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 
322 #REQUIRED > 
324 <!-- A map represents the preferences stored at a node (if any). --> <!ELEMENT 
325 map (entry*) > 
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 
329 #REQUIRED > 
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 
339 located as follows: 
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 
355 thrown. 
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. 
407 Note finally that: 
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 
460 "0.0" 
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, 
464 node*) > 
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 
473 #REQUIRED > 
475 <!-- A map represents the preferences stored at a node (if any). --> <!ELEMENT 
476 map (entry*) > 
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 
480 #REQUIRED > 
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 
490 located as follows: 
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 
506 thrown. 
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. 
558 Note finally that: 
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 
611 "0.0" 
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, 
615 node*) > 
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 
624 #REQUIRED > 
626 <!-- A map represents the preferences stored at a node (if any). --> <!ELEMENT 
627 map (entry*) > 
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 
631 #REQUIRED > 
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 
641 located as follows: 
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 
657 thrown. 
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 
672 implicit.) 
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 
691 removed node.) 
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 
698 each descendant. 
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 
725 descendant. 
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|
733          
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|
743          
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 
750 calls to get. 
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|
758          
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 
775 may not. 
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|
784          
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 
801 not. 
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|
809          
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 
821 persistent. 
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 
825 not on others. 
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 
844        associated with key. 
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,
852   boolean def)
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,
881   byte[] def)
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,
911   double def)
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,
937   float def)
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,
963   int def)
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,
989   long def)
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|
1016          
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 
1023 created. 
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|
1054          
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 
1084 or descendants). 
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|
1093          
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,
1129   boolean value)
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,
1143   byte[] value)
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,
1161   double value)
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,
1175   float value)
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,
1189   int value)
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,
1203   long value)
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 
1218 any. 
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|
1230          
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 
1256 events. 
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|
1273          
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.