oracle.adf.share.prefs
Class ADFPreferences

java.lang.Object
  java.util.prefs.Preferences
      java.util.prefs.AbstractPreferences
          oracle.adf.share.prefs.ADFPreferences

public class ADFPreferences
extends java.util.prefs.AbstractPreferences

An implementation of Preferences class providing a MDS repository based persistence mechanism. This class also provides a richer user level preferences, using the J2EE authenticated user. It also enables access to preference objects, which return preferences based on a user over system ordering.
It should be noted that accessing Preference objects directly though the statics in this class assumes that the Preference Utility is being used within the context of an ADF Web Application. As such the details required to connect to the MDS Repository are obtained by the utility from the ADF Context.
Consumers wanting to use the ADFPreferences Utility outside of the scope of an ADF Web Application should only access ADFPreferences objects through the ADFPreferencesFactory class which has been constructed passing into it the ADFPreferencesSimpleConfig object, that has inturn been constructed by passing in a MDSInstance object.

Field Summary

protected static java.lang.String	FILENAME The filename used for the MDS preference documents
protected ADFPreferencesManager	mManager The ADFPreferencesManager object that helps manages the preferences

Fields inherited from class java.util.prefs.AbstractPreferences

lock, newNode

Fields inherited from class java.util.prefs.Preferences

MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH

Constructor Summary

	ADFPreferences(java.util.prefs.AbstractPreferences parent, java.lang.String name) Creates a preference node with the specified parent and the specified name relative to its parent.
protected	ADFPreferences(ADFPreferencesManager manager, java.lang.String path) Constructor used to create a Preference object and set against it the specified MDSHelper object, which will have been created with the path and customization context required for this Preference object.

Method Summary

java.util.Map<java.lang.String,java.lang.String>	bulkGet() This method enables a bulk get of all preference items that are accessible on this particular preference node.
java.util.Map<java.lang.String,java.lang.String>	bulkGet(java.util.Set<java.lang.String> prefSet) This method enables a bulk get of a specified set of preference items that are accessible on this particular preference node.
void	bulkPut(java.util.Map<java.lang.String,java.lang.String> putMap) This method enables bulk putting of a set of Preference items (String key, String value map elements).
java.lang.String[]	childrenNamesSpi() Returns the names of the children of this preference node.
java.util.prefs.AbstractPreferences	childSpi(java.lang.String name) Returns the named child of this preference node, creating it if it does not already exist.
void	flushSpi() This method is invoked with this node locked.
java.lang.String	get(java.lang.String key, java.lang.String def)
protected oracle.adf.share.prefs.MDSHelper	getMDSHelper() Returns the MDSHelper object associated with this Preference node.
static java.lang.String	getMDSPathForExport(java.util.prefs.Preferences prefs) Returns the full MDS path associated with the Preferences object passed into the method.
static java.lang.String	getMDSPathForExport(java.lang.String preferencePath) Returns the full MDS path associated with the Preferences path passed into the method.
java.lang.String	getSpi(java.lang.String key) Return the value associated with the specified key at this preference node, or null if there is no association for this key, or the association cannot be determined at this time.
static oracle.mds.cust.CustomizationClass	getSystemCustomizationClass() Returns the CustomizationClass associated with the System Customizations.
static oracle.mds.cust.CustomizationClass	getUserCustomizationClass() Returns the CustomizationClass associated with the User Customizations.
java.lang.String[]	keysSpi() Returns all of the keys that have an associated value in this preference node.
void	put(java.lang.String key, java.lang.String val)
void	putSpi(java.lang.String key, java.lang.String value) Put the given key-value association into this preference node.
void	remove(java.lang.String key)
void	removeNodeSpi() Removes this preference node, invalidating it and any preferences that it contains.
void	removeSpi(java.lang.String key) Remove the association (if any) for the specified key at this preference node.
void	setUsernameOverride(java.lang.String username) Enables overriding the ADFContext based username derivation in Preferences access.
void	syncSpi() This method is invoked with this node locked.
static java.util.prefs.Preferences	systemNodeForPackage(java.lang.Class<?> c) Returns the preference node from the system preference tree that is associated (by convention) with the specified class's package.
static java.util.prefs.Preferences	systemRoot() Returns the root preference node for the system.
static java.util.prefs.Preferences	userNodeForPackage(java.lang.Class<?> c) Returns the preference node from the calling user's preference tree that is associated (by convention) with the specified class's package.
static ADFPreferences	userOverSystemNodeForPackage(java.lang.Class<?> c) Returns the preference node associated with the MDS customization array's preference tree that is associated (by convention) with the specified class's package.
static java.util.prefs.Preferences	userOverSystemRoot() Returns the root preference node for MDS sessions customization configuration specified in adf-config.xml
static java.util.prefs.Preferences	userRoot() Returns the root preference node for the calling user.

