to top
Android APIs
public abstract class

AbstractPreferences

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

Class Overview

This abstract class is a partial implementation of the abstract class Preferences, which can be used to simplify Preferences provider's implementation. This class defines nine abstract SPI methods, which must be implemented by a preference provider.

See Also

Summary

[Expand]
Inherited Constants
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)
Constructs a new AbstractPreferences instance using the given parent node and node name.
Public Methods
String absolutePath()
Gets the absolute path string of this preference node.
void addNodeChangeListener(NodeChangeListener ncl)
Registers a NodeChangeListener instance for this node, which will handle NodeChangeEvents.
void addPreferenceChangeListener(PreferenceChangeListener pcl)
Registers a PreferenceChangeListener instance for this node, which will handle PreferenceChangeEvents.
String[] childrenNames()
Returns the names of all children of this node or an empty array if this node has no children.
void clear()
Removes all preferences of this node.
void exportNode(OutputStream ostream)
Exports all of the preferences of this node to a XML document using the given output stream.
void exportSubtree(OutputStream ostream)
Exports all of the preferences of this node and all its descendants to a XML document using the given output stream.
void flush()
Forces all pending updates to this node and its descendants to be persisted in the backing store.
String get(String key, String deflt)
Gets the String value mapped to the given key or its default value if no value is mapped or no backing store is available.
boolean getBoolean(String key, boolean deflt)
Gets the boolean value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is invalid.
byte[] getByteArray(String key, byte[] deflt)
Gets the byte array value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.
double getDouble(String key, double deflt)
Gets the double value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.
float getFloat(String key, float deflt)
Gets the float value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.
int getInt(String key, int deflt)
Gets the int value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.
long getLong(String key, long deflt)
Gets the long value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.
boolean isUserNode()
Returns whether this is a user preference node.
String[] keys()
Returns all preference keys stored in this node or an empty array if no key was found.
String name()
Returns the name of this node.
Preferences node(String name)
Returns the preference node with the given path name.
boolean nodeExists(String name)
Returns whether the preference node with the given path name exists.
Preferences parent()
Returns the parent preference node of this node or null if this node is the root node.
void put(String key, String value)
Adds a new preference to this node using the given key and value or updates the value if a preference with the given key already exists.
void putBoolean(String key, boolean value)
Adds a new preference with a boolean value to this node using the given key and value or updates the value if a preference with the given key already exists.
void putByteArray(String key, byte[] value)
Adds a new preference to this node using the given key and the string form of the given value or updates the value if a preference with the given key already exists.
void putDouble(String key, double value)
Adds a new preference to this node using the given key and double value or updates the value if a preference with the given key already exists.
void putFloat(String key, float value)
Adds a new preference to this node using the given key and float value or updates the value if a preference with the given key already exists.
void putInt(String key, int value)
Adds a new preference to this node using the given key and int value or updates the value if a preference with the given key already exists.
void putLong(String key, long value)
Adds a new preference to this node using the given key and long value or updates the value if a preference with the given key already exists.
void remove(String key)
Removes the preference mapped to the given key from this node.
void removeNode()
Removes this preference node with all its descendants.
void removeNodeChangeListener(NodeChangeListener ncl)
Removes the given NodeChangeListener instance from this node.
void removePreferenceChangeListener(PreferenceChangeListener pcl)
Removes the given PreferenceChangeListener instance from this node.
void sync()
Synchronizes the data of this preference node and its descendants with the back-end preference store.
String toString()
Returns a string representation of this node.
Protected Methods
final AbstractPreferences[] cachedChildren()
Returns an array of all cached child nodes.
abstract AbstractPreferences childSpi(String name)
Returns the child preference node with the given name, creating it if it does not exist.
abstract String[] childrenNamesSpi()
Returns the names of all of the child nodes of this node or an empty array if this node has no children.
abstract void flushSpi()
Flushes changes of this node to the backing store.
AbstractPreferences getChild(String name)
Returns the child node with the specified name or null if it doesn't exist.
abstract String getSpi(String key)
Gets the preference value mapped to the given key.
boolean isRemoved()
Returns whether this node has been removed by invoking the method removeNode().
abstract String[] keysSpi()
Returns an array of all preference keys of this node or an empty array if no preferences have been found.
abstract void putSpi(String name, String value)
Puts the given key-value pair into this node.
abstract void removeNodeSpi()
Removes this node from the preference hierarchy tree.
abstract void removeSpi(String key)
Removes the preference with the specified key.
abstract void syncSpi()
Synchronizes this node with the backing store.
[Expand]
Inherited Methods
From class java.util.prefs.Preferences
From class java.lang.Object

