This interface allows applications to store and retrieve user and system * preference data. This data is stored * persistently in an implementation-dependent backing store. Typical * implementations include flat files, OS-specific registries, * directory servers and SQL databases. * *
For each bundle, there is a separate tree of nodes for * each user, and one for system preferences. The precise description of * "user" and "system" will vary from one bundle to another. Typical * information stored in the user preference tree might include font choice, * and color choice for a bundle which interacts with the user via a * servlet. Typical information stored in the system preference tree * might include installation data, or things like * high score information for a game program. * *
Nodes in a preference tree are named in a similar fashion to * directories in a hierarchical file system. Every node in a preference * tree has a node name (which is not necessarily unique), * a unique absolute path name, and a path name relative to each * ancestor including itself. * *
The root node has a node name of the empty String object (""). Every other * node has an arbitrary node name, specified at the time it is created. The * only restrictions on this name are that it cannot be the empty string, and * it cannot contain the slash character ('/'). * *
The root node has an absolute path name of "/". Children of * the root node have absolute path names of "/" + <node * name>. All other nodes have absolute path names of <parent's * absolute path name> + "/" + <node name>. * Note that all absolute path names begin with the slash character. * *
A node n's path name relative to its ancestor a * is simply the string that must be appended to a's absolute path name * in order to form n's absolute path name, with the initial slash * character (if present) removed. Note that: *
Note finally that: *
Each Preference node has zero or more properties * associated with it, where a property consists of a name and a value. * The bundle writer is free to choose any appropriate names for properties. * Their values can be of type String, long, int, boolean, * byte[], float, or double but * they can always be accessed as if they were String objects. * *
All node name and property name comparisons are case-sensitive. * *
All of the methods that modify preference data are permitted to * operate asynchronously; they may return immediately, and changes * will eventually propagate to the persistent backing store, with * an implementation-dependent delay. The flush method * may be used to synchronously force updates to the backing store. * *
Implementations must automatically attempt to flush * to the backing store any pending * updates for a bundle's preferences when the bundle is stopped or otherwise * ungets the Preferences Service. * *
The methods in this class may be invoked concurrently by multiple threads * in a single Java Virtual Machine (JVM) without the need for external * synchronization, and the * results will be equivalent to some serial execution. If this class is used * concurrently by multiple JVMs that store their preference data in * the same backing store, the data store will not be corrupted, but no * other guarantees are made concerning the consistency of the preference * data. * * * @version $Revision: 1.17 $ * @author Open Services Gateway Initiative */ public interface Preferences { /** * Associates the specified value with the specified key in this * node. * * @param key key with which the specified value is to be associated. * @param value value to be associated with the specified key. * @throws NullPointerException if key or value is null. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. */ public abstract void put(String key, String value); /** * Returns the value associated with the specified key in this * node. Returns the specified default if there is no value associated * with the key, or the backing store is inaccessible. * * @param key key whose associated value is to be returned. * @param def the value to be returned in the event that this * node has no value associated with key * or the backing store is inaccessible. * @return the value associated with key, or def * if no value is associated with key. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @throws NullPointerException if key is null. (A * null default is permitted.) */ public abstract String get(String key, String def); /** * Removes the value associated with the specified key in this * node, if any. * * @param key key whose mapping is to be removed from this node. * @see #get(String,String) * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. */ public abstract void remove(String key); /** * Removes all of the properties (key-value associations) in this * node. This call has no effect on any descendants * of this node. * * @throws BackingStoreException if this operation cannot be completed * due to a failure in the backing store, or inability to * communicate with it. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #remove(String) */ public abstract void clear() throws BackingStoreException; /** * Associates a String object representing the specified int value with the * specified key in this node. The associated string is the * one that would be returned if the int value were passed to * Integer.toString(int). This method is intended for use in * conjunction with {@link #getInt}method. * *
Implementor's note: it is not necessary that the property * value be represented by a String object in the backing store. If * the backing store supports integer values, it is not unreasonable to * use them. This implementation detail is not visible through the * Preferences API, which allows the value to be read as an int * (with getInt or a String (with get) type. * * @param key key with which the string form of value is to be associated. * @param value value whose string form is to be associated with key. * @throws NullPointerException if key is null. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #getInt(String,int) */ public abstract void putInt(String key, int value); /** * Returns the int value represented by the String object associated with the * specified key in this node. The String object is converted to * an int as by Integer.parseInt(String). Returns the * specified default if there is no value associated with the key, * the backing store is inaccessible, or if * Integer.parseInt(String) would throw a * NumberFormatException if the associated * value were passed. This * method is intended for use in conjunction with the {@link #putInt}method. * * @param key key whose associated value is to be returned as an int. * @param def the value to be returned in the event that this * node has no value associated with key * or the associated value cannot be interpreted as an int * or the backing store is inaccessible. * @return the int value represented by the String object associated with * key in this node, or def if the * associated value does not exist or cannot be interpreted as * an int type. * @throws NullPointerException if key is null. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #putInt(String,int) * @see #get(String,String) */ public abstract int getInt(String key, int def); /** * Associates a String object representing the specified long value with the * specified key in this node. The associated String object is the * one that would be returned if the long value were passed to * Long.toString(long). This method is intended for use in * conjunction with the {@link #getLong}method. * *
Implementor's note: it is not necessary that the * value be represented by a String type in the backing store. If * the backing store supports long values, it is not unreasonable to * use them. This implementation detail is not visible through the * Preferences API, which allows the value to be read as a long * (with getLong or a String (with get) type. * * @param key key with which the string form of value is to be associated. * @param value value whose string form is to be associated with key. * @throws NullPointerException if key is null. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #getLong(String,long) */ public abstract void putLong(String key, long value); /** * Returns the long value represented by the String object associated with the * specified key in this node. The String object is converted to * a long as by Long.parseLong(String). Returns the * specified default if there is no value associated with the key, * the backing store is inaccessible, or if * Long.parseLong(String) would throw a * NumberFormatException if the associated * value were passed. This * method is intended for use in conjunction with the {@link #putLong}method. * * @param key key whose associated value is to be returned as a long value. * @param def the value to be returned in the event that this * node has no value associated with key * or the associated value cannot be interpreted as a long type * or the backing store is inaccessible. * @return the long value represented by the String object associated with * key in this node, or def if the * associated value does not exist or cannot be interpreted as * a long type. * @throws NullPointerException if key is null. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #putLong(String,long) * @see #get(String,String) */ public abstract long getLong(String key, long def); /** * Associates a String object representing the specified boolean value with the * specified key in this node. The associated string is * "true" if the value is true, and "false" if it is * false. This method is intended for use in conjunction with * the {@link #getBoolean}method. * *
Implementor's note: it is not necessary that the * value be represented by a string in the backing store. If * the backing store supports boolean values, it is not unreasonable to * use them. This implementation detail is not visible through the * Preferences API, which allows the value to be read as a * boolean (with getBoolean) or a String (with get) type. * * @param key key with which the string form of value is to be associated. * @param value value whose string form is to be associated with key. * @throws NullPointerException if key is null. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #getBoolean(String,boolean) * @see #get(String,String) */ public abstract void putBoolean(String key, boolean value); /** * Returns the boolean value represented by the String object associated with the * specified key in this node. Valid strings * are "true", which represents true, and "false", which * represents false. Case is ignored, so, for example, "TRUE" * and "False" are also valid. This method is intended for use in * conjunction with the {@link #putBoolean}method. * *
Returns the specified default if there is no value * associated with the key, the backing store is inaccessible, or if the * associated value is something other than "true" or * "false", ignoring case. * * @param key key whose associated value is to be returned as a boolean. * @param def the value to be returned in the event that this * node has no value associated with key * or the associated value cannot be interpreted as a boolean * or the backing store is inaccessible. * @return the boolean value represented by the String object associated with * key in this node, or null if the * associated value does not exist or cannot be interpreted as * a boolean. * @throws NullPointerException if key is null. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #get(String,String) * @see #putBoolean(String,boolean) */ public abstract boolean getBoolean(String key, boolean def); /** * Associates a String object representing the specified float value with the * specified key in this node. The associated String object is the * one that would be returned if the float value were passed to * Float.toString(float). This method is intended for use in * conjunction with the {@link #getFloat}method. * *
Implementor's note: it is not necessary that the * value be represented by a string in the backing store. If * the backing store supports float values, it is not unreasonable to * use them. This implementation detail is not visible through the * Preferences API, which allows the value to be read as a * float (with getFloat) or a String (with get) type. * * @param key key with which the string form of value is to be associated. * @param value value whose string form is to be associated with key. * @throws NullPointerException if key is null. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #getFloat(String,float) */ public abstract void putFloat(String key, float value); /** * Returns the float value represented by the String object associated with the * specified key in this node. The String object is converted to an * int value as by Float.parseFloat(String). Returns the specified * default if there is no value associated with the key, the backing store * is inaccessible, or if Float.parseFloat(String) would throw a * NumberFormatException if the associated value were passed. * This method is intended for use in conjunction with the {@link #putFloat}method. * * @param key key whose associated value is to be returned as a float value. * @param def the value to be returned in the event that this * node has no value associated with key * or the associated value cannot be interpreted as a float type * or the backing store is inaccessible. * @return the float value represented by the string associated with * key in this node, or def if the * associated value does not exist or cannot be interpreted as * a float type. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @throws NullPointerException if key is null. * @see #putFloat(String,float) * @see #get(String,String) */ public abstract float getFloat(String key, float def); /** * Associates a String object representing the specified double value with the * specified key in this node. The associated String object is the * one that would be returned if the double value were passed to * Double.toString(double). This method is intended for use in * conjunction with the {@link #getDouble}method * *
Implementor's note: it is not necessary that the * value be represented by a string in the backing store. If * the backing store supports double values, it is not unreasonable to * use them. This implementation detail is not visible through the * Preferences API, which allows the value to be read as a * double (with getDouble) or a String (with get) type. * * @param key key with which the string form of value is to be associated. * @param value value whose string form is to be associated with key. * @throws NullPointerException if key is null. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #getDouble(String,double) */ public abstract void putDouble(String key, double value); /** * Returns the double value represented by the String object associated with the * specified key in this node. The String object is converted to an * int value as by Double.parseDouble(String). * Returns the specified * default if there is no value associated with the key, the backing store * is inaccessible, or if Double.parseDouble(String) would throw a * NumberFormatException if the associated value were passed. * This method is intended for use in conjunction with the {@link #putDouble} method. * * @param key key whose associated value is to be returned as a double value. * @param def the value to be returned in the event that this * node has no value associated with key * or the associated value cannot be interpreted as a double type * or the backing store is inaccessible. * @return the double value represented by the String object associated with * key in this node, or def if the * associated value does not exist or cannot be interpreted as * a double type. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the the {@link #removeNode()}method. * @throws NullPointerException if key is null. * @see #putDouble(String,double) * @see #get(String,String) */ public abstract double getDouble(String key, double def); /** * Associates a String object representing the specified byte[] with the * specified key in this node. The associated String object * the Base64 encoding of the byte[], as defined in RFC 2045, Section 6.8, * with one minor change: the string will consist solely of characters * from the Base64 Alphabet; it will not contain any newline * characters. * This method is intended for use in conjunction with * the {@link #getByteArray}method. * *
Implementor's note: it is not necessary that the * value be represented by a String type in the backing store. If * the backing store supports byte[] values, it is not unreasonable to * use them. This implementation detail is not visible through the * Preferences API, which allows the value to be read as an * a byte[] object (with getByteArray) or a String object * (with get). * * @param key key with which the string form of value is to be associated. * @param value value whose string form is to be associated with key. * @throws NullPointerException if key or value * is null. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #getByteArray(String,byte[]) * @see #get(String,String) */ public abstract void putByteArray(String key, byte[] value); /** * Returns the byte[] value represented by the String object associated with * the specified key in this node. Valid String objects are * Base64 encoded binary data, as defined in * RFC 2045, Section 6.8, * with one minor change: the string must consist solely of characters * from the Base64 Alphabet; no newline characters or * extraneous characters are permitted. This method is intended for use * in conjunction with the {@link #putByteArray} method. * *
Returns the specified default if there is no value * associated with the key, the backing store is inaccessible, or if the * associated value is not a valid Base64 encoded byte array * (as defined above). * * @param key key whose associated value is to be returned as a byte[] object. * @param def the value to be returned in the event that this * node has no value associated with key * or the associated value cannot be interpreted as a byte[] type, * or the backing store is inaccessible. * @return the byte[] value represented by the String object associated with * key in this node, or def if the * associated value does not exist or cannot be interpreted as * a byte[]. * @throws NullPointerException if key is null. (A * null value for def is permitted.) * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #get(String,String) * @see #putByteArray(String,byte[]) */ public abstract byte[] getByteArray(String key, byte[] def); /** * Returns all of the keys that have an associated value in this * node. (The returned array will be of size zero if * this node has no preferences and not null!) * * @return an array of the keys that have an associated value in this * node. * @throws BackingStoreException if this operation cannot be completed * due to a failure in the backing store, or inability to * communicate with it. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. */ public abstract String[] keys() throws BackingStoreException; /** * Returns the names of the children of this node. * (The returned array will be of size zero if this node has * no children and not null!) * * @return the names of the children of this node. * @throws BackingStoreException if this operation cannot be completed * due to a failure in the backing store, or inability to * communicate with it. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. */ public abstract String[] childrenNames() throws BackingStoreException; /** * Returns the parent of this node, or null if this is * the root. * * @return the parent of this node. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. */ public abstract Preferences parent(); /** * Returns a named Preferences object (node), creating it and any of its ancestors * if they do not already exist. Accepts a relative or absolute pathname. * Absolute pathnames (which begin with '/') are interpreted * relative to the root of this node. Relative pathnames * (which begin with any character other than '/') are * interpreted relative to this node itself. The empty string * ("") is a valid relative pathname, referring to this * node itself. * *
If the returned node did not exist prior to this call, this node and * any ancestors that were created by this call are not guaranteed * to become persistent until the flush method is called on * the returned node (or one of its descendants). * * @param pathName the path name of the Preferences object to return. * @return the specified Preferences object. * @throws IllegalArgumentException if the path name is invalid. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @throws NullPointerException if path name is null. * @see #flush() */ public abstract Preferences node(String pathName); /** * Returns true if the named node exists. Accepts a relative * or absolute pathname. Absolute pathnames (which begin with * '/') are interpreted relative to the root of this * node. Relative pathnames (which begin with any character other than * '/') are interpreted relative to this node itself. * The pathname "" is valid, and refers to this node * itself. * *
If this node (or an ancestor) has already been removed with the * {@link #removeNode()}method, it is legal to invoke this method, * but only with the pathname ""; the invocation will return * false. Thus, the idiom p.nodeExists("") may be * used to test whether p has been removed. * * @param pathName the path name of the node whose existence * is to be checked. * @return true if the specified node exists. * @throws BackingStoreException if this operation cannot be completed * due to a failure in the backing store, or inability to * communicate with it. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method and * pathname is not the empty string (""). * @throws IllegalArgumentException if the path name is invalid * (i.e., it contains multiple consecutive slash * characters, or ends with a slash character and is more than * one character long). */ public abstract boolean nodeExists(String pathName) throws BackingStoreException; /** * Removes this node and all of its descendants, invalidating * any properties contained in the removed nodes. Once a node has been * removed, attempting any method other than name(), * absolutePath() or * nodeExists("") on the corresponding Preferences * instance will fail with an IllegalStateException. (The * methods defined on Object can still be invoked on a node after * it has been removed; they will not throw * IllegalStateException.) * *
The removal is not guaranteed to be persistent until the * flush method is called on the parent of this node. * (It is illegal to remove the root node.) * * @throws IllegalStateException if this node (or an ancestor) has already * been removed with the {@link #removeNode()}method. * @throws RuntimeException if this is a root node. * @throws BackingStoreException if this operation cannot be * completed due to a failure in the backing store, or * inability to communicate with it. * @see #flush() */ public abstract void removeNode() throws BackingStoreException; /** * Returns this node's name, relative to its parent. * * @return this node's name, relative to its parent. */ public abstract String name(); /** * Returns this node's absolute path name. Note that: *
Once this method returns * successfully, it is safe to assume that all changes made in the * subtree rooted at this node prior to the method invocation have become * permanent. * *
Implementations are free to flush changes into the persistent store * at any time. They do not need to wait for this method to be called. * *
When a flush occurs on a newly created node, it is made persistent, * as are any ancestors (and descendants) that have yet to be made * persistent. Note however that any properties value changes in * ancestors are not guaranteed to be made persistent. * * @throws BackingStoreException if this operation cannot be completed * due to a failure in the backing store, or inability to * communicate with it. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #sync() */ public abstract void flush() throws BackingStoreException; /** * Ensures that future reads from this node and its * descendants reflect any changes that were committed to the persistent * store (from any VM) prior to the sync invocation. As a * side-effect, forces any changes in the contents of this node * and its descendants to the persistent store, as if the flush * method had been invoked on this node. * * @throws BackingStoreException if this operation cannot be completed * due to a failure in the backing store, or inability to * communicate with it. * @throws IllegalStateException if this node (or an ancestor) has been * removed with the {@link #removeNode()}method. * @see #flush() */ public abstract void sync() throws BackingStoreException; }