Methods inherited from class java.util.prefs.AbstractPreferences

absolutePath, addNodeChangeListener, addPreferenceChangeListener, cachedChildren, childrenNames, clear, exportNode, exportSubtree, flush, getBoolean, getByteArray, getChild, getDouble, getFloat, getInt, getLong, isRemoved, isUserNode, keys, name, node, nodeExists, parent, putBoolean, putByteArray, putDouble, putFloat, putInt, putLong, removeNode, removeNodeChangeListener, removePreferenceChangeListener, sync, toString

Methods inherited from class java.util.prefs.Preferences

importPreferences

Methods inherited from class java.lang.Object

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

Field Detail

mManager

protected final ADFPreferencesManager mManager

The ADFPreferencesManager object that helps manages the preferences

FILENAME

protected static final java.lang.String FILENAME

The filename used for the MDS preference documents

See Also:

Constant Field Values

Constructor Detail

ADFPreferences

protected ADFPreferences(ADFPreferencesManager manager,
                         java.lang.String path)
                  throws oracle.mds.config.MDSConfigurationException,
                         oracle.mds.core.MetadataExistsException,
                         oracle.mds.exception.UnsupportedUpdateException,
                         oracle.mds.persistence.MDSIOException,
                         oracle.mds.core.ConcurrentMOChangeException,
                         oracle.mds.core.ValidationException,
                         java.lang.ClassNotFoundException,
                         oracle.mds.exception.MDSException

Constructor used to create a Preference object and set against it the specified MDSHelper object, which will have been created with the path and customization context required for this Preference object. This method is for internal use only and not to be publically accessible.

Parameters:

manager - The manager associated with this Preference object.

Throws:

oracle.mds.config.MDSConfigurationException

oracle.mds.core.MetadataExistsException

oracle.mds.exception.UnsupportedUpdateException

oracle.mds.persistence.MDSIOException

oracle.mds.core.ConcurrentMOChangeException

oracle.mds.core.ValidationException

java.lang.ClassNotFoundException

oracle.mds.exception.MDSException

ADFPreferences

public ADFPreferences(java.util.prefs.AbstractPreferences parent,
                      java.lang.String name)

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

Method Detail

getSpi

public java.lang.String getSpi(java.lang.String key)

