java.util.prefs

Class Preferences

Known Direct Subclasses:
AbstractPreferences

public abstract class Preferences
extends Object

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

Since:
1.4

Field Summary

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.

Constructor Summary

Preferences()
Creates a new Preferences node.

Method Summary

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.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MAX_KEY_LENGTH

public static final int MAX_KEY_LENGTH
Maximum entry key length. 80 characters.
Field Value:
80

MAX_NAME_LENGTH

public static final int MAX_NAME_LENGTH
Maximum node name length. 80 characters.
Field Value:
80

MAX_VALUE_LENGTH

public static final int MAX_VALUE_LENGTH
Maximum entry value length. 8192 characters.
Field Value:
8192

Constructor Details

Preferences

protected Preferences()
Creates a new Preferences node. Can only be used by subclasses. Empty implementation.

Method Details

absolutePath

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

addNodeChangeListener

public abstract void addNodeChangeListener(NodeChangeListener listener)

addPreferenceChangeListener

public abstract void addPreferenceChangeListener(PreferenceChangeListener listener)

childrenNames

public abstract String[] childrenNames()
            throws BackingStoreException
Returns all the direct sub nodes of this preferences node. Needs access to the backing store to give a meaningfull answer.
Throws:
BackingStoreException - when the backing store cannot be reached
IllegalStateException - when this node has been removed

clear

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

Throws:
BackingStoreException - when the backing store cannot be reached
IllegalStateException - if this node has been removed

exportNode

public abstract void exportNode(OutputStream os)
            throws BackingStoreException,
                   IOException
Export this node, but not its descendants, as XML to the indicated output stream. The XML will be encoded using UTF-8 and will use a specified document type:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
Parameters:
os - the output stream to which the XML is sent
Throws:
BackingStoreException - if preference data cannot be read
IOException - if an error occurs while writing the XML
IllegalStateException - if this node or an ancestor has been removed

exportSubtree

public abstract void exportSubtree(OutputStream os)
            throws BackingStoreException,
                   IOException
Export this node and all its descendants as XML to the indicated output stream. The XML will be encoded using UTF-8 and will use a specified document type:
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
Parameters:
os - the output stream to which the XML is sent
Throws:
BackingStoreException - if preference data cannot be read
IOException - if an error occurs while writing the XML
IllegalStateException - if this node or an ancestor has been removed

flush

public abstract 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.
Throws:
BackingStoreException - when the backing store cannot be reached
IllegalStateException - if this node has been removed

get

public abstract 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.
Throws:
IllegalArgumentException - if key is larger then 80 characters
IllegalStateException - if this node has been removed
NullPointerException - if key is null

getBoolean

public abstract 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.
Throws:
IllegalArgumentException - if key is larger then 80 characters
IllegalStateException - if this node has been removed
NullPointerException - if key is null

getByteArray

public abstract 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.
Throws:
IllegalArgumentException - if key is larger then 80 characters
IllegalStateException - if this node has been removed
NullPointerException - if key is null

getDouble

public abstract 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.
Throws:
IllegalArgumentException - if key is larger then 80 characters
IllegalStateException - if this node has been removed
NullPointerException - if key is null

getFloat

public abstract 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.
Throws:
IllegalArgumentException - if key is larger then 80 characters
IllegalStateException - if this node has been removed
NullPointerException - if key is null

getInt

public abstract 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.
Throws:
IllegalArgumentException - if key is larger then 80 characters
IllegalStateException - if this node has been removed
NullPointerException - if key is null

getLong

public abstract 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.
Throws:
IllegalArgumentException - if key is larger then 80 characters
IllegalStateException - if this node has been removed
NullPointerException - if key is null

importPreferences

public static void importPreferences(InputStream is)
            throws InvalidPreferencesFormatException,
                   IOException
Import preferences from the given input stream. This expects preferences to be represented in XML as emitted by exportNode(OutputStream) and exportSubtree(OutputStream).
Throws:
IOException - if there is an error while reading
InvalidPreferencesFormatException - if the XML is not properly formatted

