org.jboss.cache
Interface NodeSPI<K,V>

All Superinterfaces:
Node<K,V>
All Known Implementing Classes:
NodeInvocationDelegate, NullMarkerNode, NullMarkerNodeForRemoval, ReadCommittedNode, RepeatableReadNode

@NotThreadSafe
public interface NodeSPI<K,V>
extends Node<K,V>

A more detailed interface to Node, which is used when writing plugins for or extending JBoss Cache. References are usually obtained by calling methods on CacheSPI.

You should NEVER attempt to directly cast a Node instance to this interface. In future, the implementation may not allow it.

This interface contains overridden method signatures of some methods from Node, overridden to ensure return types of Node are replaced with NodeSPI.

An important note on the xxxDirect() methods below. These methods are counterparts to similarly named methods in Node - e.g., getDirect(Object) is a direct access counterpart to Node.get(Object), the difference being that:

The big difference with the direct access methods are that it is the onus of the caller to ensure proper locks are obtained prior to the call. A proper call should have gone through a locking-capable interceptor first and based on the cache configuration's locking policy, an appropriate lock should be obtained prior to the call. These direct access methods will throw LockingExceptions if appropriate locks haven't been obtained by the caller.

It is important to node that the direct read methods, such as getDataDirect(), return unmodifiable collections. In addition to being unmodifiable, they are also defensively copied from the underlying data map to ensure view consistency.

Since:
2.0.0
Author:
Manik Surtani (manik AT jboss DOT org)
See Also:
Node, CacheSPI

