Preferences


1   /*
2    * $Header: /cvshome/build/org.osgi.service.prefs/src/org/osgi/service/prefs/Preferences.java,v 1.11 2006/07/11 00:54:04 hargrave Exp $
3    * 
4    * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
5    * 
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.osgi.service.prefs;
19  
20  /**
21   * A node in a hierarchical collection of preference data.
22   * 
23   * <p>
24   * This interface allows applications to store and retrieve user and system
25   * preference data. This data is stored persistently in an
26   * implementation-dependent backing store. Typical implementations include flat
27   * files, OS-specific registries, directory servers and SQL databases.
28   * 
29   * <p>
30   * For each bundle, there is a separate tree of nodes for each user, and one for
31   * system preferences. The precise description of "user" and "system" will vary
32   * from one bundle to another. Typical information stored in the user preference
33   * tree might include font choice, and color choice for a bundle which interacts
34   * with the user via a servlet. Typical information stored in the system
35   * preference tree might include installation data, or things like high score
36   * information for a game program.
37   * 
38   * <p>
39   * Nodes in a preference tree are named in a similar fashion to directories in a
40   * hierarchical file system. Every node in a preference tree has a <i>node name
41   * </i> (which is not necessarily unique), a unique <i>absolute path name </i>,
42   * and a path name <i>relative </i> to each ancestor including itself.
43   * 
44   * <p>
45   * The root node has a node name of the empty <code>String</code> object ("").
46   * Every other node has an arbitrary node name, specified at the time it is
47   * created. The only restrictions on this name are that it cannot be the empty
48   * string, and it cannot contain the slash character ('/').
49   * 
50   * <p>
51   * The root node has an absolute path name of <code>"/"</code>. Children of the
52   * root node have absolute path names of <code>"/" + </code> <i>&lt;node name&gt;
53   * </i>. All other nodes have absolute path names of <i>&lt;parent's absolute
54   * path name&gt; </i> <code> + "/" + </code> <i>&lt;node name&gt; </i>. Note that
55   * all absolute path names begin with the slash character.
56   * 
57   * <p>
58   * A node <i>n </i>'s path name relative to its ancestor <i>a </i> is simply the
59   * string that must be appended to <i>a </i>'s absolute path name in order to
60   * form <i>n </i>'s absolute path name, with the initial slash character (if
61   * present) removed. Note that:
62   * <ul>
63   * <li>No relative path names begin with the slash character.
64   * <li>Every node's path name relative to itself is the empty string.
65   * <li>Every node's path name relative to its parent is its node name (except
66   * for the root node, which does not have a parent).
67   * <li>Every node's path name relative to the root is its absolute path name
68   * with the initial slash character removed.
69   * </ul>
70   * 
71   * <p>
72   * Note finally that:
73   * <ul>
74   * <li>No path name contains multiple consecutive slash characters.
75   * <li>No path name with the exception of the root's absolute path name end in
76   * the slash character.
77   * <li>Any string that conforms to these two rules is a valid path name.
78   * </ul>
79   * 
80   * <p>
81   * Each <code>Preference</code> node has zero or more properties associated with
82   * it, where a property consists of a name and a value. The bundle writer is
83   * free to choose any appropriate names for properties. Their values can be of
84   * type <code>String</code>,<code>long</code>,<code>int</code>,<code>boolean</code>,
85   * <code>byte[]</code>,<code>float</code>, or <code>double</code> but they can
86   * always be accessed as if they were <code>String</code> objects.
87   * 
88   * <p>
89   * All node name and property name comparisons are case-sensitive.
90   * 
91   * <p>
92   * All of the methods that modify preference data are permitted to operate
93   * asynchronously; they may return immediately, and changes will eventually
94   * propagate to the persistent backing store, with an implementation-dependent
95   * delay. The <code>flush</code> method may be used to synchronously force updates
96   * to the backing store.
97   * 
98   * <p>
99   * Implementations must automatically attempt to flush to the backing store any
100  * pending updates for a bundle's preferences when the bundle is stopped or
101  * otherwise ungets the Preferences Service.
102  * 
103  * <p>
104  * The methods in this class may be invoked concurrently by multiple threads in
105  * a single Java Virtual Machine (JVM) without the need for external
106  * synchronization, and the results will be equivalent to some serial execution.
107  * If this class is used concurrently <i>by multiple JVMs </i> that store their
108  * preference data in the same backing store, the data store will not be
109  * corrupted, but no other guarantees are made concerning the consistency of the
110  * preference data.
111  * 
112  * 
113  * @version $Revision: 1.11 $
114  */
115 public interface Preferences {
116     /**
117      * Associates the specified value with the specified key in this node.
118      * 
119      * @param key key with which the specified value is to be associated.
120      * @param value value to be associated with the specified key.
121      * @throws NullPointerException if <code>key</code> or <code>value</code> is
122      *         <code>null</code>.
123      * @throws IllegalStateException if this node (or an ancestor) has been
124      *         removed with the {@link #removeNode()} method.
125      */
126     public void put(String   key, String   value);
127 
128     /**
129      * Returns the value associated with the specified <code>key</code> in this
130      * node. Returns the specified default if there is no value associated with
131      * the <code>key</code>, or the backing store is inaccessible.
132      * 
133      * @param key key whose associated value is to be returned.
134      * @param def the value to be returned in the event that this node has no
135      *        value associated with <code>key</code> or the backing store is
136      *        inaccessible.
137      * @return the value associated with <code>key</code>, or <code>def</code> if
138      *         no value is associated with <code>key</code>.
139      * @throws IllegalStateException if this node (or an ancestor) has been
140      *         removed with the {@link #removeNode()} method.
141      * @throws NullPointerException if <code>key</code> is <code>null</code>. (A
142      *         <code>null</code> default <i>is </i> permitted.)
143      */
144     public String   get(String   key, String   def);
145 
146     /**
147      * Removes the value associated with the specified <code>key</code> in this
148      * node, if any.
149      * 
150      * @param key key whose mapping is to be removed from this node.
151      * @see #get(String,String)
152      * @throws IllegalStateException if this node (or an ancestor) has been
153      *         removed with the {@link #removeNode()} method.
154      */
155     public void remove(String   key);
156 
157     /**
158      * Removes all of the properties (key-value associations) in this node. This
159      * call has no effect on any descendants of this node.
160      * 
161      * @throws BackingStoreException if this operation cannot be completed due
162      *         to a failure in the backing store, or inability to communicate
163      *         with it.
164      * @throws IllegalStateException if this node (or an ancestor) has been
165      *         removed with the {@link #removeNode()} method.
166      * @see #remove(String)
167      */
168     public void clear() throws BackingStoreException;
169 
170     /**
171      * Associates a <code>String</code> object representing the specified
172      * <code>int</code> value with the specified <code>key</code> in this node. The
173      * associated string is the one that would be returned if the <code>int</code>
174      * value were passed to <code>Integer.toString(int)</code>. This method is
175      * intended for use in conjunction with {@link #getInt} method.
176      * 
177      * <p>
178      * Implementor's note: it is <i>not </i> necessary that the property value
179      * be represented by a <code>String</code> object in the backing store. If the
180      * backing store supports integer values, it is not unreasonable to use
181      * them. This implementation detail is not visible through the
182      * <code>Preferences</code> API, which allows the value to be read as an
183      * <code>int</code> (with <code>getInt</code> or a <code>String</code> (with
184      * <code>get</code>) type.
185      * 
186      * @param key key with which the string form of value is to be associated.
187      * @param value <code>value</code> whose string form is to be associated with
188      *        <code>key</code>.
189      * @throws NullPointerException if <code>key</code> is <code>null</code>.
190      * @throws IllegalStateException if this node (or an ancestor) has been
191      *         removed with the {@link #removeNode()} method.
192      * @see #getInt(String,int)
193      */
194     public void putInt(String   key, int value);
195 
196     /**
197      * Returns the <code>int</code> value represented by the <code>String</code>
198      * object associated with the specified <code>key</code> in this node. The
199      * <code>String</code> object is converted to an <code>int</code> as by
200      * <code>Integer.parseInt(String)</code>. Returns the specified default if
201      * there is no value associated with the <code>key</code>, the backing store
202      * is inaccessible, or if <code>Integer.parseInt(String)</code> would throw a
203      * <code>NumberFormatException</code> if the associated <code>value</code> were
204      * passed. This method is intended for use in conjunction with the
205      * {@link #putInt} method.
206      * 
207      * @param key key whose associated value is to be returned as an
208      *        <code>int</code>.
209      * @param def the value to be returned in the event that this node has no
210      *        value associated with <code>key</code> or the associated value
211      *        cannot be interpreted as an <code>int</code> or the backing store is
212      *        inaccessible.
213      * @return the <code>int</code> value represented by the <code>String</code>
214      *         object associated with <code>key</code> in this node, or
215      *         <code>def</code> if the associated value does not exist or cannot
216      *         be interpreted as an <code>int</code> type.
217      * @throws NullPointerException if <code>key</code> is <code>null</code>.
218      * @throws IllegalStateException if this node (or an ancestor) has been
219      *         removed with the {@link #removeNode()} method.
220      * @see #putInt(String,int)
221      * @see #get(String,String)
222      */
223     public int getInt(String   key, int def);
224 
225     /**
226      * Associates a <code>String</code> object representing the specified
227      * <code>long</code> value with the specified <code>key</code> in this node. The
228      * associated <code>String</code> object is the one that would be returned if
229      * the <code>long</code> value were passed to <code>Long.toString(long)</code>.
230      * This method is intended for use in conjunction with the {@link #getLong}
231      * method.
232      * 
233      * <p>
234      * Implementor's note: it is <i>not </i> necessary that the <code>value</code>
235      * be represented by a <code>String</code> type in the backing store. If the
236      * backing store supports <code>long</code> values, it is not unreasonable to
237      * use them. This implementation detail is not visible through the <code>
238      * Preferences</code> API, which allows the value to be read as a
239      * <code>long</code> (with <code>getLong</code> or a <code>String</code> (with
240      * <code>get</code>) type.
241      * 
242      * @param key <code>key</code> with which the string form of <code>value</code>
243      *        is to be associated.
244      * @param value <code>value</code> whose string form is to be associated with
245      *        <code>key</code>.
246      * @throws NullPointerException if <code>key</code> is <code>null</code>.
247      * @throws IllegalStateException if this node (or an ancestor) has been
248      *         removed with the {@link #removeNode()} method.
249      * @see #getLong(String,long)
250      */
251     public void putLong(String   key, long value);
252 
253     /**
254      * Returns the <code>long</code> value represented by the <code>String</code>
255      * object associated with the specified <code>key</code> in this node. The
256      * <code>String</code> object is converted to a <code>long</code> as by
257      * <code>Long.parseLong(String)</code>. Returns the specified default if
258      * there is no value associated with the <code>key</code>, the backing store
259      * is inaccessible, or if <code>Long.parseLong(String)</code> would throw a
260      * <code>NumberFormatException</code> if the associated <code>value</code> were
261      * passed. This method is intended for use in conjunction with the
262      * {@link #putLong} method.
263      * 
264      * @param key <code>key</code> whose associated value is to be returned as a
265      *        <code>long</code> value.
266      * @param def the value to be returned in the event that this node has no
267      *        value associated with <code>key</code> or the associated value
268      *        cannot be interpreted as a <code>long</code> type or the backing
269      *        store is inaccessible.
270      * @return the <code>long</code> value represented by the <code>String</code>
271      *         object associated with <code>key</code> in this node, or
272      *         <code>def</code> if the associated value does not exist or cannot
273      *         be interpreted as a <code>long</code> type.
274      * @throws NullPointerException if <code>key</code> is <code>null</code>.
275      * @throws IllegalStateException if this node (or an ancestor) has been
276      *         removed with the {@link #removeNode()} method.
277      * @see #putLong(String,long)
278      * @see #get(String,String)
279      */
280     public long getLong(String   key, long def);
281 
282     /**
283      * Associates a <code>String</code> object representing the specified
284      * <code>boolean</code> value with the specified key in this node. The
285      * associated string is "true" if the value is <code>true</code>, and "false"
286      * if it is <code>false</code>. This method is intended for use in
287      * conjunction with the {@link #getBoolean} method.
288      * 
289      * <p>
290      * Implementor's note: it is <i>not </i> necessary that the value be
291      * represented by a string in the backing store. If the backing store
292      * supports <code>boolean</code> values, it is not unreasonable to use them.
293      * This implementation detail is not visible through the <code>Preferences
294      * </code> API, which allows the value to be read as a <code>boolean</code>
295      * (with <code>getBoolean</code>) or a <code>String</code> (with <code>get</code>)
296      * type.
297      * 
298      * @param key <code>key</code> with which the string form of value is to be
299      *        associated.
300      * @param value value whose string form is to be associated with
301      *        <code>key</code>.
302      * @throws NullPointerException if <code>key</code> is <code>null</code>.
303      * @throws IllegalStateException if this node (or an ancestor) has been
304      *         removed with the {@link #removeNode()} method.
305      * @see #getBoolean(String,boolean)
306      * @see #get(String,String)
307      */
308     public void putBoolean(String   key, boolean value);
309 
310     /**
311      * Returns the <code>boolean</code> value represented by the <code>String</code>
312      * object associated with the specified <code>key</code> in this node. Valid
313      * strings are "true", which represents <code>true</code>, and "false", which
314      * represents <code>false</code>. Case is ignored, so, for example, "TRUE"
315      * and "False" are also valid. This method is intended for use in
316      * conjunction with the {@link #putBoolean} method.
317      * 
318      * <p>
319      * Returns the specified default if there is no value associated with the
320      * <code>key</code>, the backing store is inaccessible, or if the associated
321      * value is something other than "true" or "false", ignoring case.
322      * 
323      * @param key <code>key</code> whose associated value is to be returned as a
324      *        <code>boolean</code>.
325      * @param def the value to be returned in the event that this node has no
326      *        value associated with <code>key</code> or the associated value
327      *        cannot be interpreted as a <code>boolean</code> or the backing store
328      *        is inaccessible.
329      * @return the <code>boolean</code> value represented by the <code>String</code>
330      *         object associated with <code>key</code> in this node, or
331      *         <code>null</code> if the associated value does not exist or cannot
332      *         be interpreted as a <code>boolean</code>.
333      * @throws NullPointerException if <code>key</code> is <code>null</code>.
334      * @throws IllegalStateException if this node (or an ancestor) has been
335      *         removed with the {@link #removeNode()} method.
336      * @see #get(String,String)
337      * @see #putBoolean(String,boolean)
338      */
339     public boolean getBoolean(String   key, boolean def);
340 
341     /**
342      * Associates a <code>String</code> object representing the specified
343      * <code>float</code> value with the specified <code>key</code> in this node.
344      * The associated <code>String</code> object is the one that would be returned
345      * if the <code>float</code> value were passed to
346      * <code>Float.toString(float)</code>. This method is intended for use in
347      * conjunction with the {@link #getFloat} method.
348      * 
349      * <p>
350      * Implementor's note: it is <i>not </i> necessary that the value be
351      * represented by a string in the backing store. If the backing store
352      * supports <code>float</code> values, it is not unreasonable to use them.
353      * This implementation detail is not visible through the <code>Preferences
354      * </code> API, which allows the value to be read as a <code>float</code> (with
355      * <code>getFloat</code>) or a <code>String</code> (with <code>get</code>) type.
356      * 
357      * @param key <code>key</code> with which the string form of value is to be
358      *        associated.
359      * @param value value whose string form is to be associated with
360      *        <code>key</code>.
361      * @throws NullPointerException if <code>key</code> is <code>null</code>.
362      * @throws IllegalStateException if this node (or an ancestor) has been
363      *         removed with the {@link #removeNode()} method.
364      * @see #getFloat(String,float)
365      */
366     public void putFloat(String   key, float value);
367 
368     /**
369      * Returns the float <code>value</code> represented by the <code>String</code>
370      * object associated with the specified <code>key</code> in this node. The
371      * <code>String</code> object is converted to a <code>float</code> value as by
372      * <code>Float.parseFloat(String)</code>. Returns the specified default if
373      * there is no value associated with the <code>key</code>, the backing store
374      * is inaccessible, or if <code>Float.parseFloat(String)</code> would throw a
375      * <code>NumberFormatException</code> if the associated value were passed.
376      * This method is intended for use in conjunction with the {@link #putFloat}
377      * method.
378      * 
379      * @param key <code>key</code> whose associated value is to be returned as a
380      *        <code>float</code> value.
381      * @param def the value to be returned in the event that this node has no
382      *        value associated with <code>key</code> or the associated value
383      *        cannot be interpreted as a <code>float</code> type or the backing
384      *        store is inaccessible.
385      * @return the <code>float</code> value represented by the string associated
386      *         with <code>key</code> in this node, or <code>def</code> if the
387      *         associated value does not exist or cannot be interpreted as a
388      *         <code>float</code> type.
389      * @throws IllegalStateException if this node (or an ancestor) has been
390      *         removed with the {@link #removeNode()} method.
391      * @throws NullPointerException if <code>key</code> is <code>null</code>.
392      * @see #putFloat(String,float)
393      * @see #get(String,String)
394      */
395     public float getFloat(String   key, float def);
396 
397     /**
398      * Associates a <code>String</code> object representing the specified
399      * <code>double</code> value with the specified <code>key</code> in this node.
400      * The associated <code>String</code> object is the one that would be returned
401      * if the <code>double</code> value were passed to
402      * <code>Double.toString(double)</code>. This method is intended for use in
403      * conjunction with the {@link #getDouble} method
404      * 
405      * <p>
406      * Implementor's note: it is <i>not </i> necessary that the value be
407      * represented by a string in the backing store. If the backing store
408      * supports <code>double</code> values, it is not unreasonable to use them.
409      * This implementation detail is not visible through the <code>Preferences
410      * </code> API, which allows the value to be read as a <code>double</code> (with
411      * <code>getDouble</code>) or a <code>String</code> (with <code>get</code>)
412      * type.
413      * 
414      * @param key <code>key</code> with which the string form of value is to be
415      *        associated.
416      * @param value value whose string form is to be associated with
417      *        <code>key</code>.
418      * @throws NullPointerException if <code>key</code> is <code>null</code>.
419      * @throws IllegalStateException if this node (or an ancestor) has been
420      *         removed with the {@link #removeNode()} method.
421      * @see #getDouble(String,double)
422      */
423     public void putDouble(String   key, double value);
424 
425     /**
426      * Returns the <code>double</code> value represented by the <code>String</code>
427      * object associated with the specified <code>key</code> in this node. The
428      * <code>String</code> object is converted to a <code>double</code> value as by
429      * <code>Double.parseDouble(String)</code>. Returns the specified default if
430      * there is no value associated with the <code>key</code>, the backing store
431      * is inaccessible, or if <code>Double.parseDouble(String)</code> would throw
432      * a <code>NumberFormatException</code> if the associated value were passed.
433      * This method is intended for use in conjunction with the
434      * {@link #putDouble} method.
435      * 
436      * @param key <code>key</code> whose associated value is to be returned as a
437      *        <code>double</code> value.
438      * @param def the value to be returned in the event that this node has no
439      *        value associated with <code>key</code> or the associated value
440      *        cannot be interpreted as a <code>double</code> type or the backing
441      *        store is inaccessible.
442      * @return the <code>double</code> value represented by the <code>String</code>
443      *         object associated with <code>key</code> in this node, or
444      *         <code>def</code> if the associated value does not exist or cannot
445      *         be interpreted as a <code>double</code> type.
446      * @throws IllegalStateException if this node (or an ancestor) has been
447      *         removed with the the {@link #removeNode()} method.
448      * @throws NullPointerException if <code>key</code> is <code>null</code>.
449      * @see #putDouble(String,double)
450      * @see #get(String,String)
451      */
452     public double getDouble(String   key, double def);
453 
454     /**
455      * Associates a <code>String</code> object representing the specified
456      * <code>byte[]</code> with the specified <code>key</code> in this node. The
457      * associated <code>String</code> object the <i>Base64 </i> encoding of the
458      * <code>byte[]</code>, as defined in <a
459      * HREF="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045 </a>, Section 6.8,
460      * with one minor change: the string will consist solely of characters from
461      * the <i>Base64 Alphabet </i>; it will not contain any newline characters.
462      * This method is intended for use in conjunction with the
463      * {@link #getByteArray} method.
464      * 
465      * <p>
466      * Implementor's note: it is <i>not </i> necessary that the value be
467      * represented by a <code>String</code> type in the backing store. If the
468      * backing store supports <code>byte[]</code> values, it is not unreasonable
469      * to use them. This implementation detail is not visible through the <code>
470      * Preferences</code> API, which allows the value to be read as an a
471      * <code>byte[]</code> object (with <code>getByteArray</code>) or a
472      * <code>String</code> object (with <code>get</code>).
473      * 
474      * @param key <code>key</code> with which the string form of <code>value</code>
475      *        is to be associated.
476      * @param value <code>value</code> whose string form is to be associated with
477      *        <code>key</code>.
478      * @throws NullPointerException if <code>key</code> or <code>value</code> is
479      *         <code>null</code>.
480      * @throws IllegalStateException if this node (or an ancestor) has been
481      *         removed with the {@link #removeNode()} method.
482      * @see #getByteArray(String,byte[])
483      * @see #get(String,String)
484      */
485     public void putByteArray(String   key, byte[] value);
486 
487     /**
488      * Returns the <code>byte[]</code> value represented by the <code>String</code>
489      * object associated with the specified <code>key</code> in this node. Valid
490      * <code>String</code> objects are <i>Base64 </i> encoded binary data, as
491      * defined in <a HREF="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045 </a>,
492      * Section 6.8, with one minor change: the string must consist solely of
493      * characters from the <i>Base64 Alphabet </i>; no newline characters or
494      * extraneous characters are permitted. This method is intended for use in
495      * conjunction with the {@link #putByteArray} method.
496      * 
497      * <p>
498      * Returns the specified default if there is no value associated with the
499      * <code>key</code>, the backing store is inaccessible, or if the associated
500      * value is not a valid Base64 encoded byte array (as defined above).
501      * 
502      * @param key <code>key</code> whose associated value is to be returned as a
503      *        <code>byte[]</code> object.
504      * @param def the value to be returned in the event that this node has no
505      *        value associated with <code>key</code> or the associated value
506      *        cannot be interpreted as a <code>byte[]</code> type, or the backing
507      *        store is inaccessible.
508      * @return the <code>byte[]</code> value represented by the <code>String</code>
509      *         object associated with <code>key</code> in this node, or
510      *         <code>def</code> if the associated value does not exist or cannot
511      *         be interpreted as a <code>byte[]</code>.
512      * @throws NullPointerException if <code>key</code> is <code>null</code>. (A
513      *         <code>null</code> value for <code>def</code> <i>is </i> permitted.)
514      * @throws IllegalStateException if this node (or an ancestor) has been
515      *         removed with the {@link #removeNode()} method.
516      * @see #get(String,String)
517      * @see #putByteArray(String,byte[])
518      */
519     public byte[] getByteArray(String   key, byte[] def);
520 
521     /**
522      * Returns all of the keys that have an associated value in this node. (The
523      * returned array will be of size zero if this node has no preferences and
524      * not <code>null</code>!)
525      * 
526      * @return an array of the keys that have an associated value in this node.
527      * @throws BackingStoreException if this operation cannot be completed due
528      *         to a failure in the backing store, or inability to communicate
529      *         with it.
530      * @throws IllegalStateException if this node (or an ancestor) has been
531      *         removed with the {@link #removeNode()} method.
532      */
533     public String  [] keys() throws BackingStoreException;
534 
535     /**
536      * Returns the names of the children of this node. (The returned array will
537      * be of size zero if this node has no children and not <code>null</code>!)
538      * 
539      * @return the names of the children of this node.
540      * @throws BackingStoreException if this operation cannot be completed due
541      *         to a failure in the backing store, or inability to communicate
542      *         with it.
543      * @throws IllegalStateException if this node (or an ancestor) has been
544      *         removed with the {@link #removeNode()} method.
545      */
546     public String  [] childrenNames() throws BackingStoreException;
547 
548     /**
549      * Returns the parent of this node, or <code>null</code> if this is the root.
550      * 
551      * @return the parent of this node.
552      * @throws IllegalStateException if this node (or an ancestor) has been
553      *         removed with the {@link #removeNode()} method.
554      */
555     public Preferences parent();
556 
557     /**
558      * Returns a named <code>Preferences</code> object (node), creating it and any
559      * of its ancestors if they do not already exist. Accepts a relative or
560      * absolute pathname. Absolute pathnames (which begin with <code>'/'</code>)
561      * are interpreted relative to the root of this node. Relative pathnames
562      * (which begin with any character other than <code>'/'</code>) are
563      * interpreted relative to this node itself. The empty string (<code>""</code>)
564      * is a valid relative pathname, referring to this node itself.
565      * 
566      * <p>
567      * If the returned node did not exist prior to this call, this node and any
568      * ancestors that were created by this call are not guaranteed to become
569      * persistent until the <code>flush</code> method is called on the returned
570      * node (or one of its descendants).
571      * 
572      * @param pathName the path name of the <code>Preferences</code> object to
573      *        return.
574      * @return the specified <code>Preferences</code> object.
575      * @throws IllegalArgumentException if the path name is invalid.
576      * @throws IllegalStateException if this node (or an ancestor) has been
577      *         removed with the {@link #removeNode()} method.
578      * @throws NullPointerException if path name is <code>null</code>.
579      * @see #flush()
580      */
581     public Preferences node(String   pathName);
582 
583     /**
584      * Returns true if the named node exists. Accepts a relative or absolute
585      * pathname. Absolute pathnames (which begin with <code>'/'</code>) are
586      * interpreted relative to the root of this node. Relative pathnames (which
587      * begin with any character other than <code>'/'</code>) are interpreted
588      * relative to this node itself. The pathname <code>""</code> is valid, and
589      * refers to this node itself.
590      * 
591      * <p>
592      * If this node (or an ancestor) has already been removed with the
593      * {@link #removeNode()} method, it <i>is </i> legal to invoke this method,
594      * but only with the pathname <code>""</code>; the invocation will return
595      * <code>false</code>. Thus, the idiom <code>p.nodeExists("")</code> may be
596      * used to test whether <code>p</code> has been removed.
597      * 
598      * @param pathName the path name of the node whose existence is to be
599      *        checked.
600      * @return true if the specified node exists.
601      * @throws BackingStoreException if this operation cannot be completed due
602      *         to a failure in the backing store, or inability to communicate
603      *         with it.
604      * @throws IllegalStateException if this node (or an ancestor) has been
605      *         removed with the {@link #removeNode()} method and
606      *         <code>pathname</code> is not the empty string (<code>""</code>).
607      * @throws IllegalArgumentException if the path name is invalid (i.e., it
608      *         contains multiple consecutive slash characters, or ends with a
609      *         slash character and is more than one character long).
610      */
611     public boolean nodeExists(String   pathName)
612             throws BackingStoreException;
613 
614     /**
615      * Removes this node and all of its descendants, invalidating any properties
616      * contained in the removed nodes. Once a node has been removed, attempting
617      * any method other than <code>name()</code>,<code>absolutePath()</code> or
618      * <code>nodeExists("")</code> on the corresponding <code>Preferences</code>
619      * instance will fail with an <code>IllegalStateException</code>. (The
620      * methods defined on <code>Object</code> can still be invoked on a node after
621      * it has been removed; they will not throw <code>IllegalStateException</code>.)
622      * 
623      * <p>
624      * The removal is not guaranteed to be persistent until the <code>flush</code>
625      * method is called on the parent of this node.
626      * 
627      * @throws IllegalStateException if this node (or an ancestor) has already
628      *         been removed with the {@link #removeNode()} method.
629      * @throws BackingStoreException if this operation cannot be completed due
630      *         to a failure in the backing store, or inability to communicate
631      *         with it.
632      * @see #flush()
633      */
634     public void removeNode() throws BackingStoreException;
635 
636     /**
637      * Returns this node's name, relative to its parent.
638      * 
639      * @return this node's name, relative to its parent.
640      */
641     public String   name();
642 
643     /**
644      * Returns this node's absolute path name. Note that:
645      * <ul>
646      * <li>Root node - The path name of the root node is <code>"/"</code>.
647      * <li>Slash at end - Path names other than that of the root node may not
648      * end in slash (<code>'/'</code>).
649      * <li>Unusual names -<code>"."</code> and <code>".."</code> have <i>no </i>
650      * special significance in path names.
651      * <li>Illegal names - The only illegal path names are those that contain
652      * multiple consecutive slashes, or that end in slash and are not the root.
653      * </ul>
654      * 
655      * @return this node's absolute path name.
656      */
657     public String   absolutePath();
658 
659     /**
660      * Forces any changes in the contents of this node and its descendants to
661      * the persistent store.
662      * 
663      * <p>
664      * Once this method returns successfully, it is safe to assume that all
665      * changes made in the subtree rooted at this node prior to the method
666      * invocation have become permanent.
667      * 
668      * <p>
669      * Implementations are free to flush changes into the persistent store at
670      * any time. They do not need to wait for this method to be called.
671      * 
672      * <p>
673      * When a flush occurs on a newly created node, it is made persistent, as
674      * are any ancestors (and descendants) that have yet to be made persistent.
675      * Note however that any properties value changes in ancestors are <i>not
676      * </i> guaranteed to be made persistent.
677      * 
678      * @throws BackingStoreException if this operation cannot be completed due
679      *         to a failure in the backing store, or inability to communicate
680      *         with it.
681      * @throws IllegalStateException if this node (or an ancestor) has been
682      *         removed with the {@link #removeNode()} method.
683      * @see #sync()
684      */
685     public void flush() throws BackingStoreException;
686 
687     /**
688      * Ensures that future reads from this node and its descendants reflect any
689      * changes that were committed to the persistent store (from any VM) prior
690      * to the <code>sync</code> invocation. As a side-effect, forces any changes
691      * in the contents of this node and its descendants to the persistent store,
692      * as if the <code>flush</code> method had been invoked on this node.
693      * 
694      * @throws BackingStoreException if this operation cannot be completed due
695      *         to a failure in the backing store, or inability to communicate
696      *         with it.
697      * @throws IllegalStateException if this node (or an ancestor) has been
698      *         removed with the {@link #removeNode()} method.
699      * @see #flush()
700      */
701     public void sync() throws BackingStoreException;
702 }
703
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags