java.util.prefs
Class Preferences
Preference node containing key value entries and subnodes.
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
- 1.4
String | absolutePath() - Returns the absolute path name of this preference node.
|
void | addNodeChangeListener(NodeChangeListener listener)
|
void | addPreferenceChangeListener(PreferenceChangeListener listener)
|
String[] | childrenNames() - Returns all the direct sub nodes of this preferences node.
|
void | clear() - Removes all entries from this preferences node.
|
void | exportNode(OutputStream os) - XXX
|
void | exportSubtree(OutputStream os) - XXX
|
void | flush() - Writes all preference changes on this and any subnode that have not
yet been written to the backing store.
|
String | get(String key, String defaultVal) - Returns the value associated with the key in this preferences node.
|
boolean | getBoolean(String key, boolean defaultVal) - Convenience method for getting the given entry as a boolean.
|
byte[] | getByteArray(String key, byte[] defaultVal) - Convenience method for getting the given entry as a byte array.
|
double | getDouble(String key, double defaultVal) - Convenience method for getting the given entry as a double.
|
float | getFloat(String key, float defaultVal) - Convenience method for getting the given entry as a float.
|
int | getInt(String key, int defaultVal) - Convenience method for getting the given entry as an integer.
|
long | getLong(String key, long defaultVal) - Convenience method for getting the given entry as a long.
|
static void | importPreferences(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.
|
String[] | keys() - Returns an (possibly empty) array with all the keys of the preference
entries of this node.
|
String | name() - Returns the name of this preferences node.
|
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 '/').
|
boolean | nodeExists(String path) - Returns true if the node that the path points to exists in memory or
in the backing store.
|
Preferences | parent() - Returns the parent preferences node of this node or null if this is
the root of the preferences tree.
|
void | put(String key, String value) - Sets the value of the given preferences entry for this node.
|
void | putBoolean(String key, boolean value) - Convenience method for setting the given entry as a boolean.
|
void | putByteArray(String key, byte[] value) - Convenience method for setting the given entry as an array of bytes.
|
void | putDouble(String key, double value) - Convenience method for setting the given entry as a double.
|
void | putFloat(String key, float value) - Convenience method for setting the given entry as a float.
|
void | putInt(String key, int value) - Convenience method for setting the given entry as an integer.
|
void | putLong(String key, long value) - Convenience method for setting the given entry as a long.
|
void | remove(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(NodeChangeListener listener)
|
void | removePreferenceChangeListener(PreferenceChangeListener listener)
|
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.
|
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.
|
clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait |
MAX_KEY_LENGTH
public static final int MAX_KEY_LENGTH
Maximum entry key length. 80 characters.
- 80
MAX_NAME_LENGTH
public static final int MAX_NAME_LENGTH
Maximum node name length. 80 characters.
- 80
MAX_VALUE_LENGTH
public static final int MAX_VALUE_LENGTH
Maximum entry value length. 8192 characters.
- 8192
Preferences
protected Preferences()
Creates a new Preferences node. Can only be used by subclasses.
Empty implementation.
absolutePath
public String absolutePath()
Returns the absolute path name of this preference node.
The absolute path name of a node is the path name of its parent node
plus a '/' plus its own name. If the node is the root node and has no
parent then its name is "" and its absolute path name is "/".
clear
public void clear()
throws BackingStoreException
Removes all entries from this preferences node. May need access to the
backing store to get and clear all entries.
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 removed
flush
public void flush()
throws BackingStoreException
Writes all preference changes on this and any subnode that have not
yet been written to the backing store. This has no effect on the
preference entries in this VM, but it makes sure that all changes
are visible to other programs (other VMs might need to call the
sync()
method to actually see the changes to the backing
store.
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removed
get
public String get(String key,
String defaultVal)
Returns the value associated with the key in this preferences node. If
the default value of the key cannot be found in the preferences node
entries or something goes wrong with the backing store the supplied
default value is returned.
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is null
getBoolean
public boolean getBoolean(String key,
boolean defaultVal)
Convenience method for getting the given entry as a boolean.
When the string representation of the requested entry is either
"true" or "false" (ignoring case) then that value is returned,
otherwise the given default boolean value is returned.
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is null
getByteArray
public byte[] getByteArray(String key,
byte[] defaultVal)
Convenience method for getting the given entry as a byte array.
When the string representation of the requested entry is a valid
Base64 encoded string (without any other characters, such as newlines)
then the decoded Base64 string is returned as byte array,
otherwise the given default byte array value is returned.
IllegalArgumentException
- if key is larger then 80 charactersIllegalStateException
- if this node has been removedNullPointerException
- if key is null
getDouble
public double getDouble(String key,
double defaultVal)
Convenience method for getting the given entry as a double.
When the string representation of the requested entry can be decoded
with 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 null
getFloat
public float getFloat(String key,
float defaultVal)
Convenience method for getting the given entry as a float.
When the string representation of the requested entry can be decoded
with 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 null
getInt
public int getInt(String key,
int defaultVal)
Convenience method for getting the given entry as an integer.
When the string representation of the requested entry can be decoded
with 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 null
getLong
public long getLong(String key,
long defaultVal)
Convenience method for getting the given entry as a long.
When the string representation of the requested entry can be decoded
with 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 null
isUserNode
public boolean isUserNode()
Returns true if this node comes from the user preferences tree, false
if it comes from the system preferences tree.
name
public String name()
Returns the name of this preferences node. The name of the node cannot
be null, can be mostly 80 characters and cannot contain any '/'
characters. The root node has as name "".
node
public 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 '/').
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 long
nodeExists
public boolean nodeExists(String path)
throws BackingStoreException
Returns true if the node that the path points to exists in memory or
in the backing store. Otherwise it returns false or an exception is
thrown. When this node is removed the only valid parameter is the
empty string (indicating this node), the return value in that case
will be false.
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 long
put
public void put(String key,
String value)
Sets the value of the given preferences entry for this node.
Key and value cannot be null, the key cannot exceed 80 characters
and the value cannot exceed 8192 characters.
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 removed
putByteArray
public void putByteArray(String key,
byte[] value)
Convenience method for setting the given entry as an array of bytes.
The byte array is converted to a Base64 encoded string
and then stored in the preference entry as that string.
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 removed
removeNode
public void removeNode()
throws BackingStoreException
Removes this and all subnodes from the backing store and clears all
entries. After removal this instance will not be useable (except for
a few methods that don't throw a
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 node
sync
public void sync()
throws BackingStoreException
Writes and reads all preference changes to and from this and any
subnodes. This makes sure that all local changes are written to the
backing store and that all changes to the backing store are visible
in this preference node (and all subnodes).
BackingStoreException
- when the backing store cannot be
reachedIllegalStateException
- if this node has been removed
systemNodeForPackage
public static Preferences systemNodeForPackage(Class c)
throws SecurityException
Returns the system preferences node for the package of a class.
The package node name of the class is determined by dropping the
final component of the fully qualified class name and
changing all '.' to '/' in the package name. If the class of the
object has no package then the package node name is "<unnamed>".
The returned node is systemRoot().node(packageNodeName)
.
c
- Object whose default system preference node is requested
SecurityException
- when a security manager is installed and
the caller does not have RuntimePermission("preferences")
.
systemRoot
public static Preferences systemRoot()
throws SecurityException
Returns the system preferences root node containing usefull preferences
for all users. It is save to cache this value since it should always
return the same preference node.
- the root system preference node
SecurityException
- when a security manager is installed and
the caller does not have RuntimePermission("preferences")
.
toString
public String toString()
Returns the String given by
(isUserNode() ? "User":"System") + " Preference Node: " + absolutePath()
- toString in interface Object
userNodeForPackage
public static Preferences userNodeForPackage(Class c)
throws SecurityException
Returns the user preferences node for the package of a class.
The package node name of the class is determined by dropping the
final component of the fully qualified class name and
changing all '.' to '/' in the package name. If the class of the
object has no package then the package node name is "<unnamed>".
The returned node is userRoot().node(packageNodeName)
.
c
- Object whose default userpreference node is requested
SecurityException
- when a security manager is installed and
the caller does not have RuntimePermission("preferences")
.
userRoot
public static Preferences userRoot()
throws SecurityException
Returns the user preferences root node containing preferences for the
the current user. How different users are identified is implementation
depended. It can be determined by Thread, Access Control Context or
Subject.
- the root user preference node
SecurityException
- when a security manager is installed and
the caller does not have RuntimePermission("preferences")
.
Preferences -- Preference node containing key value entries and subnodes
Copyright (C) 2001, 2004, 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.
Linking this library statically or dynamically with other modules is
making a combined work based on this library. Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.
As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module. An independent module is a module which is not derived from
or based on this library. If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so. If you do not wish to do so, delete this
exception statement from your version.