Method Summary
 void addChild(Object nodeName, Node<K,V> nodeToAdd)
          Adds or replaces a child by name.
 NodeSPI<K,V> addChildDirect(Fqn childName)
          Adds a child directly to a Node.
 NodeSPI<K,V> addChildDirect(Fqn f, boolean notify)
          Same as addChildDirect(Fqn) except that it optionally allows you to suppress notification events for the creation of this node.
 void addChildDirect(NodeSPI<K,V> child)
          Directly adds the node passed in to the children map of the current node.
 NodeSPI<K,V> addChildDirect(Object childName, boolean notify)
          Same as addChildDirect(Fqn, boolean) except that it just takes a child name
 void clearDataDirect()
          Functionally the same as Node.clearData() except that it operates directly on the node and bypasses the interceptor chain.
 void commitUpdate(InvocationContext ctx, DataContainer container)
          Commits any updates made on this node to the underlying data structure, making it visible to all other transactions.
 boolean containsKeyDirect(K key)
          Returns true if a mapping exists for this key.
 CacheSPI<K,V> getCache()
          Retrieves a reference to the cache in which this Node resides.
 NodeSPI<K,V> getChildDirect(Fqn childName)
          Retrives a child directly by fully qualified name.
 NodeSPI<K,V> getChildDirect(Object childName)
          Retrives a child directly by name.
 Set<NodeSPI<K,V>> getChildrenDirect()
          Functionally the same as Node.getChildren() except that it operates directly on the node and bypasses the interceptor chain.
 Set<NodeSPI<K,V>> getChildrenDirect(boolean includeMarkedAsDeleted)
          Retrieves children (directly), optionally including any marked as deleted nodes.
 Map<Object,Node<K,V>> getChildrenMapDirect()
          Returns a map to access the raw children.
 Set<Object> getChildrenNamesDirect()
          Functionally the same as Node.getChildrenNames() except that it operates directly on the node and bypasses the interceptor chain.
 Map<K,V> getDataDirect()
          Functionally the same as Node.getData() except that it operates directly on the node and bypasses the interceptor chain.
 InternalNode getDelegationTarget()
           
 V getDirect(K key)
          Functionally the same as Node.get(Object) except that it operates directly on the node and bypasses the interceptor chain.
 Map getInternalState(boolean onlyInternalState)
          Very similar to getDataDirect(), except that this method may also encode some internal data as attributes in the map, using special _JBOSS_INTERNAL_XXX Strings as keys.
 Set<K> getKeysDirect()
          Functionally the same as Node.getKeys() except that it operates directly on the node and bypasses the interceptor chain.
 NodeLock getLock()
          Deprecated. this will be removed in 3.0.0. Please use methods on the LockManager to lock and unlock nodes.
 NodeSPI<K,V> getOrCreateChild(Object name, GlobalTransaction tx)
          Deprecated. should use the NodeFactory instead.
 NodeSPI<K,V> getParentDirect()
          Returns the parent node as a NodeSPI, instead of Node from Node.getParent(), and is otherwise identical.
 DataVersion getVersion()
          Returns the data version of this node if versioning is supported.
 boolean hasChildrenDirect()
           
 boolean isChanged()
          Only used with MVCC.
 boolean isChildrenLoaded()
          Returns true if the children of this node were loaded from a cache loader.
 boolean isCreated()
          Only used with MVCC.
 boolean isDataLoaded()
          Returns true if the data was loaded from the cache loader.
 boolean isDeleted()
          Returns true if the instance has been deleted in the current transaction.
 boolean isNullNode()
           
 void markAsDeleted(boolean marker)
          Marks the node as being deleted (or not) in the current transaction.
 void markAsDeleted(boolean marker, boolean recursive)
          Same as markAsDeleted(boolean) except that the option to recurse into children is provided.
 void markForUpdate(DataContainer container, boolean writeSkewCheck)
          Marks a node for updating.
 void print(StringBuilder sb, int indent)
          Deprecated. 
 void printDetails(StringBuilder sb, int indent)
          Prints details of this node to the StringBuilder passed in.
 void putAllDirect(Map<? extends K,? extends V> data)
          Functionally the same as Node.putAll(Map) except that it operates directly on the node and bypasses the interceptor chain.
 V putDirect(K key, V value)
          Functionally the same as Node.put(Object,Object) except that it operates directly on the node and bypasses the interceptor chain.
 boolean removeChildDirect(Fqn fqn)
          Removes a child directly from a node.
 boolean removeChildDirect(Object childName)
          Removes a child directly from a node.
 void removeChildrenDirect()
          Directly removes all children for this node.
 V removeDirect(K key)
          Removes a data key directly from a node.
 void rollbackUpdate()
          Rolls back any changes made to a node.
 void setChildrenLoaded(boolean loaded)
          Sets if the children of this node were loaded from a cache loader.
 void setChildrenMapDirect(Map<Object,Node<K,V>> children)
          Sets the node's children explictly.
 void setCreated(boolean created)
          Sets the created flag on a node.
 void setDataLoaded(boolean dataLoaded)
          Sets if the data was loaded from the cache loader.
 void setFqn(Fqn f)
          Sets the FQN of this node and resets the names of all children as well.
 void setInternalState(Map state)
          Very similar to putAllDirect(java.util.Map) except that this method first scans the map for any internal attributes using special _JBOSS_INTERNAL_XXX Strings as keys, and uses these to set internal attributes before passing the remaining attributes to putAllDirect(java.util.Map).
 void setValid(boolean valid, boolean recursive)
          Sets the validity of a node.
 void setVersion(DataVersion version)
          Sets the data version of this node if versioning is supported.
 
Methods inherited from interface org.jboss.cache.Node
addChild, clearData, dataSize, get, getChild, getChild, getChildren, getChildrenNames, getData, getFqn, getKeys, getParent, hasChild, hasChild, isLeaf, isLockForChildInsertRemove, isResident, isValid, put, putAll, putIfAbsent, releaseObjectReferences, remove, removeChild, removeChild, replace, replace, replaceAll, setLockForChildInsertRemove, setResident
 

Method Detail

isChildrenLoaded

boolean isChildrenLoaded()
Returns true if the children of this node were loaded from a cache loader.

Returns:
true if the children of this node were loaded from a cache loader.

setChildrenLoaded

void setChildrenLoaded(boolean loaded)
Sets if the children of this node were loaded from a cache loader.

Parameters:
loaded - true if loaded, false otherwise

isDataLoaded

boolean isDataLoaded()
Returns true if the data was loaded from the cache loader.

