org.jboss.cache
Interface DataContainer

All Known Implementing Classes:
DataContainerImpl

public interface DataContainer

This class defines the functionality needed for node manipulation.

Since:
2.2
Author:
Mircea.Markus@jboss.com
See Also:
DataContainerImpl

Method Summary
 List<NodeData> buildNodeData(List<NodeData> list, NodeSPI node)
          Prepares a list of NodeData objects for a specified node and all its children.
 Object[] createNodes(Fqn fqn)
          Traverses the tree to the given Fqn, creating nodes if needed.
 boolean evict(Fqn fqn)
           Following scenarios define how eviction works.
 void evict(Fqn fqn, boolean recursive)
          Evicts the given node.
 boolean exists(Fqn fqn)
          Tests if an Fqn exists and is valid and not deleted.
 Set<Fqn> getInternalFqns()
          Returns a Set of Fqns of the topmost node of internal regions that should not included in standard state transfers.
 List<Fqn> getNodesForEviction(Fqn fqn, boolean recursive)
          Generates a list of nodes for eviction.
 int getNumberOfAttributes()
          Returns an approximation of the total number of attributes in the cache.
 int getNumberOfAttributes(Fqn fqn)
          Returns an approximation of the total number of attributes in this sub cache.
 int getNumberOfLocksHeld()
          Returns the number of read or write locks held across the entire cache.
 int getNumberOfNodes()
          Returns an approximation of the total number of nodes in the cache.
 NodeSPI getRoot()
          Retrieves the root node.
 boolean hasChildren(Fqn fqn)
          Returns true if the Fqn exists, is valid and is not deleted, and the node has children.
 NodeSPI peek(Fqn fqn)
          Finds a node given a fully qualified name, directly off the interceptor chain.
 NodeSPI peek(Fqn<?> fqn, boolean includeDeletedNodes)
          Same as calling peek(fqn, includeDeletedNodes, false).
 NodeSPI peek(Fqn<?> fqn, boolean includeDeletedNodes, boolean includeInvalidNodes)
          Peeks for a specified node.
 NodeSPI peekStrict(GlobalTransaction gtx, Fqn fqn, boolean includeInvalid)
          Similar to peekVersioned(Fqn, org.jboss.cache.optimistic.DataVersion) except that it throws a NodeNotExistsException if the node cannot be found.
 NodeSPI peekVersioned(Fqn fqn, DataVersion version)
          Finds a node given a fully qualified name and DataVersion.
 NodeSPI peekVersioned(Fqn fqn, DataVersion version, boolean includeInvalidNodes)
          Searches for a specific node, with a specific data version and, optionally, invalid nodes as well, but not deleted nodes.
 void registerInternalFqn(Fqn fqn)
          Adds the specified Fqn to the list of Fqns to be considered "internal".
 boolean removeFromDataStructure(Fqn f, boolean skipMarkerCheck)
          Removes the actual node from the tree data structure.
 

Method Detail

getRoot

NodeSPI getRoot()
Retrieves the root node.

Returns:
the root node

registerInternalFqn

void registerInternalFqn(Fqn fqn)
Adds the specified Fqn to the list of Fqns to be considered "internal".

Parameters:
fqn - fqn to add to list

peek

NodeSPI peek(Fqn fqn)
Finds a node given a fully qualified name, directly off the interceptor chain. In the event of an exception, returns null. Does not include invalid or deleted nodes.

Parameters:
fqn - Fully qualified name for the corresponding node.
Returns:
Node referenced by the given Fqn, or null if the node cannot be found or if there is an exception.

peekVersioned

NodeSPI peekVersioned(Fqn fqn,
                      DataVersion version)
Finds a node given a fully qualified name and DataVersion. Does not include invalid or deleted nodes. If the data version passed in is null, then data version checking is skipped. Data version checking is also skipped if optimistic locking is not used.

Parameters:
fqn - fqn to find
version - version of the node to find
Returns:
a node, if found, or null if not.

peekStrict

NodeSPI peekStrict(GlobalTransaction gtx,
                   Fqn fqn,
                   boolean includeInvalid)
Similar to peekVersioned(Fqn, org.jboss.cache.optimistic.DataVersion) except that it throws a NodeNotExistsException if the node cannot be found.

Parameters:
gtx - global transaction
fqn - fqn to find
includeInvalid - if true, invalid nodes are considered as well.
Returns:
the node

peekVersioned

NodeSPI peekVersioned(Fqn fqn,
                      DataVersion version,
                      boolean includeInvalidNodes)
Searches for a specific node, with a specific data version and, optionally, invalid nodes as well, but not deleted nodes. If the data version passed in is null, then data version checking is skipped. Data version checking is also skipped if optimistic locking is not used.

