wt.prefs
Class WTPreferences

java.lang.Object
  wt.prefs.Preferences
      wt.prefs.WTPreferences

All Implemented Interfaces:

Serializable

public class WTPreferences

extends Preferences

implements Serializable

Concrete implementation of javax.prefs.Preferences using Windchill for the backing store.

Features beyond the javax.prefs specification are available using this implementation, but typical preference operations should be invoked from the abstract Preferences class to insure compatibility with other Preferences implementation which may become available in the future.

The main additional feature of WTPreferences is the inclusion of contexts. A context defines a grouping of preference entries. An instance of WTPreference has a contextMask and an editContext attribute which define the contexts used in reading and writing preference entries. contextMask is actually an array of contexts which are searched in order for each get request. The default contextMask is {USER_CONTEXT, DEFAULT_CONTEXT} and the default editContext is the first element of the contextMask. These default settings allow a user to "hide" a system-wide default. If no entries are found within the contextMask's contexts, then the programmatic default will be returned.

Supported API: true

Extendable: false

See Also:

Serialized Form

Field Summary

private boolean	CACHE_COMPLETE
private static boolean	CACHE_VERBOSE
private static String	CLASSNAME
static String	CONTAINER_CONTEXT Constant for Container Context Preference Heirarchies Supported API: true
static String	CONTAINER_POLICY_CONTEXT Constant for Policy driven preferences Supported API: true
private String[]	contextMask
static String	DEFAULT_CONTEXT Supported API: true
static String	DIVISION_CONTEXT Constant for Division Context Preference Heirarchies Supported API: true
static String	DIVISION_POLICY_CONTEXT Constant for Policy driven preferences Supported API: true
private String	editContext
private Hashtable	entries
private PreferenceServiceFwd	prefFwd
private static String	RESOURCE
private String	user
static String	USER_CONTEXT Supported API: true
private static boolean	VERBOSE

Fields inherited from class wt.prefs.Preferences

Constructor Summary

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

Method Summary

protected Preferences	child(String name) Returns the named child of this preference node, creating it if it does not already exist.
Preferences[]	children() Returns the children of this preference node.
void	clear() Removes all of the preferences (key-value associations) in this preference node.
boolean	containsKey(String aKey, String[] mask) will return true if the Preferences contains the desired key.
private static String	createCacheKey(String key, String context)
void	flush() Forces any changes in the contents of this preference node and its descendants to the persistent store.
String	get(String key, String def) Returns the value associated with the specified key in this preference node.
String[]	getAsList(String key, String token) This method will get a Preference from the system for the desired key and along with a token String will return an array of items that represent the items in the Preference Separated by the Token.
String	getContext(String key) Returns the context which a call to a get operation would retrieve a value from.
String[]	getContextMask() Gets the value of the attribute: contextMask; The list of contexts used in retrieving values from persistance storage.
String	getEditContext() Gets the value of the attribute: editContext; Context which edit calls (ie put, remove) will be persisted against.
private PrefEntry	getEntry(String key)
PrefEntry	getEntry(String key, boolean checkCache)
private static String	getKeyFromcreateCacheKey(String key)
private String	getUser()
boolean	isContext(String key, String context) Returns true if the context used in retrieving the key's value is the same as the context passed in.
boolean	isUserContext(String key) This method will determine whether a given key's preference for the current context is the User Context.
String[]	keys() Returns all of the keys that have an associated value in this preference node.
static void	main(String[] args)
void	preload() Preloads all preference entries into the preference object.
void	preload(String[] keys) Preloads preference entries into the preference object for all keys specified in the keys argument.
String	put(String key, String value) Associated the specified value with the specified key in this preference node.
void	putAll(HashMap map) Will put all the entries in the HashMap into the Preferences System.
void	putAll(String context, HashMap map) Will put all the entries in the HashMap into the Preferences System.
String	putAsList(String key, String[] value, String token) This method will put a Preference into the system for the desired key and along with a token String will store an array of items that.
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).
void	refresh(String key) Ensures that future reads from this preference node for the key reflect any changes that have been committed to the persistent store.
void	refresh(String[] keys) Ensures that future reads for the given keys of this preference node reflect any changes that have been committed to the persistent store.
String	remove(String key) Removes the value associated with the specified key in this preference node, if any.
protected 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.
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.
static Preferences	root(boolean createCache)
void	setContextMask(String[] a_ContextMask) Sets the value of the attribute: contextMask; The list of contexts used in retrieving values from persistance storage.
void	setEditContext(String a_EditContext) Sets the value of the attribute: editContext; Context which edit calls (ie put, remove) will be persisted against.
String	toString()
private static String	uncreateCacheKey(String key)
void	updateContext(String key, String value, String context)
private void	updateEntry(PrefEntry entry)

Methods inherited from class wt.prefs.Preferences

