org.jboss.cache.optimistic
Class WorkspaceNodeImpl<K,V>

java.lang.Object
  org.jboss.cache.AbstractNode<K,V>
      org.jboss.cache.optimistic.WorkspaceNodeImpl<K,V>

All Implemented Interfaces:

Node<K,V>, WorkspaceNode<K,V>

public class WorkspaceNodeImpl<K,V>
extends AbstractNode<K,V>
implements WorkspaceNode<K,V>

Wraps an ordinary Node and adds versioning and other meta data to it.

Author:

Manik Surtani (manik@jboss.org), Steve Woodcock (stevew@jofti.com)

Nested Class Summary

Nested classes/interfaces inherited from class org.jboss.cache.AbstractNode

AbstractNode.NodeFlags

Field Summary

Fields inherited from class org.jboss.cache.AbstractNode

children, flags, fqn

Constructor Summary

WorkspaceNodeImpl(NodeSPI<K,V> node, TransactionWorkspace workspace)
Constructs with a node and workspace.

Method Summary

Node<K,V>	addChild(Fqn f) Adds a child node with the given Fqn under the current node.
void	addChild(WorkspaceNode<K,V> child) Adds a given WorkspaceNode to the current node's child map
void	clearData() Removes all mappings from the node's data map.
NodeSPI<K,V>	createChild(Object child_name, NodeSPI<K,V> parent, CacheSPI<K,V> cache, DataVersion version) Creates a child node.
int	dataSize()
V	get(K key) Returns the value to which this node maps the specified key.
protected CacheSPI<K,V>	getCache()
NodeSPI<K,V>	getChild(Fqn f) Returns the child node
NodeSPI<K,V>	getChild(Object childName) Overrides Node.getChild(Object) to return a NodeSPI rather than a Node
Set<Node<K,V>>	getChildren() Returns an immutable set of children nodes.
protected Set<Fqn>	getChildrenAddedSet()
Set<Object>	getChildrenNames() Returns an immutable set of children node names.
protected Set<Fqn>	getChildrenRemovedSet()
Map<K,V>	getData() Returns a map containing the data in this Node.
Fqn	getFqn() Returns the Fqn which represents the location of this Node in the cache structure.
Set<K>	getKeys() Returns a Set containing the data in this Node.
List<Set<Fqn>>	getMergedChildren() Returns 2 Sets - a set of children added (first set) and a set of children removed.
Map<K,V>	getMergedData() Attempts to merge data changed during the current transaction with the data in the underlying tree.
NodeSPI<K,V>	getNode() Retrieves a reference to the underlying NodeSPI instance.
NodeSPI<K,V>	getNodeSPI()
Node<K,V>	getParent() Returns the parent node.
TransactionWorkspace	getTransactionWorkspace() Retrieves a TransactionWorkspace instance associated with the current transaction, which the current WorkspaceNode instance lives in.
DataVersion	getVersion() Retrieves the data version of the in-memory node.
boolean	hasChild(Fqn f) Returns true if the child node denoted by the relative Fqn passed in exists.
boolean	hasChild(Object o) Returns true if the child node denoted by the Object name passed in exists.
protected void	initFlags()
boolean	isChildrenLoaded()
boolean	isChildrenModified()
boolean	isCreated()
boolean	isDirty() A convenience method that returns whether a node is dirty, i.e., it has been created, deleted or modified.
boolean	isLockForChildInsertRemove() Tests whether this node is configured to be exclusively locked when inserting or removing children.
boolean	isModified() Returns true if this node is modified.
boolean	isResurrected()
boolean	isValid() Tests if a node reference is still valid.
boolean	isVersioningImplicit() Tests whether versioning for the WorkspaceNode instance in the current transaction is implicit (i.e., using DefaultDataVersion rather than a custom DataVersion passed in using Option.setDataVersion(DataVersion))
void	markAsCreated() Marks the instance as having been created in the current transaction.
void	markAsDeleted(boolean marker, boolean recursive) Same as WorkspaceNode.markAsDeleted(boolean) except that the option to recurse into children is provided.
void	markAsResurrected(boolean resurrected) Marks a node as resurrected, i.e., deleted and created again within the same transaction
V	put(K key, V value) Associates the specified value with the specified key for this node.
void	putAll(Map<K,V> data) Copies all of the mappings from the specified map to this node's map.
V	putIfAbsent(K k, V v) If the specified key is not already associated with a value, associate it with the given value, and returns the Object (if any) that occupied the space, or null.
void	releaseObjectReferences(boolean recursive) Method that releases object references of cached objects held in the cache by serializing them to byte buffers.
V	remove(K key) Removes the mapping for this key from this node if it is present.
boolean	removeChild(Fqn f) Removes a child node specified by the given relative Fqn.
boolean	removeChild(Object childName) Removes a child node specified by the given name.
V	replace(K key, V value) Replace entry for key only if currently mapped to some value.
boolean	replace(K key, V oldValue, V newValue) Replace entry for key only if currently mapped to given value.
void	replaceAll(Map<K,V> data) Similar to Node.putAll(java.util.Map) except that it removes any entries that exists in the data map first.
void	setLockForChildInsertRemove(boolean lockForChildInsertRemove) Configures the behaviour of how this node is locked when adding/removing children.
void	setVersion(DataVersion version) Sets the data version of this workspace node.
void	setVersioningImplicit(boolean versioningImplicit) Sets whether versioning for the WorkspaceNode instance in the current transaction is implicit (i.e., using DefaultDataVersion rather than a custom DataVersion passed in using Option.setDataVersion(DataVersion))
String	toString()