Returns:
true if the data was loaded from the cache loader.

setDataLoaded

void setDataLoaded(boolean dataLoaded)
Sets if the data was loaded from the cache loader.

Parameters:
dataLoaded - true if loaded, false otherwise

getChildrenMapDirect

Map<Object,Node<K,V>> getChildrenMapDirect()
Returns a map to access the raw children. This method may return a null if the node does not have any children. It is important to note that this method returns a direct reference to the underlying child map and is intended for internal use only. Incorrect use may result in very inconsistent state of the cache.

Returns:
Map, keyed by child name, values Nodes.

setChildrenMapDirect

void setChildrenMapDirect(Map<Object,Node<K,V>> children)
Sets the node's children explictly. This method will remove all children currently associated with this node and add all the children passed in.

Parameters:
children - cannot be null

getOrCreateChild

@Deprecated
NodeSPI<K,V> getOrCreateChild(Object name,
                                         GlobalTransaction tx)
Deprecated. should use the NodeFactory instead.

Returns an existing child or creates a new one using a global transaction.

Parameters:
name - name of child to create
tx - transaction under which to create child
Returns:
newly created node

getLock

@Deprecated
NodeLock getLock()
Deprecated. this will be removed in 3.0.0. Please use methods on the LockManager to lock and unlock nodes.

Returns a lock for this node.

Returns:
node lock

setFqn

void setFqn(Fqn f)
Sets the FQN of this node and resets the names of all children as well.

Parameters:
f - fqn to set

isDeleted

boolean isDeleted()
Returns true if the instance has been deleted in the current transaction.

Returns:
true if the instance has been deleted in the current transaction.

markAsDeleted

void markAsDeleted(boolean marker)
Marks the node as being deleted (or not) in the current transaction. This is not recursive, child nodes are not affected.

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

markAsDeleted

void markAsDeleted(boolean marker,
                   boolean recursive)
Same as markAsDeleted(boolean) except that the option to recurse into children is provided.

Parameters:
marker - true if the node has been deleted, false if not.
recursive - if true, child nodes (and their children) are marked as well.

addChild

void addChild(Object nodeName,
              Node<K,V> nodeToAdd)
Adds or replaces a child by name.

Parameters:
nodeName - child node name (not an FQN)
nodeToAdd - child node

printDetails

void printDetails(StringBuilder sb,
                  int indent)
Prints details of this node to the StringBuilder passed in.

Parameters:
sb - StringBuilder to print to
indent - depth of this node in the tree. Used to indent details by prepending spaces.

print

@Deprecated
void print(StringBuilder sb,
                      int indent)
Deprecated. 

Prints basic information of this node to the StringBuilder passed in.

Parameters:
sb - StringBuilder to print to
indent - depth of this node in the tree. Used to indent details by prepending spaces.

setVersion

void setVersion(DataVersion version)
Sets the data version of this node if versioning is supported.

Parameters:
version - data version to apply
Throws:
UnsupportedOperationException - if versioning is not supported

getVersion

DataVersion getVersion()
Returns the data version of this node if versioning is supported.

Returns:
data version
Throws:
UnsupportedOperationException - if versioning is not supported

getChildrenDirect

Set<NodeSPI<K,V>> getChildrenDirect()
Functionally the same as Node.getChildren() except that it operates directly on the node and bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a LockingException will be thrown.

Returns:
set of child nodes.
See Also:
Node.getChildren()

removeChildrenDirect

void removeChildrenDirect()
Directly removes all children for this node. The only direct method that does not have a non-direct counterpart.


getChildrenDirect

Set<NodeSPI<K,V>> getChildrenDirect(boolean includeMarkedAsDeleted)
Retrieves children (directly), optionally including any marked as deleted nodes.

The caller needs to ensure a proper lock has been obtained prior to calling this method.

Parameters:
includeMarkedAsDeleted - if true, the returned set will include nodes marked as deleted
Returns:
a set of nodes
Throws:
LockingException - if locking was not obtained

getChildDirect