Fields

protected final Object lock

Since: API Level 1

The object used to lock this node.

protected boolean newNode

Since: API Level 1

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)

Since: API Level 1

Constructs a new AbstractPreferences instance using the given parent node and node name.

Parameters
parent the parent node of the new node or null to indicate that the new node is a root node.
name the name of the new node or an empty string to indicate that this node is called "root".
Throws
IllegalArgumentException if the name contains a slash character or is empty if parent is not null.

Public Methods

public String absolutePath ()

Since: API Level 1

Gets the absolute path string of this preference node.

Returns
  • the preference node's absolute path string.

public void addNodeChangeListener (NodeChangeListener ncl)

Since: API Level 1

Registers a NodeChangeListener instance for this node, which will handle NodeChangeEvents. NodeChangeEvents will be fired when a child node has been added to or removed from this node.

Parameters
ncl the listener to be registered.

public void addPreferenceChangeListener (PreferenceChangeListener pcl)

Since: API Level 1

Registers a PreferenceChangeListener instance for this node, which will handle PreferenceChangeEvents. PreferenceChangeEvents will be fired when a preference has been added to, removed from, or updated for this node.

Parameters
pcl the listener to be registered.

public String[] childrenNames ()

Since: API Level 1

Returns the names of all children of this node or an empty array if this node has no children.

Returns
  • the names of all children of this node.
Throws
BackingStoreException

public void clear ()

Since: API Level 1

Removes all preferences of this node.

Throws
BackingStoreException

public void exportNode (OutputStream ostream)

Since: API Level 1

Exports all of the preferences of this node to a XML document using the given output stream.

