* 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
* @author Mark Wielaard (mark@klomp.org)
*/
public abstract class Preferences {
// Static Fields
/**
* Default PreferencesFactory class used when the system property
* "java.util.prefs.PreferencesFactory" is not set.
*/
private static final String defaultFactoryClass
= "gnu.java.util.prefs.FileBasedFactory";
/** Permission needed to access system or user root. */
private static final Permission prefsPermission
= new RuntimePermission("preferences");
/**
* The preferences factory object that supplies the system and user root.
* Set and returned by the getFactory() method.
*/
private static PreferencesFactory factory;
/** Maximum node name length. 80 characters. */
public static final int MAX_NAME_LENGTH = 80;
/** Maximum entry key length. 80 characters. */
public static final int MAX_KEY_LENGTH = 80;
/** Maximum entry value length. 8192 characters. */
public static final int MAX_VALUE_LENGTH = 8192;
// Constructors
/**
* Creates a new Preferences node. Can only be used by subclasses.
* Empty implementation.
*/
protected Preferences() {}
// Static methods
/**
* 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.
*
* @return the root system preference node
* @exception SecurityException when a security manager is installed and
* the caller does not have RuntimePermission("preferences").
*/
public static Preferences systemRoot() throws SecurityException {
// Get the preferences factory and check for permission
PreferencesFactory factory = getFactory();
return factory.systemRoot();
}
/**
* 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.
*
* @return the root user preference node
* @exception SecurityException when a security manager is installed and
* the caller does not have RuntimePermission("preferences").
*/
public static Preferences userRoot() throws SecurityException {
// Get the preferences factory and check for permission
PreferencesFactory factory = getFactory();
return factory.userRoot();
}
/**
* Private helper method for systemRoot() and
* userRoot(). Checks security permission and instantiates the
* correct factory if it has not yet been set.
*
* When the preferences factory has not yet been set this method first
* tries to get the system propery "java.util.prefs.PreferencesFactory"
* and tries to initializes that class. If the system property is not set
* or initialization fails it returns an instance of the default factory
*
* The result will be immediatly visible in this VM, but may not be
* immediatly written to the backing store.
*
* @exception NullPointerException if either key or value are null
* @exception IllegalArgumentException if either key or value are to large
* @exception IllegalStateException when this node has been removed
*/
public abstract void put(String key, String value);
/**
* Convenience method for setting the given entry as a boolean.
* The boolean is converted with
* 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.
*
* @exception NullPointerException if either key or value are null
* @exception IllegalArgumentException if either key or value are to large
* @exception IllegalStateException when this node has been removed
*/
public abstract void putByteArray(String key, byte[] value);
/**
* Convenience method for setting the given entry as a double.
* The double is converted with
* The result will be immediatly visible in this VM, but may not be
* immediatly written to the backing store.
*
* @exception NullPointerException if the key is null
* @exception IllegalArgumentException if the key length is to large
* @exception IllegalStateException when this node has been removed
*/
public abstract void remove(String key);
// abstract methods (preference node manipulation)
/**
* 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.
*
* @exception BackingStoreException when the backing store cannot be
* reached
* @exception IllegalStateException if this node has been removed
*/
public abstract void clear() 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
*
* Note that according to the specification an implementation may delay
* removal of the node from the backing store till the gnu.java.util.prefs.FileBasedPreferencesFactory.
*
* @return the preferences factory to use
* @exception SecurityException when a security manager is installed and
* the caller does not have RuntimePermission("preferences").
*/
private static PreferencesFactory getFactory() throws SecurityException {
// First check for permission
SecurityManager sm = System.getSecurityManager();
if (sm != null) {
sm.checkPermission(prefsPermission);
}
// Get the factory
if (factory == null) {
// Caller might not have enough permissions
factory = AccessController.doPrivileged(
new PrivilegedActionsystemRoot().node(packageNodeName).
*
* @param c Object whose default system preference node is requested
* @returns system preferences node that should be used by class c
* @exception SecurityException when a security manager is installed and
* the caller does not have RuntimePermission("preferences").
*/
public static Preferences systemNodeForPackage(Class c)
throws SecurityException
{
return nodeForPackage(c, systemRoot());
}
/**
* 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).
*
* @param c Object whose default userpreference node is requested
* @returns userpreferences node that should be used by class c
* @exception SecurityException when a security manager is installed and
* the caller does not have RuntimePermission("preferences").
*/
public static Preferences userNodeForPackage(Class c)
throws SecurityException
{
return nodeForPackage(c, userRoot());
}
/**
* Private helper method for systemNodeForPackage() and
* userNodeForPackage(). Given the correct system or user
* root it returns the correct Preference node for the package node name
* of the given object.
*/
private static Preferences nodeForPackage(Class c, Preferences root) {
// Get the package path
String className = c.getName();
String packagePath;
int index = className.lastIndexOf('.');
if(index == -1) {
packagePath = "
* (isUserNode() ? "User":"System") + " Preference Node: " + absolutePath()
*
*/
public abstract String toString();
// abstract methods (navigation)
/**
* Returns all the direct sub nodes of this preferences node.
* Needs access to the backing store to give a meaningfull answer.
*
* @exception BackingStoreException when the backing store cannot be
* reached
* @exception IllegalStateException when this node has been removed
*/
public abstract String[] childrenNames() throws BackingStoreException;
/**
* 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 '/').
*
* @exception IllegalStateException if this node has been removed
* @exception 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 node(String path);
/**
* 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.
*
* @exception BackingStoreException when the backing store cannot be
* reached
* @exception IllegalStateException if this node has been removed
* and the path is not the empty string (indicating this node)
* @exception 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 the parent preferences node of this node or null if this is
* the root of the preferences tree.
*
* @exception IllegalStateException if this node has been removed
*/
public abstract Preferences parent();
// abstract methods (export)
/**
* 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">
* @param os the output stream to which the XML is sent
* @throws BackingStoreException if preference data cannot be read
* @throws IOException if an error occurs while writing the XML
* @throws IllegalStateException if this node or an ancestor has been removed
*/
public abstract void exportNode(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">
* @param os the output stream to which the XML is sent
* @throws BackingStoreException if preference data cannot be read
* @throws IOException if an error occurs while writing the XML
* @throws IllegalStateException if this node or an ancestor has been removed
*/
public abstract void exportSubtree(OutputStream os)
throws BackingStoreException,
IOException;
// abstract methods (preference entry manipulation)
/**
* Returns an (possibly empty) array with all the keys of the preference
* entries of this node.
*
* @exception BackingStoreException when the backing store cannot be
* reached
* @exception IllegalStateException if this node has been removed
*/
public abstract String[] keys() throws BackingStoreException;
/**
* 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.
*
* @exception IllegalArgumentException if key is larger then 80 characters
* @exception IllegalStateException if this node has been removed
* @exception NullPointerException if key is null
*/
public abstract String get(String key, String 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.
*
* @exception IllegalArgumentException if key is larger then 80 characters
* @exception IllegalStateException if this node has been removed
* @exception NullPointerException if key is null
*/
public abstract boolean getBoolean(String key, boolean 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.
*
* @exception IllegalArgumentException if key is larger then 80 characters
* @exception IllegalStateException if this node has been removed
* @exception NullPointerException if key is null
*/
public abstract byte[] getByteArray(String key, byte[] 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.
*
* @exception IllegalArgumentException if key is larger then 80 characters
* @exception IllegalStateException if this node has been removed
* @exception NullPointerException if key is null
*/
public abstract double getDouble(String key, double 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.
*
* @exception IllegalArgumentException if key is larger then 80 characters
* @exception IllegalStateException if this node has been removed
* @exception NullPointerException if key is null
*/
public abstract float getFloat(String key, float 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.
*
* @exception IllegalArgumentException if key is larger then 80 characters
* @exception IllegalStateException if this node has been removed
* @exception NullPointerException if key is null
*/
public abstract int getInt(String key, int 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.
*
* @exception IllegalArgumentException if key is larger then 80 characters
* @exception IllegalStateException if this node has been removed
* @exception NullPointerException if key is null
*/
public abstract long getLong(String key, long defaultVal);
/**
* 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.
* Boolean.toString(value)
* and then stored in the preference entry as that string.
*
* @exception NullPointerException if key is null
* @exception IllegalArgumentException if the key length is to large
* @exception IllegalStateException when this node has been removed
*/
public abstract void putBoolean(String key, boolean 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.
* Double.toString(double)
* and then stored in the preference entry as that string.
*
* @exception NullPointerException if the key is null
* @exception IllegalArgumentException if the key length is to large
* @exception IllegalStateException when this node has been removed
*/
public abstract void putDouble(String key, double 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.
*
* @exception NullPointerException if the key is null
* @exception IllegalArgumentException if the key length is to large
* @exception IllegalStateException when this node has been removed
*/
public abstract void putFloat(String key, float 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.
*
* @exception NullPointerException if the key is null
* @exception IllegalArgumentException if the key length is to large
* @exception IllegalStateException when this node has been removed
*/
public abstract void putInt(String key, int 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.
*
* @exception NullPointerException if the key is null
* @exception IllegalArgumentException if the key length is to large
* @exception IllegalStateException when this node has been removed
*/
public abstract void putLong(String key, long value);
/**
* Removes the preferences entry from this preferences node.
* sync() method to actually see the changes to the backing
* store.
*
* @exception BackingStoreException when the backing store cannot be
* reached
* @exception IllegalStateException if this node has been removed
*/
public abstract void flush() 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).
*
* @exception BackingStoreException when the backing store cannot be
* reached
* @exception IllegalStateException if this node has been removed
*/
public abstract void sync() 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.
* 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.
*
* @exception BackingStoreException when the backing store cannot be
* reached
* @exception IllegalStateException if this node has already been removed
* @exception UnsupportedOperationException if this is a root node
*/
public abstract void removeNode() throws BackingStoreException;
// abstract methods (listeners)
public abstract void addNodeChangeListener(NodeChangeListener listener);
public abstract void addPreferenceChangeListener
(PreferenceChangeListener listener);
public abstract void removeNodeChangeListener(NodeChangeListener listener);
public abstract void removePreferenceChangeListener
(PreferenceChangeListener listener);
}