NodeSPI<K,V> getChildDirect(Object childName)
Retrives a child directly by name. Functionally the same as Node.getChild(Object) except that it bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method.

Parameters:
childName - name of child
Returns:
child node
Throws:
LockingException - if locking was not obtained
See Also:
Node.getChild(Object)

addChildDirect

NodeSPI<K,V> addChildDirect(Fqn childName)
Adds a child directly to a Node. Functionally the same as Node.addChild(Fqn) except that it bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method.

Parameters:
childName - name of child
Returns:
child node
Throws:
LockingException - if locking was not obtained
See Also:
Node.addChild(Fqn)

addChildDirect

NodeSPI<K,V> addChildDirect(Fqn f,
                            boolean notify)
Same as addChildDirect(Fqn) except that it optionally allows you to suppress notification events for the creation of this node.

Parameters:
f - name of child
notify - if true, notification events are sent; if false, they are not
Returns:
child node
Throws:
LockingException - if locking was not obtained
See Also:
Node.addChild(Fqn)

addChildDirect

NodeSPI<K,V> addChildDirect(Object childName,
                            boolean notify)
Same as addChildDirect(Fqn, boolean) except that it just takes a child name

Parameters:
childName - name of child
notify - if true, notification events are sent; if false, they are not
Returns:
child node
Throws:
LockingException - if locking was not obtained
See Also:
Node.addChild(Fqn)

addChildDirect

void addChildDirect(NodeSPI<K,V> child)
Directly adds the node passed in to the children map of the current node. Will throw a CacheException if child.getFqn().getParent().equals(getFqn()) returns false.

Parameters:
child - child to add

getChildDirect

NodeSPI<K,V> getChildDirect(Fqn childName)
Retrives a child directly by fully qualified name. Functionally the same as Node.getChild(Fqn) except that it bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method.

Parameters:
childName - name of child
Returns:
child node
Throws:
LockingException - if locking was not obtained
See Also:
Node.getChild(Fqn)

removeChildDirect

boolean removeChildDirect(Fqn fqn)
Removes a child directly from a node. Functionally the same as Node.removeChild(Fqn) except that it bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a

Parameters:
fqn - of child.
Returns:
true if the node was found, false otherwise
Throws:
LockingException - if locking was not obtained
See Also:
Node.removeChild(Fqn)

removeChildDirect

boolean removeChildDirect(Object childName)
Removes a child directly from a node. Functionally the same as Node.removeChild(Object) except that bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method.

Parameters:
childName - of child.
Returns:
true if the node was found, false otherwise
Throws:
LockingException - if locking was not obtained
See Also:
Node.removeChild(Object)

removeDirect

V removeDirect(K key)
Removes a data key directly from a node. Functionally the same as Node.remove(Object) except that it bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method.

Parameters:
key - to remove
Returns:
the old data contained under the key
Throws:
LockingException - if locking was not obtained
See Also:
Node.remove(Object)

putDirect

V putDirect(K key,
            V value)
Functionally the same as Node.put(Object,Object) except that it operates directly on the node and bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a LockingException will be thrown.

Parameters:
key - of data
value - of data
Returns:
the previous value under the key passed in, or null
See Also:
Node.put(Object,Object)

putAllDirect

void putAllDirect(Map<? extends K,? extends V> data)
Functionally the same as Node.putAll(Map) except that it operates directly on the node and bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a LockingException will be thrown.

Parameters:
data - to put
See Also:
Node.putAll(Map)

getDataDirect

Map<K,V> getDataDirect()
Functionally the same as Node.getData() except that it operates directly on the node and bypasses the interceptor chain.

Note that this returns a reference to access the node's data. This data should only be modified by the cache itself. This method should never return null.

The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a LockingException will be thrown.

Returns:
map containing data
See Also:
Node.getData()

getDirect

V getDirect(K key)
Functionally the same as Node.get(Object) except that it operates directly on the node and bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a LockingException will be thrown.

Parameters:
key - data to get
Returns:
value under key
See Also:
Node.get(Object)

containsKeyDirect

boolean containsKeyDirect(K key)
Returns true if a mapping exists for this key. Returns false if no mapping exists.

