Android
java.util.prefs
public abstract class

java.util.prefs.Preferences

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

Preferences instance represents one node in preferences tree, which provide a mechanisms to store and access configuration data in a hierarchical way. Two hierarchy tree is maintained, one for system preferences shared by all users, and the other for user preferences which is specific for each user. Preferences hierarchy tree and data is stored precisely in implementation-dependent backend, and user doesn't need to care about the details.

Every node has one name and one unique absolute path in a similar way with directories in file system. The root node's name is "", and other nodes' name string cannot contains slash and cannot be empty. The root node's absolute path is "/", and other nodes' absolute path equals <parent's absolute path> + "/" + <node's name>. All absolute paths start with slash. Every node has one relative path to one of its ancestor. Relative path doesn't start with slash, and equals to absolute path when following after ancestor's absolute path and a slash.

The modification to preferences data may be asynchronous, which means they may don't block and may returns immediately, implementation can feel free to the modifications to the backend in any time until the flush() or sync() method is invoked, these two methods force synchronized updates to backend. Please note that if JVM exit normally, the implementation must assure all modifications are persisted implicitly.

User invoking methods that retrieve preferences must provide default value, default value is returned when preferences cannot be found or backend is unavailable. Some other methods will throw BackingStoreException when backend is unavailable.

Preferences can be export to/import from XML files, the XML document must have the following DOCTYPE declaration:

This system URI is not really accessed by network, it is only a identification string. Visit the DTD location to see the actual format permitted.

There has to be a concrete PreferencesFactory type for every concrete Preferences type developed. Every J2SE implementation must provide a default implementation for every supported platform, and the default implementation can be replaced in some way. This implementation uses system property java.util.prefs.PreferencesFactory to dictate the preferences implementation.

Methods of this class is thread-safe. If multi JVMs using same backend concurrently, the backend won't be corrupted, but no other guarantees is made.

Known Direct Subclasses

Summary

Constants

      Value  
int  MAX_KEY_LENGTH  Maximum size in characters of preferences key   80  0x00000050 
int  MAX_NAME_LENGTH  Maximum size in characters of preferences name   80  0x00000050 
int  MAX_VALUE_LENGTH  Maximum size in characters of preferences value   8192  0x00002000 

Protected Constructors

            Preferences()
Default constructor, for use by subclasses only.

Public Methods

abstract          String  absolutePath()
Get this preference node's absolute path string.
abstract          void  addNodeChangeListener(NodeChangeListener ncl)
Register an NodeChangeListener instance for this node, which will receive NodeChangeEvent.
abstract          void  addPreferenceChangeListener(PreferenceChangeListener pcl)
Register an PreferenceChangeListener instance for this node, which will receive PreferenceChangeEvent.
abstract          String[]  childrenNames()
Return names of all children of this node, or empty string if this node has no children.
abstract          void  clear()
Remove all preferences of this node.
abstract          void  exportNode(OutputStream ostream)
Export all preferences of this node to the given output stream in XML document.
abstract          void  exportSubtree(OutputStream ostream)
Export all preferences of this node and its all descendants to the given output stream in XML document.
abstract          void  flush()
Force the updates to this node and its descendants to the backing store.
abstract          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.
abstract          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.
abstract          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.
abstract          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.
abstract          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.
abstract          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.
abstract          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.
      static    void  importPreferences(InputStream istream)
Import all preferences from the given input stream in XML document.
abstract          boolean  isUserNode()
Return true if this is a user preferences, false if this is a system preferences
abstract          String[]  keys()
Return all preferences keys stored in this node, or empty array if no key is found.
abstract          String  name()
Return name of this node.
abstract          Preferences  node(String path)
Return the preferences node with the given path name.
abstract          boolean  nodeExists(String path)
Return the preferences node with the given path name.
abstract          Preferences  parent()
Return the parent preferences node of this node, or null if this node is root.
abstract          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.
abstract          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.
abstract          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.
abstract          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.
abstract          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.
abstract          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.
abstract          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.
abstract          void  remove(String key)
Remove the preferences mapped to the given key from this node.
abstract          void  removeNode()
Remove this preferences node and its all descendants.
abstract          void  removeNodeChangeListener(NodeChangeListener ncl)
Remove the given NodeChangeListener instance from this node.
abstract          void  removePreferenceChangeListener(PreferenceChangeListener pcl)
Remove the given PreferenceChangeListener instance from this node.
abstract          void  sync()
Synchronize this preferences node and its descendants' data with the back end preferences store.
      static    Preferences  systemNodeForPackage(Class<?> c)
