org.infinispan.tree

Interface TreeCache<K,V>

All Superinterfaces:

Lifecycle

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

Methods

Modifier and Type	Method and Description
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 TreeCache.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 TreeCache.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 TreeCache.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 TreeCache.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 TreeCache.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 TreeCache.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:

• A no-op if the node is moved unto itself. E.g., move(fqn, fqn.getParent()) will not do anything.
• If a target node does not exist it will be created silently, to be more consistent with other APIs such as put() on a nonexistent node.
• If the source node does not exist this is a no-op, to be more consistent with other APIs such as get() on a nonexistent node.

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 TreeCache.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 TreeCache.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 TreeCache.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 TreeCache.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)