Parameters:
fqn - Fqn to find
version - version of the node to find
includeInvalidNodes - if true, invalid nodes are considered
Returns:
the node, if found, or null otherwise.

peek

NodeSPI peek(Fqn<?> fqn,
             boolean includeDeletedNodes)
Same as calling peek(fqn, includeDeletedNodes, false).

Parameters:
fqn - Fqn to find
includeDeletedNodes - if true, deleted nodes are considered
Returns:
the node, if found, or null otherwise.

peek

NodeSPI peek(Fqn<?> fqn,
             boolean includeDeletedNodes,
             boolean includeInvalidNodes)
Peeks for a specified node. This involves a direct walk of the tree, starting at the root, until the required node is found. If the node is not found, a null is returned.

Parameters:
fqn - Fqn of the node to find
includeDeletedNodes - if true, deleted nodes are also considered
includeInvalidNodes - if true, invalid nodes are also considered
Returns:
the node, if found, or null otherwise.

exists

boolean exists(Fqn fqn)
Tests if an Fqn exists and is valid and not deleted.

Parameters:
fqn - the fqn representing the node to test
Returns:
true if the node exists, false otherwise.

hasChildren

boolean hasChildren(Fqn fqn)
Returns true if the Fqn exists, is valid and is not deleted, and the node has children.

Parameters:
fqn - the fqn to test
Returns:
true if the Fqn exists, is valid and is not deleted, and the node has children.

buildNodeData

List<NodeData> buildNodeData(List<NodeData> list,
                             NodeSPI node)
Prepares a list of NodeData objects for a specified node and all its children.

Parameters:
list - List of NodeData objects, which will be added to.
node - node to recursively add to the list
Returns:
the same list passed in

getNodesForEviction

List<Fqn> getNodesForEviction(Fqn fqn,
                              boolean recursive)
Generates a list of nodes for eviction. This filters out nodes that cannot be evicted, such as those which are marked as resident. See Node.setResident(boolean).

Parameters:
fqn - the node to consider for eviction
recursive - if recursive, child nodes are also considered
Returns:
a list of Fqns that can be considered for eviction

getInternalFqns

Set<Fqn> getInternalFqns()
Returns a Set of Fqns of the topmost node of internal regions that should not included in standard state transfers. Will include BuddyManager.BUDDY_BACKUP_SUBTREE if buddy replication is enabled.

Returns:
an unmodifiable Set. Will not return null.

getNumberOfLocksHeld

int getNumberOfLocksHeld()
Returns the number of read or write locks held across the entire cache.


getNumberOfNodes

int getNumberOfNodes()
Returns an approximation of the total number of nodes in the cache. Since this method doesn't acquire any locks, the number might be incorrect, or the method might even throw a ConcurrentModificationException


getNumberOfAttributes

int getNumberOfAttributes(Fqn fqn)
Returns an approximation of the total number of attributes in this sub cache.


getNumberOfAttributes

int getNumberOfAttributes()
Returns an approximation of the total number of attributes in the cache. Since this method doesn't acquire any locks, the number might be incorrect, or the method might even throw a ConcurrentModificationException

Returns:
number of attribs

removeFromDataStructure

boolean removeFromDataStructure(Fqn f,
                                boolean skipMarkerCheck)
Removes the actual node from the tree data structure.

Parameters:
f - the Fqn of the node to remove
skipMarkerCheck - if true, skips checking the boolean NodeSPI.isDeleted() flag and deletes the node anyway.
Returns:
Returns true if the node was found and removed, false if not.

evict

void evict(Fqn fqn,
           boolean recursive)
Evicts the given node. If recursive is set to true then all child nodes are recusively evicted.


evict

boolean evict(Fqn fqn)
 Following scenarios define how eviction works.
 1. If the given node is a leaf then it is entirely removed from the data structure. The node is marked as invalid.
 2. If the given node is a leaf then only the data map is cleared.
 3. If the given node is the root node then the cildren nodes are evicted. For each child node 1. or 2. applies
 

Returns:
true if the FQN is leaf and was removed; false if is an intermediate FQN and only contained data is droped.

createNodes

Object[] createNodes(Fqn fqn)
Traverses the tree to the given Fqn, creating nodes if needed. Returns a list of nodes created, as well as a reference to the last node.

E.g., Object[] results = createNode(myFqn); results[0] // this is a List<NodeSPI> of nodes created in getting to the target node. results[1] // is a NodeSPI reference to the target node, regardless of whether it was created or just found.

Parameters:
fqn - fqn to find
Returns:
see above.


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