Class TreeNodePath


  • public class TreeNodePath
    extends Object

    A class that represents a path in a tree component.

    Objects of this class are used for uniquely identifying specific nodes in a tree. They contain the path from a target node to the root node. This is used for instance to describe the selected node(s) in a tree.

    With the methods provided by this class the path can be queried as a list of ConfigurationNode objects. (Theoretically the end node of the path would already be a unique description of a path because there is only a single way to the root node; by navigating through the parent nodes an application can construct this path. However, if this information is provided explicitly as a list, it is much easier for an application to deal with paths.)

    It is also possible to query the single names and indices of the nodes comprising the path. This is especially useful for constructing a configuration key representing the path. This key can then be used for querying or manipulating the Configuration object that serves as data store for the tree's model.

    When an instance of this class is created it is fully initialized with the nodes that belong to the represented path. These references cannot be changed later any more. However, the nodes themselves are not copied because this could be expensive. Therefore the class is not immutable. It can be used by multiple threads only under the precondition that the configuration nodes involved do not change. The main use case however is that a path is obtained and processed by a single event handler in the event dispatch thread.

    Version:
    $Id: TreeNodePath.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger
    • Constructor Summary

      Constructors 
      Constructor Description
      TreeNodePath​(Collection<org.apache.commons.configuration.tree.ConfigurationNode> pathNodes)
      Creates a new instance of TreeNodePath and initializes it with the nodes comprising the path.
      TreeNodePath​(org.apache.commons.configuration.tree.ConfigurationNode target)
      Creates a new instance of TreeNodePath and initializes it with the target node.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      TreeNodePath append​(String childName)
      Returns a TreeNodePath object that was created by appending the first child node of the current target node with the given name to this path.
      TreeNodePath append​(String childName, int index)
      Returns a TreeNodePath object that was created by appending the specified child node of the current target node to this path.
      TreeNodePath append​(org.apache.commons.configuration.tree.ConfigurationNode node)
      Returns a TreeNodePath object that was created by appending the specified ConfigurationNode to this path.
      boolean equals​(Object obj)
      Tests whether two objects are equal.
      int getNodeIndex​(int index)
      Returns the index of the path node at the specified position in the path.
      String getNodeName​(int index)
      Returns the name of the path node with the given index.
      List<org.apache.commons.configuration.tree.ConfigurationNode> getNodes()
      Returns a list with the nodes comprising the path.
      org.apache.commons.configuration.tree.ConfigurationNode getTargetNode()
      Returns the target node of this path.
      int hashCode()
      Returns a hash code for this object.
      TreeNodePath parentPath()
      Returns the parent path of this TreeNodePath.
      void pathToKey​(org.apache.commons.configuration.tree.DefaultConfigurationKey key)
      Appends this path to the given ConfigurationKey.
      int size()
      Returns the length of this path.
      String toString()
      Returns a string representation for this object.
    • Constructor Detail

      • TreeNodePath

        public TreeNodePath​(org.apache.commons.configuration.tree.ConfigurationNode target)
        Creates a new instance of TreeNodePath and initializes it with the target node. From this node the path to the root will be constructed.
        Parameters:
        target - the target node (must not be null)
        Throws:
        IllegalArgumentException - if the target node is null
      • TreeNodePath

        public TreeNodePath​(Collection<org.apache.commons.configuration.tree.ConfigurationNode> pathNodes)
        Creates a new instance of TreeNodePath and initializes it with the nodes comprising the path.
        Parameters:
        pathNodes - the collection with the nodes of the path (must not be null)
        Throws:
        IllegalArgumentException - if the collection is null
    • Method Detail

      • getNodes

        public List<org.apache.commons.configuration.tree.ConfigurationNode> getNodes()
        Returns a list with the nodes comprising the path. The root node of the tree is at index 0. The target node of this path is at the highest index. Note that the list returned by this method is immutable.
        Returns:
        a list with the nodes of this path
      • size

        public int size()
        Returns the length of this path. This is the number of nodes contained in this path from the target node to the root node.
        Returns:
        the length of this path
      • getNodeName

        public String getNodeName​(int index)

        Returns the name of the path node with the given index. The purpose of this method is constructing unique configuration keys by iterating over all node names and indices. Because the root node is not part of a configuration key it is not taken into account by this method. Thus the index 0 will not return the name of the root node, but the name of the next node in the path below the root node. The last node of the path has then the index size() - 2. The following code fragment shows how this method and getNodeIndex() can be used for constructing a string representation of this path:

         TreeNodePath path = ...;
         StringBuilder buf = new StringBuilder();
         for (int i = 0; i < path.size() - 1; i++) {
           if (i > 0) {
             buf.append('/');  // separator for node names
           }
           buf.append(path.getNodeName(i);
           buf.append('[').append(path.getNodeIndex(i)).append(']');
         }
         

        Parameters:
        index - the index of the desired node
        Returns:
        the name of this node
        Throws:
        ArrayIndexOutOfBoundsException - if the index is invalid
      • getNodeIndex

        public int getNodeIndex​(int index)
        Returns the index of the path node at the specified position in the path. Analogously to getNodeName() this method is intended for constructing unique keys for paths that can be used for accessing the underlying Configuration object. Because a configuration node can have multiple child nodes with the same name indices are required for making keys unique. The index returned by this method is non 0 only if there are multiple child nodes with the same name. In this case it determines, which of these child nodes is the one that belongs to this path.
        Parameters:
        index - the index of the desired node (in the path)
        Returns:
        a unique index for this node for constructing a unique key
        Throws:
        ArrayIndexOutOfBoundsException - if the index is invalid
        See Also:
        getNodeName(int)
      • getTargetNode

        public org.apache.commons.configuration.tree.ConfigurationNode getTargetNode()
        Returns the target node of this path. This is the last component in the path.
        Returns:
        the target node of this path
      • pathToKey

        public void pathToKey​(org.apache.commons.configuration.tree.DefaultConfigurationKey key)
        Appends this path to the given ConfigurationKey. This implementation will create a unique key that corresponds to the path represented. The node names and the indices along the path are appended to the given configuration key.
        Parameters:
        key - the key (must not be null)
        Throws:
        IllegalArgumentException - if the key is null
      • parentPath

        public TreeNodePath parentPath()
        Returns the parent path of this TreeNodePath. This means that the target node of the TreeNodePath returned by this method is the parent node of this TreeNodePath's target node. This TreeNodePath must have at least a size of 2, otherwise an exception is thrown.
        Returns:
        the parent path of this TreeNodePath
        Throws:
        IllegalStateException - if this path already represents the root node
      • append

        public TreeNodePath append​(org.apache.commons.configuration.tree.ConfigurationNode node)
        Returns a TreeNodePath object that was created by appending the specified ConfigurationNode to this path. The new node becomes the target node of the new TreeNodePath object. This method is useful when navigating through a tree structure. The passed in node must be a child node of the current target node.
        Parameters:
        node - the node to be appended to the path
        Returns:
        the new TreeNodePath extended by the node
        Throws:
        IllegalArgumentException - if the passed in node is null or not a child node of the target node
      • append

        public TreeNodePath append​(String childName,
                                   int index)
        Returns a TreeNodePath object that was created by appending the specified child node of the current target node to this path. This method determines the child node with the given name and index. It then creates a new TreeNodePath object with this node as target node.
        Parameters:
        childName - the name of the child node to be appended
        index - the index of the node (in case there are multiple children with the same name)
        Returns:
        the new TreeNodePath extended by the child node
        Throws:
        IllegalArgumentException - if no child node with this name can be found
        IndexOutOfBoundsException - if the index is invalid
      • append

        public TreeNodePath append​(String childName)
        Returns a TreeNodePath object that was created by appending the first child node of the current target node with the given name to this path. This is a short cut of append(childName, 0).
        Parameters:
        childName - the name of the child node to be appended
        Returns:
        the new TreeNodePath extended by the child node
        Throws:
        IllegalArgumentException - if no child node with this name can be found
      • equals

        public boolean equals​(Object obj)
        Tests whether two objects are equal. Two path objects are considered equal if and only if they refer to the same target node.
        Overrides:
        equals in class Object
        Parameters:
        obj - the object to test
        Returns:
        a flag whether these objects are equal
      • hashCode

        public int hashCode()
        Returns a hash code for this object. The hash code is obtained from the target node.
        Overrides:
        hashCode in class Object
        Returns:
        a hash code
      • toString

        public String toString()
        Returns a string representation for this object. This string will contain a representation of the path using '/' as path separator and square brackets for indices.
        Overrides:
        toString in class Object
        Returns:
        a string for this object