Parameters:
key - The key checked for inclusion in the node data.
Returns:
true if a mapping exists for the key, false if not.

clearDataDirect

void clearDataDirect()
Functionally the same as Node.clearData() except that it operates directly on the node and bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a LockingException will be thrown.

See Also:
Node.clearData()

getKeysDirect

Set<K> getKeysDirect()
Functionally the same as Node.getKeys() except that it operates directly on the node and bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a LockingException will be thrown.

Returns:
set of keys
See Also:
Node.getKeys()

getChildrenNamesDirect

Set<Object> getChildrenNamesDirect()
Functionally the same as Node.getChildrenNames() except that it operates directly on the node and bypasses the interceptor chain.

The caller needs to ensure a proper lock has been obtained prior to calling this method, otherwise a LockingException will be thrown.

Returns:
set of children names
See Also:
Node.getChildrenNames()

getCache

CacheSPI<K,V> getCache()
Retrieves a reference to the cache in which this Node resides.

Returns:
a cache

getParentDirect

NodeSPI<K,V> getParentDirect()
Returns the parent node as a NodeSPI, instead of Node from Node.getParent(), and is otherwise identical.

Returns:
parent node
See Also:
Node.getParent()

hasChildrenDirect

boolean hasChildrenDirect()
Returns:
true if the node has one or more child nodes; false otherwise.

getInternalState

Map getInternalState(boolean onlyInternalState)
Very similar to getDataDirect(), except that this method may also encode some internal data as attributes in the map, using special _JBOSS_INTERNAL_XXX Strings as keys. Designed to be used by StateTransferGenerator and CacheStoreInterceptor which attempt to serialize nodes into a stream for storage or transfer.

Parameters:
onlyInternalState - if true, the map will only contain internal state and no other data.
Returns:
a map containing data as well as additional information about this node.
Since:
2.1.0

setInternalState

void setInternalState(Map state)
Very similar to putAllDirect(java.util.Map) except that this method first scans the map for any internal attributes using special _JBOSS_INTERNAL_XXX Strings as keys, and uses these to set internal attributes before passing the remaining attributes to putAllDirect(java.util.Map). Designed to be used by StateTransferIntegrator and CacheLoaderInterceptor classes which attempt to create nodes based on a data stream.

Parameters:
state - state to be applied
Since:
2.1.0

setValid

void setValid(boolean valid,
              boolean recursive)
Sets the validity of a node. By default, all nodes are valid unless they are deleted, invalidated or moved, either locally or remotely. To be used in conjunction with Node.isValid().

Parameters:
valid - if true, the node is marked as valid; if false, the node is invalid.
recursive - if true, the validity flag passed in is applied to all children as well.
Since:
2.1.0

isNullNode

boolean isNullNode()
Returns:
true if the node is a null marker node. Only used with MVCC.

markForUpdate

void markForUpdate(DataContainer container,
                   boolean writeSkewCheck)
Marks a node for updating. Internally, this creates a copy of the delegate and performs any checks necessary to maintain isolation level.

Only used with MVCC.

Parameters:
container - data container
writeSkewCheck - if true, and the node supports write skew checking, nodes are tested for write skews.

commitUpdate

void commitUpdate(InvocationContext ctx,
                  DataContainer container)
Commits any updates made on this node to the underlying data structure, making it visible to all other transactions.

Only used with MVCC.

Parameters:
ctx - invocation context
container - data container

isChanged

boolean isChanged()
Only used with MVCC.

Returns:
true if this node has been marked for update, false otherwise.

isCreated

boolean isCreated()
Only used with MVCC.

Returns:
true if this node has been newly created in the current scope.

getDelegationTarget

InternalNode getDelegationTarget()

setCreated

void setCreated(boolean created)
Sets the created flag on a node.

Only used with MVCC.

Parameters:
created - flag

rollbackUpdate

void rollbackUpdate()
Rolls back any changes made to a node.

Only used with MVCC.



Copyright © 2009 JBoss, a division of Red Hat. All Rights Reserved.