java.lang.Object | +--java.util.prefs.Preferences
static int | MAX_KEY_LENGTH Maximum entry key length. |
static int | MAX_NAME_LENGTH Maximum node name length. |
static int | MAX_VALUE_LENGTH Maximum entry value length. |
Preferences() Creates a new Preferences node. |
java.lang.String | absolutePath() Returns the absolute path name of this preference node. |
void | addNodeChangeListener(java.util.prefs.NodeChangeListener listener) |
void | addPreferenceChangeListener(java.util.prefs.PreferenceChangeListener listener) |
java.lang.String[] | childrenNames() Returns all the direct sub nodes of this preferences node. |
void | clear() Removes all entries from this preferences node. |
void | exportNode(java.io.OutputStream os) XXX |
void | exportSubtree(java.io.OutputStream os) XXX |
void | flush() Writes all preference changes on this and any subnode that have not yet been written to the backing store. |
java.lang.String | get(java.lang.String key, java.lang.String defaultVal) Returns the value associated with the key in this preferences node. |
boolean | getBoolean(java.lang.String key, boolean defaultVal) Convenience method for getting the given entry as a boolean. |
byte[] | getByteArray(java.lang.String key, byte[] defaultVal) Convenience method for getting the given entry as a byte array. |
double | getDouble(java.lang.String key, double defaultVal) Convenience method for getting the given entry as a double. |
float | getFloat(java.lang.String key, float defaultVal) Convenience method for getting the given entry as a float. |
int | getInt(java.lang.String key, int defaultVal) Convenience method for getting the given entry as an integer. |
long | getLong(java.lang.String key, long defaultVal) Convenience method for getting the given entry as a long. |
static void | importPreferences(java.io.InputStream is) XXX |
boolean | isUserNode() Returns true if this node comes from the user preferences tree, false if it comes from the system preferences tree. |
java.lang.String[] | keys() Returns an (possibly empty) array with all the keys of the preference entries of this node. |
java.lang.String | name() Returns the name of this preferences node. |
java.util.prefs.Preferences | node(java.lang.String path) Returns a sub node of this preferences node if the given path is relative (does not start with a '/') or a sub node of the root if the path is absolute (does start with a '/'). |
boolean | nodeExists(java.lang.String path) Returns true if the node that the path points to exists in memory or in the backing store. |
java.util.prefs.Preferences | parent() Returns the parent preferences node of this node or null if this is the root of the preferences tree. |
void | put(java.lang.String key, java.lang.String value) Sets the value of the given preferences entry for this node. |
void | putBoolean(java.lang.String key, boolean value) Convenience method for setting the given entry as a boolean. |
void | putByteArray(java.lang.String key, byte[] value) Convenience method for setting the given entry as an array of bytes. |
void | putDouble(java.lang.String key, double value) Convenience method for setting the given entry as a double. |
void | putFloat(java.lang.String key, float value) Convenience method for setting the given entry as a float. |
void | putInt(java.lang.String key, int value) Convenience method for setting the given entry as an integer. |
void | putLong(java.lang.String key, long value) Convenience method for setting the given entry as a long. |
void | remove(java.lang.String key) Removes the preferences entry from this preferences node. |
void | removeNode() Removes this and all subnodes from the backing store and clears all entries. |
void | removeNodeChangeListener(java.util.prefs.NodeChangeListener listener) |
void | removePreferenceChangeListener(java.util.prefs.PreferenceChangeListener listener) |
void | sync() Writes and reads all preference changes to and from this and any subnodes. |
static java.util.prefs.Preferences | systemNodeForPackage(java.lang.Object o) Returns the system preferences node for the package of an object. |
static java.util.prefs.Preferences | systemRoot() Returns the system preferences root node containing usefull preferences for all users. |
java.lang.String | toString() Returns the String given by
|
static java.util.prefs.Preferences | userNodeForPackage(java.lang.Object o) Returns the user preferences node for the package of an object. |
static java.util.prefs.Preferences | userRoot() Returns the user preferences root node containing preferences for the the current user. |
public static final int MAX_KEY_LENGTH
public static final int MAX_NAME_LENGTH
public static final int MAX_VALUE_LENGTH
protected Preferences()
public String absolutePath()
public void addNodeChangeListener(java.util.prefs.NodeChangeListener listener)
Parameters:listener
- public void addPreferenceChangeListener(java.util.prefs.PreferenceChangeListener listener)
Parameters:listener
- public String[] childrenNames()
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- when this node has been removedpublic void clear()
The result will be immediatly visible in this VM, but may not be immediatly written to the backing store.
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removedpublic void exportNode(java.io.OutputStream os)
os
- public void exportSubtree(java.io.OutputStream os)
os
- public void flush()
sync()
method to actually see the changes to the backing
store.
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removedpublic String get(java.lang.String key, java.lang.String defaultVal)
key
- defaultVal
- IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic boolean getBoolean(java.lang.String key, boolean defaultVal)
key
- defaultVal
- IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic byte[] getByteArray(java.lang.String key, byte[] defaultVal)
key
- defaultVal
- IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic double getDouble(java.lang.String key, double defaultVal)
Double.parseDouble()
then that double is returned,
otherwise the given default double value is returned.
key
- defaultVal
- IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic float getFloat(java.lang.String key, float defaultVal)
Float.parseFloat()
then that float is returned,
otherwise the given default float value is returned.
key
- defaultVal
- IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic int getInt(java.lang.String key, int defaultVal)
Integer.parseInt()
then that integer is returned,
otherwise the given default integer value is returned.
key
- defaultVal
- IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic long getLong(java.lang.String key, long defaultVal)
Long.parseLong()
then that long is returned,
otherwise the given default long value is returned.
key
- defaultVal
- IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic static void importPreferences(java.io.InputStream is)
is
- public boolean isUserNode()
public String[] keys()
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removedpublic String name()
public Preferences node(java.lang.String path)
path
- IllegalStateException
- if this node has been removedIllegalArgumentException
- if the path contains two or more
consecutive '/' characters, ends with a '/' charactor and is not the
string "/" (indicating the root node) or any name on the path is more
then 80 characters longpublic boolean nodeExists(java.lang.String path)
path
- BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removed
and the path is not the empty string (indicating this node)IllegalArgumentException
- if the path contains two or more
consecutive '/' characters, ends with a '/' charactor and is not the
string "/" (indicating the root node) or any name on the path is more
then 80 characters longpublic Preferences parent()
IllegalStateException
- if this node has been removedpublic void put(java.lang.String key, java.lang.String value)
The result will be immediatly visible in this VM, but may not be immediatly written to the backing store.
key
- value
- NullPointerException
- if either key or value are nullIllegalArgumentException
- if either key or value are to largeIllegalStateException
- when this node has been removedpublic void putBoolean(java.lang.String key, boolean value)
Boolean.toString(value)
and then stored in the preference entry as that string.
key
- value
- NullPointerException
- if key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void putByteArray(java.lang.String key, byte[] value)
Note that a byte array encoded as a Base64 string will be about 1.3 times larger then the original length of the byte array, which means that the byte array may not be larger about 6 KB.
key
- value
- NullPointerException
- if either key or value are nullIllegalArgumentException
- if either key or value are to largeIllegalStateException
- when this node has been removedpublic void putDouble(java.lang.String key, double value)
Double.toString(double)
and then stored in the preference entry as that string.
key
- value
- NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void putFloat(java.lang.String key, float value)
Float.toString(float)
and then stored in the preference entry as that string.
key
- value
- NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void putInt(java.lang.String key, int value)
Integer.toString(int)
and then stored in the preference entry as that string.
key
- value
- NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void putLong(java.lang.String key, long value)
Long.toString(long)
and then stored in the preference entry as that string.
key
- value
- NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void remove(java.lang.String key)
The result will be immediatly visible in this VM, but may not be immediatly written to the backing store.
key
- NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic void removeNode()
InvalidStateException
),
even when a new node with the same path name is created this instance
will not be usable again. The root (system or user) may never be removed.
Note that according to the specification an implementation may delay
removal of the node from the backing store till the flush()
method is called. But the flush()
method may throw a
IllegalStateException
when the node has been removed.
So most implementations will actually remove the node and any subnodes
from the backing store immediatly.
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has already been removedUnsupportedOperationException
- if this is a root nodepublic void removeNodeChangeListener(java.util.prefs.NodeChangeListener listener)
Parameters:listener
- public void removePreferenceChangeListener(java.util.prefs.PreferenceChangeListener listener)
Parameters:listener
- public void sync()
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removedpublic static Preferences systemNodeForPackage(java.lang.Object o)
systemRoot().node(packageNodeName)
.
o
- Object whose default system preference node is requestedSecurityException
- when a security manager is installed and
the caller does not have RuntimePermission("preferences")
.public static Preferences systemRoot()
SecurityException
- when a security manager is installed and
the caller does not have RuntimePermission("preferences")
.public String toString()
(isUserNode() ? "User":"System") + " Preference Node: " + absolutePath()
public static Preferences userNodeForPackage(java.lang.Object o)
userRoot().node(packageNodeName)
.
o
- Object whose default user preference node is requestedSecurityException
- when a security manager is installed and
the caller does not have RuntimePermission("preferences")
.public static Preferences userRoot()
SecurityException
- when a security manager is installed and
the caller does not have RuntimePermission("preferences")
.
There are two preference node trees, a system tree which can be accessed by calling
systemRoot()
containing system preferences usefull for all users, and a user tree that can be accessed by callinguserRoot()
containing preferences that can differ between different users. How different users are identified is implementation depended. It can be determined by Thread, Access Control Context or Subject.This implementation uses the "java.util.prefs.PreferencesFactory" system property to find a class that implement
PreferencesFactory
and initialized that class (if it has a public no arguments contructor) to get at the actual system or user root. If the system property is not set, or the class cannot be initialized it uses the default implementationgnu.java.util.prefs.FileBasedFactory
.Besides the two static method above to get the roots of the system and user preference node trees there are also two convenience methods to access the default preference node for a particular package an object is in. These are
userNodeForPackage()
andsystemNodeForPackage()
. Both methods take an Object as an argument so accessing preferences values can be as easy as callingPreferences.userNodeForPackage(this)
.Note that if a security manager is installed all static methods check for
RuntimePermission("preferences")
. But if this permission is given to the code then it can access and change all (user) preference nodes and entries. So you should be carefull not to store to sensitive information or make security decissions based on preference values since there is no more fine grained control over what preference values can be changed once code has been given the correct runtime permission.XXX