org.infinispan.tree
Interface TreeCache<K,V>

All Superinterfaces:
Lifecycle
All Known Implementing Classes:
TreeCacheImpl

public interface TreeCache<K,V>
extends Lifecycle

This is a tree-like facade around a Cache allowing for efficient tree-style access to cached data.

The primary purpose of this interface is to allow for efficient caching of tree-like structures such as directories, as well as to provide a compatibility layer with JBoss Cache 3.x and earlier.

For most purposes, we expect people to use the Cache interface directly as it is simpler.

The tree API assumes that a collection of Nodes, organized in a tree structure underneath a root node, contains key/value attributes of data.

Any locking happens on a node-level granularity, which means that all attributes on a node are atomic and in terms of locking, is coarse grained. At the same time, replication is fine grained, and only modified attributes in a Node are replicated.

Obtaining a TreeCache is done using the TreeCacheFactory.

   Cache cache = new DefaultCacheFactory().getCache();
   TreeCacheFactory tcf = new TreeCacheFactory();
   TreeCache tree = tcf.createTreeCache(cache);
 

Since:
4.0
Author:
Manik Surtani (manik AT jboss DOT org)
See Also:
Node

Method Summary
 void clearData(Fqn fqn)
          Removes the keys and properties from a named node.
 void clearData(Fqn fqn, Flag... flags)
           
 void clearData(String fqn)
          Convenience method that takes in a String represenation of the Fqn.
 void clearData(String fqn, Flag... flags)
           
 boolean exists(Fqn fqn)
          Tests if an Fqn exists.
 boolean exists(Fqn fqn, Flag... flags)
           
 boolean exists(String fqn)
          Tests if an Fqn exists.
 boolean exists(String fqn, Flag... flags)
           
 V get(Fqn fqn, K key)
          Convenience method that allows for direct access to the data in a Node.
 V get(Fqn fqn, K key, Flag... flags)
           
 V get(String fqn, K key)
          Convenience method that takes a string representation of an Fqn.
 V get(String fqn, K key, Flag... flags)
           
 Cache<?,?> getCache()
           
 Map<K,V> getData(Fqn fqn)
          Retrieves a defensively copied data map of the underlying node.
 Map<K,V> getData(Fqn fqn, Flag... flags)
           
 Set<K> getKeys(Fqn fqn)
          Returns a set of attribute keys for the Fqn.
 Set<K> getKeys(Fqn fqn, Flag... flags)
           
 Set<K> getKeys(String fqn)
          Convenience method that takes in a String represenation of the Fqn.
 Set<K> getKeys(String fqn, Flag... flags)
           
 Node<K,V> getNode(Fqn fqn)
          A convenience method to retrieve a node directly from the cache.
 Node<K,V> getNode(Fqn fqn, Flag... flags)
           
 Node<K,V> getNode(String fqn)
          Convenience method that takes a string representation of an Fqn.
 Node<K,V> getNode(String fqn, Flag... flags)
           
 Node<K,V> getRoot()
          Returns the root node of this cache.
 Node<K,V> getRoot(Flag... flags)
           
 void move(Fqn nodeToMove, Fqn newParent)
          Moves a part of the cache to a different subtree.
 void move(Fqn nodeToMove, Fqn newParent, Flag... flags)
           
 void move(String nodeToMove, String newParent)
          Convenience method that takes in string representations of Fqns.
 void move(String nodeToMove, String newParent, Flag... flags)
           
 V put(Fqn fqn, K key, V value)
          Associates the specified value with the specified key for a Node in this cache.
 V put(Fqn fqn, K key, V value, Flag... flags)
           
 void put(Fqn fqn, Map<? extends K,? extends V> data)
          Copies all of the mappings from the specified map to a Node.
 void put(Fqn fqn, Map<? extends K,? extends V> data, Flag... flags)
           
 V put(String fqn, K key, V value)
          Convenience method that takes a string representation of an Fqn.
 V put(String fqn, K key, V value, Flag... flags)
           
 void put(String fqn, Map<? extends K,? extends V> data)
          Convenience method that takes a string representation of an Fqn.
 void put(String fqn, Map<? extends K,? extends V> data, Flag... flags)
           
 V remove(Fqn fqn, K key)
          Removes the mapping for this key from a Node.
 V remove(Fqn fqn, K key, Flag... flags)
           
 V remove(String fqn, K key)
          Convenience method that takes a string representation of an Fqn.
 V remove(String fqn, K key, Flag... flags)
           
 boolean removeNode(Fqn fqn)
          Removes a Node indicated by absolute Fqn.
 boolean removeNode(Fqn fqn, Flag... flags)
           
 boolean removeNode(String fqn)
          Convenience method that takes a string representation of an Fqn.
 boolean removeNode(String fqn, Flag... flags)
           
 
