org.osgi.service.prefs.Preferences Maven / Gradle / Ivy
Show all versions of org.osgi.compendium Show documentation
/*
* Copyright (c) OSGi Alliance (2001, 2008). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.service.prefs;
/**
* A node in a hierarchical collection of preference data.
*
*
* 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:
*
* - No relative path names begin with the slash character.
*
- Every node's path name relative to itself is the empty string.
*
- Every node's path name relative to its parent is its node name (except
* for the root node, which does not have a parent).
*
- Every node's path name relative to the root is its absolute path name
* with the initial slash character removed.
*
*
*
* Note finally that:
*
* - No path name contains multiple consecutive slash characters.
*
- No path name with the exception of the root's absolute path name end in
* the slash character.
*
- Any string that conforms to these two rules is a valid path name.
*
*
*
* 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: 5673 $
*/
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 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 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 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 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 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 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 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 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 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 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 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 a float 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 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 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 a double 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 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 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 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 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 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 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 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 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.
*
* @throws IllegalStateException if this node (or an ancestor) has already
* been removed with the {@link #removeNode()} method.
* @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 void removeNode() throws BackingStoreException;
/**
* Returns this node's name, relative to its parent.
*
* @return this node's name, relative to its parent.
*/
public String name();
/**
* Returns this node's absolute path name. Note that:
*
* - Root node - The path name of the root node is
"/".
* - Slash at end - Path names other than that of the root node may not
* end in slash (
'/').
* - Unusual names -
"." and ".." have no
* special significance in path names.
* - Illegal names - The only illegal path names are those that contain
* multiple consecutive slashes, or that end in slash and are not the root.
*
*
* @return this node's absolute path name.
*/
public String absolutePath();
/**
* Forces any changes in the contents of this node and its descendants to
* the persistent store.
*
*
* 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 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 void sync() throws BackingStoreException;
}