Return the system preference node for the package of given class.
      static    Preferences  systemRoot()
Return the root node for system preference hierarchy.
abstract          String  toString()
Return a string description of this node.
      static    Preferences  userNodeForPackage(Class<?> c)
Return the user preference node for the package of given class.
      static    Preferences  userRoot()
Return the root node for user preference hierarchy.
Methods inherited from class java.lang.Object

Details

Constants

public static final int MAX_KEY_LENGTH

Maximum size in characters of preferences key
Constant Value: 80 (0x00000050)

public static final int MAX_NAME_LENGTH

Maximum size in characters of preferences name
Constant Value: 80 (0x00000050)

public static final int MAX_VALUE_LENGTH

Maximum size in characters of preferences value
Constant Value: 8192 (0x00002000)

Protected Constructors

protected Preferences()

Default constructor, for use by subclasses only.

Public Methods

public abstract String absolutePath()

Get this preference node's absolute path string.

Returns

  • this preference node's absolute path string.

public abstract 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

Throws

NullPointerException if the given listener is null
IllegalStateException if this node has been removed

public abstract 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

Throws

NullPointerException if the given listener is null
IllegalStateException if this node has been removed

public abstract 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

Throws

BackingStoreException if backing store is unavailable or causes operation failure
IllegalStateException if this node has been removed

public abstract void clear()

Remove all preferences of this node.

Throws

BackingStoreException if backing store is unavailable or causes operation failure
IllegalStateException if this node has been removed

public abstract 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

Throws

IOException if export operation caused an IOException
BackingStoreException if backing store is unavailable or causes operation failure
IllegalStateException if this node has been removed

public abstract 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

Throws

IOException if export operation caused an IOException
BackingStoreException if backing store is unavailable or causes operation failure
IllegalStateException if this node has been removed

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

Throws

BackingStoreException if backing store is unavailable or causes operation failure

public abstract 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

Throws

IllegalStateException if this node has been removed
NullPointerException if parameter key is null

public abstract 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

Throws

IllegalStateException if this node has been removed
NullPointerException if parameter key is null

public abstract 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

Throws

IllegalStateException if this node has been removed
NullPointerException if parameter key is null

public abstract 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

Throws

IllegalStateException if this node has been removed
NullPointerException if parameter key is null

public abstract 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

Throws

IllegalStateException if this node has been removed
NullPointerException if parameter key is null

public abstract 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

Throws

IllegalStateException if this node has been removed
NullPointerException if parameter key is null

public abstract 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

Throws

IllegalStateException if this node has been removed
NullPointerException if parameter key is null

public static void importPreferences(InputStream istream)

Import all preferences from the given input stream in XML document.

This XML document has the following DOCTYPE declaration:

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

Parameters

istream the given input stream to read data

Throws

InvalidPreferencesFormatException if the data read from given input stream is not valid XML document
IOException if import operation caused an IOException
SecurityException if RuntimePermission("preferences") is denied by a SecurityManager

public abstract 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 abstract 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

Throws

BackingStoreException if backing store is unavailable or causes operation failure
IllegalStateException if this node has been removed

public abstract String name()

Return name of this node.

Returns

  • the name of this node

public abstract Preferences node(String path)

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

path the path name of dictated preferences

Returns

  • the dictated preferences node

Throws

IllegalStateException if this node has been removed.
IllegalArgumentException if the path name is invalid.
NullPointerException if given path is null.

public abstract boolean nodeExists(String path)

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

path the path name of dictated preferences

Returns

  • true if the dictated preferences node exists

Throws

IllegalStateException if this node has been removed and the path is not empty string.
IllegalArgumentException if the path name is invalid.
NullPointerException if given path is null.
BackingStoreException if backing store is unavailable or causes operation failure

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

