Class TreeNodePath
- 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 Description TreeNodePath(Collection<org.apache.commons.configuration.tree.ConfigurationNode> pathNodes)
Creates a new instance ofTreeNodePath
and initializes it with the nodes comprising the path.TreeNodePath(org.apache.commons.configuration.tree.ConfigurationNode target)
Creates a new instance ofTreeNodePath
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 aTreeNodePath
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 aTreeNodePath
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 aTreeNodePath
object that was created by appending the specifiedConfigurationNode
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 thisTreeNodePath
.void
pathToKey(org.apache.commons.configuration.tree.DefaultConfigurationKey key)
Appends this path to the givenConfigurationKey
.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 ofTreeNodePath
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 ofTreeNodePath
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 andgetNodeIndex()
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 togetNodeName()
this method is intended for constructing unique keys for paths that can be used for accessing the underlyingConfiguration
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 givenConfigurationKey
. 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 thisTreeNodePath
. This means that the target node of theTreeNodePath
returned by this method is the parent node of thisTreeNodePath
's target node. ThisTreeNodePath
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 aTreeNodePath
object that was created by appending the specifiedConfigurationNode
to this path. The new node becomes the target node of the newTreeNodePath
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 aTreeNodePath
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 newTreeNodePath
object with this node as target node.- Parameters:
childName
- the name of the child node to be appendedindex
- 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 foundIndexOutOfBoundsException
- if the index is invalid
-
append
public TreeNodePath append(String childName)
Returns aTreeNodePath
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 ofappend(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.
-
hashCode
public int hashCode()
Returns a hash code for this object. The hash code is obtained from the target node.
-
-