Top Description Methods
org.osgi.service.prefs

public Interface Preferences

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:

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.

Author
$Id: 0858dc28b93ce3cc5b136cef7420352d8469bbc8 $

Method Summary

Modifier and TypeMethod and Description
public String

Returns:

this node's absolute path name.
absolutePath()

Returns this node's absolute path name.

public String[]

Returns:

the names of the children of this node.
childrenNames()

Returns the names of the children of this node.

public void
clear()

Removes all of the properties (key-value associations) in this node.

public void
flush()

Forces any changes in the contents of this node and its descendants to the persistent store.

public String

Returns:

the value associated with key, or def if no value is associated with key.
get(String
key whose associated value is to be returned.
key, String
the value to be returned in the event that this node has no value associated with key or the backing store is inaccessible.
def)

Returns the value associated with the specified key in this node.

public boolean

Returns:

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.
getBoolean(String
key whose associated value is to be returned as a boolean.
key, boolean
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.
def)

Returns the boolean value represented by the String object associated with the specified key in this node.

public byte[]

Returns:

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[].
getByteArray(String
key whose associated value is to be returned as a byte[] object.
key, byte[]
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.
def)

Returns the byte[] value represented by the String object associated with the specified key in this node.

public double

Returns:

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.
getDouble(String
key whose associated value is to be returned as a double value.
key, double
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.
def)

Returns the double value represented by the String object associated with the specified key in this node.

public float

Returns:

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.
getFloat(String
key whose associated value is to be returned as a float value.
key, float
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.
def)

Returns the float value represented by the String object associated with the specified key in this node.

public int

Returns:

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.
getInt(String
key whose associated value is to be returned as an int .
key, int
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.
def)

Returns the int value represented by the String object associated with the specified key in this node.

public long

Returns:

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.
getLong(String
key whose associated value is to be returned as a long value.
key, long
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.
def)

Returns the long value represented by the String object associated with the specified key in this node.

public String[]

Returns:

an array of the keys that have an associated value in this node.
keys()

Returns all of the keys that have an associated value in this node.

public String

Returns:

this node's name, relative to its parent.
name()

Returns this node's name, relative to its parent.

public Preferences

Returns:

the specified Preferences object.
node(String
the path name of the Preferences object to return.
pathName)

Returns a named Preferences object (node), creating it and any of its ancestors if they do not already exist.

public boolean

Returns:

true if the specified node exists.
nodeExists(String
the path name of the node whose existence is to be checked.
pathName)

Returns true if the named node exists.

public Preferences

Returns:

the parent of this node.
parent()

Returns the parent of this node, or null if this is the root.

public void
put(String
key with which the specified value is to be associated.
key, String
value to be associated with the specified key.
value)

Associates the specified value with the specified key in this node.

public void
putBoolean(String
key with which the string form of value is to be associated.
key, boolean
value whose string form is to be associated with key .
value)

Associates a String object representing the specified boolean value with the specified key in this node.

public void
putByteArray(String
key with which the string form of value is to be associated.
key, byte[]
value whose string form is to be associated with key.
value)

Associates a String object representing the specified byte[] with the specified key in this node.

public void
putDouble(String
key with which the string form of value is to be associated.
key, double
value whose string form is to be associated with key .
value)

Associates a String object representing the specified double value with the specified key in this node.

public void
putFloat(String
key with which the string form of value is to be associated.
key, float
value whose string form is to be associated with key .
value)

Associates a String object representing the specified float value with the specified key in this node.

public void
putInt(String
key with which the string form of value is to be associated.
key, int
value whose string form is to be associated with key.
value)

Associates a String object representing the specified int value with the specified key in this node.

public void
putLong(String
key with which the string form of value is to be associated.
key, long
value whose string form is to be associated with key.
value)

Associates a String object representing the specified long value with the specified key in this node.

public void
remove(String
key whose mapping is to be removed from this node.
key)

Removes the value associated with the specified key in this node, if any.

public void
removeNode()

Removes this node and all of its descendants, invalidating any properties contained in the removed nodes.

public void
sync()

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.

Method Detail

absolutePathback to summary
public String absolutePath()

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.
Returns:String

this node's absolute path name.

childrenNamesback to summary
public String[] childrenNames() 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!)

Returns:String[]

the names of the children of this node.

Exceptions
BackingStoreException:
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
clearback to summary
public void clear() throws BackingStoreException

Removes all of the properties (key-value associations) in this node. This call has no effect on any descendants of this node.

Exceptions
BackingStoreException:
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
remove(String)
flushback to summary
public void flush() throws BackingStoreException

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.

Exceptions
BackingStoreException:
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
sync()
getback to summary
public String get(String key, String def)

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.

Parameters
key:String

key whose associated value is to be returned.

def:String

the value to be returned in the event that this node has no value associated with key or the backing store is inaccessible.

Returns:String

the value associated with key, or def if no value is associated with key.

Exceptions
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
NullPointerException:
if key is null. (A null default is permitted.)
getBooleanback to summary
public boolean getBoolean(String key, boolean def)

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 putBoolean(String, boolean) 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.

Parameters
key:String

key whose associated value is to be returned as a boolean.

def:boolean

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.

Returns:boolean

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.