Methods inherited from class org.jboss.cache.AbstractNode

equals, hashCode, isDeleted, isFlagSet, isResident, markAsDeleted, setFlag, setFlag, setResident, unsetFlag

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.jboss.cache.optimistic.WorkspaceNode

isDeleted, markAsDeleted

Methods inherited from interface org.jboss.cache.Node

isResident, setResident

Constructor Detail

WorkspaceNodeImpl

public WorkspaceNodeImpl(NodeSPI<K,V> node,
                         TransactionWorkspace workspace)

Constructs with a node and workspace.

Method Detail

initFlags

protected void initFlags()

getChildrenAddedSet

protected Set<Fqn> getChildrenAddedSet()

getChildrenRemovedSet

protected Set<Fqn> getChildrenRemovedSet()

isChildrenModified

public boolean isChildrenModified()

Specified by:

isChildrenModified in interface WorkspaceNode<K,V>

Returns:

true if children have been added to or removed from this node. Not the same as 'dirty'.

isChildrenLoaded

public boolean isChildrenLoaded()

Specified by:

isChildrenLoaded in interface WorkspaceNode<K,V>

Returns:

true if the child map has been loaded from the underlying data structure into the workspace.

isResurrected

public boolean isResurrected()

Specified by:

isResurrected in interface WorkspaceNode<K,V>

Returns:

teur if this node has been resurrected, i.e., it was deleted and re-added within the same transaction

markAsResurrected

public void markAsResurrected(boolean resurrected)

Description copied from interface: WorkspaceNode

Marks a node as resurrected, i.e., deleted and created again within the same transaction

Specified by:

markAsResurrected in interface WorkspaceNode<K,V>

markAsDeleted

public void markAsDeleted(boolean marker,
                          boolean recursive)

Description copied from interface: WorkspaceNode

Same as WorkspaceNode.markAsDeleted(boolean) except that the option to recurse into children is provided.

Specified by:

markAsDeleted in interface WorkspaceNode<K,V>

Overrides:

markAsDeleted in class AbstractNode<K,V>

Parameters:

marker - true if the node has been deleted, false if not.

recursive - if true, child nodes (and their children) are marked as well.

isModified

public boolean isModified()

Returns true if this node is modified.

Specified by:

isModified in interface WorkspaceNode<K,V>

Returns:

true if the data map has been modified

isDirty

public boolean isDirty()

A convenience method that returns whether a node is dirty, i.e., it has been created, deleted or modified.

Specified by:

isDirty in interface WorkspaceNode<K,V>

Returns:

true if the node has been either created, deleted or modified.

getFqn

public Fqn getFqn()

Description copied from interface: Node

Returns the Fqn which represents the location of this Node in the cache structure. The Fqn returned is absolute.

Specified by:

getFqn in interface Node<K,V>

Returns:

The Fqn which represents the location of this Node in the cache structure. The Fqn returned is absolute.

putAll

public void putAll(Map<K,V> data)

Description copied from interface: Node