Throws

IllegalStateException if this node has been removed

public abstract 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

Throws

NullPointerException if the given key or value is null
IllegalArgumentException if the given key's length is bigger than MAX_KEY_LENGTH, or the value's length is bigger than MAX_VALUE_LENGTH
IllegalStateException if this node has been removed

public abstract 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

Throws

NullPointerException if the given key is null
IllegalArgumentException if the given key's length is bigger than MAX_KEY_LENGTH
IllegalStateException if this node has been removed

public abstract 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

Throws

NullPointerException if the given key or value is null
IllegalArgumentException if the given key's length is bigger than MAX_KEY_LENGTH or value's length is bigger than three quarters of MAX_KEY_LENGTH
IllegalStateException if this node has been removed

public abstract 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

Throws

NullPointerException if the given key is null
IllegalArgumentException if the given key's length is bigger than MAX_KEY_LENGTH
IllegalStateException if this node has been removed

public abstract 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

Throws

NullPointerException if the given key is null
IllegalArgumentException if the given key's length is bigger than MAX_KEY_LENGTH
IllegalStateException if this node has been removed

public abstract 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

Throws

NullPointerException if the given key is null
IllegalArgumentException if the given key's length is bigger than MAX_KEY_LENGTH
IllegalStateException if this node has been removed

public abstract 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

Throws

NullPointerException if the given key is null
IllegalArgumentException if the given key's length is bigger than MAX_KEY_LENGTH
IllegalStateException if this node has been removed

public abstract void remove(String key)

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

Parameters

key the given preferences key to removed

Throws

NullPointerException if the given key is null
IllegalStateException if this node has been removed

public abstract void removeNode()

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

Throws

BackingStoreException if backing store is unavailable or causes operation failure
IllegalStateException if this node has been removed
UnsupportedOperationException if this is a root node

public abstract void removeNodeChangeListener(NodeChangeListener ncl)

Remove the given NodeChangeListener instance from this node.

Parameters

ncl the given listener to be removed

Throws

IllegalArgumentException if the given listener
IllegalStateException if this node has been removed

public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)

Remove the given PreferenceChangeListener instance from this node.

Parameters

pcl the given listener to be removed

Throws

IllegalArgumentException if the given listener
IllegalStateException if this node has been removed

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

Throws

BackingStoreException if backing store is unavailable or causes operation failure
IllegalStateException if this node has been removed

public static Preferences systemNodeForPackage(Class<?> c)

Return the system preference node for the package of given class. The absolute path of the returned node is one slash followed by the given class's full package name with replacing each period ('.') with slash. For example, the preference's associated with class Object has absolute path like "/java/lang". As a special case, the unnamed package is associated with preference node "/". This method will create node and its ancestors if needed, and the new created nodes maybe won't be persisted until the flush() is invoked.

Parameters

c the given class

Returns

  • the system preference node for the package of given class.

Throws

NullPointerException if the given class is null
SecurityException if RuntimePermission("preferences") is denied by a SecurityManager

public static Preferences systemRoot()

Return the root node for system preference hierarchy.

Returns

  • the root node for system preference hierarchy

Throws

SecurityException if RuntimePermission("preferences") is denied by a SecurityManager

public abstract 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

public static Preferences userNodeForPackage(Class<?> c)

Return the user preference node for the package of given class. The absolute path of the returned node is one slash followed by the given class's full package name with replacing each period ('.') with slash. For example, the preference's associated with class Object has absolute path like "/java/lang". As a special case, the unnamed package is associated with preference node "/". This method will create node and its ancestors if needed, and the new created nodes maybe won't be persisted until the flush() is invoked.

Parameters

c the given class

Returns

  • the user preference node for the package of given class.

Throws

NullPointerException if the given class is null
SecurityException if RuntimePermission("preferences") is denied by a SecurityManager

public static Preferences userRoot()

Return the root node for user preference hierarchy.

Returns

  • the root node for user preference hierarchy

Throws

SecurityException if RuntimePermission("preferences") is denied by a SecurityManager
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:48