forClass, forPackage, fullName, getBoolean, getInt, init, name, node, nodeExists, parent, putBoolean, putInt

Methods inherited from class java.lang.Object

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

Field Detail

RESOURCE

private static final String RESOURCE

See Also:

Constant Field Values

CLASSNAME

private static final String CLASSNAME

entries

private Hashtable entries

contextMask

private String[] contextMask

editContext

private String editContext

DIVISION_CONTEXT

public static final String DIVISION_CONTEXT

Constant for Division Context Preference Heirarchies

Supported API: true

See Also:

Constant Field Values

DIVISION_POLICY_CONTEXT

public static final String DIVISION_POLICY_CONTEXT

Constant for Policy driven preferences

Supported API: true

See Also:

Constant Field Values

USER_CONTEXT

public static final String USER_CONTEXT

Supported API: true

See Also:

Constant Field Values

DEFAULT_CONTEXT

public static final String DEFAULT_CONTEXT

Supported API: true

See Also:

Constant Field Values

CONTAINER_CONTEXT

public static final String CONTAINER_CONTEXT

Constant for Container Context Preference Heirarchies

Supported API: true

See Also:

Constant Field Values

CONTAINER_POLICY_CONTEXT

public static final String CONTAINER_POLICY_CONTEXT

Constant for Policy driven preferences

Supported API: true

See Also:

Constant Field Values

user

private String user

prefFwd

private PreferenceServiceFwd prefFwd

VERBOSE

private static boolean VERBOSE

CACHE_VERBOSE

private static boolean CACHE_VERBOSE

CACHE_COMPLETE

private boolean CACHE_COMPLETE

Constructor Detail

WTPreferences

protected WTPreferences()

Creates a new uninitialized WTPreferences object.

Supported API: false

WTPreferences

protected WTPreferences(Preferences parent,
                        String name)

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

Supported API: false

Parameters:

parent -

name -

Throws:

java.lang.IllegalArumentException - if name contains a slahs ('/'), or parent is null and name isn't "".

WTPreferences

protected WTPreferences(Preferences parent,
                        String name,
                        boolean createCache)

Method Detail

getContextMask

public String[] getContextMask()

Gets the value of the attribute: contextMask; The list of contexts used in retrieving values from persistance storage. In retrieving values from storage, the context will be searched in order and return the first value found. The default context is {WTPreferences.USER, WTPreferences.DEFAULT}. This allows users to specify a preference value that "hide" values stored in the DEFAULT context. In the absence of a value in the USER context, the DEFAULT context will be returned. In the case that no contexts contain value, the programmatic default passed in the get calls will be returned.

Supported API: true

Returns:

String[]

See Also:

get(String,String)

setContextMask

public void setContextMask(String[] a_ContextMask)

Sets the value of the attribute: contextMask; The list of contexts used in retrieving values from persistance storage. In retrieving values from storage, the context will be searched in order and return the first value found. The default context is {WTPreferences.USER, WTPreferences.DEFAULT}. This allows users to specify a preference value that "hide" values stored in the DEFAULT context. In the absence of a value in the USER context, the DEFAULT context will be returned. In the case that no contexts contain value, the programmatic default passed in the get calls will be returned.

Supported API: true

Parameters:

a_ContextMask -

See Also:

get(String,String)

getEditContext

public String getEditContext()

Gets the value of the attribute: editContext; Context which edit calls (ie put, remove) will be persisted against. Do not create context's beginning with '$', these are reserved for use by the system.

Supported API: true

Returns:

String

See Also:

put(String,String), remove(String)

setEditContext

public void setEditContext(String a_EditContext)

Sets the value of the attribute: editContext; Context which edit calls (ie put, remove) will be persisted against. Do not create context's beginning with '$', these are reserved for use by the system.

Supported API: true

Parameters:

a_EditContext -

See Also:

put(String,String), remove(String)

preload

public void preload()

Preloads all preference entries into the preference object. If preload is not set then preference entries will be retrieved from the server as necessary. Preload should probably be used if the application knows that it will be retrieving multiple entries.

Supported API: true

preload

public void preload(String[] keys)

Preloads preference entries into the preference object for all keys specified in the keys argument. If preload is not set then preference entries will be retrieved from the server as necessary. Preload should probably be used if the application knows that it will be retrieving multiple entries.

Supported API: true

Parameters:

keys -

getContext

public String getContext(String key)

Returns the context which a call to a get operation would retrieve a value from. The context returned from this call may contain additional information beyond that of the editContext which created the element. Use the isContext method to check which context a value is retrieved from.

Supported API: true

Parameters:

key - key whose associated value's context is returned.

Returns:

String

See Also:

isContext(String,String)

isContext

public boolean isContext(String key,
                         String context)

Returns true if the context used in retrieving the key's value is the same as the context passed in. This should be used in place of comparing a context with the value returned by getContext. getContext may have additional information appended to the context which is stripped by the comparison within this method.