Copies all of the mappings from the specified map to this node's map. If any data exists, existing keys are overwritten with the keys in the new map. The behavior is equivalent to:

 Node node;
 for (Map.Entry me : map.entrySet())
   node.put(me.getKey(), me.getValue());
 

Specified by:

putAll in interface Node<K,V>

Parameters:

data - map to copy from

replaceAll

public void replaceAll(Map<K,V> data)

Description copied from interface: Node

Similar to Node.putAll(java.util.Map) except that it removes any entries that exists in the data map first. Note that this happens atomically, under a single lock. This is the analogous to doing a Node.clearData() followed by a Node.putAll(java.util.Map) in the same transaction.

Specified by:

replaceAll in interface Node<K,V>

Parameters:

data - map to copy from

put

public V put(K key,
             V value)

Description copied from interface: Node

Associates the specified value with the specified key for this node. If this node previously contained a mapping for this key, the old value is replaced by the specified value.

Specified by:

put in interface Node<K,V>

Parameters:

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

value - value to be associated with the specified key.

Returns:

Returns the old value contained under this key. Null if key doesn't exist.

remove

public V remove(K key)

Description copied from interface: Node

Removes the mapping for this key from this node if it is present. Returns the value to which the node previously associated the key, or null if the node contained no mapping for this key

Specified by:

remove in interface Node<K,V>

Parameters:

key - key whose mapping is to be removed

Returns:

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

get

public V get(K key)

Description copied from interface: Node

Returns the value to which this node maps the specified key. Returns null if the node contains no mapping for this key.

Specified by:

get in interface Node<K,V>

Parameters:

key - key of the data to return

Returns:

the value to which this node maps the specified key, or null if the map contains no mapping for this key

getKeys

public Set<K> getKeys()

Description copied from interface: Node

Returns a Set containing the data in this Node.

Specified by:

getKeys in interface Node<K,V>

Returns:

a Set containing the data in this Node. If there is no data, an empty Set is returned. The Set returned is always immutable.

getChildrenNames

public Set<Object> getChildrenNames()

Description copied from interface: Node

Returns an immutable set of children node names.

Specified by:

getChildrenNames in interface Node<K,V>

Returns:

an immutable Set of child node names. Empty Set if there aren't any children.

getParent

public Node<K,V> getParent()

Description copied from interface: Node

Returns the parent node. If this is the root node, this method returns null.

Specified by:

getParent in interface Node<K,V>

Returns:

the parent node, or null if this is the root node

createChild

public NodeSPI<K,V> createChild(Object child_name,
                                NodeSPI<K,V> parent,
                                CacheSPI<K,V> cache,
                                DataVersion version)

Description copied from interface: WorkspaceNode

Creates a child node.

Specified by:

createChild in interface WorkspaceNode<K,V>

Parameters:

child_name - Object name of the child to create

parent - A reference to the parent node

cache - CacheSPI instance to create this node in

version - DataVersion to apply to the child. If null, DefaultDataVersion.ZERO will be used.

Returns:

a NodeSPI pointing to the newly created child.

isVersioningImplicit

public boolean isVersioningImplicit()

Description copied from interface: WorkspaceNode

Tests whether versioning for the WorkspaceNode instance in the current transaction is implicit (i.e., using DefaultDataVersion rather than a custom DataVersion passed in using Option.setDataVersion(DataVersion))

Specified by:

isVersioningImplicit in interface WorkspaceNode<K,V>

Returns:

true if versioning is implicit.

setVersioningImplicit

public void setVersioningImplicit(boolean versioningImplicit)

Description copied from interface: WorkspaceNode

Sets whether versioning for the WorkspaceNode instance in the current transaction is implicit (i.e., using DefaultDataVersion rather than a custom DataVersion passed in using Option.setDataVersion(DataVersion))

Specified by:

setVersioningImplicit in interface WorkspaceNode<K,V>

Parameters:

versioningImplicit - set to true if versioning is implicit, false otherwise.

getChild

public NodeSPI<K,V> getChild(Object childName)

Description copied from interface: WorkspaceNode

Overrides Node.getChild(Object) to return a NodeSPI rather than a Node

Specified by:

getChild in interface Node<K,V>

Specified by:

getChild in interface WorkspaceNode<K,V>

Parameters:

childName - name of the child

Returns:

a direct child of the current node.

getNode

public NodeSPI<K,V> getNode()

