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

All Superinterfaces:
Node<K,V>
All Known Implementing Classes:
UnversionedNode, VersionedNode

@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@jboss.org)
See Also:
Node, CacheSPI

Method Summary
 void addChild(java.lang.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.
 void addChildDirect(NodeSPI<K,V> child)
          Directly adds the node passed in to the children map of the current node.
 void clearDataDirect()
          Functionally the same as Node.clearData() except that it operates directly on the node and bypasses the interceptor chain.
 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(java.lang.Object childName)
          Retrives a child directly by name.
 java.util.Set<NodeSPI<K,V>> getChildrenDirect()
          Functionally the same as Node.getChildren() except that it operates directly on the node and bypasses the interceptor chain.
 java.util.Set<NodeSPI<K,V>> getChildrenDirect(boolean includeMarkedAsDeleted)
          Retrieves children (directly), optionally including any marked as deleted nodes.
 java.util.Map<java.lang.Object,Node<K,V>> getChildrenMapDirect()
          Returns a map to access the raw children.
 java.util.Set<java.lang.Object> getChildrenNamesDirect()
          Functionally the same as Node.getChildrenNames() except that it operates directly on the node and bypasses the interceptor chain.
 java.util.Map<K,V> getDataDirect()
          Functionally the same as Node.getData() except that it operates directly on the node and bypasses the interceptor chain.
 V getDirect(K key)
          Functionally the same as Node.get(Object) except that it operates directly on the node and bypasses the interceptor chain.
 java.util.Set<K> getKeysDirect()
          Functionally the same as Node.getKeys() except that it operates directly on the node and bypasses the interceptor chain.
 NodeLock getLock()
          Returns a lock for this node.
 NodeSPI<K,V> getOrCreateChild(java.lang.Object name, GlobalTransaction tx)
          Returns an existing child or creates a new one using a global transaction.
 NodeSPI<K,V> getParent()
          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 isChildrenLoaded()
          Returns true if the children of this node were loaded from a cache loader.
 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.
 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 print(java.lang.StringBuffer sb, int indent)
          Prints basic information of this node to the StringBuffer passed in.
 void printDetails(java.lang.StringBuffer sb, int indent)
          Prints details of this node to the StringBuffer passed in.
 void putAllDirect(java.util.Map<K,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(java.lang.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 setChildrenLoaded(boolean loaded)
          Sets if the children of this node were loaded from a cache loader.
 void setChildrenMapDirect(java.util.Map<java.lang.Object,Node<K,V>> children)
          Sets the node's children explictly.
 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 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, hasChild, hasChild, isValid, put, putAll, putIfAbsent, remove, removeChild, removeChild, replace, replace, replaceAll
 

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

java.util.Map<java.lang.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(java.util.Map<java.lang.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

NodeSPI<K,V> getOrCreateChild(java.lang.Object name,
                              GlobalTransaction tx)
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

NodeLock getLock()
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(java.lang.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(java.lang.StringBuffer sb,
                  int indent)
Prints details of this node to the StringBuffer passed in.

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

print

void print(java.lang.StringBuffer sb,
           int indent)
Prints basic information of this node to the StringBuffer passed in.

Parameters:
sb - StringBuffer 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:
java.lang.UnsupportedOperationException - if versioning is not supported

getVersion

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

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

getChildrenDirect

java.util.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

java.util.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(java.lang.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

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(java.lang.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(java.util.Map<K,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

java.util.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.

Also note that this method returns an unmodifiable reference to the underlying data map.

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)

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

java.util.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

java.util.Set<java.lang.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

getParent

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

Specified by:
getParent in interface Node<K,V>
Returns:
parent node
See Also:
Node.getParent()

hasChildrenDirect

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