org.apache.felix.prefs
Class PreferencesImpl

java.lang.Object
  extended by org.apache.felix.prefs.PreferencesImpl
All Implemented Interfaces:
Preferences

public class PreferencesImpl
extends Object
implements Preferences

This is an implementation of the preferences. The access to the preferences is synchronized on the instance by making (nearly) all public methods synchronized. This avoids the heavy management of a separate read/write lock. Such a lock is too heavy for the simple operations preferences support. The various getXX and putXX methods are not synchronized as they all use the get/put methods which are synchronized.


Field Summary
protected  ChangeSet changeSet
          The change set keeps track of all changes.
protected  Map children
          The child nodes.
protected  PreferencesDescription description
          The description for this preferences.
protected  String name
          The name of the properties.
protected  PreferencesImpl parent
          The parent.
protected  Map properties
          The properties.
protected  BackingStoreManager storeManager
          The backing store manager.
protected  boolean valid
          Has this node been removed?
 
Constructor Summary
PreferencesImpl(PreferencesDescription d, BackingStoreManager storeManager)
          Construct the root node of the tree.
PreferencesImpl(PreferencesImpl p, String name)
          Construct a child node.
 
Method Summary
 String absolutePath()
          Returns this node's absolute path name.
 void applyChanges(PreferencesImpl prefs)
          Apply the changes done to the passed preferences object.
protected  void checkKey(String key)
          The key is not allowed to be null.
protected  void checkValidity()
          Check if this node is still valid.
protected  void checkValue(Object value)
          The value is not allowed to be null.
 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.
 String get(String key, String def)
          Returns the value associated with the specified key in this node.
 BackingStoreManager getBackingStoreManager()
          Return the backing store manager.
 boolean getBoolean(String key, boolean def)
          Returns the boolean value represented by the String object associated with the specified key in this node.
 byte[] getByteArray(String key, byte[] def)
          Returns the byte[] value represented by the String object associated with the specified key in this node.
 ChangeSet getChangeSet()
          Return the change set.
 Collection getChildren()
          Return all children or an empty collection.
 PreferencesDescription getDescription()
          Return the preferences description.
 double getDouble(String key, double def)
          Returns the double value represented by the String object associated with the specified key in this node.
 float getFloat(String key, float def)
          Returns the float value represented by the String object associated with the specified key in this node.
 int getInt(String key, int def)
          Returns the int value represented by the String object associated with the specified key in this node.
 long getLong(String key, long def)
          Returns the long value represented by the String object associated with the specified key in this node.
protected  PreferencesImpl getNode(String path, boolean saveNewlyCreatedNode, boolean create)
          Get a relative node.
 PreferencesImpl getOrCreateNode(String pathName)
          Get or create the node.
 Map getProperties()
          Return the properties set.
 PreferencesImpl getRoot()
          Get the root preferences.
 boolean isValid()
           
 String[] keys()
          Returns all of the keys that have an associated value in this node.
 String name()
          Returns this node's name, relative to its parent.
 Preferences node(String pathName)
          We do not synchronize this method to avoid dead locks as this method might call another preferences object in the hierarchy.
 boolean nodeExists(String pathName)
          We do not synchronize this method to avoid dead locks as this method might call another preferences object in the hierarchy.
 Preferences parent()
          Returns the parent of this node, or null if this is the root.
 void put(String key, String value)
          Associates the specified value with the specified key in this node.
 void putBoolean(String key, boolean value)
          Associates a String object representing the specified boolean value with the specified key in this node.
 void putByteArray(String key, byte[] value)
          Associates a String object representing the specified byte[] with the specified key in this node.
 void putDouble(String key, double value)
          Associates a String object representing the specified double value with the specified key in this node.
 void putFloat(String key, float value)
          Associates a String object representing the specified float value with the specified key in this node.
 void putInt(String key, int value)
          Associates a String object representing the specified int value with the specified key in this node.
 void putLong(String key, long value)
          Associates a String object representing the specified long value with the specified key in this node.
 void remove(String key)
          Removes the value associated with the specified key in this node, if any.
protected  void removeChild(PreferencesImpl child)
           
 void removeNode()
          Removes this node and all of its descendants, invalidating any properties contained in the removed nodes.
protected  void safelyRemoveNode()
          Safely remove a node by resetting all properties and calling this method on all children recursively.
 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.
 void update(PreferencesImpl impl)
          Update from the preferences impl.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

properties

protected final Map properties
The properties.


valid

protected boolean valid
Has this node been removed?


parent

protected final PreferencesImpl parent
The parent.


children

protected final Map children
The child nodes.


name

protected final String name
The name of the properties.


description

protected final PreferencesDescription description
The description for this preferences.


storeManager

protected final BackingStoreManager storeManager
The backing store manager.


