Package org.infinispan.tree

Interface Node<K,​V>

  • @ThreadSafe
public interface Node<K,​V>
    A Node is a named logical grouping of data in the TreeCache API of JBoss Cache. A node should be used to contain data for a single data record, for example information about a particular person or account.

    One purpose of grouping cache data into separate nodes is to minimize transaction locking interference, and increase concurrency. So for example, when multiple threads or possibly distributed caches are accessing different accounts simultaneously.

    A node has references to its children, parent (each node except the root - defined by Fqn.ROOT - has a single parent) and data contained within the node (as key/value pairs). The data access methods are similar to the collections Map interface, but some are read-only or return copies of the underlying data.

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

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      Node<K,​V> addChild​(Fqn f)
      Adds a child node with the given Fqn under the current node.
      Node<K,​V> addChild​(Fqn f, Flag... flags)  
      void clearData()
      Removes all mappings from the node's data map.
      void clearData​(Flag... flags)  
      int dataSize()  
      int dataSize​(Flag... flags)  
      V get​(K key)
      Returns the value to which this node maps the specified key.
      V get​(K key, Flag... flags)  
      Node<K,​V> getChild​(java.lang.Object name)  
      Node<K,​V> getChild​(java.lang.Object name, Flag... flags)  
      Node<K,​V> getChild​(Fqn f)
      Returns the child node
      Node<K,​V> getChild​(Fqn f, Flag... flags)  
      java.util.Set<Node<K,​V>> getChildren()
      Returns an immutable set of children nodes.
      java.util.Set<Node<K,​V>> getChildren​(Flag... flags)  
      java.util.Set<java.lang.Object> getChildrenNames()
      Returns an immutable set of children node names.
      java.util.Set<java.lang.Object> getChildrenNames​(Flag... flags)  
      java.util.Map<K,​V> getData()
      Returns a map containing the data in this Node.
      java.util.Map<K,​V> getData​(Flag... flags)  
      Fqn getFqn()
      Returns the Fqn which represents the location of this Node in the cache structure.
      java.util.Set<K> getKeys()
      Returns a Set containing the data in this Node.
      java.util.Set<K> getKeys​(Flag... flags)  
      Node<K,​V> getParent()
      Returns the parent node.
      Node<K,​V> getParent​(Flag... flags)  
      boolean hasChild​(java.lang.Object o)
      Returns true if the child node denoted by the Object name passed in exists.
      boolean hasChild​(java.lang.Object o, Flag... flags)  
      boolean hasChild​(Fqn f)
      Returns true if the child node denoted by the relative Fqn passed in exists.
      boolean hasChild​(Fqn f, Flag... flags)  
      boolean isValid()
      Tests if a node reference is still valid.
      V put​(K key, V value)
      Associates the specified value with the specified key for this node.
      V put​(K key, V value, Flag... flags)  
      void putAll​(java.util.Map<? extends K,​? extends V> map)
      Copies all of the mappings from the specified map to this node's map.
      void putAll​(java.util.Map<? extends K,​? extends V> map, Flag... flags)  
      V putIfAbsent​(K key, V value)
      If the specified key is not already associated with a value, associate it with the given value, and returns the Object (if any) that occupied the space, or null.
      V putIfAbsent​(K key, V value, Flag... flags)  
      V remove​(K key)
      Removes the mapping for this key from this node if it is present.
      V remove​(K key, Flag... flags)  
      boolean removeChild​(java.lang.Object childName)
      Removes a child node specified by the given name.
      boolean removeChild​(java.lang.Object childName, Flag... flags)  
      boolean removeChild​(Fqn f)
      Removes a child node specified by the given relative Fqn.
      boolean removeChild​(Fqn f, Flag... flags)  
      void removeChildren()  
      void removeChildren​(Flag... flags)  
      V replace​(K key, V value)
      Replace entry for key only if currently mapped to some value.
      V replace​(K key, V value, Flag... flags)  
      boolean replace​(K key, V oldValue, V newValue)
      Replace entry for key only if currently mapped to given value.
      boolean replace​(K key, V oldValue, V newValue, Flag... flags)  
      void replaceAll​(java.util.Map<? extends K,​? extends V> map)
      Similar to putAll(java.util.Map) except that it removes any entries that exists in the data map first.
      void replaceAll​(java.util.Map<? extends K,​? extends V> map, Flag... flags)  

    • Method Detail

      • getParent

        Node<K,​V> getParent()
        Returns the parent node. If this is the root node, this method returns this.
        Returns:
        the parent node, or self if this is the root node

      • getParent

        Node<K,​V> getParent​(Flag... flags)

      • getChildren

        java.util.Set<Node<K,​V>> getChildren()
        Returns an immutable set of children nodes.
        Returns:
        an immutable Set of child nodes. Empty Set if there aren't any children.

      • getChildren

        java.util.Set<Node<K,​V>> getChildren​(Flag... flags)

      • getChildrenNames

        java.util.Set<java.lang.Object> getChildrenNames()
        Returns an immutable set of children node names.
        Returns:
        an immutable Set of child node names. Empty Set if there aren't any children.

      • getChildrenNames

        java.util.Set<java.lang.Object> getChildrenNames​(Flag... flags)

      • getData

        java.util.Map<K,​V> getData()
        Returns a map containing the data in this Node.
        Returns:
        a Map containing the data in this Node. If there is no data, an empty Map is returned. The Map returned is always immutable.

      • getData

        java.util.Map<K,​V> getData​(Flag... flags)

      • getKeys

        java.util.Set<K> getKeys()
        Returns a Set containing the data in this Node.
        Returns:
        a Set containing the data in this Node. If there is no data, an empty Set is returned. The Set returned is always immutable.

      • getKeys

        java.util.Set<K> getKeys​(Flag... flags)

      • getFqn

        Fqn getFqn()
        Returns the Fqn which represents the location of this Node in the cache structure. The Fqn returned is absolute.
        Returns:
        The Fqn which represents the location of this Node in the cache structure. The Fqn returned is absolute.

      • addChild

        Node<K,​V> addChild​(Fqn f)
        Adds a child node with the given Fqn under the current node. Returns the newly created node.

        If the child exists returns the child node anyway. Guaranteed to return a non-null node.

        The Fqn passed in is relative to the current node. The new child node will have an absolute fqn calculated as follows: 

        new Fqn(getFqn(), f)
        . See Fqn for the operation of this constructor.
        Parameters:
        f - Fqn of the child node, relative to the current node.
        Returns:
        the newly created node, or the existing node if one already exists.

      • removeChild

        boolean removeChild​(Fqn f)
        Removes a child node specified by the given relative Fqn.

        If you wish to remove children based on absolute Fqns, use the TreeCache interface instead.

        Parameters:
        f - Fqn of the child node, relative to the current node.
        Returns:
        true if the node was found and removed, false otherwise

      • removeChild

        boolean removeChild​(Fqn f,
                    Flag... flags)

      • removeChild

        boolean removeChild​(java.lang.Object childName)
        Removes a child node specified by the given name.
        Parameters:
        childName - name of the child node, directly under the current node.
        Returns:
        true if the node was found and removed, false otherwise

      • removeChild

        boolean removeChild​(java.lang.Object childName,
                    Flag... flags)

      • getChild

        Node<K,​V> getChild​(Fqn f)
        Returns the child node
        Parameters:
        f - Fqn of the child node
        Returns:
        null if the child does not exist.

      • getChild

        Node<K,​V> getChild​(java.lang.Object name)
        Parameters:
        name - name of the child
        Returns:
        a direct child of the current node.

      • getChild

        Node<K,​V> getChild​(java.lang.Object name,
                         Flag... flags)

      • put

        V put​(K key,
      V value)
        Associates the specified value with the specified key for this node. If this node previously contained a mapping for this key, the old value is replaced by the specified value.
        Parameters:
        key - key with which the specified value is to be associated.
        value - value to be associated with the specified key.
        Returns:
        Returns the old value contained under this key. Null if key doesn't exist.

      • put

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

      • putIfAbsent

        V putIfAbsent​(K key,
              V value)
        If the specified key is not already associated with a value, associate it with the given value, and returns the Object (if any) that occupied the space, or null.

        Equivalent to calling 

           if (!node.getKeys().contains(key))
     return node.put(key, value);
   else
     return node.get(key);

        except that this is atomic.

        Parameters:
        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.

      • putIfAbsent

        V putIfAbsent​(K key,
              V value,
              Flag... flags)

      • replace

        V replace​(K key,
          V value)
        Replace entry for key only if currently mapped to some value. Acts as 
         if ((node.getKeys().contains(key))
 {
     return node.put(key, value);
 }
 else
     return null;

        except that this is atomic.

        Parameters:
        key - key with which the specified value is 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.

      • replace

        V replace​(K key,
          V value,
          Flag... flags)

      • replace

        boolean replace​(K key,
                V oldValue,
                V newValue)
        Replace entry for key only if currently mapped to given value. Acts as 
         if (node.get(key).equals(oldValue))
 {
     node.put(key, newValue);
     return true;
 }
 else
     return false;

        except that this is atomic.

        Parameters:
        key - key with which the specified value is associated.
        oldValue - value expected to be associated with the specified key.
        newValue - value to be associated with the specified key.
        Returns:
        true if the value was replaced

      • replace

        boolean replace​(K key,
                V oldValue,
                V newValue,
                Flag... flags)

      • putAll

        void putAll​(java.util.Map<? extends K,​? extends V> map)
        Copies all of the mappings from the specified map to this node's map. If any data exists, existing keys are overwritten with the keys in the new map. The behavior is equivalent to: 
         Node node;
 for (Map.Entry me : map.entrySet())
   node.put(me.getKey(), me.getValue());
        Parameters:
        map - map to copy from

      • putAll

        void putAll​(java.util.Map<? extends K,​? extends V> map,
            Flag... flags)

      • replaceAll

        void replaceAll​(java.util.Map<? extends K,​? extends V> map)
        Similar to putAll(java.util.Map) except that it removes any entries that exists in the data map first. Note that this happens atomically, under a single lock. This is the analogous to doing a clearData() followed by a putAll(java.util.Map) in the same transaction.
        Parameters:
        map - map to copy from

      • replaceAll

        void replaceAll​(java.util.Map<? extends K,​? extends V> map,
                Flag... flags)

      • get

        V get​(K key)
        Returns the value to which this node maps the specified key. Returns null if the node contains no mapping for this key.
        Parameters:
        key - key of the data to return
        Returns:
        the value to which this node maps the specified key, or null if the map contains no mapping for this key

      • get

        V get​(K key,
      Flag... flags)

      • remove

        V remove​(K key)
        Removes the mapping for this key from this node if it is present. Returns the value to which the node previously associated the key, or null if the node contained no mapping for this key
        Parameters:
        key - key whose mapping is to be removed
        Returns:
        previous value associated with specified key, or null if there was no mapping for key

      • remove

        V remove​(K key,
         Flag... flags)

      • clearData

        void clearData()
        Removes all mappings from the node's data map.

      • clearData

        void clearData​(Flag... flags)

      • dataSize

        int dataSize()
        Returns:
        the number of elements (key/value pairs) in the node's data map.

      • dataSize

        int dataSize​(Flag... flags)

      • hasChild

        boolean hasChild​(Fqn f)
        Returns true if the child node denoted by the relative Fqn passed in exists.
        Parameters:
        f - Fqn relative to the current node of the child you are testing the existence of.
        Returns:
        true if the child node denoted by the relative Fqn passed in exists.

      • hasChild

        boolean hasChild​(Fqn f,
                 Flag... flags)

      • hasChild

        boolean hasChild​(java.lang.Object o)
        Returns true if the child node denoted by the Object name passed in exists.
        Parameters:
        o - name of the child, relative to the current node
        Returns:
        true if the child node denoted by the name passed in exists.

      • hasChild

        boolean hasChild​(java.lang.Object o,
                 Flag... flags)

      • isValid

        boolean isValid()
        Tests if a node reference is still valid. A node reference may become invalid if it has been removed, invalidated or moved, either locally or remotely. If a node is invalid, it should be fetched again from the cache or a valid parent node. Operations on invalid nodes will throw a NodeNotValidException.
        Returns:
        true if the node is valid.

      • removeChildren

        void removeChildren()

      • removeChildren

        void removeChildren​(Flag... flags)