Package 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 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

        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

      • 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​(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

      • 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

      • 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.

      • 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​(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.

      • clearData

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

      • 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)