1 *java.util.prefs.AbstractPreferences* *AbstractPreferences* This class provides
3 public abstract class AbstractPreferences
4 extends |java.util.prefs.Preferences|
6 |java.util.prefs.AbstractPreferences_Description|
7 |java.util.prefs.AbstractPreferences_Fields|
8 |java.util.prefs.AbstractPreferences_Constructors|
9 |java.util.prefs.AbstractPreferences_Methods|
11 ================================================================================
13 *java.util.prefs.AbstractPreferences_Fields*
14 |java.lang.Object_java.util.prefs.AbstractPreferences.lock|
15 |boolean_java.util.prefs.AbstractPreferences.newNode|
17 *java.util.prefs.AbstractPreferences_Constructors*
18 |java.util.prefs.AbstractPreferences(AbstractPreferences,String)|Creates a pref
20 *java.util.prefs.AbstractPreferences_Methods*
21 |java.util.prefs.AbstractPreferences.absolutePath()|Implements the absolutePath
22 |java.util.prefs.AbstractPreferences.addNodeChangeListener(NodeChangeListener)|
23 |java.util.prefs.AbstractPreferences.addPreferenceChangeListener(PreferenceChangeListener)|
24 |java.util.prefs.AbstractPreferences.cachedChildren()|Returns all known unremov
25 |java.util.prefs.AbstractPreferences.childrenNames()|Implements the children me
26 |java.util.prefs.AbstractPreferences.childrenNamesSpi()|Returns the names of th
27 |java.util.prefs.AbstractPreferences.childSpi(String)|Returns the named child o
28 |java.util.prefs.AbstractPreferences.clear()|Implements the clear method as per
29 |java.util.prefs.AbstractPreferences.exportNode(OutputStream)|Implements the ex
30 |java.util.prefs.AbstractPreferences.exportSubtree(OutputStream)|Implements the
31 |java.util.prefs.AbstractPreferences.flush()|Implements the flush method as per
32 |java.util.prefs.AbstractPreferences.flushSpi()|This method is invoked with thi
33 |java.util.prefs.AbstractPreferences.get(String,String)|Implements the get meth
34 |java.util.prefs.AbstractPreferences.getBoolean(String,boolean)|Implements the
35 |java.util.prefs.AbstractPreferences.getByteArray(String,byte[])|Implements the
36 |java.util.prefs.AbstractPreferences.getChild(String)|Returns the named child i
37 |java.util.prefs.AbstractPreferences.getDouble(String,double)|Implements the ge
38 |java.util.prefs.AbstractPreferences.getFloat(String,float)|Implements the getF
39 |java.util.prefs.AbstractPreferences.getInt(String,int)|Implements the getInt m
40 |java.util.prefs.AbstractPreferences.getLong(String,long)|Implements the getLon
41 |java.util.prefs.AbstractPreferences.getSpi(String)|Return the value associated
42 |java.util.prefs.AbstractPreferences.isRemoved()|Returns true iff this node (or
43 |java.util.prefs.AbstractPreferences.isUserNode()|Implements the isUserNode met
44 |java.util.prefs.AbstractPreferences.keys()|Implements the keys method as per t
45 |java.util.prefs.AbstractPreferences.keysSpi()|Returns all of the keys that hav
46 |java.util.prefs.AbstractPreferences.name()|Implements the name method as per t
47 |java.util.prefs.AbstractPreferences.node(String)|Implements the node method as
48 |java.util.prefs.AbstractPreferences.nodeExists(String)|Implements the nodeExis
49 |java.util.prefs.AbstractPreferences.parent()|Implements the parent method as p
50 |java.util.prefs.AbstractPreferences.put(String,String)|Implements the put meth
51 |java.util.prefs.AbstractPreferences.putBoolean(String,boolean)|Implements the
52 |java.util.prefs.AbstractPreferences.putByteArray(String,byte[])|Implements the
53 |java.util.prefs.AbstractPreferences.putDouble(String,double)|Implements the pu
54 |java.util.prefs.AbstractPreferences.putFloat(String,float)|Implements the putF
55 |java.util.prefs.AbstractPreferences.putInt(String,int)|Implements the putInt m
56 |java.util.prefs.AbstractPreferences.putLong(String,long)|Implements the putLon
57 |java.util.prefs.AbstractPreferences.putSpi(String,String)|Put the given key-va
58 |java.util.prefs.AbstractPreferences.remove(String)|Implements the remove(Strin
59 |java.util.prefs.AbstractPreferences.removeNode()|Implements the removeNode() m
60 |java.util.prefs.AbstractPreferences.removeNodeChangeListener(NodeChangeListener)|
61 |java.util.prefs.AbstractPreferences.removeNodeSpi()|Removes this preference no
62 |java.util.prefs.AbstractPreferences.removePreferenceChangeListener(PreferenceChangeListener)|
63 |java.util.prefs.AbstractPreferences.removeSpi(String)|Remove the association (
64 |java.util.prefs.AbstractPreferences.sync()|Implements the sync method as per t
65 |java.util.prefs.AbstractPreferences.syncSpi()|This method is invoked with this
66 |java.util.prefs.AbstractPreferences.toString()|Returns the absolute path name
68 *java.util.prefs.AbstractPreferences_Description*
70 This class provides a skeletal implementation of the
71 (|java.util.prefs.Preferences|) class, greatly easing the task of implementing
74 This class is for Preferences implementers only. Normal users of the
75 Preferences facility should have no need to consult this documentation. The
76 (|java.util.prefs.Preferences|) documentation should suffice.
78 Implementors must override the nine abstract service-provider interface (SPI)
79 methods: (|java.util.prefs.AbstractPreferences|) ,
80 (|java.util.prefs.AbstractPreferences|) ,
81 (|java.util.prefs.AbstractPreferences|) ,
82 (|java.util.prefs.AbstractPreferences|) ,
83 (|java.util.prefs.AbstractPreferences|) ,
84 (|java.util.prefs.AbstractPreferences|) ,
85 (|java.util.prefs.AbstractPreferences|) ,
86 (|java.util.prefs.AbstractPreferences|) and
87 (|java.util.prefs.AbstractPreferences|) . All of the concrete methods specify
88 precisely how they are implemented atop these SPI methods. The implementor may,
89 at his discretion, override one or more of the concrete methods if the default
90 implementation is unsatisfactory for any reason, such as performance.
92 The SPI methods fall into three groups concerning exception behavior. The
93 getSpi method should never throw exceptions, but it doesn't really matter, as
94 any exception thrown by this method will be intercepted by
95 (|java.util.prefs.AbstractPreferences|) , which will return the specified
96 default value to the caller. The removeNodeSpi, keysSpi, childrenNamesSpi,
97 syncSpi and flushSpi methods are specified to throw
98 (|java.util.prefs.BackingStoreException|) , and the implementation is required
99 to throw this checked exception if it is unable to perform the operation. The
100 exception propagates outward, causing the corresponding API method to fail.
102 The remaining SPI methods (|java.util.prefs.AbstractPreferences|) ,
103 (|java.util.prefs.AbstractPreferences|) and
104 (|java.util.prefs.AbstractPreferences|) have more complicated exception
105 behavior. They are not specified to throw BackingStoreException, as they can
106 generally obey their contracts even if the backing store is unavailable. This
107 is true because they return no information and their effects are not required
108 to become permanent until a subsequent call to {Preferences#flush()} or
109 {Preferences#sync()}. Generally speaking, these SPI methods should not throw
110 exceptions. In some implementations, there may be circumstances under which
111 these calls cannot even enqueue the requested operation for later processing.
112 Even under these circumstances it is generally better to simply ignore the
113 invocation and return, rather than throwing an exception. Under these
114 circumstances, however, all subsequent invocations of flush() and sync should
115 return false, as returning true would imply that all previous operations had
116 successfully been made permanent.
118 There is one circumstance under which putSpi, removeSpi and childSpi should
119 throw an exception: if the caller lacks sufficient privileges on the underlying
120 operating system to perform the requested operation. This will, for instance,
121 occur on most systems if a non-privileged user attempts to modify system
122 preferences. (The required privileges will vary from implementation to
123 implementation. On some implementations, they are the right to modify the
124 contents of some directory in the file system; on others they are the right to
125 modify contents of some key in a registry.) Under any of these circumstances,
126 it would generally be undesirable to let the program continue executing as if
127 these operations would become permanent at a later time. While implementations
128 are not required to throw an exception under these circumstances, they are
129 encouraged to do so. A (|java.lang.SecurityException|) would be appropriate.
131 Most of the SPI methods require the implementation to read or write information
132 at a preferences node. The implementor should beware of the fact that another
133 VM may have concurrently deleted this node from the backing store. It is the
134 implementation's responsibility to recreate the node if it has been deleted.
136 Implementation note: In Sun's default Preferences implementations, the user's
137 identity is inherited from the underlying operating system and does not change
138 for the lifetime of the virtual machine. It is recognized that server-side
139 Preferences implementations may have the user identity change from request to
140 request, implicitly passed to Preferences methods via the use of a static
141 (|java.lang.ThreadLocal|) instance. Authors of such implementations are
142 strongly encouraged to determine the user at the time preferences are accessed
143 (for example by the (|java.util.prefs.AbstractPreferences|) or
144 (|java.util.prefs.AbstractPreferences|) method) rather than permanently
145 associating a user with each Preferences instance. The latter behavior
146 conflicts with normal Preferences usage and would lead to great confusion.
149 *java.lang.Object_java.util.prefs.AbstractPreferences.lock*
151 This class provides a skeletal implementation of the
152 (|java.util.prefs.Preferences|) class, greatly easing the task of implementing
155 This class is for Preferences implementers only. Normal users of the
156 Preferences facility should have no need to consult this documentation. The
157 (|java.util.prefs.Preferences|) documentation should suffice.
159 Implementors must override the nine abstract service-provider interface (SPI)
160 methods: (|java.util.prefs.AbstractPreferences|) ,
161 (|java.util.prefs.AbstractPreferences|) ,
162 (|java.util.prefs.AbstractPreferences|) ,
163 (|java.util.prefs.AbstractPreferences|) ,
164 (|java.util.prefs.AbstractPreferences|) ,
165 (|java.util.prefs.AbstractPreferences|) ,
166 (|java.util.prefs.AbstractPreferences|) ,
167 (|java.util.prefs.AbstractPreferences|) and
168 (|java.util.prefs.AbstractPreferences|) . All of the concrete methods specify
169 precisely how they are implemented atop these SPI methods. The implementor may,
170 at his discretion, override one or more of the concrete methods if the default
171 implementation is unsatisfactory for any reason, such as performance.
173 The SPI methods fall into three groups concerning exception behavior. The
174 getSpi method should never throw exceptions, but it doesn't really matter, as
175 any exception thrown by this method will be intercepted by
176 (|java.util.prefs.AbstractPreferences|) , which will return the specified
177 default value to the caller. The removeNodeSpi, keysSpi, childrenNamesSpi,
178 syncSpi and flushSpi methods are specified to throw
179 (|java.util.prefs.BackingStoreException|) , and the implementation is required
180 to throw this checked exception if it is unable to perform the operation. The
181 exception propagates outward, causing the corresponding API method to fail.
183 The remaining SPI methods (|java.util.prefs.AbstractPreferences|) ,
184 (|java.util.prefs.AbstractPreferences|) and
185 (|java.util.prefs.AbstractPreferences|) have more complicated exception
186 behavior. They are not specified to throw BackingStoreException, as they can
187 generally obey their contracts even if the backing store is unavailable. This
188 is true because they return no information and their effects are not required
189 to become permanent until a subsequent call to {Preferences#flush()} or
190 {Preferences#sync()}. Generally speaking, these SPI methods should not throw
191 exceptions. In some implementations, there may be circumstances under which
192 these calls cannot even enqueue the requested operation for later processing.
193 Even under these circumstances it is generally better to simply ignore the
194 invocation and return, rather than throwing an exception. Under these
195 circumstances, however, all subsequent invocations of flush() and sync should
196 return false, as returning true would imply that all previous operations had
197 successfully been made permanent.
199 There is one circumstance under which putSpi, removeSpi and childSpi should
200 throw an exception: if the caller lacks sufficient privileges on the underlying
201 operating system to perform the requested operation. This will, for instance,
202 occur on most systems if a non-privileged user attempts to modify system
203 preferences. (The required privileges will vary from implementation to
204 implementation. On some implementations, they are the right to modify the
205 contents of some directory in the file system; on others they are the right to
206 modify contents of some key in a registry.) Under any of these circumstances,
207 it would generally be undesirable to let the program continue executing as if
208 these operations would become permanent at a later time. While implementations
209 are not required to throw an exception under these circumstances, they are
210 encouraged to do so. A (|java.lang.SecurityException|) would be appropriate.
212 Most of the SPI methods require the implementation to read or write information
213 at a preferences node. The implementor should beware of the fact that another
214 VM may have concurrently deleted this node from the backing store. It is the
215 implementation's responsibility to recreate the node if it has been deleted.
217 Implementation note: In Sun's default Preferences implementations, the user's
218 identity is inherited from the underlying operating system and does not change
219 for the lifetime of the virtual machine. It is recognized that server-side
220 Preferences implementations may have the user identity change from request to
221 request, implicitly passed to Preferences methods via the use of a static
222 (|java.lang.ThreadLocal|) instance. Authors of such implementations are
223 strongly encouraged to determine the user at the time preferences are accessed
224 (for example by the (|java.util.prefs.AbstractPreferences|) or
225 (|java.util.prefs.AbstractPreferences|) method) rather than permanently
226 associating a user with each Preferences instance. The latter behavior
227 conflicts with normal Preferences usage and would lead to great confusion.
230 *boolean_java.util.prefs.AbstractPreferences.newNode*
232 This class provides a skeletal implementation of the
233 (|java.util.prefs.Preferences|) class, greatly easing the task of implementing
236 This class is for Preferences implementers only. Normal users of the
237 Preferences facility should have no need to consult this documentation. The
238 (|java.util.prefs.Preferences|) documentation should suffice.
240 Implementors must override the nine abstract service-provider interface (SPI)
241 methods: (|java.util.prefs.AbstractPreferences|) ,
242 (|java.util.prefs.AbstractPreferences|) ,
243 (|java.util.prefs.AbstractPreferences|) ,
244 (|java.util.prefs.AbstractPreferences|) ,
245 (|java.util.prefs.AbstractPreferences|) ,
246 (|java.util.prefs.AbstractPreferences|) ,
247 (|java.util.prefs.AbstractPreferences|) ,
248 (|java.util.prefs.AbstractPreferences|) and
249 (|java.util.prefs.AbstractPreferences|) . All of the concrete methods specify
250 precisely how they are implemented atop these SPI methods. The implementor may,
251 at his discretion, override one or more of the concrete methods if the default
252 implementation is unsatisfactory for any reason, such as performance.
254 The SPI methods fall into three groups concerning exception behavior. The
255 getSpi method should never throw exceptions, but it doesn't really matter, as
256 any exception thrown by this method will be intercepted by
257 (|java.util.prefs.AbstractPreferences|) , which will return the specified
258 default value to the caller. The removeNodeSpi, keysSpi, childrenNamesSpi,
259 syncSpi and flushSpi methods are specified to throw
260 (|java.util.prefs.BackingStoreException|) , and the implementation is required
261 to throw this checked exception if it is unable to perform the operation. The
262 exception propagates outward, causing the corresponding API method to fail.
264 The remaining SPI methods (|java.util.prefs.AbstractPreferences|) ,
265 (|java.util.prefs.AbstractPreferences|) and
266 (|java.util.prefs.AbstractPreferences|) have more complicated exception
267 behavior. They are not specified to throw BackingStoreException, as they can
268 generally obey their contracts even if the backing store is unavailable. This
269 is true because they return no information and their effects are not required
270 to become permanent until a subsequent call to {Preferences#flush()} or
271 {Preferences#sync()}. Generally speaking, these SPI methods should not throw
272 exceptions. In some implementations, there may be circumstances under which
273 these calls cannot even enqueue the requested operation for later processing.
274 Even under these circumstances it is generally better to simply ignore the
275 invocation and return, rather than throwing an exception. Under these
276 circumstances, however, all subsequent invocations of flush() and sync should
277 return false, as returning true would imply that all previous operations had
278 successfully been made permanent.
280 There is one circumstance under which putSpi, removeSpi and childSpi should
281 throw an exception: if the caller lacks sufficient privileges on the underlying
282 operating system to perform the requested operation. This will, for instance,
283 occur on most systems if a non-privileged user attempts to modify system
284 preferences. (The required privileges will vary from implementation to
285 implementation. On some implementations, they are the right to modify the
286 contents of some directory in the file system; on others they are the right to
287 modify contents of some key in a registry.) Under any of these circumstances,
288 it would generally be undesirable to let the program continue executing as if
289 these operations would become permanent at a later time. While implementations
290 are not required to throw an exception under these circumstances, they are
291 encouraged to do so. A (|java.lang.SecurityException|) would be appropriate.
293 Most of the SPI methods require the implementation to read or write information
294 at a preferences node. The implementor should beware of the fact that another
295 VM may have concurrently deleted this node from the backing store. It is the
296 implementation's responsibility to recreate the node if it has been deleted.
298 Implementation note: In Sun's default Preferences implementations, the user's
299 identity is inherited from the underlying operating system and does not change
300 for the lifetime of the virtual machine. It is recognized that server-side
301 Preferences implementations may have the user identity change from request to
302 request, implicitly passed to Preferences methods via the use of a static
303 (|java.lang.ThreadLocal|) instance. Authors of such implementations are
304 strongly encouraged to determine the user at the time preferences are accessed
305 (for example by the (|java.util.prefs.AbstractPreferences|) or
306 (|java.util.prefs.AbstractPreferences|) method) rather than permanently
307 associating a user with each Preferences instance. The latter behavior
308 conflicts with normal Preferences usage and would lead to great confusion.
312 *java.util.prefs.AbstractPreferences(AbstractPreferences,String)*
314 protected AbstractPreferences(
315 java.util.prefs.AbstractPreferences parent,
316 java.lang.String name)
318 Creates a preference node with the specified parent and the specified name
319 relative to its parent.
321 parent - the parent of this preference node, or null if this is the root.
322 name - the name of this preference node, relative to its parent, or "" if this is the
325 *java.util.prefs.AbstractPreferences.absolutePath()*
327 public |java.lang.String| absolutePath()
329 Implements the absolutePath method as per the specification in
330 (|java.util.prefs.Preferences|) .
332 This implementation merely returns the absolute path name that was computed at
333 the time that this node was constructed (based on the name that was passed to
334 this node's constructor, and the names that were passed to this node's
335 ancestors' constructors).
338 Returns: this preference node's absolute path name.
339 *java.util.prefs.AbstractPreferences.addNodeChangeListener(NodeChangeListener)*
341 public void addNodeChangeListener(java.util.prefs.NodeChangeListener ncl)
346 *java.util.prefs.AbstractPreferences.addPreferenceChangeListener(PreferenceChangeListener)*
348 public void addPreferenceChangeListener(java.util.prefs.PreferenceChangeListener pcl)
353 *java.util.prefs.AbstractPreferences.cachedChildren()*
355 protected final |java.util.prefs.AbstractPreferences| cachedChildren()
357 Returns all known unremoved children of this node.
360 Returns: all known unremoved children of this node.
361 *java.util.prefs.AbstractPreferences.childrenNames()*
363 public |java.lang.String| childrenNames()
364 throws |java.util.prefs.BackingStoreException|
366 Implements the children method as per the specification in
367 (|java.util.prefs.Preferences|) .
369 This implementation obtains this preference node's lock, checks that the node
370 has not been removed, constructs a TreeSet initialized to the names of children
371 already cached (the children in this node's "child-cache"), invokes
372 (|java.util.prefs.AbstractPreferences|) , and adds all of the returned
373 child-names into the set. The elements of the tree set are dumped into a String
374 array using the toArray method, and this array is returned.
377 Returns: the names of the children of this preference node.
378 *java.util.prefs.AbstractPreferences.childrenNamesSpi()*
380 protected abstract |java.lang.String| childrenNamesSpi()
381 throws |java.util.prefs.BackingStoreException|
383 Returns the names of the children of this preference node. (The returned array
384 will be of size zero if this node has no children.) This method need not return
385 the names of any nodes already cached, but may do so without harm.
387 This method is invoked with the lock on this node held.
389 If this node throws a BackingStoreException, the exception will propagate out
390 beyond the enclosing (|java.util.prefs.AbstractPreferences|) invocation.
393 Returns: an array containing the names of the children of this preference node.
394 *java.util.prefs.AbstractPreferences.childSpi(String)*
396 protected abstract |java.util.prefs.AbstractPreferences| childSpi(java.lang.String name)
398 Returns the named child of this preference node, creating it if it does not
399 already exist. It is guaranteed that name is non-null, non-empty, does not
400 contain the slash character ('/'), and is no longer than
401 (|java.util.prefs.AbstractPreferences|) characters. Also, it is guaranteed that
402 this node has not been removed. (The implementor needn't check for any of these
405 Finally, it is guaranteed that the named node has not been returned by a
406 previous invocation of this method or (|java.util.prefs.AbstractPreferences|)
407 after the last time that it was removed. In other words, a cached value will
408 always be used in preference to invoking this method. Subclasses need not
409 maintain their own cache of previously returned children.
411 The implementer must ensure that the returned node has not been removed. If a
412 like-named child of this node was previously removed, the implementer must
413 return a newly constructed AbstractPreferences node; once removed, an
414 AbstractPreferences node cannot be "resuscitated."
416 If this method causes a node to be created, this node is not guaranteed to be
417 persistent until the flush method is invoked on this node or one of its
418 ancestors (or descendants).
420 This method is invoked with the lock on this node held.
422 name - The name of the child node to return, relative to this preference node.
424 Returns: The named child node.
425 *java.util.prefs.AbstractPreferences.clear()*
428 throws |java.util.prefs.BackingStoreException|
430 Implements the clear method as per the specification in
431 (|java.util.prefs.Preferences|) .
433 This implementation obtains this preference node's lock, invokes
434 (|java.util.prefs.AbstractPreferences|) to obtain an array of keys, and
435 iterates over the array invoking (|java.util.prefs.AbstractPreferences|) on
439 *java.util.prefs.AbstractPreferences.exportNode(OutputStream)*
441 public void exportNode(java.io.OutputStream os)
442 throws |java.util.prefs.BackingStoreException|
443 |java.io.IOException|
445 Implements the exportNode method as per the specification in
446 (|java.util.prefs.Preferences|) .
448 os - the output stream on which to emit the XML document.
450 *java.util.prefs.AbstractPreferences.exportSubtree(OutputStream)*
452 public void exportSubtree(java.io.OutputStream os)
453 throws |java.util.prefs.BackingStoreException|
454 |java.io.IOException|
456 Implements the exportSubtree method as per the specification in
457 (|java.util.prefs.Preferences|) .
459 os - the output stream on which to emit the XML document.
461 *java.util.prefs.AbstractPreferences.flush()*
464 throws |java.util.prefs.BackingStoreException|
466 Implements the flush method as per the specification in
467 (|java.util.prefs.Preferences|) .
469 This implementation calls a recursive helper method that locks this node,
470 invokes flushSpi() on it, unlocks this node, and recursively invokes this
471 method on each "cached child." A cached child is a child of this node that has
472 been created in this VM and not subsequently removed. In effect, this method
473 does a depth first traversal of the "cached subtree" rooted at this node,
474 calling flushSpi() on each node in the subTree while only that node is locked.
475 Note that flushSpi() is invoked top-down.
477 If this method is invoked on a node that has been removed with the
478 (|java.util.prefs.AbstractPreferences|) method, flushSpi() is invoked on this
479 node, but not on others.
482 *java.util.prefs.AbstractPreferences.flushSpi()*
484 protected abstract void flushSpi()
485 throws |java.util.prefs.BackingStoreException|
487 This method is invoked with this node locked. The contract of this method is to
488 force any cached changes in the contents of this preference node to the backing
489 store, guaranteeing their persistence. (It is perfectly possible that this node
490 does not exist on the backing store, either because it has been deleted by
491 another VM, or because it has not yet been created.) Note that this method
492 should not flush the preferences in any subnodes of this node. If the backing
493 store naturally flushes an entire subtree at once, the implementer is
494 encouraged to override flush(), rather than merely overriding this method.
496 If this node throws a BackingStoreException, the exception will propagate out
497 beyond the enclosing (|java.util.prefs.AbstractPreferences|) invocation.
500 *java.util.prefs.AbstractPreferences.get(String,String)*
502 public |java.lang.String| get(
503 java.lang.String key,
504 java.lang.String def)
506 Implements the get method as per the specification in
507 (|java.util.prefs.Preferences|) .
509 This implementation first checks to see if key is null throwing a
510 NullPointerException if this is the case. Then it obtains this preference
511 node's lock, checks that the node has not been removed, invokes
512 (|java.util.prefs.AbstractPreferences|) , and returns the result, unless the
513 getSpi invocation returns null or throws an exception, in which case this
514 invocation returns def.
516 key - key whose associated value is to be returned.
517 def - the value to be returned in the event that this preference node has no value
520 Returns: the value associated with key, or def if no value is associated with key.
521 *java.util.prefs.AbstractPreferences.getBoolean(String,boolean)*
523 public boolean getBoolean(
524 java.lang.String key,
527 Implements the getBoolean method as per the specification in
528 (|java.util.prefs.Preferences|) .
530 This implementation invokes <tt>get(key,
531 null)</tt>(|java.util.prefs.AbstractPreferences|) . If the return value is
532 non-null, it is compared with "true" using (|java.lang.String|) . If the
533 comparison returns true, this invocation returns true. Otherwise, the original
534 return value is compared with "false", again using (|java.lang.String|) . If
535 the comparison returns true, this invocation returns false. Otherwise, this
536 invocation returns def.
538 key - key whose associated value is to be returned as a boolean.
539 def - the value to be returned in the event that this preference node has no value
540 associated with key or the associated value cannot be interpreted as a
543 Returns: the boolean value represented by the string associated with key in this
544 preference node, or def if the associated value does not exist or
545 cannot be interpreted as a boolean.
546 *java.util.prefs.AbstractPreferences.getByteArray(String,byte[])*
548 public byte getByteArray(
549 java.lang.String key,
552 Implements the getByteArray method as per the specification in
553 (|java.util.prefs.Preferences|) .
555 key - key whose associated value is to be returned as a byte array.
556 def - the value to be returned in the event that this preference node has no value
557 associated with key or the associated value cannot be interpreted as a
560 Returns: the byte array value represented by the string associated with key in this
561 preference node, or def if the associated value does not exist or
562 cannot be interpreted as a byte array.
563 *java.util.prefs.AbstractPreferences.getChild(String)*
565 protected |java.util.prefs.AbstractPreferences| getChild(java.lang.String nodeName)
566 throws |java.util.prefs.BackingStoreException|
568 Returns the named child if it exists, or null if it does not. It is guaranteed
569 that nodeName is non-null, non-empty, does not contain the slash character
570 ('/'), and is no longer than (|java.util.prefs.AbstractPreferences|)
571 characters. Also, it is guaranteed that this node has not been removed. (The
572 implementor needn't check for any of these things if he chooses to override
575 Finally, it is guaranteed that the named node has not been returned by a
576 previous invocation of this method or (|java.util.prefs.AbstractPreferences|)
577 after the last time that it was removed. In other words, a cached value will
578 always be used in preference to invoking this method. (The implementor needn't
579 maintain his own cache of previously returned children if he chooses to
580 override this method.)
582 This implementation obtains this preference node's lock, invokes
583 (|java.util.prefs.AbstractPreferences|) to get an array of the names of this
584 node's children, and iterates over the array comparing the name of each child
585 with the specified node name. If a child node has the correct name, the
586 (|java.util.prefs.AbstractPreferences|) method is invoked and the resulting
587 node is returned. If the iteration completes without finding the specified
588 name, null is returned.
590 nodeName - name of the child to be searched for.
592 Returns: the named child if it exists, or null if it does not.
593 *java.util.prefs.AbstractPreferences.getDouble(String,double)*
595 public double getDouble(
596 java.lang.String key,
599 Implements the getDouble method as per the specification in
600 (|java.util.prefs.Preferences|) .
602 This implementation invokes <tt>get(key,
603 null)</tt>(|java.util.prefs.AbstractPreferences|) . If the return value is
604 non-null, the implementation attempts to translate it to an double with
605 (|java.lang.Double|) . If the attempt succeeds, the return value is returned by
606 this method. Otherwise, def is returned.
608 key - key whose associated value is to be returned as a double.
609 def - the value to be returned in the event that this preference node has no value
610 associated with key or the associated value cannot be interpreted as a
613 Returns: the double value represented by the string associated with key in this
614 preference node, or def if the associated value does not exist or
615 cannot be interpreted as a double.
616 *java.util.prefs.AbstractPreferences.getFloat(String,float)*
618 public float getFloat(
619 java.lang.String key,
622 Implements the getFloat method as per the specification in
623 (|java.util.prefs.Preferences|) .
625 This implementation invokes <tt>get(key,
626 null)</tt>(|java.util.prefs.AbstractPreferences|) . If the return value is
627 non-null, the implementation attempts to translate it to an float with
628 (|java.lang.Float|) . If the attempt succeeds, the return value is returned by
629 this method. Otherwise, def is returned.
631 key - key whose associated value is to be returned as a float.
632 def - the value to be returned in the event that this preference node has no value
633 associated with key or the associated value cannot be interpreted as a
636 Returns: the float value represented by the string associated with key in this
637 preference node, or def if the associated value does not exist or
638 cannot be interpreted as a float.
639 *java.util.prefs.AbstractPreferences.getInt(String,int)*
642 java.lang.String key,
645 Implements the getInt method as per the specification in
646 (|java.util.prefs.Preferences|) .
648 This implementation invokes <tt>get(key,
649 null)</tt>(|java.util.prefs.AbstractPreferences|) . If the return value is
650 non-null, the implementation attempts to translate it to an int with
651 (|java.lang.Integer|) . If the attempt succeeds, the return value is returned
652 by this method. Otherwise, def is returned.
654 key - key whose associated value is to be returned as an int.
655 def - the value to be returned in the event that this preference node has no value
656 associated with key or the associated value cannot be interpreted as an
659 Returns: the int value represented by the string associated with key in this preference
660 node, or def if the associated value does not exist or cannot be
661 interpreted as an int.
662 *java.util.prefs.AbstractPreferences.getLong(String,long)*
665 java.lang.String key,
668 Implements the getLong method as per the specification in
669 (|java.util.prefs.Preferences|) .
671 This implementation invokes <tt>get(key,
672 null)</tt>(|java.util.prefs.AbstractPreferences|) . If the return value is
673 non-null, the implementation attempts to translate it to a long with
674 (|java.lang.Long|) . If the attempt succeeds, the return value is returned by
675 this method. Otherwise, def is returned.
677 key - key whose associated value is to be returned as a long.
678 def - the value to be returned in the event that this preference node has no value
679 associated with key or the associated value cannot be interpreted as a
682 Returns: the long value represented by the string associated with key in this preference
683 node, or def if the associated value does not exist or cannot be
684 interpreted as a long.
685 *java.util.prefs.AbstractPreferences.getSpi(String)*
687 protected abstract |java.lang.String| getSpi(java.lang.String key)
689 Return the value associated with the specified key at this preference node, or
690 null if there is no association for this key, or the association cannot be
691 determined at this time. It is guaranteed that key is non-null. Also, it is
692 guaranteed that this node has not been removed. (The implementor needn't check
693 for either of these things.)
695 Generally speaking, this method should not throw an exception under any
696 circumstances. If, however, if it does throw an exception, the exception will
697 be intercepted and treated as a null return value.
699 This method is invoked with the lock on this node held.
702 Returns: the value associated with the specified key at this preference node, or null if
703 there is no association for this key, or the association cannot be
704 determined at this time.
705 *java.util.prefs.AbstractPreferences.isRemoved()*
707 protected boolean isRemoved()
709 Returns true iff this node (or an ancestor) has been removed with the
710 (|java.util.prefs.AbstractPreferences|) method. This method locks this node
711 prior to returning the contents of the private field used to track this state.
714 Returns: true iff this node (or an ancestor) has been removed with the {@link
715 #removeNode()} method.
716 *java.util.prefs.AbstractPreferences.isUserNode()*
718 public boolean isUserNode()
720 Implements the isUserNode method as per the specification in
721 (|java.util.prefs.Preferences|) .
723 This implementation compares this node's root node (which is stored in a
724 private field) with the value returned by (|java.util.prefs.Preferences|) . If
725 the two object references are identical, this method returns true.
728 Returns: true if this preference node is in the user preference tree, false if it's in
729 the system preference tree.
730 *java.util.prefs.AbstractPreferences.keys()*
732 public |java.lang.String| keys()
733 throws |java.util.prefs.BackingStoreException|
735 Implements the keys method as per the specification in
736 (|java.util.prefs.Preferences|) .
738 This implementation obtains this preference node's lock, checks that the node
739 has not been removed and invokes (|java.util.prefs.AbstractPreferences|) .
742 Returns: an array of the keys that have an associated value in this preference node.
743 *java.util.prefs.AbstractPreferences.keysSpi()*
745 protected abstract |java.lang.String| keysSpi()
746 throws |java.util.prefs.BackingStoreException|
748 Returns all of the keys that have an associated value in this preference node.
749 (The returned array will be of size zero if this node has no preferences.) It
750 is guaranteed that this node has not been removed.
752 This method is invoked with the lock on this node held.
754 If this node throws a BackingStoreException, the exception will propagate out
755 beyond the enclosing (|java.util.prefs.AbstractPreferences|) invocation.
758 Returns: an array of the keys that have an associated value in this preference node.
759 *java.util.prefs.AbstractPreferences.name()*
761 public |java.lang.String| name()
763 Implements the name method as per the specification in
764 (|java.util.prefs.Preferences|) .
766 This implementation merely returns the name that was passed to this node's
770 Returns: this preference node's name, relative to its parent.
771 *java.util.prefs.AbstractPreferences.node(String)*
773 public |java.util.prefs.Preferences| node(java.lang.String path)
775 Implements the node method as per the specification in
776 (|java.util.prefs.Preferences|) .
778 This implementation obtains this preference node's lock and checks that the
779 node has not been removed. If path is "", this node is returned; if path is
780 "/", this node's root is returned. If the first character in path is not '/',
781 the implementation breaks path into tokens and recursively traverses the path
782 from this node to the named node, "consuming" a name and a slash from path at
783 each step of the traversal. At each step, the current node is locked and the
784 node's child-cache is checked for the named node. If it is not found, the name
785 is checked to make sure its length does not exceed MAX_NAME_LENGTH. Then the
786 (|java.util.prefs.AbstractPreferences|) method is invoked, and the result
787 stored in this node's child-cache. If the newly created Preferences object's
788 (|java.util.prefs.AbstractPreferences|) field is true and there are any node
789 change listeners, a notification event is enqueued for processing by the event
792 When there are no more tokens, the last value found in the child-cache or
793 returned by childSpi is returned by this method. If during the traversal, two
794 "/" tokens occur consecutively, or the final token is "/" (rather than a name),
795 an appropriate IllegalArgumentException is thrown.
797 If the first character of path is '/' (indicating an absolute path name name)
798 this preference node's lock is dropped prior to breaking path into tokens, and
799 this method recursively traverses the path starting from the root (rather than
800 starting from this node). The traversal is otherwise identical to the one
801 described for relative path names. Dropping the lock on this node prior to
802 commencing the traversal at the root node is essential to avoid the possibility
803 of deadlock, as per the locking
804 invariant(|java.util.prefs.AbstractPreferences|) .
806 path - the path name of the preference node to return.
808 Returns: the specified preference node.
809 *java.util.prefs.AbstractPreferences.nodeExists(String)*
811 public boolean nodeExists(java.lang.String path)
812 throws |java.util.prefs.BackingStoreException|
814 Implements the nodeExists method as per the specification in
815 (|java.util.prefs.Preferences|) .
817 This implementation is very similar to (|java.util.prefs.AbstractPreferences|)
818 , except that (|java.util.prefs.AbstractPreferences|) is used instead of
819 (|java.util.prefs.AbstractPreferences|) .
821 path - the path name of the node whose existence is to be checked.
823 Returns: true if the specified node exists.
824 *java.util.prefs.AbstractPreferences.parent()*
826 public |java.util.prefs.Preferences| parent()
828 Implements the parent method as per the specification in
829 (|java.util.prefs.Preferences|) .
831 This implementation obtains this preference node's lock, checks that the node
832 has not been removed and returns the parent value that was passed to this
836 Returns: the parent of this preference node.
837 *java.util.prefs.AbstractPreferences.put(String,String)*
840 java.lang.String key,
841 java.lang.String value)
843 Implements the put method as per the specification in
844 (|java.util.prefs.Preferences|) .
846 This implementation checks that the key and value are legal, obtains this
847 preference node's lock, checks that the node has not been removed, invokes
848 (|java.util.prefs.AbstractPreferences|) , and if there are any preference
849 change listeners, enqueues a notification event for processing by the event
852 key - key with which the specified value is to be associated.
853 value - value to be associated with the specified key.
855 *java.util.prefs.AbstractPreferences.putBoolean(String,boolean)*
857 public void putBoolean(
858 java.lang.String key,
861 Implements the putBoolean method as per the specification in
862 (|java.util.prefs.Preferences|) .
864 This implementation translates value to a string with (|java.lang.String|) and
865 invokes (|java.util.prefs.AbstractPreferences|) on the result.
867 key - key with which the string form of value is to be associated.
868 value - value whose string form is to be associated with key.
870 *java.util.prefs.AbstractPreferences.putByteArray(String,byte[])*
872 public void putByteArray(
873 java.lang.String key,
876 Implements the putByteArray method as per the specification in
877 (|java.util.prefs.Preferences|) .
879 key - key with which the string form of value is to be associated.
880 value - value whose string form is to be associated with key.
882 *java.util.prefs.AbstractPreferences.putDouble(String,double)*
884 public void putDouble(
885 java.lang.String key,
888 Implements the putDouble method as per the specification in
889 (|java.util.prefs.Preferences|) .
891 This implementation translates value to a string with (|java.lang.Double|) and
892 invokes (|java.util.prefs.AbstractPreferences|) on the result.
894 key - key with which the string form of value is to be associated.
895 value - value whose string form is to be associated with key.
897 *java.util.prefs.AbstractPreferences.putFloat(String,float)*
899 public void putFloat(
900 java.lang.String key,
903 Implements the putFloat method as per the specification in
904 (|java.util.prefs.Preferences|) .
906 This implementation translates value to a string with (|java.lang.Float|) and
907 invokes (|java.util.prefs.AbstractPreferences|) on the result.
909 key - key with which the string form of value is to be associated.
910 value - value whose string form is to be associated with key.
912 *java.util.prefs.AbstractPreferences.putInt(String,int)*
915 java.lang.String key,
918 Implements the putInt method as per the specification in
919 (|java.util.prefs.Preferences|) .
921 This implementation translates value to a string with (|java.lang.Integer|) and
922 invokes (|java.util.prefs.AbstractPreferences|) on the result.
924 key - key with which the string form of value is to be associated.
925 value - value whose string form is to be associated with key.
927 *java.util.prefs.AbstractPreferences.putLong(String,long)*
930 java.lang.String key,
933 Implements the putLong method as per the specification in
934 (|java.util.prefs.Preferences|) .
936 This implementation translates value to a string with (|java.lang.Long|) and
937 invokes (|java.util.prefs.AbstractPreferences|) on the result.
939 key - key with which the string form of value is to be associated.
940 value - value whose string form is to be associated with key.
942 *java.util.prefs.AbstractPreferences.putSpi(String,String)*
944 protected abstract void putSpi(
945 java.lang.String key,
946 java.lang.String value)
948 Put the given key-value association into this preference node. It is guaranteed
949 that key and value are non-null and of legal length. Also, it is guaranteed
950 that this node has not been removed. (The implementor needn't check for any of
953 This method is invoked with the lock on this node held.
956 *java.util.prefs.AbstractPreferences.remove(String)*
958 public void remove(java.lang.String key)
960 Implements the remove(String) method as per the specification in
961 (|java.util.prefs.Preferences|) .
963 This implementation obtains this preference node's lock, checks that the node
964 has not been removed, invokes (|java.util.prefs.AbstractPreferences|) and if
965 there are any preference change listeners, enqueues a notification event for
966 processing by the event dispatch thread.
968 key - key whose mapping is to be removed from the preference node.
970 *java.util.prefs.AbstractPreferences.removeNode()*
972 public void removeNode()
973 throws |java.util.prefs.BackingStoreException|
975 Implements the removeNode() method as per the specification in
976 (|java.util.prefs.Preferences|) .
978 This implementation checks to see that this node is the root; if so, it throws
979 an appropriate exception. Then, it locks this node's parent, and calls a
980 recursive helper method that traverses the subtree rooted at this node. The
981 recursive method locks the node on which it was called, checks that it has not
982 already been removed, and then ensures that all of its children are cached: The
983 (|java.util.prefs.AbstractPreferences|) method is invoked and each returned
984 child name is checked for containment in the child-cache. If a child is not
985 already cached, the (|java.util.prefs.AbstractPreferences|) method is invoked
986 to create a Preferences instance for it, and this instance is put into the
987 child-cache. Then the helper method calls itself recursively on each node
988 contained in its child-cache. Next, it invokes
989 (|java.util.prefs.AbstractPreferences|) , marks itself as removed, and removes
990 itself from its parent's child-cache. Finally, if there are any node change
991 listeners, it enqueues a notification event for processing by the event
994 Note that the helper method is always invoked with all ancestors up to the
995 "closest non-removed ancestor" locked.
998 *java.util.prefs.AbstractPreferences.removeNodeChangeListener(NodeChangeListener)*
1000 public void removeNodeChangeListener(java.util.prefs.NodeChangeListener ncl)
1005 *java.util.prefs.AbstractPreferences.removeNodeSpi()*
1007 protected abstract void removeNodeSpi()
1008 throws |java.util.prefs.BackingStoreException|
1010 Removes this preference node, invalidating it and any preferences that it
1011 contains. The named child will have no descendants at the time this invocation
1012 is made (i.e., the (|java.util.prefs.Preferences|) method invokes this method
1013 repeatedly in a bottom-up fashion, removing each of a node's descendants before
1014 removing the node itself).
1016 This method is invoked with the lock held on this node and its parent (and all
1017 ancestors that are being removed as a result of a single invocation to
1018 (|java.util.prefs.Preferences|) ).
1020 The removal of a node needn't become persistent until the flush method is
1021 invoked on this node (or an ancestor).
1023 If this node throws a BackingStoreException, the exception will propagate out
1024 beyond the enclosing (|java.util.prefs.AbstractPreferences|) invocation.
1027 *java.util.prefs.AbstractPreferences.removePreferenceChangeListener(PreferenceChangeListener)*
1029 public void removePreferenceChangeListener(java.util.prefs.PreferenceChangeListener pcl)
1034 *java.util.prefs.AbstractPreferences.removeSpi(String)*
1036 protected abstract void removeSpi(java.lang.String key)
1038 Remove the association (if any) for the specified key at this preference node.
1039 It is guaranteed that key is non-null. Also, it is guaranteed that this node
1040 has not been removed. (The implementor needn't check for either of these
1043 This method is invoked with the lock on this node held.
1046 *java.util.prefs.AbstractPreferences.sync()*
1049 throws |java.util.prefs.BackingStoreException|
1051 Implements the sync method as per the specification in
1052 (|java.util.prefs.Preferences|) .
1054 This implementation calls a recursive helper method that locks this node,
1055 invokes syncSpi() on it, unlocks this node, and recursively invokes this method
1056 on each "cached child." A cached child is a child of this node that has been
1057 created in this VM and not subsequently removed. In effect, this method does a
1058 depth first traversal of the "cached subtree" rooted at this node, calling
1059 syncSpi() on each node in the subTree while only that node is locked. Note that
1060 syncSpi() is invoked top-down.
1063 *java.util.prefs.AbstractPreferences.syncSpi()*
1065 protected abstract void syncSpi()
1066 throws |java.util.prefs.BackingStoreException|
1068 This method is invoked with this node locked. The contract of this method is to
1069 synchronize any cached preferences stored at this node with any stored in the
1070 backing store. (It is perfectly possible that this node does not exist on the
1071 backing store, either because it has been deleted by another VM, or because it
1072 has not yet been created.) Note that this method should not synchronize the
1073 preferences in any subnodes of this node. If the backing store naturally syncs
1074 an entire subtree at once, the implementer is encouraged to override sync(),
1075 rather than merely overriding this method.
1077 If this node throws a BackingStoreException, the exception will propagate out
1078 beyond the enclosing (|java.util.prefs.AbstractPreferences|) invocation.
1081 *java.util.prefs.AbstractPreferences.toString()*
1083 public |java.lang.String| toString()
1085 Returns the absolute path name of this preferences node.