Exceptions
NullPointerException:
if key is null.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
get(String, String), putBoolean(String, boolean)
getByteArrayback to summary
public byte[] getByteArray(String key, byte[] def)

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 putByteArray(String, byte[]) 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).

Parameters
key:String

key whose associated value is to be returned as a byte[] object.

def:byte[]

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.

Returns:byte[]

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[].

Exceptions
NullPointerException:
if key is null. (A null value for def is permitted.)
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
get(String, String), putByteArray(String, byte[])
getDoubleback to summary
public double getDouble(String key, double def)

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 putDouble method.

Parameters
key:String

key whose associated value is to be returned as a double value.

def:double

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.

Returns:double

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.

Exceptions
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
NullPointerException:
if key is null.
See Also
putDouble(String, double), get(String, String)
getFloatback to summary
public float getFloat(String key, float def)

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 putFloat(String, float) method.

Parameters
key:String

key whose associated value is to be returned as a float value.

def:float

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.

Returns:float

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.

Exceptions
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
NullPointerException:
if key is null.
See Also
putFloat(String, float), get(String, String)
getIntback to summary
public int getInt(String key, int def)

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 putInt(String, int) method.

Parameters
key:String

key whose associated value is to be returned as an int .

def:int

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.

Returns:int

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.

Exceptions
NullPointerException:
if key is null.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
putInt(String, int), get(String, String)
getLongback to summary
public long getLong(String key, long def)

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 putLong(String, long) method.

Parameters
key:String

key whose associated value is to be returned as a long value.

def:long

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.

Returns:long

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.

Exceptions
NullPointerException:
if key is null.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
putLong(String, long), get(String, String)
keysback to summary
public String[] keys() throws BackingStoreException

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!)

Returns:String[]

an array of the keys that have an associated value in this node.

Exceptions
BackingStoreException:
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
nameback to summary
public String name()

Returns this node's name, relative to its parent.

Returns:String

this node's name, relative to its parent.

nodeback to summary
public Preferences node(String pathName)

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).

Parameters
pathName:String

the path name of the Preferences object to return.

Returns:Preferences

the specified Preferences object.

Exceptions
IllegalArgumentException:
if the path name is invalid.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
NullPointerException:
if path name is null.
See Also
flush()
nodeExistsback to summary
public boolean nodeExists(String pathName) throws BackingStoreException

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 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.

Parameters
pathName:String

the path name of the node whose existence is to be checked.

Returns:boolean

true if the specified node exists.

Exceptions
BackingStoreException:
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method and pathname is not the empty string ("").
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).
parentback to summary
public Preferences parent()

Returns the parent of this node, or null if this is the root.

Returns:Preferences

the parent of this node.

Exceptions
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
putback to summary
public void put(String key, String value)

Associates the specified value with the specified key in this node.

Parameters
key:String

key with which the specified value is to be associated.

value:String

value to be associated with the specified key.

Exceptions
NullPointerException:
if key or value is null.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
putBooleanback to summary
public void putBoolean(String key, boolean value)

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 getBoolean(String, boolean) 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.

Parameters
key:String

key with which the string form of value is to be associated.

value:boolean

value whose string form is to be associated with key .

Exceptions
NullPointerException:
if key is null.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
getBoolean(String, boolean), get(String, String)
putByteArrayback to summary
public void putByteArray(String key, byte[] value)

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 getByteArray(String, byte[]) 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 ).

Parameters
key:String

key with which the string form of value is to be associated.

value:byte[]

value whose string form is to be associated with key.

Exceptions
NullPointerException:
if key or value is null.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
getByteArray(String, byte[]), get(String, String)
putDoubleback to summary
public void putDouble(String key, double value)

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 getDouble(String, double) 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.

Parameters
key:String

key with which the string form of value is to be associated.

value:double

value whose string form is to be associated with key .

Exceptions
NullPointerException:
if key is null.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
getDouble(String, double)
putFloatback to summary
public void putFloat(String key, float value)

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 getFloat(String, float) 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.

Parameters
key:String

key with which the string form of value is to be associated.

value:float

value whose string form is to be associated with key .

Exceptions
NullPointerException:
if key is null.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
getFloat(String, float)
putIntback to summary
public void putInt(String key, int value)

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 getInt(String, int) 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.

Parameters
key:String

key with which the string form of value is to be associated.

value:int

value whose string form is to be associated with key.

Exceptions
NullPointerException:
if key is null.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
getInt(String, int)
putLongback to summary
public void putLong(String key, long value)

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 getLong(String, long) 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.

Parameters
key:String

key with which the string form of value is to be associated.

value:long

value whose string form is to be associated with key.

Exceptions
NullPointerException:
if key is null.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
getLong(String, long)
removeback to summary
public void remove(String key)

Removes the value associated with the specified key in this node, if any.

Parameters
key:String

key whose mapping is to be removed from this node.

Exceptions
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
get(String, String)
removeNodeback to summary
public void removeNode() 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.

Exceptions
BackingStoreException:
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
IllegalStateException:
if this node (or an ancestor) has already been removed with the removeNode() method.
See Also
flush()
syncback to summary
public void sync() 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.

Exceptions
BackingStoreException:
if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
IllegalStateException:
if this node (or an ancestor) has been removed with the removeNode() method.
See Also
flush()