wt.prefs
Class Preferences

java.lang.Object
  wt.prefs.Preferences

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

WTPreferences

public abstract class Preferences

extends Object

implements Serializable

Abstract implementation of the javax.prefs.Preferences class. This is an approved javax standard with no concrete implementations available as of our implementation. Once the official implementation is available, it will likely replace this implementation. See http://java.sun.com/aboutJava/communityprocess/jsr/jsr_010_prefs.html for more information. The implementation class returned by the static factory methods in this class may be specified usin gthe system property "javax.Preferences.implementation". This defaults to wt.prefs.WTPreferences.

Supported API: true

Extendable: false

See Also:

Serialized Form

Field Summary

private static String	CLASSNAME
private static Class	impl
private String	nodeName
private String	path
private static String	RESOURCE

Constructor Summary

protected	Preferences() Creates a new uninitialized Preferences object.
protected	Preferences(Preferences parent, String name) Creates a new preference node with the specified parent and the specified name relative to its parent.

Method Summary

protected abstract Preferences	child(String name) Returns the named child of this preference node, creating it if it does not already exist.
abstract Preferences[]	children() Returns the children of this preference node.
void	clear() Removes all of the preferences (key-value associations) in this preference node.
abstract void	flush() Forces any changes in the contents of this preference node and its descendants to the persistent store.
static Preferences	forClass(Object o) Returns the preference node associated (by convention) with the specified object's class.
static Preferences	forPackage(Object o) Returns the preference node associated (by convention) with the specified object's package.
String	fullName() Returns this preference node's absolute path name.
abstract String	get(String key, String def) Returns the value associated with the specified key in this preference node.
boolean	getBoolean(String key, boolean def) Returns the boolean value represented by the string associated with the specified key in this preference node.
int	getInt(String key, int def) Returns the int value represented by the string associated with the specified key in this preference node.
protected void	init(Preferences parent, String name) Initializes this Preferences object, which must be uninitialized prior to this call.
abstract String[]	keys() Returns all of the keys that have an associated value in this preference node.
String	name() Returns this preference node's name, relative to its parent.
Preferences	node(String pathName) Returns the named preference node, creating it and any of its ancestors if they do not already exist.
boolean	nodeExists(String pathName) Returns true if the named preference node exists.
Preferences	parent() Returns the parent of this preference node, or null if this is the root.
abstract String	put(String key, String value) Associated the specified value with the specified key in this preference node.
void	putBoolean(String key, boolean value) Associates a string representing the specified boolean value with the specified key in this preference node.
void	putInt(String key, int value) Associates a string representing the specified int value with the specified key in this preference node.
abstract void	refresh() Ensures that future reads from this preference node and its descendants reflect any changes that have been committed to the persistent store (from any VM).
abstract String	remove(String key) Removes the value associated with the specified key in this preference node, if any.
protected abstract boolean	removeChild(String name) Removes the named child of this preference node and all of its descendants, invalidating any preferences contained in the removed nodes.
abstract boolean	removeNode(String pathName) Removes the named preference node and all of its descendants, invalidating any preferences contained in the removed nodes.
static Preferences	root() Returns the root preference node for the calling user.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RESOURCE

private static final String RESOURCE

See Also:

Constant Field Values

CLASSNAME

private static final String CLASSNAME

path

private String path

nodeName

private String nodeName

impl

private static Class impl

Constructor Detail

Preferences

protected Preferences()

Creates a new uninitialized Preferences object. This protected constructor is provided (in conjunction with the init method) solely to permit serializable subclasses of this non-serializable class.

Supported API: false

See Also:

init(Preferences,String)

Preferences

protected Preferences(Preferences parent,
                      String name)

Creates a new preference node with the specified parent and the specified name relative to its parent.

Supported API: false

Parameters:

parent - the parent of this preference node, or null if this is the root.

name - the name of this preference node, relative to its parent, or "" if this is the root.

Throws:

IllegalArgumentException - if name contains a slash ('/'), or parent is null and name isn't "".

Method Detail

child

protected abstract Preferences child(String name)

Returns the named child of this preference node, creating it if it does not already exist. The name must be a string consisting of one or more characters. Names must not contain the slash character ('/').

If this call causes a node to be created, this node is not guaranteed to be persistent until the flush method is called on this node or one of its ancestors (or descendants).

Supported API: true

Parameters:

name - the name of the child node to return, relative to this preference node

Returns:

the named child node.

Throws:

IllegalArgumentException - if child's name is invalid.

children

public abstract Preferences[] children()

Returns the children of this preference node. (The returned array will be of size zero if this node has no children.)