Methods inherited from interface org.infinispan.lifecycle.Lifecycle
start, stop
 

Method Detail

getRoot

Node<K,V> getRoot()
Returns the root node of this cache.

Returns:
the root node

getRoot

Node<K,V> getRoot(Flag... flags)

put

V put(Fqn fqn,
      K key,
      V value)
Associates the specified value with the specified key for a Node in this cache. If the Node previously contained a mapping for this key, the old value is replaced by the specified value.

Parameters:
fqn - absolute Fqn to the Node to be accessed.
key - key with which the specified value is to be 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. A null return can also indicate that the Node previously associated null with the specified key, if the implementation supports null values.
Throws:
IllegalStateException - if the cache is not in a started state.

put

V put(Fqn fqn,
      K key,
      V value,
      Flag... flags)

put

V put(String fqn,
      K key,
      V value)
Convenience method that takes a string representation of an Fqn. Otherwise identical to put(Fqn, Object, Object)

Parameters:
fqn - String representation of the Fqn
key - key with which the specified value is to be 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. A null return can also indicate that the Node previously associated null with the specified key, if the implementation supports null values.
Throws:
IllegalStateException - if the cache is not in a started state

put

V put(String fqn,
      K key,
      V value,
      Flag... flags)

put

void put(Fqn fqn,
         Map<? extends K,? extends V> data)
Copies all of the mappings from the specified map to a Node.

Parameters:
fqn - absolute Fqn to the Node to copy the data to
data - mappings to copy
Throws:
IllegalStateException - if the cache is not in a started state

put

void put(Fqn fqn,
         Map<? extends K,? extends V> data,
         Flag... flags)

put

void put(String fqn,
         Map<? extends K,? extends V> data)
Convenience method that takes a string representation of an Fqn. Otherwise identical to put(Fqn, java.util.Map)

Parameters:
fqn - String representation of the Fqn
data - data map to insert
Throws:
IllegalStateException - if the cache is not in a started state

put

void put(String fqn,
         Map<? extends K,? extends V> data,
         Flag... flags)

remove

V remove(Fqn fqn,
         K key)
Removes the mapping for this key from a Node. Returns the value to which the Node previously associated the key, or null if the Node contained no mapping for this key.

Parameters:
fqn - absolute Fqn to the Node to be accessed.
key - key whose mapping is to be removed from the Node
Returns:
previous value associated with specified Node's key
Throws:
IllegalStateException - if the cache is not in a started state

remove

V remove(Fqn fqn,
         K key,
         Flag... flags)

remove

V remove(String fqn,
         K key)
Convenience method that takes a string representation of an Fqn. Otherwise identical to remove(Fqn, Object)

Parameters:
fqn - string representation of the Fqn to retrieve
key - key to remove
Returns:
old value removed, or null if the fqn does not exist
Throws:
IllegalStateException - if the cache is not in a started state

remove

V remove(String fqn,
         K key,
         Flag... flags)

removeNode

boolean removeNode(Fqn fqn)
Removes a Node indicated by absolute Fqn.

Parameters:
fqn - Node to remove
Returns:
true if the node was removed, false if the node was not found
Throws:
IllegalStateException - if the cache is not in a started state

removeNode

boolean removeNode(Fqn fqn,
                   Flag... flags)

removeNode

boolean removeNode(String fqn)
Convenience method that takes a string representation of an Fqn. Otherwise identical to removeNode(Fqn)

Parameters:
fqn - string representation of the Fqn to retrieve
Returns:
true if the node was found and removed, false otherwise
Throws:
IllegalStateException - if the cache is not in a started state

removeNode

boolean removeNode(String fqn,
                   Flag... flags)

getNode

Node<K,V> getNode(Fqn fqn)
A convenience method to retrieve a node directly from the cache. Equivalent to calling cache.getRoot().getChild(fqn).

Parameters:
fqn - fqn of the node to retrieve
Returns:
a Node object, or a null if the node does not exist.
Throws:
IllegalStateException - if the cache is not in a started state

getNode

Node<K,V> getNode(Fqn fqn,
                  Flag... flags)

getNode

Node<K,V> getNode(String fqn)
Convenience method that takes a string representation of an Fqn. Otherwise identical to getNode(Fqn)

Parameters:
fqn - string representation of the Fqn to retrieve
Returns:
node, or null if the node does not exist
Throws:
IllegalStateException - if the cache is not in a started state

getNode

Node<K,V> getNode(String fqn,
                  Flag... flags)

get

V get(Fqn fqn,
      K key)
Convenience method that allows for direct access to the data in a Node.

Parameters:
fqn - absolute Fqn to the Node to be accessed.
key - key under which value is to be retrieved.
Returns:
returns data held under specified key in Node denoted by specified Fqn.
Throws:
IllegalStateException - if the cache is not in a started state

