The Java Community Process(SM) Program - communityprocess

Use of JCP site is subject to the JCP Terms of Use and the Oracle Privacy Policy

: Class Preferences

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.prefs
Class Preferences

java.lang.Object
  |
  +--javax.prefs.Preferences

public abstract class Preferences
extends java.lang.Object

A node in a hierarchical collection of preference data. This class allows applications to store and retrieve user preference and configuration data. This data is stored persistently in an implementation-dependent backing store. Possible implementations include flat files, OS-specific registries, directory servers and SQL databases.

All of the methods that modify preference data are permitted to operate asynchronously; they may return immediately, and changes will eventually propagate to the persistent backing store. The flush method may be used to force updates to the backing store.

Implementations must ensure that there is at most one Preferences object representing a given node in the Preferences hierarchy at a given time. In other words, if p1 and p2 are references to Preferences objects representing the same node in the preferences hierarchy, then p1==p2.

The methods in this class may be invoked concurrently by multiple threads in a single JVM without the need for external synchronization, and the results will be equivalent to some serial execution. If this class is used concurrently by multiple JVMs that store their preference data in the same backing store, the data store will not be corrupted, but no other guarantees are made concerning the consistency of the preference data.

Implementor's note: Concrete implementations of this abstract class must provide a public no-arguments constructor that creates the root preference node. This constructor will be called exactly once, the first time one of the static factories in this class is invoked. Further calls to the static factories will return objects obtained by invoking methods on this object (or they'll return the object itself). Implementation note: In Sun's JRE, the implementation class returned by the static factory methods in this class is may be specified using the system property "javax.Preferences.implementation". If this property is not set, a platform-specific default implementation is used. Note that this is not a part of the specification and is subject to change in future releases.

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