isUserNode

public abstract boolean isUserNode()
Returns true if this node comes from the user preferences tree, false if it comes from the system preferences tree.

keys

public abstract String[] keys()
            throws BackingStoreException
Returns an (possibly empty) array with all the keys of the preference entries of this node.
Throws:
BackingStoreException - when the backing store cannot be reached
IllegalStateException - if this node has been removed

name

public abstract 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 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 '/').
Throws:
IllegalStateException - if this node has been removed
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

nodeExists

public abstract 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.
Throws:
BackingStoreException - when the backing store cannot be reached
IllegalStateException - 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

parent

public abstract Preferences parent()
Returns the parent preferences node of this node or null if this is the root of the preferences tree.
Throws:
IllegalStateException - if this node has been removed

put

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

Throws:
NullPointerException - if either key or value are null
IllegalArgumentException - if either key or value are to large
IllegalStateException - when this node has been removed

putBoolean

public abstract void putBoolean(String key,
                                boolean value)
Convenience method for setting the given entry as a boolean. The boolean is converted with Boolean.toString(value) and then stored in the preference entry as that string.
Throws:
NullPointerException - if key is null
IllegalArgumentException - if the key length is to large
IllegalStateException - when this node has been removed

putByteArray

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

Throws:
NullPointerException - if either key or value are null
IllegalArgumentException - if either key or value are to large
IllegalStateException - when this node has been removed

putDouble

public abstract void putDouble(String key,
                               double value)
Convenience method for setting the given entry as a double. The double is converted with Double.toString(double) and then stored in the preference entry as that string.
Throws:
NullPointerException - if the key is null
IllegalArgumentException - if the key length is to large
IllegalStateException - when this node has been removed

putFloat

public abstract void putFloat(String key,
                              float value)
Convenience method for setting the given entry as a float. The float is converted with Float.toString(float) and then stored in the preference entry as that string.
Throws:
NullPointerException - if the key is null
IllegalArgumentException - if the key length is to large
IllegalStateException - when this node has been removed

putInt

public abstract void putInt(String key,
                            int value)
Convenience method for setting the given entry as an integer. The integer is converted with Integer.toString(int) and then stored in the preference entry as that string.
Throws:
NullPointerException - if the key is null
IllegalArgumentException - if the key length is to large
IllegalStateException - when this node has been removed

putLong

public abstract void putLong(String key,
                             long value)
Convenience method for setting the given entry as a long. The long is converted with Long.toString(long) and then stored in the preference entry as that string.
Throws:
NullPointerException - if the key is null
IllegalArgumentException - if the key length is to large
IllegalStateException - when this node has been removed

remove

public abstract void remove(String key)
Removes the preferences entry from this preferences node.

The result will be immediatly visible in this VM, but may not be immediatly written to the backing store.

Throws:
NullPointerException - if the key is null
IllegalArgumentException - if the key length is to large
IllegalStateException - when this node has been removed

removeNode

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

Throws:
BackingStoreException - when the backing store cannot be reached
IllegalStateException - if this node has already been removed
UnsupportedOperationException - if this is a root node

removeNodeChangeListener

public abstract void removeNodeChangeListener(NodeChangeListener listener)

removePreferenceChangeListener

public abstract void removePreferenceChangeListener(PreferenceChangeListener listener)

sync

public abstract 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).
Throws:
BackingStoreException - when the backing store cannot be reached
IllegalStateException - 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).
Parameters:
c - Object whose default system preference node is requested
Throws:
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.
Returns:
the root system preference node
Throws:
SecurityException - when a security manager is installed and the caller does not have RuntimePermission("preferences").

toString

public abstract String toString()
Returns the String given by (isUserNode() ? "User":"System") + " Preference Node: " + absolutePath()
Overrides:
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).
Parameters:
c - Object whose default userpreference node is requested
Throws:
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.
Returns:
the root user preference node
Throws:
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, 2006 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.