This XML document uses the UTF-8 encoding and is written according to the DTD in its DOCTYPE declaration, which is the following: 

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
Please note that (unlike the methods of this class that don't concern serialization), this call is not thread-safe.

Parameters
ostream the output stream to write the XML-formatted data to.
Throws
IOException
BackingStoreException

public void exportSubtree (OutputStream ostream)

Since: API Level 1

Exports all of the preferences of this node and all its descendants to a XML document using the given output stream.

This XML document uses the UTF-8 encoding and is written according to the DTD in its DOCTYPE declaration, which is the following: 

 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
Please note that (unlike the methods of this class that don't concern serialization), this call is not thread-safe.

Parameters
ostream the output stream to write the XML-formatted data to.
Throws
IOException
BackingStoreException

public void flush ()

Since: API Level 1

Forces all pending updates to this node and its descendants to be persisted in the backing store.

If this node has been removed, the invocation of this method only flushes this node, not its descendants.

Throws
BackingStoreException

public String get (String key, String deflt)

Since: API Level 1

Gets the String value mapped to the given key or its default value if no value is mapped or no backing store is available.

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 no backing store is available.
Returns
  • the preference value mapped to the given key.

public boolean getBoolean (String key, boolean deflt)

Since: API Level 1

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

The only valid values are the String "true", which represents true and "false", which represents false, ignoring case.

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, if the backing store is unavailable, or if the value is invalid.
Returns
  • the boolean value mapped to the given key.

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

Since: API Level 1

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

To be valid, the value string must be 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, if the backing store is unavailable, or if the value is invalid.
Returns
  • the byte array value mapped to the given key.

public double getDouble (String key, double deflt)

Since: API Level 1

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

To be valid, the value string must be a string that can be converted to a double 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, if the backing store is unavailable, or if the value is invalid.
Returns
  • the double value mapped to the given key.

public float getFloat (String key, float deflt)

Since: API Level 1

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

To be valid, the value string must be a string that can be converted to a float 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, if the backing store is unavailable, or if the value is invalid.
Returns
  • the float value mapped to the given key.

public int getInt (String key, int deflt)

Since: API Level 1

Gets the int value mapped to the given key or its default value if no value is mapped, if the backing store is unavailable, or if the value is an invalid string.

To be valid, the value string must be a string that can be converted to an int 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, if the backing store is unavailable, or if the value is invalid.
Returns
  • the integer value mapped to the given key.

public long getLong (String key, long deflt)

Since: API Level 1

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

To be valid, the value string must be a string that can be converted to a long 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, if the backing store is unavailable, or if the value is invalid.
Returns
  • the long value mapped to the given key.

public boolean isUserNode ()

Since: API Level 1

Returns whether this is a user preference node.

Returns
  • true, if this is a user preference node, false if this is a system preference node.

public String[] keys ()

Since: API Level 1

Returns all preference keys stored in this node or an empty array if no key was found.

Returns
  • the list of all preference keys of this node.
Throws
BackingStoreException

public String name ()

Since: API Level 1

Returns the name of this node.

Returns
  • the name of this node.

public Preferences node (String name)

Since: API Level 1

Returns the preference node with the given path name. The path name can be relative or absolute. The requested node 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 a slash, otherwise it will be treated as an absolute path.

Parameters
name the path name of the requested preference node.
Returns
  • the requested preference node.

public boolean nodeExists (String name)

Since: API Level 1

Returns whether the preference node with the given path name exists. The path is treated as relative to this node if it doesn't start with a slash, otherwise it is treated as an absolute path.

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

Parameters
name the path name of the preference node to query.
Returns
  • true, if the queried preference node exists, false otherwise.
Throws
BackingStoreException

public Preferences parent ()

Since: API Level 1

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

Returns
  • the parent preference node of this node.

public void put (String key, String value)

Since: API Level 1

Adds a new preference to this node using the given key and value or updates the value if a preference with the given key already exists.

Parameters
key the preference key to be added or updated.
value the preference value for the given key.

public void putBoolean (String key, boolean value)

Since: API Level 1

Adds a new preference with a boolean value to this node using the given key and value or updates the value if a preference with the given key already exists.

Parameters
key the preference key to be added or updated.
value the preference boolean value for the given key.

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

Since: API Level 1

Adds a new preference to this node using the given key and the string form of the given value or updates the value if a preference with the given key already exists.

The string form of the 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 preference key to be added or updated.
value the preference value for the given key.

public void putDouble (String key, double value)

Since: API Level 1

Adds a new preference to this node using the given key and double value or updates the value if a preference with the given key already exists.

The value is stored in its string form, which is the result of invoking Double.toString(double).

Parameters
key the preference key to be added or updated.
value the preference value for the given key.

public void putFloat (String key, float value)

Since: API Level 1

Adds a new preference to this node using the given key and float value or updates the value if a preference with the given key already exists.

The value is stored in its string form, which is the result of invoking Float.toString(float).

Parameters
key the preference key to be added or updated.
value the preference value for the given key.

public void putInt (String key, int value)

Since: API Level 1

Adds a new preference to this node using the given key and int value or updates the value if a preference with the given key already exists.

The value is stored in its string form, which is the result of invoking Integer.toString(int).

Parameters
key the preference key to be added or updated.
value the preference value for the given key.

public void putLong (String key, long value)

Since: API Level 1

Adds a new preference to this node using the given key and long value or updates the value if a preference with the given key already exists.

The value is stored in its string form, which is the result of invoking Long.toString(long).

Parameters
key the preference key to be added or updated.
value the preference value for the given key.

public void remove (String key)

Since: API Level 1

Removes the preference mapped to the given key from this node.

Parameters
key the key of the preference to be removed.

public void removeNode ()

Since: API Level 1

Removes this preference node with all its descendants. The removal won't necessarily be persisted until the method flush() is invoked.

Throws
BackingStoreException

public void removeNodeChangeListener (NodeChangeListener ncl)

Since: API Level 1

Removes the given NodeChangeListener instance from this node.

Parameters
ncl the listener to be removed.

public void removePreferenceChangeListener (PreferenceChangeListener pcl)

Since: API Level 1

Removes the given PreferenceChangeListener instance from this node.

Parameters
pcl the listener to be removed.

public void sync ()

Since: API Level 1

Synchronizes the data of this preference node and its descendants with the back-end preference store. Any changes found in the back-end data should be reflected in this node and its descendants, and at the same time any local changes to this node and descendants should be persisted.

Throws
BackingStoreException

public String toString ()

Since: API Level 1

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

Returns
  • the string representation of this node.

Protected Methods

protected final AbstractPreferences[] cachedChildren ()

Since: API Level 1

Returns an array of all cached child nodes.

Returns
  • the array of cached child nodes.

protected abstract AbstractPreferences childSpi (String name)

Since: API Level 1

Returns the child preference node with the given name, creating it if it does not exist. The caller of this method should ensure that the given name is valid and that this node has not been removed or cached. If the named node has just been removed, the implementation of this method must create a new one instead of reactivating the removed one.

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

Parameters
name the name of the child preference to be returned.
Returns
  • the child preference node.

protected abstract String[] childrenNamesSpi ()

Since: API Level 1

Returns the names of all of the child nodes of this node or an empty array if this node has no children. The names of cached children are not required to be returned.

Returns
  • the names of this node's children.
Throws
BackingStoreException if the backing store is unavailable or causes an operation failure.

protected abstract void flushSpi ()

Since: API Level 1

Flushes changes of this node to the backing store. This method should only flush this node and should not include the descendant nodes. Any implementation that wants to provide functionality to flush all nodes at once should override the method flush().

Throws
BackingStoreException if the backing store is unavailable or causes an operation failure.

protected AbstractPreferences getChild (String name)

Since: API Level 1

Returns the child node with the specified name or null if it doesn't exist. Implementers can assume that the name supplied to this method will be a valid node name string (conforming to the node naming format) and will not correspond to a node that has been cached or removed.

Parameters
name the name of the desired child node.
Returns
  • the child node with the given name or null if it doesn't exist.
Throws
BackingStoreException if the backing store is unavailable or causes an operation failure.

protected abstract String getSpi (String key)

Since: API Level 1

Gets the preference value mapped to the given key. The caller of this method should ensure that the given key is valid and that this node has not been removed. This method should not throw any exceptions but if it does, the caller will ignore the exception, regarding it as a null return value.

Parameters
key the given key to be searched for.
Returns
  • the preference value mapped to the given key.

protected boolean isRemoved ()

Since: API Level 1

Returns whether this node has been removed by invoking the method removeNode().

Returns
  • true, if this node has been removed, false otherwise.

protected abstract String[] keysSpi ()

Since: API Level 1

Returns an array of all preference keys of this node or an empty array if no preferences have been found. The caller of this method should ensure that this node has not been removed.

Returns
  • the array of all preference keys.
Throws
BackingStoreException if the backing store is unavailable or causes an operation failure.

protected abstract void putSpi (String name, String value)

Since: API Level 1

Puts the given key-value pair into this node. Caller of this method should ensure that both of the given values are valid and that this node has not been removed.

Parameters
name the given preference key.
value the given preference value.

protected abstract void removeNodeSpi ()

Since: API Level 1

Removes this node from the preference hierarchy tree. The caller of this method should ensure that this node has no child nodes, which means the method Preferences.removeNode() should invoke this method multiple-times in bottom-up pattern. The removal is not required to be persisted until after it is flushed.

Throws
BackingStoreException if the backing store is unavailable or causes an operation failure.

protected abstract void removeSpi (String key)

Since: API Level 1

Removes the preference with the specified key. The caller of this method should ensure that the given key is valid and that this node has not been removed.

Parameters
key the key of the preference that is to be removed.

protected abstract void syncSpi ()

Since: API Level 1

Synchronizes this node with the backing store. This method should only synchronize this node and should not include the descendant nodes. An implementation that wants to provide functionality to synchronize all nodes at once should override the method sync().

Throws
BackingStoreException if the backing store is unavailable or causes an operation failure.