To check if the returned value is from the user's context:

boolean fromUser = pref.isContext("foo", WTPreferences.USER_CONTEXT);

Supported API: true

Parameters:

key - key whose associated value's context is being compared.

context - context which is being compared with key's context. This may be any context, predefined context's are USER_CONTEXT and DEFAULT_CONTEXT.

Returns:

boolean

See Also:

getContext(String), USER_CONTEXT, DEFAULT_CONTEXT

isUserContext

public boolean isUserContext(String key)

This method will determine whether a given key's preference for the current context is the User Context. Since mutli-level user preferences means that a given node could have mutliple contexts, this method will determine that for the current search context is the designated key present at the $USER_CONTEXT such that a get( ) call will return the user's value.

Supported API: false

Parameters:

key - The key to determine the context for.

Returns:

boolean

putAll

public void putAll(String context,
                   HashMap map)
            throws WTException

Will put all the entries in the HashMap into the Preferences System.

Supported API: true

Parameters:

context - The edit context

map - The map of key/value pairs

Throws:

WTException

putAll

public void putAll(HashMap map)
            throws WTException

Will put all the entries in the HashMap into the Preferences System. The edit context will be set to the user Edit Context

Supported API: true

Parameters:

map - The map of key/value pairs

Throws:

WTException

refresh

public void refresh(String key)

Ensures that future reads from this preference node for the key reflect any changes that have been committed to the persistent store.

Supported API: true

Parameters:

key -

See Also:

flush()

refresh

public void refresh(String[] keys)

Ensures that future reads for the given keys of this preference node reflect any changes that have been committed to the persistent store.

Supported API: true

Parameters:

keys -

See Also:

flush()

child

protected 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

Specified by:

child in class Preferences

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

Specified by:

children in class Preferences

Returns:

the children of this preference node.

flush

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

Specified by:

flush in class Preferences

Throws:

WTException

get

public 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

Specified by:

get in class Preferences

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.

keys

public String[] keys()

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

Supported API: true

Specified by:

keys in class Preferences

Returns:

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

put

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

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

Supported API: true

Specified by:

put in class Preferences

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

refresh

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

Specified by:

refresh in class Preferences

See Also:

flush()

remove

public 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

Specified by:

remove in class Preferences

Parameters:

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

Throws:

WTException

See Also:

get(String, String)

removeChild

protected 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

Specified by:

removeChild in class Preferences

Parameters:

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

Throws:

WTException

removeNode

public 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

Specified by:

removeNode in class Preferences

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

Description copied from class: Preferences

Returns the root preference node for the calling user.

Supported API: true

root

public static Preferences root(boolean createCache)

getAsList

public String[] getAsList(String key,
                          String token)

This method will get a Preference from the system for the desired key and along with a token String will return an array of items that represent the items in the Preference Separated by the Token.

If there are many values associated with a given Preference which could be combined into a single Preference, such as for item X there is an order and size. If the character '|' was used as the token then calling getAsList(keyX, "|") would return a String array which matches the array order passed to the putAsList( ) method, say in this case { Order, Size }

Parameters:

key - The key to obtain the Preference for

token - The token to use to split the Preferences. If token is null then the String will be tokenized using \uFFFF.

Returns:

String[] An array of values for the Preference Key

putAsList

public String putAsList(String key,
                        String[] value,
                        String token)
                 throws WTException

This method will put a Preference into the system for the desired key and along with a token String will store an array of items that.

The values are stored in the order they are presented in the value parameter using the token.

Parameters:

key - The key to store the Preference for

value - The array of items to insert into Preferences in the order They are to be inserted.

token - The token to use to split the Preferences. If token is null then \uFFFF is used

Throws:

WTException

updateContext

public void updateContext(String key,
                          String value,
                          String context)
                   throws WTException

Throws:

WTException

updateEntry

private void updateEntry(PrefEntry entry)
                  throws WTException

Throws:

WTException

clear

public void clear()
           throws WTException

Description copied from class: Preferences

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

Overrides:

clear in class Preferences

Throws:

WTException

containsKey

public boolean containsKey(String aKey,
                           String[] mask)

will return true if the Preferences contains the desired key.

added by JAD 11/17/2000

Parameters:

aKey - The key to search for.

mask - The context mask to use for checking values.

Returns:

true if the key is in the preference.

getEntry

private final PrefEntry getEntry(String key)

getEntry

public final PrefEntry getEntry(String key,
                                boolean checkCache)

toString

public String toString()

uncreateCacheKey

private static final String uncreateCacheKey(String key)

getKeyFromcreateCacheKey

private static final String getKeyFromcreateCacheKey(String key)

getUser

private String getUser()
                throws WTException

Throws:

WTException

createCacheKey

private static final String createCacheKey(String key,
                                           String context)

main

public static void main(String[] args)