Android
java.util.prefs
public abstract class

java.util.prefs.AbstractPreferences

java.lang.Object
java.util.prefs.Preferences
java.util.prefs.AbstractPreferences

This class is partly implementation of Preferences, which can be used to simplify Preferences provider's implementation.

This class define nine abstract SPI methods, which must be implemented by preference provider. And provider can also override other methods of this class. Some SPI methods will throw BackingStoreException, including childrenNamesSpi(), flushSpi(), keysSpi(), removeNodeSpi(), syncSpi(); getSpi(String, String) never throws any exceptions; the last SPI methods, putSpi(String), removeSpi(String) and childSpi(String) won't throw BackingStoreException, but in some implementations, they may throw SecurityException due to lacking the permission to access backing end storage.

See Also

Summary

Constants inherited from class java.util.prefs.Preferences

Fields

protected    final  Object  lock  The object used to lock this node. 
protected      boolean  newNode  This field is true if this node is created while it doesn't exist in the backing store. 

Protected Constructors

            AbstractPreferences(AbstractPreferences parent, String name)
Construct a new AbstractPreferences instance using given parent node and node name.

Public Methods

          String  absolutePath()
Get this preference node's absolute path string.
          void  addNodeChangeListener(NodeChangeListener ncl)
Register an NodeChangeListener instance for this node, which will receive NodeChangeEvent.
          void  addPreferenceChangeListener(PreferenceChangeListener pcl)
Register an PreferenceChangeListener instance for this node, which will receive PreferenceChangeEvent.
          String[]  childrenNames()
Return names of all children of this node, or empty string if this node has no children.
          void  clear()
Remove all preferences of this node.
          void  exportNode(OutputStream ostream)
Export all preferences of this node to the given output stream in XML document.
          void  exportSubtree(OutputStream ostream)
Export all preferences of this node and its all descendants to the given output stream in XML document.
          void  flush()
Force the updates to this node and its descendants to the backing store.
          String  get(String key, String deflt)
Return the string value mapped to the given key, or default value if no value is mapped or backing store is unavailable.
          boolean  getBoolean(String key, boolean deflt)
Return the boolean value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid.
          byte[]  getByteArray(String key, byte[] deflt)
Return the byte array value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid string.
          double  getDouble(String key, double deflt)
Return the double value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid string.
          float  getFloat(String key, float deflt)
Return the float value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid string.
          int  getInt(String key, int deflt)
Return the float value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid string.
          long  getLong(String key, long deflt)
Return the long value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid string.
          boolean  isUserNode()
Return true if this is a user preferences, false if this is a system preferences
          String[]  keys()
Return all preferences keys stored in this node, or empty array if no key is found.
          String  name()
Return name of this node.
          Preferences  node(String name)
Return the preferences node with the given path name.
          boolean  nodeExists(String name)
Return the preferences node with the given path name.
          Preferences  parent()
Return the parent preferences node of this node, or null if this node is root.
          void  put(String key, String value)
Add new preferences to this node using given key and value, or update value if preferences with given key has already existed.
          void  putBoolean(String key, boolean value)
Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.
          void  putByteArray(String key, byte[] value)
Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.
          void  putDouble(String key, double value)
Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.
          void  putFloat(String key, float value)
Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.
          void  putInt(String key, int value)
Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.
          void  putLong(String key, long value)
Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.
          void  remove(String key)
Remove the preferences mapped to the given key from this node.
          void  removeNode()
Remove this preferences node and its all descendants.
          void  removeNodeChangeListener(NodeChangeListener ncl)
Remove the given NodeChangeListener instance from this node.
          void  removePreferenceChangeListener(PreferenceChangeListener pcl)
Remove the given PreferenceChangeListener instance from this node.
          void  sync()
Synchronize this preferences node and its descendants' data with the back end preferences store.
          String  toString()
Return a string description of this node.

Protected Methods

    final      AbstractPreferences[]  cachedChildren()
