java.util.prefs
Class TransientPreferences

java.lang.Object
  |
  +--java.util.prefs.Preferences
        |
        +--java.util.prefs.AbstractPreferences
              |
              +--java.util.prefs.TransientPreferences

public class TransientPreferences

extends AbstractPreferences

This specialization of Preferences provides a means of holding transient contextual settings to pass from one program entity to another, such as between isolates. There is no connection between transient preferences and the backing store used by regular Preferences; however, export/import to and from XML is supported. Export of transient preferences to XML is via the inherited exportNode method, but import is via an additional constructor.

Transient preferences maintain an attribute marking the preferences object as containing "user" or "system" preferences. This is only used when exporting the transient preferences to XML, the default value (a "user" preference) should be generally correct.

Here are some code fragments demonstrating TransientPreferences usage:

 // Pass a few context values to a new isolate
 TransientPreferences ctx = new TransientPreferences();
 ctx.put("workPath", "inventory.update");
 ctx.put("workClass", "restock");
 Isolate newIsolate = new Isolate( ..., ctx, ...);

 // Merge above preferences with existing one and save it to XML
 TransientPreferences existingCtx = ...;
 ctx.merge(existingCtx);
 ctx.export(new FileOutputStream("batchupdate_prefs.xml"));
 
 // Retrieve preferences from a stream, customize and use
 TransientPreferences ictx = new TransientPreferences(new
                 FileInputStream("some_prefs.xml"));
 ictx.remove("historyFlag");
 Isolate myIsolate = Isolate( ... ictx, ...);
 

For details about the the methods of this class see java.util.prefs.Preferences

Since:

1.5

Field Summary

Fields inherited from class java.util.prefs.Preferences

MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH

Constructor Summary

TransientPreferences()
Constructs an empty transient preferences object.

TransientPreferences(boolean isUserNode)
Constructs an empty transient preferences object.

TransientPreferences(InputStream is)
Constructs a new transient preferences tree from an XML formatted input stream.

TransientPreferences(Preferences base)
Constructs a new transient preferences tree based on a deep copy of the subtree rooted at base.

Method Summary

String[]	childrenNames() Overrides Preferences.childrenNames, but does not throw a BackingStoreException.
void	clear() Overrides Preferences.clear, but does not throw a BackingStoreException.
void	exportNode(OutputStream os) Overrides Preferences.exportNode, but does not throw a BackingStoreException.
void	exportSubtree(OutputStream os) Overrides Preferences.exportSubtree, but does not throw a BackingStoreException.
void	flush() Overrides Preferences.flush, but does not throw a BackingStoreException.
String[]	keys() Overrides Preferences.keys, but does not throw a BackingStoreException.
void	merge(TransientPreferences source) Merge the given source tree of transient preferences into the this tree.
boolean	nodeExists(String n) Overrides Preferences.nodeExists, but does not throw a BackingStoreException.
void	removeNode() Overrides Preferences.removeNode, but does not throw a BackingStoreException.
void	sync() Overrides Preferences.sync, but does not throw a BackingStoreException.

Methods inherited from class java.util.prefs.AbstractPreferences

absolutePath, addNodeChangeListener, addPreferenceChangeListener, get, getBoolean, getByteArray, getDouble, getFloat, getInt, getLong, isUserNode, name, node, parent, put, putBoolean, putByteArray, putDouble, putFloat, putInt, putLong, remove, removeNodeChangeListener, removePreferenceChangeListener, toString

Methods inherited from class java.util.prefs.Preferences

importPreferences, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TransientPreferences

public TransientPreferences()

Constructs an empty transient preferences object. Preferences object is defined with the "user" attribute (vs. a "system" attribute). The returned object will be the root of a new tree of preferences.

TransientPreferences

public TransientPreferences(boolean isUserNode)

Constructs an empty transient preferences object. The isUserNode parameter defines if the Preferences object is given "user" (true) or "system" attribute (false). The returned object will be the root of a new tree of preferences.

Parameters:

isUserNode - creates a "user" node if true "system" node otherwise

Throws:

NullPointerException - if isUserNode is null

TransientPreferences

public TransientPreferences(Preferences base)

Constructs a new transient preferences tree based on a deep copy of the subtree rooted at base. The "user" or "system" attribute of the given base is copied into the new transient preferences object.

Parameters:

base - the existing TransientPreferences object to copy

Throws:

NullPointerException - if base is null

TransientPreferences

public TransientPreferences(InputStream is)
                     throws IOException,
                            InvalidPreferencesFormatException

Constructs a new transient preferences tree from an XML formatted input stream. The input stream must correspond to the Preferences XML DTD (see Preferences), or an InvalidPreferencesFormatException will be thrown.

Parameters:

is - the input stream from which to read the XML document

Throws:

IOException - if reading from the specified output stream results in an IOException

InvalidPreferencesFormatException - if data on input stream does not constitute a valid XML document with the mandated document type

NullPointerException - if is is null

See Also:

Preferences.exportSubtree(java.io.OutputStream)

Method Detail

merge

public void merge(TransientPreferences source)

Merge the given source tree of transient preferences into the this tree. All keys and children of source will be deeply copied into this node (i.e., modifications to source after merge returns will not affect this tree). Any overlapping keys will have their values replaced by the source values, and existing child nodes will be merged in the same way.

The "system"/"user" attribute of the source preferences is ignored during the deep copy, and new child nodes of this node are given the same attribute value as this.

This method is an exception to the general rule that the results of concurrently executing multiple methods in this class yields results equivalent to some serial execution. The method behaves as if implemented on top of the other public methods in this class, notably key, childrenNames, node, get and put.

Parameters:

source - the transient preferences object to merge

Throws:

NullPointerException - if source is null

keys

public String[] keys()

Overrides Preferences.keys, but does not throw a BackingStoreException.

{@inheritDoc}

Overrides:

keys in class AbstractPreferences

childrenNames

public String[] childrenNames()

Overrides Preferences.childrenNames, but does not throw a BackingStoreException.

{@inheritDoc}

Overrides:

childrenNames in class AbstractPreferences

clear

public void clear()

Overrides Preferences.clear, but does not throw a BackingStoreException.

{@inheritDoc}

Overrides:

clear in class AbstractPreferences

nodeExists

public boolean nodeExists(String n)

Overrides Preferences.nodeExists, but does not throw a BackingStoreException.

{@inheritDoc}

Overrides:

nodeExists in class AbstractPreferences

removeNode

public void removeNode()

Overrides Preferences.removeNode, but does not throw a BackingStoreException.

{@inheritDoc}

Overrides:

removeNode in class AbstractPreferences

flush

public void flush()

Overrides Preferences.flush, but does not throw a BackingStoreException.

{@inheritDoc}

Overrides:

flush in class AbstractPreferences

sync

public void sync()

Overrides Preferences.sync, but does not throw a BackingStoreException.

{@inheritDoc}

Overrides:

sync in class AbstractPreferences

exportNode

public void exportNode(OutputStream os)
                throws IOException

Overrides Preferences.exportNode, but does not throw a BackingStoreException.

{@inheritDoc}

Overrides:

exportNode in class AbstractPreferences

IOException

exportSubtree

public void exportSubtree(OutputStream os)
                   throws IOException

Overrides Preferences.exportSubtree, but does not throw a BackingStoreException.

{@inheritDoc}

Overrides:

exportSubtree in class AbstractPreferences

IOException