TreeNodePath (JGUIraffe BOM 1.3.1 API)

java.lang.Object
- net.sf.jguiraffe.gui.builder.components.model.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 and 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 and Description
`TreeNodePath`	`append(org.apache.commons.configuration.tree.ConfigurationNode node)` Returns a `TreeNodePath` object that was created by appending the specified `ConfigurationNode` to this path.
`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.
`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.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- 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

Class TreeNodePath

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TreeNodePath

TreeNodePath

Method Detail

getNodes

size

getNodeName

getNodeIndex

getTargetNode

pathToKey

parentPath

append

append

append

equals

hashCode

toString