changeSet

protected final ChangeSet changeSet
The change set keeps track of all changes.

Constructor Detail

PreferencesImpl

public PreferencesImpl(PreferencesDescription d,
                       BackingStoreManager storeManager)
Construct the root node of the tree.

Parameters:
d - The unique description.
storeManager - The backing store.

PreferencesImpl

public PreferencesImpl(PreferencesImpl p,
                       String name)
Construct a child node.

Parameters:
p - The parent node.
name - The node name
Method Detail

getChangeSet

public ChangeSet getChangeSet()
Return the change set.


getDescription

public PreferencesDescription getDescription()
Return the preferences description.

Returns:
The preferences description.

getRoot

public PreferencesImpl getRoot()
Get the root preferences.


getChildren

public Collection getChildren()
Return all children or an empty collection.

Returns:
A collection containing the children.

getProperties

public Map getProperties()
Return the properties set.


getBackingStoreManager

public BackingStoreManager getBackingStoreManager()
Return the backing store manager.


checkValidity

protected void checkValidity()
                      throws IllegalStateException
Check if this node is still valid. It gets invalid if it has been removed.

Throws:
IllegalStateException

checkKey

protected void checkKey(String key)
                 throws NullPointerException
The key is not allowed to be null.

Throws:
NullPointerException

checkValue

protected void checkValue(Object value)
                   throws NullPointerException
The value is not allowed to be null.

Throws:
NullPointerException

isValid

public boolean isValid()

put

public void put(String key,
                String value)
Description copied from interface: Preferences
Associates the specified value with the specified key in this node.

Specified by:
put in interface Preferences
Parameters:
key - key with which the specified value is to be associated.
value - value to be associated with the specified key.
See Also:
Preferences.put(java.lang.String, java.lang.String)

get

public String get(String key,
                  String def)
Description copied from interface: Preferences
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.

Specified by:
get in interface Preferences
Parameters:
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.
Returns:
the value associated with key, or def if no value is associated with key.
See Also:
Preferences.get(java.lang.String, java.lang.String)

remove

public void remove(String key)
Description copied from interface: Preferences
Removes the value associated with the specified key in this node, if any.

Specified by:
remove in interface Preferences
Parameters:
key - key whose mapping is to be removed from this node.
See Also:
Preferences.remove(java.lang.String)

clear

public void clear()
           throws BackingStoreException
Description copied from interface: Preferences
Removes all of the properties (key-value associations) in this node. This call has no effect on any descendants of this node.

Specified by:
clear in interface Preferences
Throws:
BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
See Also:
Preferences.clear()

putInt

public void putInt(String key,
                   int value)
Description copied from interface: Preferences
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 Preferences.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.

Specified by:
putInt in interface Preferences
Parameters:
key - key with which the string form of value is to be associated.
value - value whose string form is to be associated with key.
See Also:
Preferences.putInt(java.lang.String, int)

getInt

public int getInt(String key,
                  int def)
Description copied from interface: Preferences
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 Preferences.putInt(java.lang.String, int) method.

Specified by:
getInt in interface Preferences
Parameters:
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.
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.
See Also:
Preferences.getInt(java.lang.String, int)

putLong

public void putLong(String key,
                    long value)
Description copied from interface: Preferences
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 Preferences.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.

Specified by:
putLong in interface Preferences
Parameters:
key - key with which the string form of value is to be associated.
value - value whose string form is to be associated with key.
See Also:
Preferences.putLong(java.lang.String, long)

getLong

public long getLong(String key,
                    long def)
Description copied from interface: Preferences
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 Preferences.putLong(java.lang.String, long) method.

Specified by:
getLong in interface Preferences
Parameters:
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.
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.
See Also:
Preferences.getLong(java.lang.String, long)

putBoolean

public void putBoolean(String key,
                       boolean value)
Description copied from interface: Preferences
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 Preferences.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.

Specified by:
putBoolean in interface Preferences
Parameters:
key - key with which the string form of value is to be associated.
value - value whose string form is to be associated with key.
See Also:
Preferences.putBoolean(java.lang.String, boolean)

getBoolean

public boolean getBoolean(String key,
                          boolean def)
Description copied from interface: Preferences
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 Preferences.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.

Specified by:
getBoolean in interface Preferences
Parameters:
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.
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.
See Also:
Preferences.getBoolean(java.lang.String, boolean)

putFloat

public void putFloat(String key,
                     float value)
Description copied from interface: Preferences
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 Preferences.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.

Specified by:
putFloat in interface Preferences
Parameters:
key - key with which the string form of value is to be associated.
value - value whose string form is to be associated with key.
See Also:
Preferences.putFloat(java.lang.String, float)

getFloat

public float getFloat(String key,
                      float def)
Description copied from interface: Preferences
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 Preferences.putFloat(java.lang.String, float) method.

Specified by:
getFloat in interface Preferences
Parameters:
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.
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.
See Also:
Preferences.getFloat(java.lang.String, float)

putDouble

public void putDouble(String key,
                      double value)
Description copied from interface: Preferences
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 Preferences.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.

Specified by:
putDouble in interface Preferences
Parameters:
key - key with which the string form of value is to be associated.
value - value whose string form is to be associated with key.
See Also:
Preferences.putDouble(java.lang.String, double)

getDouble

public double getDouble(String key,
                        double def)
Description copied from interface: Preferences
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 Preferences.putDouble(java.lang.String, double) method.

Specified by:
getDouble in interface Preferences
Parameters:
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.
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.
See Also:
Preferences.getDouble(java.lang.String, double)

putByteArray

public void putByteArray(String key,
                         byte[] value)
Description copied from interface: Preferences
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 Preferences.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).

Specified by:
putByteArray in interface Preferences
Parameters:
key - key with which the string form of value is to be associated.
value - value whose string form is to be associated with key.
See Also:
Preferences.putByteArray(java.lang.String, byte[])

getByteArray

public byte[] getByteArray(String key,
                           byte[] def)
Description copied from interface: Preferences
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 Preferences.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).

Specified by:
getByteArray in interface Preferences
Parameters:
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.
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[].
See Also:
Preferences.getByteArray(java.lang.String, byte[])

keys

public String[] keys()
              throws BackingStoreException
Description copied from interface: Preferences
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!)

Specified by:
keys in interface Preferences
Returns:
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.
See Also:
Preferences.keys()

childrenNames

public String[] childrenNames()
                       throws BackingStoreException
Description copied from interface: Preferences
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!)

Specified by:
childrenNames in interface Preferences
Returns:
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.
See Also:
Preferences.childrenNames()

parent

public Preferences parent()
Description copied from interface: Preferences
Returns the parent of this node, or null if this is the root.

Specified by:
parent in interface Preferences
Returns:
the parent of this node.
See Also:
Preferences.parent()

node

public Preferences node(String pathName)
We do not synchronize this method to avoid dead locks as this method might call another preferences object in the hierarchy.

Specified by:
node in interface Preferences
Parameters:
pathName - the path name of the Preferences object to return.
Returns:
the specified Preferences object.
See Also:
Preferences.node(java.lang.String)

getOrCreateNode

public PreferencesImpl getOrCreateNode(String pathName)
Get or create the node. If the node already exists, it's just returned. If not it is created.

Parameters:
pathName -
Returns:
The preferences impl for the path.

getNode

protected PreferencesImpl getNode(String path,
                                  boolean saveNewlyCreatedNode,
                                  boolean create)
Get a relative node.

Parameters:
path -
Returns:

nodeExists

public boolean nodeExists(String pathName)
                   throws BackingStoreException
We do not synchronize this method to avoid dead locks as this method might call another preferences object in the hierarchy.

Specified by:
nodeExists in interface Preferences
Parameters:
pathName - the path name of the node whose existence is to be checked.
Returns:
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.
See Also:
Preferences.nodeExists(java.lang.String)

removeNode

public void removeNode()
                throws BackingStoreException
Description copied from interface: Preferences
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.

Specified by:
removeNode in interface Preferences
Throws:
BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
See Also:
Preferences.removeNode()

safelyRemoveNode

protected void safelyRemoveNode()
Safely remove a node by resetting all properties and calling this method on all children recursively.


removeChild

protected void removeChild(PreferencesImpl child)

name

public String name()
Description copied from interface: Preferences
Returns this node's name, relative to its parent.

Specified by:
name in interface Preferences
Returns:
this node's name, relative to its parent.
See Also:
Preferences.name()

absolutePath

public String absolutePath()
Description copied from interface: Preferences
Returns this node's absolute path name. Note that:

Specified by:
absolutePath in interface Preferences
Returns:
this node's absolute path name.
See Also:
Preferences.absolutePath()

flush

public void flush()
           throws BackingStoreException
Description copied from interface: Preferences
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.

Specified by:
flush in interface Preferences
Throws:
BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
See Also:
Preferences.flush()

sync

public void sync()
          throws BackingStoreException
Description copied from interface: Preferences
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.

Specified by:
sync in interface Preferences
Throws:
BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
See Also:
Preferences.sync()

update

public void update(PreferencesImpl impl)
Update from the preferences impl.

Parameters:
impl -

applyChanges

public void applyChanges(PreferencesImpl prefs)
Apply the changes done to the passed preferences object.

Parameters:
prefs -


Copyright © 2013 The Apache Software Foundation. All Rights Reserved.