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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void clearData​(java.lang.String fqn)
      Convenience method that takes in a String represenation of the Fqn.
      void clearData​(java.lang.String fqn, Flag... flags)  
      void clearData​(Fqn fqn)
      Removes the keys and properties from a named node.
      void clearData​(Fqn fqn, Flag... flags)  
      boolean exists​(java.lang.String fqn)
      Tests if an Fqn exists.
      boolean exists​(java.lang.String fqn, Flag... flags)  
      boolean exists​(Fqn fqn)
      Tests if an Fqn exists.
      boolean exists​(Fqn fqn, Flag... flags)  
      V get​(java.lang.String fqn, K key)
      Convenience method that takes a string representation of an Fqn.
      V get​(java.lang.String fqn, K key, 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)  
      Cache<?,​?> getCache()  
      java.util.Map<K,​V> getData​(Fqn fqn)
      Retrieves a defensively copied data map of the underlying node.
      java.util.Map<K,​V> getData​(Fqn fqn, Flag... flags)  
      java.util.Set<K> getKeys​(java.lang.String fqn)
      Convenience method that takes in a String represenation of the Fqn.
      java.util.Set<K> getKeys​(java.lang.String fqn, Flag... flags)  
      java.util.Set<K> getKeys​(Fqn fqn)
      Returns a set of attribute keys for the Fqn.
      java.util.Set<K> getKeys​(Fqn fqn, Flag... flags)  
      Node<K,​V> getNode​(java.lang.String fqn)
      Convenience method that takes a string representation of an Fqn.
      Node<K,​V> getNode​(java.lang.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> getRoot()
      Returns the root node of this cache.
      Node<K,​V> getRoot​(Flag... flags)  
      void move​(java.lang.String nodeToMove, java.lang.String newParent)
      Convenience method that takes in string representations of Fqns.
      void move​(java.lang.String nodeToMove, java.lang.String newParent, 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 put​(java.lang.String fqn, java.util.Map<? extends K,​? extends V> data)
      Convenience method that takes a string representation of an Fqn.
      void put​(java.lang.String fqn, java.util.Map<? extends K,​? extends V> data, Flag... flags)  
      V put​(java.lang.String fqn, K key, V value)
      Convenience method that takes a string representation of an Fqn.
      V put​(java.lang.String fqn, K key, V value, Flag... flags)  
      void put​(Fqn fqn, java.util.Map<? extends K,​? extends V> data)
      Copies all of the mappings from the specified map to a Node.
      void put​(Fqn fqn, java.util.Map<? extends K,​? extends V> data, 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)  
      V remove​(java.lang.String fqn, K key)
      Convenience method that takes a string representation of an Fqn.
      V remove​(java.lang.String fqn, K key, 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)  
      boolean removeNode​(java.lang.String fqn)
      Convenience method that takes a string representation of an Fqn.
      boolean removeNode​(java.lang.String fqn, Flag... flags)  
      boolean removeNode​(Fqn fqn)
      Removes a Node indicated by absolute Fqn.
      boolean removeNode​(Fqn fqn, Flag... flags)  
    • 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:
        java.lang.IllegalStateException - if the cache is not in a started state.
      • put

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

        V put​(java.lang.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:
        java.lang.IllegalStateException - if the cache is not in a started state
      • put

        V put​(java.lang.String fqn,
              K key,
              V value,
              Flag... flags)
      • put

        void put​(Fqn fqn,
                 java.util.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:
        java.lang.IllegalStateException - if the cache is not in a started state
      • put

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

        void put​(java.lang.String fqn,
                 java.util.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:
        java.lang.IllegalStateException - if the cache is not in a started state
      • put

        void put​(java.lang.String fqn,
                 java.util.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:
        java.lang.IllegalStateException - if the cache is not in a started state
      • remove

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

        V remove​(java.lang.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:
        java.lang.IllegalStateException - if the cache is not in a started state
      • remove

        V remove​(java.lang.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:
        java.lang.IllegalStateException - if the cache is not in a started state
      • removeNode

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

        boolean removeNode​(java.lang.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:
        java.lang.IllegalStateException - if the cache is not in a started state
      • removeNode

        boolean removeNode​(java.lang.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:
        java.lang.IllegalStateException - if the cache is not in a started state
      • getNode

        Node<K,​V> getNode​(java.lang.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:
        java.lang.IllegalStateException - if the cache is not in a started state
      • getNode

        Node<K,​V> getNode​(java.lang.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:
        java.lang.IllegalStateException - if the cache is not in a started state
      • get

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

        V get​(java.lang.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:
        java.lang.IllegalStateException - if the cache is not in a started state
      • get

        V get​(java.lang.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.
        java.lang.IllegalStateException - if Cache.getStatus() would not return ComponentStatus.RUNNING.
      • getData

        java.util.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
        java.lang.IllegalStateException - if Cache.getStatus() would not return ComponentStatus.RUNNING.
      • getData

        java.util.Map<K,​V> getData​(Fqn fqn,
                                         Flag... flags)
      • getKeys

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

        java.util.Set<K> getKeys​(java.lang.String fqn,
                                 Flag... flags)
      • getKeys

        java.util.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:
        java.lang.IllegalStateException - if Cache.getStatus() would not return ComponentStatus.RUNNING.
      • getKeys

        java.util.Set<K> getKeys​(Fqn fqn,
                                 Flag... flags)
      • clearData

        void clearData​(java.lang.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:
        java.lang.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​(java.lang.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​(java.lang.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)