Return arrays of all cached children node.
abstract          AbstractPreferences  childSpi(String name)
Return the child preference node with the given name, and create new one if it does not exist.
abstract          String[]  childrenNamesSpi()
Return names of this node's all children , or empty array if this node has no child.
abstract          void  flushSpi()
Flush changes of this node to the backing store.
          AbstractPreferences  getChild(String name)
Return the child node with given name, or null if it doesn't exist.
abstract          String  getSpi(String key)
Get the preference value mapped to the given key.
          boolean  isRemoved()
Return true if and only if this node has been removed by invoking removeNode.
abstract          String[]  keysSpi()
Return all keys of this node's preferences, or empty array if no preference found on this node.
abstract          void  putSpi(String name, String value)
Put the given key-value pair into this node.
abstract          void  removeNodeSpi()
Remove this node from the preference hierarchy tree.
abstract          void  removeSpi(String key)
Remove the preference with the given key.
abstract          void  syncSpi()
Synchronize this node with the backing store.
Methods inherited from class java.util.prefs.Preferences
Methods inherited from class java.lang.Object

Details

Fields

protected final Object lock

The object used to lock this node.

protected boolean newNode

This field is true if this node is created while it doesn't exist in the backing store. This field's default value is false, and it is checked when the node creation is completed, and if it is true, the node change event will be fired for this node's parent.

Protected Constructors

protected AbstractPreferences(AbstractPreferences parent, String name)

Construct a new AbstractPreferences instance using given parent node and node name.

Parameters

parent the parent node of this node, can be null, which means this node is root
name the name of this node, can be empty(""), which means this node is root

Throws

IllegalArgumentException if name contains slash, or be empty if parent is not null

Public Methods

public String absolutePath()

Get this preference node's absolute path string.

Returns

  • this preference node's absolute path string.

public void addNodeChangeListener(NodeChangeListener ncl)

Register an NodeChangeListener instance for this node, which will receive NodeChangeEvent. NodeChangeEvent will be produced when direct child node is added to or removed from this node.

Parameters

ncl the given listener to be registered

public void addPreferenceChangeListener(PreferenceChangeListener pcl)

Register an PreferenceChangeListener instance for this node, which will receive PreferenceChangeEvent. PreferenceChangeEvent will be produced when preference is added to, removed from or updated for this node.

Parameters

pcl the given listener to be registered

public String[] childrenNames()

Return names of all children of this node, or empty string if this node has no children.

Returns

  • names of all children of this node

public void clear()

Remove all preferences of this node.

public void exportNode(OutputStream ostream)

Export all preferences of this node to the given output stream in XML document.

This XML document has the following DOCTYPE declaration:

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
And the UTF-8 encoding will be used. Please note that this node is not thread-safe, which is an exception of this class.

Parameters

ostream the output stream to export the XML

public void exportSubtree(OutputStream ostream)

Export all preferences of this node and its all descendants to the given output stream in XML document.

This XML document has the following DOCTYPE declaration:

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
* And the UTF-8 encoding will be used. Please note that this node is not thread-safe, which is an exception of this class.

Parameters

ostream the output stream to export the XML

public void flush()

Force the updates to this node and its descendants to the backing store.

If this node has been removed, then the invocation of this method only flush this node without descendants.

public String get(String key, String deflt)

Return the string value mapped to the given key, or default value if no value is mapped or backing store is unavailable.

Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

Parameters

key the preference key
deflt the default value, which will be returned if no value is mapped to the given key or backing store unavailable

Returns

  • the preference value mapped to the given key, or default value if no value is mapped or backing store unavailable

public boolean getBoolean(String key, boolean deflt)

Return the boolean value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid.

The valid value is string equals "true", which represents true, or "false", which represents false, case is ignored.

Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

Parameters

key the preference key
deflt the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid

Returns

  • the boolean value mapped to the given key, or default value if no value is mapped, backing store unavailable or value is invalid

public byte[] getByteArray(String key, byte[] deflt)

Return the byte array value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid string.

The valid value string is Base64 encoded binary data. The Base64 encoding is as defined in RFC 2045, section 6.8.

Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

