|
OSGi™ Service Platform Release 2 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 configuration 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.
Method Summary | |
java.lang.String |
absolutePath()
Returns this node's absolute path name. |
java.lang.String[] |
childrenNames()
Returns the names of the children of this node. |
void |
clear()
Removes all of the properties (key-value associations) in this node. |
void |
flush()
Forces any changes in the contents of this node and its descendants to the persistent store. |
java.lang.String |
get(java.lang.String key,
java.lang.String def)
Returns the value associated with the specified key in this node. |
boolean |
getBoolean(java.lang.String key,
boolean def)
Returns the boolean value represented by the String object associated with the specified key in this node. |
byte[] |
getByteArray(java.lang.String key,
byte[] def)
Returns the byte[] value represented by the String object associated with the specified key in this node. |
double |
getDouble(java.lang.String key,
double def)
Returns the double value represented by the String object associated with the specified key in this node. |
float |
getFloat(java.lang.String key,
float def)
Returns the float value represented by the String object associated with the specified key in this node. |
int |
getInt(java.lang.String key,
int def)
Returns the int value represented by the String object associated with the specified key in this node. |
long |
getLong(java.lang.String key,
long def)
Returns the long value represented by the String object associated with the specified key in this node. |
java.lang.String[] |
keys()
Returns all of the keys that have an associated value in this node. |
java.lang.String |
name()
Returns this node's name, relative to its parent. |
Preferences |
node(java.lang.String pathName)
Returns a named Preferences object (node), creating it and any of its ancestors if they do not already exist. |
boolean |
nodeExists(java.lang.String pathName)
Returns true if the named node exists. |
Preferences |
parent()
Returns the parent of this node, or null if this is the root. |
void |
put(java.lang.String key,
java.lang.String value)
Associates the specified value with the specified key in this node. |
void |
putBoolean(java.lang.String key,
boolean value)
Associates a String object representing the specified boolean value with the specified key in this node. |
void |
putByteArray(java.lang.String key,
byte[] value)
Associates a String object representing the specified byte[] with the specified key in this node. |
void |
putDouble(java.lang.String key,
double value)
Associates a String object representing the specified double value with the specified key in this node. |
void |
putFloat(java.lang.String key,
float value)
Associates a String object representing the specified float value with the specified key in this node. |
void |
putInt(java.lang.String key,
int value)
Associates a String object representing the specified int value with the specified key in this node. |
void |
putLong(java.lang.String key,
long value)
Associates a String object representing the specified long value with the specified key in this node. |
void |
remove(java.lang.String key)
Removes the value associated with the specified key in this node, if any. |
void |
removeNode()
Removes this node and all of its descendants, invalidating any properties contained in the removed nodes. |
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 |
public void put(java.lang.String key, java.lang.String value)
key
- key with which the specified value is to be associated.value
- value to be associated with the specified key.
java.lang.NullPointerException
- if key or value is null.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.public java.lang.String get(java.lang.String key, java.lang.String def)
key
- key whose associated value is to be returned.def
- the value to be returned in the event that this
node has no value associated with key
or the backing store is inaccessible.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.
java.lang.NullPointerException
- if key is null. (A
null default is permitted.)public void remove(java.lang.String key)
key
- key whose mapping is to be removed from this node.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.get(String,String)
public void clear() throws BackingStoreException
BackingStoreException
- if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.remove(String)
public void putInt(java.lang.String key, int value)
getInt(java.lang.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.
key
- key with which the string form of value is to be associated.value
- value whose string form is to be associated with key.
java.lang.NullPointerException
- if key is null.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.getInt(String,int)
public int getInt(java.lang.String key, int def)
putInt(java.lang.String, int)
method.
key
- key whose associated value is to be returned as an int.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.
java.lang.NullPointerException
- if key is null.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.putInt(String,int)
,
get(String,String)
public void putLong(java.lang.String key, long value)
getLong(java.lang.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.
key
- key with which the string form of value is to be associated.value
- value whose string form is to be associated with key.
java.lang.NullPointerException
- if key is null.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.getLong(String,long)
public long getLong(java.lang.String key, long def)
putLong(java.lang.String, long)
method.
key
- key whose associated value is to be returned as a long value.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.
java.lang.NullPointerException
- if key is null.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.putLong(String,long)
,
get(String,String)
public void putBoolean(java.lang.String key, boolean value)
getBoolean(java.lang.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.
key
- key with which the string form of value is to be associated.value
- value whose string form is to be associated with key.
java.lang.NullPointerException
- if key is null.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.getBoolean(String,boolean)
,
get(String,String)
public boolean getBoolean(java.lang.String key, boolean def)
putBoolean(java.lang.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.
key
- key whose associated value is to be returned as a boolean.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.
java.lang.NullPointerException
- if key is null.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.get(String,String)
,
putBoolean(String,boolean)
public void putFloat(java.lang.String key, float value)
getFloat(java.lang.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.
key
- key with which the string form of value is to be associated.value
- value whose string form is to be associated with key.
java.lang.NullPointerException
- if key is null.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.getFloat(String,float)
public float getFloat(java.lang.String key, float def)
putFloat(java.lang.String, float)
method.
key
- key whose associated value is to be returned as a float value.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.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.
java.lang.NullPointerException
- if key is null.putFloat(String,float)
,
get(String,String)
public void putDouble(java.lang.String key, double value)
getDouble(java.lang.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.
key
- key with which the string form of value is to be associated.value
- value whose string form is to be associated with key.
java.lang.NullPointerException
- if key is null.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.getDouble(String,double)
public double getDouble(java.lang.String key, double def)
putDouble(java.lang.String, double)
method.
key
- key whose associated value is to be returned as a double value.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.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the the removeNode()
method.
java.lang.NullPointerException
- if key is null.putDouble(String,double)
,
get(String,String)
public void putByteArray(java.lang.String key, byte[] value)
getByteArray(java.lang.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).
key
- key with which the string form of value is to be associated.value
- value whose string form is to be associated with key.
java.lang.NullPointerException
- if key or value
is null.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.getByteArray(String,byte[])
,
get(String,String)
public byte[] getByteArray(java.lang.String key, byte[] def)
putByteArray(java.lang.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).
key
- key whose associated value is to be returned as a byte[] object.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.
java.lang.NullPointerException
- if key is null.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.get(String,String)
,
putByteArray(String,byte[])
public java.lang.String[] keys() throws BackingStoreException
BackingStoreException
- if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.public java.lang.String[] childrenNames() throws BackingStoreException
BackingStoreException
- if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.public Preferences parent()
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.public Preferences node(java.lang.String pathName)
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).
pathName
- the path name of the Preferences object to return.
java.lang.IllegalArgumentException
- if the path name is invalid.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.flush()
public boolean nodeExists(java.lang.String pathName) throws BackingStoreException
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.
pathName
- the path name of the node whose existence
is to be checked.
BackingStoreException
- if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method and
pathname is not the empty string ("").public void removeNode() throws BackingStoreException
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.)
java.lang.IllegalStateException
- if this node (or an ancestor) has already
been removed with the removeNode()
method.
java.lang.RuntimeException
- if this is a root node.
BackingStoreException
flush()
public java.lang.String name()
public java.lang.String absolutePath()
public void flush() throws BackingStoreException
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.
BackingStoreException
- if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.sync()
public void sync() throws BackingStoreException
BackingStoreException
- if this operation cannot be completed
due to a failure in the backing store, or inability to
communicate with it.
java.lang.IllegalStateException
- if this node (or an ancestor) has been
removed with the removeNode()
method.flush()
|
OSGi™ Service Platform Release 2 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |