Class Preferences

public static final int MAX_KEY_LENGTH

Maximum entry key length. 80 characters.

Field Value:

80

public static final int MAX_NAME_LENGTH

Maximum node name length. 80 characters.

Field Value:

80

public static final int MAX_VALUE_LENGTH

Maximum entry value length. 8192 characters.

Field Value:

8192

protected Preferences()

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

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

public abstract void addNodeChangeListener(NodeChangeListener listener)

public abstract void addPreferenceChangeListener(PreferenceChangeListener listener)

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

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

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

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

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

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

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

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

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

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

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

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

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

public abstract boolean isUserNode()

Returns true if this node comes from the user preferences tree, false if it comes from the system preferences tree.

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

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 "".

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

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

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

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

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

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

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

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

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

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

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

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

public abstract void removeNodeChangeListener(NodeChangeListener listener)

public abstract void removePreferenceChangeListener(PreferenceChangeListener listener)

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

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").

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").

public abstract String toString()

Returns the String given by (isUserNode() ? "User":"System") + " Preference Node: " + absolutePath()

Overrides:

toString in interface Object

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").

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").