Description copied from interface: WorkspaceNode

Retrieves a reference to the underlying NodeSPI instance.

Specified by:

getNode in interface WorkspaceNode<K,V>

Returns:

a node

getVersion

public DataVersion getVersion()

Description copied from interface: WorkspaceNode

Retrieves the data version of the in-memory node.

Specified by:

getVersion in interface WorkspaceNode<K,V>

Returns:

A data version

setVersion

public void setVersion(DataVersion version)

Description copied from interface: WorkspaceNode

Sets the data version of this workspace node.

Specified by:

setVersion in interface WorkspaceNode<K,V>

Parameters:

version - a DataVersion implementation.

getMergedChildren

public List<Set<Fqn>> getMergedChildren()

Description copied from interface: WorkspaceNode

Returns 2 Sets - a set of children added (first set) and a set of children removed.

Specified by:

getMergedChildren in interface WorkspaceNode<K,V>

Returns:

a merged map of child names and Nodes

getMergedData

public Map<K,V> getMergedData()

Description copied from interface: WorkspaceNode

Attempts to merge data changed during the current transaction with the data in the underlying tree.

Specified by:

getMergedData in interface WorkspaceNode<K,V>

Returns:

a merged map of key/value pairs.

getTransactionWorkspace

public TransactionWorkspace getTransactionWorkspace()

Description copied from interface: WorkspaceNode

Retrieves a TransactionWorkspace instance associated with the current transaction, which the current WorkspaceNode instance lives in.

Specified by:

getTransactionWorkspace in interface WorkspaceNode<K,V>

Returns:

a TransactionWorkspace.

isCreated

public boolean isCreated()

Specified by:

isCreated in interface WorkspaceNode<K,V>

Returns:

true if the instance was created in the current transaction; i.e., it did not exist in the underlying data tree.

markAsCreated

public void markAsCreated()

Description copied from interface: WorkspaceNode

Marks the instance as having been created in the current transaction.

Specified by:

markAsCreated in interface WorkspaceNode<K,V>

getData

public Map<K,V> getData()

Description copied from interface: Node

Returns a map containing the data in this Node.

Specified by:

getData in interface Node<K,V>

Returns:

a Map containing the data in this Node. If there is no data, an empty Map is returned. The Map returned is always immutable.

toString

public String toString()

Overrides:

toString in class Object

addChild

public Node<K,V> addChild(Fqn f)

Description copied from interface: Node

Adds a child node with the given Fqn under the current node. Returns the newly created node.

If the child exists returns the child node anyway. Guaranteed to return a non-null node.

The Fqn passed in is relative to the current node. The new child node will have an absolute fqn calculated as follows:

new Fqn(getFqn(), f)

. See Fqn for the operation of this constructor.

Specified by:

addChild in interface Node<K,V>

Parameters:

f - Fqn of the child node, relative to the current node.

Returns:

the newly created node, or the existing node if one already exists.

addChild

public void addChild(WorkspaceNode<K,V> child)

Description copied from interface: WorkspaceNode

Adds a given WorkspaceNode to the current node's child map

Specified by:

addChild in interface WorkspaceNode<K,V>

clearData

public void clearData()

Description copied from interface: Node

Removes all mappings from the node's data map.

Specified by:

clearData in interface Node<K,V>

dataSize

public int dataSize()

Specified by:

dataSize in interface Node<K,V>

Returns:

the number of elements (key/value pairs) in the node's data map.

hasChild

public boolean hasChild(Object o)

Description copied from interface: Node

Returns true if the child node denoted by the Object name passed in exists.

Specified by:

hasChild in interface Node<K,V>

Parameters:

o - name of the child, relative to the current node

Returns:

true if the child node denoted by the name passed in exists.

isValid

public boolean isValid()

Description copied from interface: Node

Tests if a node reference is still valid. A node reference may become invalid if it has been removed, invalidated or moved, either locally or remotely. If a node is invalid, it should be fetched again from the cache or a valid parent node. Operations on invalid nodes will throw a NodeNotValidException.

Specified by:

isValid in interface Node<K,V>

Returns:

true if the node is valid.

isLockForChildInsertRemove

public boolean isLockForChildInsertRemove()

Description copied from interface: Node

Tests whether this node is configured to be exclusively locked when inserting or removing children.