get

V get(Fqn fqn,
      K key,
      Flag... flags)

get

V get(String fqn,
      K key)
Convenience method that takes a string representation of an Fqn. Otherwise identical to get(Fqn, Object)

Parameters:
fqn - string representation of the Fqn to retrieve
key - key to fetch
Returns:
value, or null if the fqn does not exist.
Throws:
IllegalStateException - if the cache is not in a started state

get

V get(String fqn,
      K key,
      Flag... flags)

move

void move(Fqn nodeToMove,
          Fqn newParent)
          throws NodeNotExistsException
Moves a part of the cache to a different subtree.

E.g.:

assume a cache structure such as:

  /a/b/c
  /a/b/d
  /a/b/e
 

Fqn f1 = Fqn.fromString("/a/b/c"); Fqn f2 = Fqn.fromString("/a/b/d");

cache.move(f1, f2);

Will result in:

 

/a/b/d/c /a/b/e

and now

  Fqn f3 = Fqn.fromString("/a/b/e");
  Fqn f4 = Fqn.fromString("/a");
  cache.move(f3, f4);
 

will result in:

 /a/b/d/c
 /a/e
 
No-op if the node to be moved is the root node.

Note: As of 3.0.0 and when using MVCC locking, more specific behaviour is defined as follows:

Parameters:
nodeToMove - the Fqn of the node to move.
newParent - new location under which to attach the node being moved.
Throws:
NodeNotExistsException - may throw one of these if the target node does not exist or if a different thread has moved this node elsewhere already.
IllegalStateException - if Cache.getStatus() would not return ComponentStatus.RUNNING.

move

void move(Fqn nodeToMove,
          Fqn newParent,
          Flag... flags)
          throws NodeNotExistsException
Throws:
NodeNotExistsException

move

void move(String nodeToMove,
          String newParent)
          throws NodeNotExistsException
Convenience method that takes in string representations of Fqns. Otherwise identical to move(Fqn, Fqn)

Throws:
IllegalStateException - if Cache.getStatus() would not return ComponentStatus.RUNNING.
NodeNotExistsException

move

void move(String nodeToMove,
          String newParent,
          Flag... flags)
          throws NodeNotExistsException
Throws:
NodeNotExistsException

getData

Map<K,V> getData(Fqn fqn)
Retrieves a defensively copied data map of the underlying node. A convenience method to retrieving a node and getting data from the node directly.

Parameters:
fqn -
Returns:
map of data, or an empty map
Throws:
CacheException
IllegalStateException - if Cache.getStatus() would not return ComponentStatus.RUNNING.

getData

Map<K,V> getData(Fqn fqn,
                 Flag... flags)

getKeys

Set<K> getKeys(String fqn)
Convenience method that takes in a String represenation of the Fqn. Otherwise identical to getKeys(Fqn).


getKeys

Set<K> getKeys(String fqn,
               Flag... flags)

getKeys

Set<K> getKeys(Fqn fqn)
Returns a set of attribute keys for the Fqn. Returns null if the node is not found, otherwise a Set. The set is a copy of the actual keys for this node.

A convenience method to retrieving a node and getting keys from the node directly.

Parameters:
fqn - name of the node
Throws:
IllegalStateException - if Cache.getStatus() would not return ComponentStatus.RUNNING.

getKeys

Set<K> getKeys(Fqn fqn,
               Flag... flags)

clearData

void clearData(String fqn)
Convenience method that takes in a String represenation of the Fqn. Otherwise identical to clearData(Fqn).

Throws:
IllegalStateException - if Cache.getStatus() would not return ComponentStatus.RUNNING.

clearData

void clearData(String fqn,
               Flag... flags)

clearData

void clearData(Fqn fqn)
Removes the keys and properties from a named node.

A convenience method to retrieving a node and getting keys from the node directly.

Parameters:
fqn - name of the node
Throws:
IllegalStateException - if Cache.getStatus() would not return ComponentStatus.RUNNING.

clearData

void clearData(Fqn fqn,
               Flag... flags)

getCache

Cache<?,?> getCache()
Returns:
a reference to the underlying cache instance

exists

boolean exists(String fqn)
Tests if an Fqn exists. Convenience method for exists(Fqn)

Parameters:
fqn - string representation of an Fqn
Returns:
true if the fqn exists, false otherwise

exists

boolean exists(String fqn,
               Flag... flags)

exists

boolean exists(Fqn fqn)
Tests if an Fqn exists.

Parameters:
fqn - Fqn to test
Returns:
true if the fqn exists, false otherwise

exists

boolean exists(Fqn fqn,
               Flag... flags)

Google Analytics

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