| java.lang.Object
 java.util.prefs.Preferences
All known Subclasses: java.util.prefs.AbstractPreferences,
| Preferences | | abstract public class Preferences (Code) | | 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.
See Also: PreferencesFactory
since:
1.4 |
| Constructor Summary | |
| protected | Preferences()
Default constructor, for use by subclasses only. |
| Method Summary | |
| abstract public String | absolutePath()
Get this preference node's absolute path string. | | abstract public void | addNodeChangeListener(NodeChangeListener ncl)
Register an NodeChangeListener instance for this node, which
will receive NodeChangeEvent. | | abstract public void | addPreferenceChangeListener(PreferenceChangeListener pcl)
Register an PreferenceChangeListener instance for this node, which
will receive PreferenceChangeEvent. | | abstract public String[] | childrenNames()
Return names of all children of this node, or empty string if this node
has no children. | | abstract public void | clear()
Remove all preferences of this node. | | abstract public void | exportNode(OutputStream ostream)
Export all preferences of this node to the given output stream in XML
document. | | abstract public void | exportSubtree(OutputStream ostream)
Export all preferences of this node and its all descendants to the given
output stream in XML document. | | abstract public void | flush()
Force the updates to this node and its descendants to the backing store. | | abstract 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. | | abstract 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. | | abstract 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. | | abstract 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) Double.parseDouble(String) .
Some implementations may store default values in backing stores. | | abstract 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) Float.parseFloat(String) .
Some implementations may store default values in backing stores. | | abstract 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) Integer.parseInt(String) .
Some implementations may store default values in backing stores. | | abstract 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) Long.parseLong(String) .
Some implementations may store default values in backing stores. | | public static void | importPreferences(InputStream istream)
Import all preferences from the given input stream in XML document. | | abstract public boolean | isUserNode()
| | abstract public String[] | keys()
Return all preferences keys stored in this node, or empty array if no
key is found. | | abstract public String | name()
Return name of this node. | | abstract public Preferences | node(String path)
Return the preferences node with the given path name. | | abstract public boolean | nodeExists(String path)
Return the preferences node with the given path name. | | abstract public Preferences | parent()
Return the parent preferences node of this node, or null if this node is root. | | abstract 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. | | abstract 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. | | abstract 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. | | abstract 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. | | abstract 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. | | abstract 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. | | abstract 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. | | abstract public void | remove(String key)
Remove the preferences mapped to the given key from this node. | | abstract public void | removeNode()
Remove this preferences node and its all descendants. | | abstract public void | removeNodeChangeListener(NodeChangeListener ncl)
Remove the given NodeChangeListener instance from this node. | | abstract public void | removePreferenceChangeListener(PreferenceChangeListener pcl)
Remove the given PreferenceChangeListener instance from this node. | | abstract public void | sync()
Synchronize this preferences node and its descendants' data with the back
end preferences store. | | public static Preferences | systemNodeForPackage(Class c)
Return the system preference node for the package of given class. | | public static Preferences | systemRoot()
Return the root node for system preference hierarchy. | | abstract public String | toString()
Return a string description of this node. | | public static Preferences | userNodeForPackage(Class c)
Return the user preference node for the package of given class. | | public static Preferences | userRoot()
Return the root node for user preference hierarchy. |
| MAX_KEY_LENGTH | | final public static int MAX_KEY_LENGTH(Code) | | Maximum size in characters of preferences key
|
| MAX_NAME_LENGTH | | final public static int MAX_NAME_LENGTH(Code) | | Maximum size in characters of preferences name
|
| MAX_VALUE_LENGTH | | final public static int MAX_VALUE_LENGTH(Code) | | Maximum size in characters of preferences value
|
| Preferences | | protected Preferences()(Code) | | Default constructor, for use by subclasses only.
|
| absolutePath | | abstract public String absolutePath()(Code) | | Get this preference node's absolute path string.
this preference node's absolute path string. |
| addNodeChangeListener | | abstract public void addNodeChangeListener(NodeChangeListener ncl)(Code) | | 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
throws:
IllegalStateException - if this node has been removed |
| addPreferenceChangeListener | | abstract public void addPreferenceChangeListener(PreferenceChangeListener pcl)(Code) | | 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
throws:
IllegalStateException - if this node has been removed |
| exportNode | | abstract public void exportNode(OutputStream ostream) throws IOException, BackingStoreException(Code) | | 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
throws:
BackingStoreException - if backing store is unavailable or causes operation failure
throws:
IllegalStateException - if this node has been removed |
| exportSubtree | | abstract public void exportSubtree(OutputStream ostream) throws IOException, BackingStoreException(Code) | | 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
throws:
BackingStoreException - if backing store is unavailable or causes operation failure
throws:
IllegalStateException - if this node has been removed |
| flush | | abstract public void flush() throws BackingStoreException(Code) | | 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 |
| get | | abstract public String get(String key, String deflt)(Code) | | 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
Parameters:
deflt - the default value, which will be returned if no value is mapped to the given key or backing store unavailable 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
throws:
NullPointerException - if parameter key is null |
| getBoolean | | abstract public boolean getBoolean(String key, boolean deflt)(Code) | | 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
Parameters:
deflt - the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid 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
throws:
NullPointerException - if parameter key is null |
| getByteArray | | abstract public byte[] getByteArray(String key, byte[] deflt)(Code) | | 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
Parameters:
deflt - the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid 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
throws:
NullPointerException - if parameter key is null |
| getDouble | | abstract public double getDouble(String key, double deflt)(Code) | | 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) 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
Parameters:
deflt - the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid 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
throws:
NullPointerException - if parameter key is null |
| getFloat | | abstract public float getFloat(String key, float deflt)(Code) | | 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) 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
Parameters:
deflt - the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid 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
throws:
NullPointerException - if parameter key is null |
| getInt | | abstract public int getInt(String key, int deflt)(Code) | | 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) 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
Parameters:
deflt - the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid 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
throws:
NullPointerException - if parameter key is null |
| getLong | | abstract public long getLong(String key, long deflt)(Code) | | 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) 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
Parameters:
deflt - the default value, which will be returned if no value is mapped to the given key, backing store unavailable or value is invalid 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
throws:
NullPointerException - if parameter key is null |
| importPreferences | | public static void importPreferences(InputStream istream) throws InvalidPreferencesFormatException, IOException(Code) | | 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
throws:
IOException - if import operation caused an IOException
throws:
SecurityException - if RuntimePermission("preferences") is denied by a SecurityManager |
| isUserNode | | abstract public boolean isUserNode()(Code) | | Return true if this is a user preferences, false if this is a system
preferences
true if this is a user preferences, false if this is a system preferences |
| name | | abstract public String name()(Code) | | Return name of this node.
the name of this node |
| node | | abstract public Preferences node(String path)(Code) | | 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 the dictated preferences node
throws:
IllegalStateException - if this node has been removed.
throws:
IllegalArgumentException - if the path name is invalid.
throws:
NullPointerException - if given path is null. |
| nodeExists | | abstract public boolean nodeExists(String path) throws BackingStoreException(Code) | | 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 true if the dictated preferences node exists
throws:
IllegalStateException - if this node has been removed and the path is not empty string.
throws:
IllegalArgumentException - if the path name is invalid.
throws:
NullPointerException - if given path is null.
throws:
BackingStoreException - if backing store is unavailable or causes operation failure |
| parent | | abstract public Preferences parent()(Code) | | Return the parent preferences node of this node, or null if this node is root.
the parent preferences node of this node.
throws:
IllegalStateException - if this node has been removed |
| put | | abstract public void put(String key, String value)(Code) | | 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
Parameters:
value - the preferences value for the given key
throws:
NullPointerException - if the given key or value is null
throws:
IllegalArgumentException - if the given key's length is bigger than MAX_KEY_LENGTH, or the value's length is bigger than MAX_VALUE_LENGTH
throws:
IllegalStateException - if this node has been removed |
| putBoolean | | abstract public void putBoolean(String key, boolean value)(Code) | | 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
Parameters:
value - the preferences value for the given key
throws:
NullPointerException - if the given key is null
throws:
IllegalArgumentException - if the given key's length is bigger than MAX_KEY_LENGTH
throws:
IllegalStateException - if this node has been removed |
| putByteArray | | abstract public void putByteArray(String key, byte[] value)(Code) | | 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
Parameters:
value - the preferences value for the given key
throws:
NullPointerException - if the given key or value is null
throws:
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
throws:
IllegalStateException - if this node has been removed |
| putDouble | | abstract public void putDouble(String key, double value)(Code) | | 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) Double.toString(double)
Parameters:
key - the preferences key to be added or be updated
Parameters:
value - the preferences value for the given key
throws:
NullPointerException - if the given key is null
throws:
IllegalArgumentException - if the given key's length is bigger than MAX_KEY_LENGTH
throws:
IllegalStateException - if this node has been removed |
| putFloat | | abstract public void putFloat(String key, float value)(Code) | | 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) Float.toString(float)
Parameters:
key - the preferences key to be added or be updated
Parameters:
value - the preferences value for the given key
throws:
NullPointerException - if the given key is null
throws:
IllegalArgumentException - if the given key's length is bigger than MAX_KEY_LENGTH
throws:
IllegalStateException - if this node has been removed |
| putInt | | abstract public void putInt(String key, int value)(Code) | | 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) Integer.toString(int)
Parameters:
key - the preferences key to be added or be updated
Parameters:
value - the preferences value for the given key
throws:
NullPointerException - if the given key is null
throws:
IllegalArgumentException - if the given key's length is bigger than MAX_KEY_LENGTH
throws:
IllegalStateException - if this node has been removed |
| putLong | | abstract public void putLong(String key, long value)(Code) | | 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) Long.toString(long)
Parameters:
key - the preferences key to be added or be updated
Parameters:
value - the preferences value for the given key
throws:
NullPointerException - if the given key is null
throws:
IllegalArgumentException - if the given key's length is bigger than MAX_KEY_LENGTH
throws:
IllegalStateException - if this node has been removed |
| remove | | abstract public void remove(String key)(Code) | | 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
throws:
IllegalStateException - if this node has been removed |
| sync | | abstract public void sync() throws BackingStoreException(Code) | | 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
throws:
IllegalStateException - if this node has been removed |
| systemNodeForPackage | | public static Preferences systemNodeForPackage(Class c)(Code) | | 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 the system preference node for the package of given class.
throws:
NullPointerException - if the given class is null
throws:
SecurityException - if RuntimePermission("preferences") is denied by a SecurityManager |
| systemRoot | | public static Preferences systemRoot()(Code) | | Return the root node for system preference hierarchy.
the root node for system preference hierarchy
throws:
SecurityException - if RuntimePermission("preferences") is denied by a SecurityManager |
| toString | | abstract public String toString()(Code) | | Return a string description of this node. The format is "User/System
Preference Node: " followed by this node's absolute path.
a string description of this node |
| userNodeForPackage | | public static Preferences userNodeForPackage(Class c)(Code) | | 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 the user preference node for the package of given class.
throws:
NullPointerException - if the given class is null
throws:
SecurityException - if RuntimePermission("preferences") is denied by a SecurityManager |
| userRoot | | public static Preferences userRoot()(Code) | | Return the root node for user preference hierarchy.
the root node for user preference hierarchy
throws:
SecurityException - if RuntimePermission("preferences") is denied by a SecurityManager |
|
|