Parameters

key the preference key
deflt the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid

Returns

  • the byte array value mapped to the given key, or default value if no value is mapped, backing store unavailable or value is invalid

public double getDouble(String key, double deflt)

Return the double value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid string.

The valid value string can be converted to double number by Double.parseDouble(String).

Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

Parameters

key the preference key
deflt the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid

Returns

  • the double value mapped to the given key, or default value if no value is mapped, backing store unavailable or value is invalid

public float getFloat(String key, float deflt)

Return the float value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid string.

The valid value string can be converted to float number by Float.parseFloat(String).

Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

Parameters

key the preference key
deflt the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid

Returns

  • the float value mapped to the given key, or default value if no value is mapped, backing store unavailable or value is invalid

public int getInt(String key, int deflt)

Return the float value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid string.

The valid value string can be converted to integer by Integer.parseInt(String).

Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

Parameters

key the preference key
deflt the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid

Returns

  • the integer value mapped to the given key, or default value if no value is mapped, backing store unavailable or value is invalid

public long getLong(String key, long deflt)

Return the long value mapped to the given key, or default value if no value is mapped, backing store is unavailable, or the value is invalid string.

The valid value string can be converted to long integer by Long.parseLong(String).

Some implementations may store default values in backing stores. In this case, if there is no value mapped to the given key, the stored default value is returned.

Parameters

key the preference key
deflt the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid

Returns

  • the long value mapped to the given key, or default value if no value is mapped, backing store unavailable or value is invalid

public boolean isUserNode()

Return true if this is a user preferences, false if this is a system preferences

Returns

  • true if this is a user preferences, false if this is a system preferences

public String[] keys()

Return all preferences keys stored in this node, or empty array if no key is found.

Returns

  • all preferences keys in this node

public String name()

Return name of this node.

Returns

  • the name of this node

public Preferences node(String name)

Return the preferences node with the given path name. The path name can be relative or absolute. The dictated preferences and its ancestors will be created if they do not exist.

The path is treated as relative to this node if it doesn't start with slash, or as absolute otherwise.

Parameters

name the path name of dictated preferences

Returns

  • the dictated preferences node

public boolean nodeExists(String name)

Return the preferences node with the given path name. The path is treated as relative to this node if it doesn't start with slash, or as absolute otherwise.

Please note that if this node has been removed, invocation of this node will throw IllegalStateException except the given path is empty string, which will return false.

Parameters

name the path name of dictated preferences

Returns

  • true if the dictated preferences node exists

public Preferences parent()

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

Returns

  • the parent preferences node of this node.

public void put(String key, String value)

Add new preferences to this node using given key and value, or update value if preferences with given key has already existed.

Parameters

key the preferences key to be added or be updated
value the preferences value for the given key

public void putBoolean(String key, boolean value)

Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.

Parameters

key the preferences key to be added or be updated
value the preferences value for the given key

public void putByteArray(String key, byte[] value)

Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.

The string form of value is the Base64 encoded binary data of the given byte array. The Base64 encoding is as defined in RFC 2045, section 6.8.

Parameters

key the preferences key to be added or be updated
value the preferences value for the given key

public void putDouble(String key, double value)

Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.

The string form of given value is the result of invoking Double.toString(double)

Parameters

key the preferences key to be added or be updated
value the preferences value for the given key

public void putFloat(String key, float value)

Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.

The string form of given value is the result of invoking Float.toString(float)

Parameters

key the preferences key to be added or be updated
value the preferences value for the given key

public void putInt(String key, int value)

Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.

The string form of given value is the result of invoking Integer.toString(int)

Parameters

key the preferences key to be added or be updated
value the preferences value for the given key

public void putLong(String key, long value)

Add new preferences to this node using given key and string form of given value, or update value if preferences with given key has already existed.

The string form of given value is the result of invoking Long.toString(long)

Parameters

key the preferences key to be added or be updated
value the preferences value for the given key

public void remove(String key)

Remove the preferences mapped to the given key from this node.