The default value for this is what is configured in the LockParentForChildInsertRemove configuration property, programatically reachable by querying Configuration.isLockParentForChildInsertRemove()

This can also be configured on a per-node basis using Node.setLockForChildInsertRemove(boolean)

Specified by:

isLockForChildInsertRemove in interface Node<K,V>

Returns:

true if the node is configured to be exclusively locked for child insertions and removal, false otherwise.

setLockForChildInsertRemove

public void setLockForChildInsertRemove(boolean lockForChildInsertRemove)

Description copied from interface: Node

Configures the behaviour of how this node is locked when adding/removing children.

Specified by:

setLockForChildInsertRemove in interface Node<K,V>

Parameters:

lockForChildInsertRemove - if true, exclusive locks will be obtained when children are added/removed. If false, a shared "read lock" will be obtained instead.

releaseObjectReferences

public void releaseObjectReferences(boolean recursive)

Description copied from interface: Node

Method that releases object references of cached objects held in the cache by serializing them to byte buffers. Cached objects are lazily deserialized when accessed again, based on the calling thread's context class loader.

This can be expensive, based on the effort required to serialize cached objects.

Specified by:

releaseObjectReferences in interface Node<K,V>

Parameters:

recursive - if true, child nodes will have their object references released as well.

getChild

public NodeSPI<K,V> getChild(Fqn f)

Description copied from interface: Node

Returns the child node

Specified by:

getChild in interface Node<K,V>

Specified by:

getChild in interface WorkspaceNode<K,V>

Parameters:

f - Fqn of the child node

Returns:

null if the child does not exist.

getChildren

public Set<Node<K,V>> getChildren()

Description copied from interface: Node

Returns an immutable set of children nodes.

Specified by:

getChildren in interface Node<K,V>

Returns:

an immutable Set of child nodes. Empty Set if there aren't any children.

hasChild

public boolean hasChild(Fqn f)

Description copied from interface: Node

Returns true if the child node denoted by the relative Fqn passed in exists.

Specified by:

hasChild in interface Node<K,V>

Parameters:

f - Fqn relative to the current node of the child you are testing the existence of.

Returns:

true if the child node denoted by the relative Fqn passed in exists.

getNodeSPI

public NodeSPI<K,V> getNodeSPI()

putIfAbsent

public V putIfAbsent(K k,
                     V v)

Description copied from interface: Node

If the specified key is not already associated with a value, associate it with the given value, and returns the Object (if any) that occupied the space, or null.

Equivalent to calling

   if (!node.getKeys().contains(key))
     return node.put(key, value);
   else
     return node.get(key);
 

except that this is atomic.

Specified by:

putIfAbsent in interface Node<K,V>

Parameters:

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

v - value to be associated with the specified key.

Returns:

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

replace

public V replace(K key,
                 V value)

Description copied from interface: Node

Replace entry for key only if currently mapped to some value. Acts as

 if ((node.getKeys().contains(key))
 {
     return node.put(key, value);
 }
 else
     return null;
 

except that this is atomic.

Specified by:

replace in interface Node<K,V>

Parameters:

key - key with which the specified value is 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 key.

replace

public boolean replace(K key,
                       V oldValue,
                       V newValue)

Description copied from interface: Node

Replace entry for key only if currently mapped to given value. Acts as

 if (node.get(key).equals(oldValue))
 {
     node.put(key, newValue);
     return true;
 }
 else
     return false;
 

except that this is atomic.

Specified by:

replace in interface Node<K,V>

Parameters:

key - key with which the specified value is associated.

oldValue - value expected to be associated with the specified key.

newValue - value to be associated with the specified key.

Returns:

true if the value was replaced

removeChild

public boolean removeChild(Fqn f)

Description copied from interface: Node

Removes a child node specified by the given relative Fqn.

If you wish to remove children based on absolute Fqns, use the Cache interface instead.

Specified by:

removeChild in interface Node<K,V>

Parameters:

f - Fqn of the child node, relative to the current node.

Returns:

true if the node was found and removed, false otherwise

removeChild

public boolean removeChild(Object childName)

Description copied from interface: Node

Removes a child node specified by the given name.

Specified by:

removeChild in interface Node<K,V>

Parameters:

childName - name of the child node, directly under the current node.

Returns:

true if the node was found and removed, false otherwise

getCache

protected CacheSPI<K,V> getCache()