Return the value associated with the specified key at this preference node, or null if there is no association for this key, or the association cannot be determined at this time. It is guaranteed that key is non-null. Also, it is guaranteed that this node has not been removed. (The implementor needn't check for either of these things.)

Generally speaking, this method should not throw an exception under any circumstances. If, however, if it does throw an exception, the exception will be intercepted and treated as a null return value.

This method is invoked with the lock on this node held.

Specified by:

getSpi in class java.util.prefs.AbstractPreferences

Returns:

the value associated with the specified key at this preference node, or null if there is no association for this key, or the association cannot be determined at this time.

putSpi

public void putSpi(java.lang.String key,
                   java.lang.String value)

Put the given key-value association into this preference node. It is guaranteed that key and value are non-null and of legal length. Also, it is guaranteed that this node has not been removed. (The implementor needn't check for any of these things.)

This method is invoked with the lock on this node held.

Specified by:

putSpi in class java.util.prefs.AbstractPreferences

removeSpi

public void removeSpi(java.lang.String key)

Remove the association (if any) for the specified key at this preference node. It is guaranteed that key is non-null. Also, it is guaranteed that this node has not been removed. (The implementor needn't check for either of these things.)

This method is invoked with the lock on this node held.

Specified by:

removeSpi in class java.util.prefs.AbstractPreferences

childSpi

public java.util.prefs.AbstractPreferences childSpi(java.lang.String name)

Returns the named child of this preference node, creating it if it does not already exist. It is guaranteed that name is non-null, non-empty, does not contain the slash character ('/'), and is no longer than Preferences.MAX_NAME_LENGTH characters. Also, it is guaranteed that this node has not been removed. (The implementor needn't check for any of these things.)

Finally, it is guaranteed that the named node has not been returned by a previous invocation of this method or AbstractPreferences.getChild(String) after the last time that it was removed. In other words, a cached value will always be used in preference to invoking this method. Subclasses need not maintain their own cache of previously returned children.

The implementer must ensure that the returned node has not been removed. If a like-named child of this node was previously removed, the implementer must return a newly constructed AbstractPreferences node; once removed, an AbstractPreferences node cannot be "resuscitated."

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

This method is invoked with the lock on this node held.

Specified by:

childSpi in class java.util.prefs.AbstractPreferences

Parameters:

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

Returns:

The named child node.

removeNodeSpi

public void removeNodeSpi()
                   throws java.util.prefs.BackingStoreException

Removes this preference node, invalidating it and any preferences that it contains. The named child will have no descendants at the time this invocation is made (i.e., the Preferences.removeNode() method invokes this method repeatedly in a bottom-up fashion, removing each of a node's descendants before removing the node itself).

This method is invoked with the lock held on this node and its parent (and all ancestors that are being removed as a result of a single invocation to Preferences.removeNode()).

The removal of a node needn't become persistent until the flush method is invoked on this node (or an ancestor).

If this node throws a BackingStoreException, the exception will propagate out beyond the enclosing AbstractPreferences.removeNode() invocation.

Specified by:

removeNodeSpi in class java.util.prefs.AbstractPreferences

Throws:

java.util.prefs.BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

keysSpi

public java.lang.String[] keysSpi()
                           throws java.util.prefs.BackingStoreException

Returns all of the keys that have an associated value in this preference node. (The returned array will be of size zero if this node has no preferences.) It is guaranteed that this node has not been removed.

This method is invoked with the lock on this node held.

If this node throws a BackingStoreException, the exception will propagate out beyond the enclosing AbstractPreferences.keys() invocation.

Specified by:

keysSpi in class java.util.prefs.AbstractPreferences

Returns:

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

Throws:

java.util.prefs.BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

childrenNamesSpi

public java.lang.String[] childrenNamesSpi()
                                    throws java.util.prefs.BackingStoreException

Returns the names of the children of this preference node. (The returned array will be of size zero if this node has no children.) This method need not return the names of any nodes already cached, but may do so without harm.

This method is invoked with the lock on this node held.

If this node throws a BackingStoreException, the exception will propagate out beyond the enclosing AbstractPreferences.childrenNames() invocation.

Specified by:

childrenNamesSpi in class java.util.prefs.AbstractPreferences

Returns:

an array containing the names of the children of this preference node.

Throws:

java.util.prefs.BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

flushSpi

public void flushSpi()
              throws java.util.prefs.BackingStoreException

This method is invoked with this node locked. The contract of this method is to force any cached changes in the contents of this preference node to the backing store, guaranteeing their persistence. (It is perfectly possible that this node does not exist on the backing store, either because it has been deleted by another VM, or because it has not yet been created.) Note that this method should not flush the preferences in any subnodes of this node. If the backing store naturally flushes an entire subtree at once, the implementer is encouraged to override flush(), rather than merely overriding this method.

If this node throws a BackingStoreException, the exception will propagate out beyond the enclosing AbstractPreferences.flush() invocation.

Specified by:

flushSpi in class java.util.prefs.AbstractPreferences

Throws:

java.util.prefs.BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

syncSpi

public void syncSpi()
             throws java.util.prefs.BackingStoreException

This method is invoked with this node locked. The contract of this method is to synchronize any cached preferences stored at this node with any stored in the backing store. (It is perfectly possible that this node does not exist on the backing store, either because it has been deleted by another VM, or because it has not yet been created.) Note that this method should not synchronize the preferences in any subnodes of this node. If the backing store naturally syncs an entire subtree at once, the implementer is encouraged to override sync(), rather than merely overriding this method.

If this node throws a BackingStoreException, the exception will propagate out beyond the enclosing AbstractPreferences.sync() invocation.

Specified by:

syncSpi in class java.util.prefs.AbstractPreferences

Throws:

java.util.prefs.BackingStoreException - if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.

userOverSystemRoot

public static java.util.prefs.Preferences userOverSystemRoot()

Returns the root preference node for MDS sessions customization configuration specified in adf-config.xml

Returns:

the root preference node for the MDS sessions customization configuration specified in adf-config.xml

Throws:

java.lang.SecurityException - If a security manager is present and it denies RuntimePermission("preferences").

See Also:

RuntimePermission

userOverSystemNodeForPackage

public static ADFPreferences userOverSystemNodeForPackage(java.lang.Class<?> c)

Returns the preference node associated with the MDS customization array's preference tree that is associated (by convention) with the specified class's package. The MDS customization level is obtained from the adf-config.xml configuiration associated with the MDS Session. The convention is as follows: the absolute path name 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 path name of the node associated with the class com.acme.widget is /com/acme/widget.

This convention does not apply to the unnamed package, whose associated preference node is <unnamed>. This node is not intended for long term use, but for convenience in the early development of programs that do not yet belong to a package, and for "throwaway" programs. Valuable data should not be stored at this node as it is shared by all programs that use it.

A class Foo wishing to access preferences pertaining to its package can obtain a preference node as follows:

    static Preferences prefs = Preferences.nodeForPackage(Foo.class);
 

This idiom obviates the need for using a string to describe the preferences node and decreases the likelihood of a run-time failure. (If the class name is misspelled, it will typically result in a compile-time error.)

Invoking this method will result in the creation of the returned node and its ancestors if they do not already exist. 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 permanent until the flush method is called on the returned node (or one of its ancestors or descendants).

Parameters:

c - the class for whose package a MDS Sesson configuration customization level preference node is desired.

Returns:

the MDS Sesson configuration preference node associated with the package of which c is a member.

Throws:

java.lang.NullPointerException - if c is null.

java.lang.SecurityException - if a security manager is present and it denies RuntimePermission("preferences").

See Also:

RuntimePermission

getMDSHelper

protected oracle.adf.share.prefs.MDSHelper getMDSHelper()

Returns the MDSHelper object associated with this Preference node. The helper object is used to interface the preference requirements with the MDS backend repository.

Returns:

The MDSHelper object assoicated with this Preference node.

get

public java.lang.String get(java.lang.String key,
                            java.lang.String def)

Overrides:

get in class java.util.prefs.AbstractPreferences

put

public void put(java.lang.String key,
                java.lang.String val)

Overrides:

put in class java.util.prefs.AbstractPreferences

bulkPut

public void bulkPut(java.util.Map<java.lang.String,java.lang.String> putMap)

This method enables bulk putting of a set of Preference items (String key, String value map elements). It is intended to be used as a utiltity method for advanced users, as it is not available in the java.util.prefs packages.

Users of this method will have to access the method directly from the an ADFPreference object as opposed to a java.util.pref.Preferences class.

A usage example is given below:

// Create a bulk set
Map<String, String> prefsPutMap = new HashMap<String, String>();
prefsPutMap.put("pref1", "value1");
prefsPutMap.put("pref2", "value2");
prefsPutMap.put("pref3", "value3");
ADFPreferences pref = (ADFPreferences)mPrefFactory.

userNodeForPackage (my.demo.service.PrefAccessor.class);

pref.bulkPut(prefsPutMap);

Parameters:

putMap - The Map (String, String) object containing the String key, String value map elements to be populated in a bulk manner on the preference node associated with this preference object.

bulkGet

public java.util.Map<java.lang.String,java.lang.String> bulkGet()

This method enables a bulk get of all preference items that are accessible on this particular preference node. The preference data is retruned as a Map object containing String key, String value items. This api is not part of the java.util.pref standard and so is only accessible from the ADFPreferences object directly, and not java.util.prefs.Preferences The example code below assumes the data in the bulkPut exists in the preference node. If it doesn't the keys will not exist a null value would be returned by the map get(key) call.
Consumers of this API will need to handle this possibility in their usages of the API.

ADFPreferences prefNode =

(ADFPreferences)mPrefFactory.userNodeForPackage (my.demo.service.PrefAccessor.class);

Map<String, String> prefs = pref.bulkGet();
String pref1Value = prefs.get("pref1");
String pref2Value = prefs.get("pref2");
String pref3Value = prefs.get("pref3");

Returns:

The map of Sting key, String value items for each preference item that has been set against the node associated with this preference object.

bulkGet

public java.util.Map<java.lang.String,java.lang.String> bulkGet(java.util.Set<java.lang.String> prefSet)

This method enables a bulk get of a specified set of preference items that are accessible on this particular preference node. This utility method is expected to be useful to users who know which set of preferences they wish to get value for. The Set object passed in to this method has to contain a String key element per requested preference. The preference result is a Map object containing String key, String value items. This api is not part of the java.util.pref standard and so is only accessible from the ADFPreferences object directly, and not java.util.prefs.Preferences The example code below assumes the data in the bulkPut exists in the preference node. If it doesn't the keys will not exist a null value would be returned by the map get(key) call.
Consumers of this API will need to handle this possibility in their usages of the API.

ADFPreferences prefNode =

(ADFPreferences)mPrefFactory.userNodeForPackage (my.demo.service.PrefAccessor.class);

Set<String> requestedPrefSet= new HashSet<String>(2);
s.add("pref1");
s.add("pref3");
Map<String, String> prefs = pref.bulkGet(requestedPrefSet);
String pref1Value = prefs.get("pref1");
String pref3Value = prefs.get("pref3");

Returns:

The map of Sting key, String value items for each preference item that has been set against the node associated with this preference object.

remove

public void remove(java.lang.String key)

Overrides:

remove in class java.util.prefs.AbstractPreferences

systemRoot

public static java.util.prefs.Preferences systemRoot()

Returns the root preference node for the system.

Returns:

the root preference node for the system.

Throws:

java.lang.SecurityException - If a security manager is present and it denies RuntimePermission("preferences").

See Also:

RuntimePermission

userRoot

public static java.util.prefs.Preferences userRoot()

Returns the root preference node for the calling user.

Returns:

the root preference node for the calling user.

Throws:

java.lang.SecurityException - If a security manager is present and it denies RuntimePermission("preferences").

See Also:

RuntimePermission

userNodeForPackage

public static java.util.prefs.Preferences userNodeForPackage(java.lang.Class<?> c)

Returns the preference node from the calling user's preference tree that is associated (by convention) with the specified class's package. The convention is as follows: the absolute path name 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 path name of the node associated with the class com.acme.widget is /com/acme/widget.

This convention does not apply to the unnamed package, whose associated preference node is <unnamed>. This node is not intended for long term use, but for convenience in the early development of programs that do not yet belong to a package, and for "throwaway" programs. Valuable data should not be stored at this node as it is shared by all programs that use it.

A class Foo wishing to access preferences pertaining to its package can obtain a preference node as follows:

    static Preferences prefs = Preferences.userNodeForPackage(Foo.class);
 

This idiom obviates the need for using a string to describe the preferences node and decreases the likelihood of a run-time failure. (If the class name is misspelled, it will typically result in a compile-time error.)

Invoking this method will result in the creation of the returned node and its ancestors if they do not already exist. 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 permanent until the flush method is called on the returned node (or one of its ancestors or descendants).

Parameters:

c - the class for whose package a user preference node is desired.

Returns:

the user preference node associated with the package of which c is a member.

Throws:

java.lang.NullPointerException - if c is null.

java.lang.SecurityException - if a security manager is present and it denies RuntimePermission("preferences").

See Also:

RuntimePermission

systemNodeForPackage

public static java.util.prefs.Preferences systemNodeForPackage(java.lang.Class<?> c)

Returns the preference node from the system preference tree that is associated (by convention) with the specified class's package. The convention is as follows: the absolute path name 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 path name of the node associated with the class com.acme.widget is /com/acme/widget.

This convention does not apply to the unnamed package, whose associated preference node is <unnamed>. This node is not intended for long term use, but for convenience in the early development of programs that do not yet belong to a package, and for "throwaway" programs. Valuable data should not be stored at this node as it is shared by all programs that use it.

A class Foo wishing to access preferences pertaining to its package can obtain a preference node as follows:

  static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);
 

This idiom obviates the need for using a string to describe the preferences node and decreases the likelihood of a run-time failure. (If the class name is misspelled, it will typically result in a compile-time error.)

Invoking this method will result in the creation of the returned node and its ancestors if they do not already exist. 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 permanent until the flush method is called on the returned node (or one of its ancestors or descendants).

Parameters:

c - the class for whose package a system preference node is desired.

Returns:

the system preference node associated with the package of which c is a member.

Throws:

java.lang.NullPointerException - if c is null.

java.lang.SecurityException - if a security manager is present and it denies RuntimePermission("preferences").

See Also:

RuntimePermission

getMDSPathForExport

public static java.lang.String getMDSPathForExport(java.lang.String preferencePath)

Returns the full MDS path associated with the Preferences path passed into the method. This method is typically only used for Lifecycle operations.

Parameters:

preferencePath - The path to the Preferences node whose MDS root path is required, .e.g. "my/demo/app"

Returns:

The full MDS path associated with the Preferences path. e.g. "/oracle/adf/share/prefs/$data/my/demo/app"

getMDSPathForExport

public static java.lang.String getMDSPathForExport(java.util.prefs.Preferences prefs)

Returns the full MDS path associated with the Preferences object passed into the method. This method is typically only used for Lifecycle operations.

Parameters:

prefs - The Preferences object whose MDS root path is required.

Returns:

The full MDS path associated with the Preferences object.

getSystemCustomizationClass

public static oracle.mds.cust.CustomizationClass getSystemCustomizationClass()

Returns the CustomizationClass associated with the System Customizations. This method is typically only used for Lifecycle operations.

Returns:

the CustomizationClass associated with the System Customizations.

getUserCustomizationClass

public static oracle.mds.cust.CustomizationClass getUserCustomizationClass()

Returns the CustomizationClass associated with the User Customizations. This method is typically only used for Lifecycle operations.

Returns:

the CustomizationClass associated with the User Customizations.

setUsernameOverride

public void setUsernameOverride(java.lang.String username)

Enables overriding the ADFContext based username derivation in Preferences access. This override allows users of the api to obtain user preference values for users other than the logged in user, whose ID is used when not overridden by the UserCustomizationClass. In effect this method enables updating the getValue method of the UserCustomizationClass such that the passed in username value is returned instead of that of the username associated with the ADFContext. Note the preference nodes are held in managed map hence after use one should set the UsernameOverride value to null to turn off the override, enabling a revertion to the default behaviour, otherwise the values for the last overridden user will be returned by processes accessing the ADFPreferences in the same thread.

Parameters:

username - The username to be used by the UserCustomizationClass, in place of the default ADFContext derived logged in username.