Method Summary
`void`	`addNodeChangeListener(NodeChangeListener ncl)` Adds the specified listener to receive `NodeChange` events for this node.
`void`	`addPropertyChangeListener(java.beans.PropertyChangeListener pcl)` Adds the specified listener to receive property change events for this preference node.
`protected abstract Preferences`	`child(java.lang.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(java.lang.Object o)` Returns the preference node associated (by convention) with the specified object's class.
`static Preferences`	`forPackage(java.lang.Object o)` Returns the preference node associated (by convention) with the specified object's package.
`java.lang.String`	`fullName()` Returns this preference node's absolute path name.
`abstract java.lang.String`	`get(java.lang.String key, java.lang.String def)` Returns the value associated with the specified key in this preference node.
`boolean`	`getBoolean(java.lang.String key, boolean def)` Returns the boolean value represented by the string associated with the specified key in this preference node.
`int`	`getInt(java.lang.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, java.lang.String name)` Initializes this Preferences object, which must be uninitialized prior to this call.
`abstract java.lang.String[]`	`keys()` Returns all of the keys that have an associated value in this preference node.
`java.lang.String`	`name()` Returns this preference node's name, relative to its parent.
`Preferences`	`node(java.lang.String pathName)` Returns the named preference node, creating it and any of its ancestors if they do not already exist.
`boolean`	`nodeExists(java.lang.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 java.lang.String`	`put(java.lang.String key, java.lang.String value)` Associates the specified value with the specified key in this preference node.
`void`	`putBoolean(java.lang.String key, boolean value)` Associates a string representing the specified boolean value with the specified key in this preference node.
`void`	`putInt(java.lang.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 java.lang.String`	`remove(java.lang.String key)` Removes the value associated with the specified key in this preference node, if any.
`protected abstract boolean`	`removeChild(java.lang.String name)` Removes the named child of this preference node and all of its descendants, invalidating any preferences contained in the removed nodes.
`boolean`	`removeNode(java.lang.String pathName)` Removes the named preference node and all of its descendants, invalidating any preferences contained in the removed nodes.
`void`	`removeNodeChangeListener(NodeChangeListener tcl)` Removes the specified `NodeChangeListener`, so it no longer receives change events.
`void`	`removePropertyChangeListener(java.beans.PropertyChangeListener pcl)` Removes the specified property change listener, so it no longer receives change events.
`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

Constructor Detail

Preferences

protected Preferences(Preferences parent,
                      java.lang.String name)

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

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:: java.lang.IllegalArgumentException - if name contains a slash ('/'), or parent is null and name isn't "".

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.

See Also:: init(Preferences,String)

Method Detail

init

protected void init(Preferences parent,
                    java.lang.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.

Parameters:: name - the name of this preference node, relative to its parent, or "" if this is the root.; parent - the parent of this preference node, or null if this is the root.
Throws:: java.lang.IllegalArgumentException - if name contains a slash ('/'), or parent is null and name isn't "".; IllegalStateException - if object is already initialized.
See Also:: Preferences()

forClass

public static Preferences forClass(java.lang.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);

(This idiom obviates the need for hard-coding the package and class names, reducing the likelihood of error.)

Returns:: The preference node associated with o's class.

forPackage

public static Preferences forPackage(java.lang.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 is /java/lang.

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

    Preferences prefs = Preferences.forPackage(this);

(This idiom obviates the need for hard-coding the package name, reducing the likelihood of error.)

Returns:: The preference node associated with o's package.

root

public static Preferences root()

Returns the root preference node for the calling user.

Returns:: the root preference node for the calling user.

put

public abstract java.lang.String put(java.lang.String key,
                                     java.lang.String value)

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

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:: NullPointerException - if key or value is null.

get

public abstract java.lang.String get(java.lang.String key,
                                     java.lang.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.

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.

remove

public abstract java.lang.String remove(java.lang.String key)

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.

Parameters:: key - key whose mapping is to be removed from the preference node.
Returns:: value previously associated with specified key, or null if there was no mapping for key. If the implementation supports stored defaults and there was no value previously associated with the specified key but there is a stored default, this operation may return this default rather than null.
See Also:: get(String,String)

putInt

public void putInt(java.lang.String key,
                   int value)

Associates a string representing the specified int value with the specified key in this preference node. The associated string is the one that 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.

Implementor's note: it is not necessary that the preference value be represented by a string in the backing store. If the backing store supports integer values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as an int (with getInt) or a string (with get).

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.
See Also:: getInt(String,int), get(String,String)

getInt

public int getInt(java.lang.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.

If the implementation supports stored defaults and such a default exists and is accessible, it is used in preference to the specified default.

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

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

putBoolean

public void putBoolean(java.lang.String key,
                       boolean value)

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 intended to be used in conjunction with getBoolean.

Implementor's note: it is not necessary that the preference value be represented by a string in the backing store. If the backing store supports boolean values, it is not unreasonable to use them. This implementation detail is not visible through the Preferences API, which allows the value to be read as an boolean (with getBoolean) or a string (with get).

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.
See Also:: getBoolean(String,boolean), get(String,String)

getBoolean

public boolean getBoolean(java.lang.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".

If the implementation supports stored defaults and such a default exists and is accessible, it is used in preference to the specified default. This convenience method is intended to be used in conjunction with putBoolean.

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

keys

public abstract java.lang.String[] keys()

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

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

clear

public void clear()

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

If this implementation supports stored defaults, and this node in the preferences hierarchy contains any such defaults, the stored defaults will be "exposed" by this call, in the sense that they will be returned by succeeding calls to get.

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

Returns:: the children of this preference node.

parent

public Preferences parent()

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

Returns:: the parent of this preference node.

node

public Preferences node(java.lang.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).

Parameters:: pathName - the path name of the preference node to return.
Returns:: the specified preference node.
Throws:: java.lang.IllegalArgumentException - if the path name is invalid.
See Also:: flush()

nodeExists

public boolean nodeExists(java.lang.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.

Parameters:: pathName - the path name of the node whose existence is to be checked.
Returns:: true if the specified node exists.

removeNode

public boolean removeNode(java.lang.String pathName)

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.

If this implementation supports stored defaults, this call may not appear to remove the specified node, in the sense that the node object will still be usable. If this node or any of its descendants have any stored defaults, they will be "exposed" by this call, in the sense that they will be returned by succeeding calls to get.

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. (It is illegal to remove the root node.)

Parameters:: pathName - the path name of the preference node to remove.
Returns:: true if the specified preference node existed prior to the call.
Throws:: java.lang.IllegalArgumentException - if the path name is invalid or the specified node is the root node.
See Also:: flush()

child

protected abstract Preferences child(java.lang.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 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).

Parameters:: name - The name of the child node to return, relative to this preference node.
Returns:: The named child node.
Throws:: java.lang.IllegalArgumentException - if child's name is invalid.

removeChild

protected abstract boolean removeChild(java.lang.String name)

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

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.

Parameters:: name - The name of the child node to remove, relative to this preference node.
Returns:: true if the named child node existed prior to the call.

name

public java.lang.String name()

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

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

fullName

public java.lang.String fullName()

Returns this preference node's absolute path name.

Returns:: this preference node's absolute path name.

flush

public abstract void flush()
                    throws java.io.IOException

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.

Implementors note: the foregoing implies that once a call to this method fails, all succeeding calls must fail until any pending changes have been made permanent.

Throws:: java.io.IOException - if the changes cannot be flushed.

refresh

public abstract void refresh()
                      throws java.io.IOException

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

Some implementations may, as a side-effect, cause this VM's pending updates (if any) to be flushed to the persistent store, but this behavior is not required. (A pending update is an update that has not yet propagated to the persistent store.) Some implementations, however, may cause this VM's pending updates (if any) to be lost. If the caller wishes to ensure that this does not happen, flush should be called prior to refresh.

Implementation note: implementors should generally strive to avoid the loss of any pending updates when this method is called.

Throws:: java.io.IOException - IO required for the execution of this call could not be completed.
See Also:: flush()

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener pcl)

Adds the specified listener to receive property change events for this preference node. A property change event is generated when a preference is added to this node, removed from this node, or when the value associated with a key in this node is changed. The property name is the preference being added, removed or modified. An old value of null indicates that a preference has been added to the node. A new value of null indicates that a preference has been removed.

Events are only guaranteed for changes made within the same JVM as the registered listener, though some implementations may generate events for changes made outside this JVM. Events may be generated before the changes have been made permanent. Events are not generated when preferences are modified in descendants of this node; a caller desiring such events must register with each descendant.

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener pcl)

Removes the specified property change listener, so it no longer receives change events.

Throws:: java.lang.IllegalArgumentException - if pcl was not a registered property change listener on this node.

addNodeChangeListener

public void addNodeChangeListener(NodeChangeListener ncl)

Adds the specified listener to receive NodeChange events for this node. A NodeChange event is generated when a child node is added to or removed from this node. Events are only guaranteed for changes made within the same JVM as the registered listener, though some implementations may generate events for changes made outside this JVM. Events may be generated before the changes have been made permanent. Events are not generated when indirect descendants of this node are added or removed; a caller desiring such events must register with each descendant.

removeNodeChangeListener

public void removeNodeChangeListener(NodeChangeListener tcl)

Removes the specified NodeChangeListener, so it no longer receives change events.

Throws:: java.lang.IllegalArgumentException - if ncl was not a registered NodeChangeListener on this node.

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.prefs Class Preferences

Preferences

Preferences

init

forClass

forPackage

root

put

get

remove

putInt

getInt

putBoolean

getBoolean

keys

clear

children

parent

node

nodeExists

removeNode

child

removeChild

name

fullName

flush

refresh

addPropertyChangeListener

removePropertyChangeListener

addNodeChangeListener

removeNodeChangeListener

javax.prefs
Class Preferences