Supported API: true

Returns:

the children of this preference node.

clear

public void clear()
           throws WTException

Removes all of the preferences (key-value associations) in this preference node. This call has no effect on any descendants of this node.

Supported API: true

Throws:

WTException

flush

public abstract void flush()
                    throws WTException

Forces any changes in the contents of this preference node and its descendants to the persistent store. If this preference node has been created since the last call to flush, it and all its ancestors and descendants are made permanent by this operation. Note that this call is not guaranteed to flush any preference values in ancestor nodes; merely the nodes' existence.

Once this method returns successfully, it is safe to assume that all changes made prior to the call have become permanent.

Throws:

WTException

forClass

public static Preferences forClass(Object o)

Returns the preference node associated (by convention) with the specified object's class. the convention is as follows: the absolute pathname of the node is the fully qualified class name, preceded by a slash ('/'), and with each period ('.') replaced by a slash. For example, the absolute pathname of the node associated with the class java.lang.System is java/lang/System.

An object wishing to access preferences pertaining to its class can obtain a preference node as follows:

Preferences prefs = Preferences.forClass(this);

Supported API: true

Parameters:

o -

Returns:

The preference node associated with o's class.

forPackage

public static Preferences forPackage(Object o)

Returns the preference node associated (by convention) with the specified object's package. The convention is as follows: the absolute pathname of the node is the fully qualified package name, preceded by a slash ('/'), and with each period ('.') replaced by a slash. For example, the absolute pathname of the node associated with the class java.lang.System is /java/lang.

An object wishing to access preference pertaining to its package can obtain a preference node as follows:

Preferences prefs = Preferences.forPackage(this);

Supported API: true

Parameters:

o -

Returns:

the preference node associated with o's package.

fullName

public String fullName()

Returns this preference node's absolute path name.

Supported API: true

Returns:

this preference node's absolute path name.

get

public abstract String get(String key,
                           String def)

Returns the value associated with the specified key in this preference node. Returns the specified default if there is no value associated with the key, or the backing store is inaccessible.

Some implementations may store default values in their backing stores. If there is no value associated with the specified key, but there is such a persistent default, it is returned in preference to the specified default.

Supported API: true

Parameters:

key - key whose associated value is to be returned.

def - the value to be returned in the event that this preference node has no value associated with key.

Returns:

the value associated with key, or def if no value is associated with key.

getBoolean

public boolean getBoolean(String key,
                          boolean def)

Returns the boolean value represented by the string associated with the specified key in this preference node. The only valid strings are "true", which represents true, and "false", which represents false. Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if the associated value is something other than "true" or "false".

Supported API: true

Parameters:

key - key whose associated value is to be converted to be returned as a boolean.

def - the value to be returned in the event that this preference node has no value associated with key or the associated value cannot be interpreted as a boolean.

Returns:

the boolean value represented by the string associated with key in this preference node, or null if the associated value does not exist or cannot be interpreted as a boolean.

See Also:

get(String,String), putBoolean(String,boolean)

getInt

public int getInt(String key,
                  int def)

Returns the int value represented by the string associated with the specified key in this preference node. the string is converted to an integer as by Integer.parseInt(String). returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if Integer.parseInt would throw a NumberFormatException if the associated value were passed.

This convenience method is intended to be used in conjunction with putInt.

Supported API: true

Parameters:

key - key whose associated value is to be converted to be returned as an int.

def - the value to be returned in the event that this preference node has no value associated with key or the associated value cannot be interpreted as an int.

Returns:

the int value represented by the string associated with key in this preference node, or null if the associated value does not exist or cannot be interpreted as an int.

See Also:

get(String,String), putInt(String,int)

init

protected void init(Preferences parent,
                    String name)

Initializes this Preferences object, which must be uninitialized prior to this call. this protected method is provided (in conjunction with the no-args constructor) solely to permit serializable subclasses of this non-serializable class.

Supported API: true

Parameters:

parent - the parent of this preference node, or null if this is the root

name - the name of this preference node, relative to its parent, or "" if this is the root.

Throws:

IllegalArgumentException - if name contains a slash ('/"), or parent is null and name isn't "".

IllegalStateException - if object is already initialized.

keys

public abstract String[] keys()

Returns all of the keys that have an associated value in this preference node.

Supported API: true

Returns:

an array of the keys that have an associated value in this preference node.

name

public String name()

Returns this preference node's name, relative to its parent.

Supported API: true

Returns:

this preference node's name, relative to its parent.

node

public Preferences node(String pathName)

Returns the named preference node, creating it and any of its ancestors if they do not already exist. Accepts a relative or absolute pathname. Absolute pathnames (which begin with '/') are interpreted relative to the root of this preference node. Relative pathnames (which begin with any character other than slash) are interpreted relative to this Preferences itself. The pathname "" is valid, and refers to this preference node itself.

If the returned node did not exist prior to this call, this node and any ancestors that were created by this call are not guaranteed to become persistent until the flush method is called on the returned node (or one of its descendants).

Supported API: true

Parameters:

pathName - the path name of the preference node to return.

Returns:

the specified preference node.

Throws:

IllegalArgumentException - if the path name is invalid

See Also:

flush()

nodeExists

public boolean nodeExists(String pathName)

Returns true if the named preference node exists. Accepts a relative or absolute pathname. Absolute pathnames (which begin with '/') are interpreted relative to the root of this preference node. Relative pathnames (which begin with any character other than slash) are interpreted relative to this Preferences itself. The pathname "" is valid, and refers to this preference node itself.

Supported API: true

Parameters:

pathName - the path name of the node whose existence is to be checked.

Returns:

true if the specified node exists.

parent

public Preferences parent()

Returns the parent of this preference node, or null if this is the root.

Supported API: true

Returns:

the parent of this preference node.

put

public abstract String put(String key,
                           String value)
                    throws WTException

Associated the specified value with the specified key in this preference node.

Supported API: true

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for the key.

Throws:

WTException

putBoolean

public void putBoolean(String key,
                       boolean value)
                throws WTException

Associates a string representing the specified boolean value with the specified key in this preference node. The associated string is "true" if the value is true, and "false" if it is false.

This convenience method is inteded to be used in conjunction with getBoolean.

Supported API: true

Parameters:

key - key with which the string form of value is to be associated.

value - value whose string form is to be associated with key.

Throws:

NullPointerException - if key is null

WTException

See Also:

getBoolean(String,boolean), get(String,String)

putInt

public void putInt(String key,
                   int value)
            throws WTException

Associates a string representing the specified int value with the specified key in this preference node. The associated string is the on ethat would be returned if the int value were passed to Integer.toString(int).

this convenience method is intended to be used in conjunction with getInt.

Parameters:

key - key with which the string form of value is to be associated.

value - value whos e string form is to be associated with key.

Throws:

WTException

See Also:

getInt(String, int), get(String, String)

refresh

public abstract void refresh()

Ensures that future reads from this preference node and its descendants reflect any changes that have been committed to the persistent store (from any VM).

See Also:

flush()

remove

public abstract String remove(String key)
                       throws WTException

Removes the value associated with the specified key in this preference node, if any. returns the value previously associated with the key, or null if there was no value associated with the key.

If this implementation supports stored defaults, and there is such a default for the specified property, the stored default will be "exposed" by this call, in the sense that it will be returned by a succeeding call to get.

Supported API: true

Parameters:

key - key whose mapping is to be removed from the preference node.

Throws:

WTException

See Also:

get(String, String)

removeChild

protected abstract boolean removeChild(String name)
                                throws WTException

Removes the named child of this preference node and all of its descendants, invalidating any preferences contained in the removed nodes. Once a node has been removed, attempting any operation on the corresponding Preferences object may fail with an IllegalStateException.

The removal of the specified node is not guaranteed to be persistent until the flush method is called on an ancestor of the specified node.

Supported API: true

Parameters:

name - the name of the child node to remove, relative to this preference node.

Throws:

WTException

removeNode

public abstract boolean removeNode(String pathName)
                            throws WTException

Removes the named preference node and all of its descendants, invalidating any preferences contained in the removed nodes. Accepts a relative or absolute pathname. Absolute pathnames (which begin with '/') are interpreted relative to the root of this preference node. Relative pathnames (which begin with any character other than slash) are interpreted relative to this Preferences itself. The pathname "" is valid, and refers to this preference node itself. Once a node has been removed, attempting any operation on the corresponding Preferences object may fail with an IllegalStateOperation. The removal of the specified node is not guaranteed to be persistent until the flushmethod is called on an ancestor of the specified node. (It is illegal to remove the root node.) The context of the node which is being removed will be the same edit and search context defined for the current node. Thus a context can delete a node and all of their subnodes, but not another context's nodes.

Supported API: true

Parameters:

pathName - the path name of the preference node to remove.

Returns:

true if the specified preference node existed prior to the call

Throws:

WTException

See Also:

flush()

root

public static Preferences root()

Returns the root preference node for the calling user.

Supported API: true

Returns:

the root preference node for the calling user.