public abstract class Preferences extends Object
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 calling
userRoot()
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 implementation
gnu.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()
and systemNodeForPackage()
.
Both methods take an Object as an argument so accessing preferences values
can be as easy as calling Preferences.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
Modifier and Type | Field and Description |
---|---|
static int |
MAX_KEY_LENGTH
Maximum entry key length. 80 characters.
|
static int |
MAX_NAME_LENGTH
Maximum node name length. 80 characters.
|
static int |
MAX_VALUE_LENGTH
Maximum entry value length. 8192 characters.
|
Modifier | Constructor and Description |
---|---|
protected |
Preferences()
Creates a new Preferences node.
|
Modifier and Type | Method and Description |
---|---|
abstract String |
absolutePath()
Returns the absolute path name of this preference node.
|
abstract void |
addNodeChangeListener(NodeChangeListener listener) |
abstract void |
addPreferenceChangeListener(PreferenceChangeListener listener) |
abstract String[] |
childrenNames()
Returns all the direct sub nodes of this preferences node.
|
abstract void |
clear()
Removes all entries from this preferences node.
|
abstract void |
exportNode(OutputStream os)
Export this node, but not its descendants, as XML to the
indicated output stream.
|
abstract void |
exportSubtree(OutputStream os)
Export this node and all its descendants as XML to the
indicated output stream.
|
abstract void |
flush()
Writes all preference changes on this and any subnode that have not
yet been written to the backing store.
|
abstract String |
get(String key,
String defaultVal)
Returns the value associated with the key in this preferences node.
|
abstract boolean |
getBoolean(String key,
boolean defaultVal)
Convenience method for getting the given entry as a boolean.
|
abstract byte[] |
getByteArray(String key,
byte[] defaultVal)
Convenience method for getting the given entry as a byte array.
|
abstract double |
getDouble(String key,
double defaultVal)
Convenience method for getting the given entry as a double.
|
abstract float |
getFloat(String key,
float defaultVal)
Convenience method for getting the given entry as a float.
|
abstract int |
getInt(String key,
int defaultVal)
Convenience method for getting the given entry as an integer.
|
abstract long |
getLong(String key,
long defaultVal)
Convenience method for getting the given entry as a long.
|
static void |
importPreferences(InputStream is)
Import preferences from the given input stream.
|
abstract boolean |
isUserNode()
Returns true if this node comes from the user preferences tree, false
if it comes from the system preferences tree.
|
abstract String[] |
keys()
Returns an (possibly empty) array with all the keys of the preference
entries of this node.
|
abstract String |
name()
Returns the name of this preferences node.
|
abstract Preferences |
node(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 '/').
|
abstract boolean |
nodeExists(String path)
Returns true if the node that the path points to exists in memory or
in the backing store.
|
abstract Preferences |
parent()
Returns the parent preferences node of this node or null if this is
the root of the preferences tree.
|
abstract void |
put(String key,
String value)
Sets the value of the given preferences entry for this node.
|
abstract void |
putBoolean(String key,
boolean value)
Convenience method for setting the given entry as a boolean.
|
abstract void |
putByteArray(String key,
byte[] value)
Convenience method for setting the given entry as an array of bytes.
|
abstract void |
putDouble(String key,
double value)
Convenience method for setting the given entry as a double.
|
abstract void |
putFloat(String key,
float value)
Convenience method for setting the given entry as a float.
|
abstract void |
putInt(String key,
int value)
Convenience method for setting the given entry as an integer.
|
abstract void |
putLong(String key,
long value)
Convenience method for setting the given entry as a long.
|
abstract void |
remove(String key)
Removes the preferences entry from this preferences node.
|
abstract void |
removeNode()
Removes this and all subnodes from the backing store and clears all
entries.
|
abstract void |
removeNodeChangeListener(NodeChangeListener listener) |
abstract void |
removePreferenceChangeListener(PreferenceChangeListener listener) |
abstract void |
sync()
Writes and reads all preference changes to and from this and any
subnodes.
|
static Preferences |
systemNodeForPackage(Class<?> c)
Returns the system preferences node for the package of a class.
|
static Preferences |
systemRoot()
Returns the system preferences root node containing usefull preferences
for all users.
|
abstract String |
toString()
Returns the String given by
(isUserNode() ? |
static Preferences |
userNodeForPackage(Class<?> c)
Returns the user preferences node for the package of a class.
|
static Preferences |
userRoot()
Returns the user preferences root node containing preferences for the
the current user.
|
public static final int MAX_NAME_LENGTH
public static final int MAX_KEY_LENGTH
public static final int MAX_VALUE_LENGTH
protected Preferences()
public static Preferences systemRoot() throws SecurityException
SecurityException
- when a security manager is installed and
the caller does not have RuntimePermission("preferences")
.public static Preferences userRoot() throws SecurityException
SecurityException
- when a security manager is installed and
the caller does not have RuntimePermission("preferences")
.public static Preferences systemNodeForPackage(Class<?> c) throws SecurityException
systemRoot().node(packageNodeName)
.c
- 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 userNodeForPackage(Class<?> c) throws SecurityException
userRoot().node(packageNodeName)
.c
- Object whose default userpreference node is requestedSecurityException
- when a security manager is installed and
the caller does not have RuntimePermission("preferences")
.public static void importPreferences(InputStream is) throws InvalidPreferencesFormatException, IOException
exportNode(OutputStream)
and
exportSubtree(OutputStream)
.IOException
- if there is an error while readingInvalidPreferencesFormatException
- if the XML is not properly
formattedpublic abstract String absolutePath()
public abstract boolean isUserNode()
public abstract String name()
public abstract String toString()
(isUserNode() ? "User":"System") + " Preference Node: " + absolutePath()
toString
in class Object
Object.getClass()
,
Object.hashCode()
,
Class.getName()
,
Integer.toHexString(int)
public abstract String[] childrenNames() throws BackingStoreException
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- when this node has been removedpublic abstract Preferences node(String 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 abstract boolean nodeExists(String path) throws BackingStoreException
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 abstract Preferences parent()
IllegalStateException
- if this node has been removedpublic abstract void exportNode(OutputStream os) throws BackingStoreException, IOException
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
os
- the output stream to which the XML is sentBackingStoreException
- if preference data cannot be readIOException
- if an error occurs while writing the XMLIllegalStateException
- if this node or an ancestor has been removedpublic abstract void exportSubtree(OutputStream os) throws BackingStoreException, IOException
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
os
- the output stream to which the XML is sentBackingStoreException
- if preference data cannot be readIOException
- if an error occurs while writing the XMLIllegalStateException
- if this node or an ancestor has been removedpublic abstract String[] keys() throws BackingStoreException
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removedpublic abstract String get(String key, String defaultVal)
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic abstract boolean getBoolean(String key, boolean defaultVal)
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic abstract byte[] getByteArray(String key, byte[] defaultVal)
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic abstract double getDouble(String key, double defaultVal)
Double.parseDouble()
then that double is returned,
otherwise the given default double value is returned.IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic abstract float getFloat(String key, float defaultVal)
Float.parseFloat()
then that float is returned,
otherwise the given default float value is returned.IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic abstract int getInt(String key, int defaultVal)
Integer.parseInt()
then that integer is returned,
otherwise the given default integer value is returned.IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic abstract long getLong(String key, long defaultVal)
Long.parseLong()
then that long is returned,
otherwise the given default long value is returned.IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is nullpublic abstract void put(String key, String value)
The result will be immediatly visible in this VM, but may not be immediatly written to the backing store.
NullPointerException
- if either key or value are nullIllegalArgumentException
- if either key or value are to largeIllegalStateException
- when this node has been removedpublic abstract void putBoolean(String key, boolean value)
Boolean.toString(value)
and then stored in the preference entry as that string.NullPointerException
- if key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic abstract void putByteArray(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.
NullPointerException
- if either key or value are nullIllegalArgumentException
- if either key or value are to largeIllegalStateException
- when this node has been removedpublic abstract void putDouble(String key, double value)
Double.toString(double)
and then stored in the preference entry as that string.NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic abstract void putFloat(String key, float value)
Float.toString(float)
and then stored in the preference entry as that string.NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic abstract void putInt(String key, int value)
Integer.toString(int)
and then stored in the preference entry as that string.NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic abstract void putLong(String key, long value)
Long.toString(long)
and then stored in the preference entry as that string.NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic abstract void remove(String key)
The result will be immediatly visible in this VM, but may not be immediatly written to the backing store.
NullPointerException
- if the key is nullIllegalArgumentException
- if the key length is to largeIllegalStateException
- when this node has been removedpublic abstract void clear() throws BackingStoreException
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 abstract void flush() throws BackingStoreException
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 abstract void sync() throws BackingStoreException
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removedpublic abstract void removeNode() throws BackingStoreException
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 abstract void addNodeChangeListener(NodeChangeListener listener)
public abstract void addPreferenceChangeListener(PreferenceChangeListener listener)
public abstract void removeNodeChangeListener(NodeChangeListener listener)
public abstract void removePreferenceChangeListener(PreferenceChangeListener listener)