Parameters

key the given preferences key to removed

public void removeNode()

Remove this preferences node and its all descendants. The removal maybe won't be persisted until the flush() method is invoked.

public void removeNodeChangeListener(NodeChangeListener ncl)

Remove the given NodeChangeListener instance from this node.

Parameters

ncl the given listener to be removed

public void removePreferenceChangeListener(PreferenceChangeListener pcl)

Remove the given PreferenceChangeListener instance from this node.

Parameters

pcl the given listener to be removed

public void sync()

Synchronize this preferences node and its descendants' data with the back end preferences store. The changes of back end should be reflect by this node and its descendants, meanwhile, the changes of this node and descendants should be persisted.

public String toString()

Return a string description of this node. The format is "User/System Preference Node: " followed by this node's absolute path.

Returns

  • a string description of this node

Protected Methods

protected final AbstractPreferences[] cachedChildren()

Return arrays of all cached children node.

Returns

  • arrays of all cached children node.

protected abstract AbstractPreferences childSpi(String name)

Return the child preference node with the given name, and create new one if it does not exist. Invoker of this method should assure that the given name are valid as well as this node is not removed. Invocation of this method implies that the node with given name is not cached(or, has been removed.) If the named node has just been removed, implementation of this method must create a new one instead of reactivated the removed one.

The new creation is not required to be persisted immediately until the flush method is invoked.

Returns

  • AbstractPreferences

protected abstract String[] childrenNamesSpi()

Return names of this node's all children , or empty array if this node has no child. Cached children name is not required to be returned.

Returns

  • names of this node's all children

Throws

BackingStoreException if backing store is unavailable or causes operation failure

protected abstract void flushSpi()

Flush changes of this node to the backing store. This method should only flush this node, and should not include the descendant nodes. The implementation which want to flush all nodes at once should override flush() method.

Throws

BackingStoreException if backing store is unavailable or causes operation failure

protected AbstractPreferences getChild(String name)

Return the child node with given name, or null if it doesn't exist. The given name must be valid and this node cannot be removed. Invocation of this method implies that the node with given name is not cached(or, has been removed.)

Parameters

name the given child name to be got

Returns

  • the child node with given name, or null if it doesn't exist

Throws

BackingStoreException if backing store is unavailable or causes operation failure

protected abstract String getSpi(String key)

Get the preference value mapped to the given key. Invoker of this method should assure that given key are valid as well as this node is not removed. This method should not throw exceptions, but if it does, the invoker should catch it and deal with it as null return value.

Parameters

key the given key to be searched for

Returns

  • the preference value mapped to the given key

protected boolean isRemoved()

Return true if and only if this node has been removed by invoking removeNode.

Returns

  • true if and only if this node has been removed by invoking removeNode

protected abstract String[] keysSpi()

Return all keys of this node's preferences, or empty array if no preference found on this node. Invoker of this method should assure that this node is not removed.

Returns

  • all keys of this node's preferences

Throws

BackingStoreException if backing store is unavailable or causes operation failure

protected abstract void putSpi(String name, String value)

Put the given key-value pair into this node. Invoker of this method should assure that both the given values are valid as well as this node is not removed.

Parameters

name the given preference key
value the given preference value

protected abstract void removeNodeSpi()

Remove this node from the preference hierarchy tree. The invoker of this method should assure that this node has no child node, which means the Preferences.removeNode() should invoke this method multi-times in bottom-up pattern. The removal is not required to be persisted at once until the it is flushed.

Throws

BackingStoreException if backing store is unavailable or causes operation failure

protected abstract void removeSpi(String key)

Remove the preference with the given key. Invoker of this method should assure that given key are valid as well as this node is not removed.

Parameters

key the given key to removed

protected abstract void syncSpi()

Synchronize this node with the backing store. This method should only synchronize this node, and should not include the descendant nodes. The implementation which want to synchronize all nodes at once should override sync() method.

Throws

BackingStoreException if backing store is unavailable or causes operation failure
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:48