Module java.desktop
Package javax.swing.tree

# Class TreePath

java.lang.Object
javax.swing.tree.TreePath

All Implemented Interfaces:
  `Serializable`

public class TreePath extends Object implements Serializable
`TreePath` represents an array of objects that uniquely identify the path to a node in a tree. The elements of the array are ordered with the root as the first element of the array. For example, a file on the file system is uniquely identified based on the array of parent directories and the name of the file. The path `/tmp/foo/bar` could be represented by a `TreePath` as `new TreePath(new Object[] {"tmp", "foo", "bar"})`.

`TreePath` is used extensively by `JTree` and related classes. For example, `JTree` represents the selection as an array of `TreePath`s. When used with `JTree`, the elements of the path are the objects returned from the `TreeModel`. When `JTree` is paired with `DefaultTreeModel`, the elements of the path are `TreeNode`s. The following example illustrates extracting the user object from the selection of a `JTree`:

       DefaultMutableTreeNode root = ...;
       DefaultTreeModel model = new DefaultTreeModel(root);
       JTree tree = new JTree(model);
       ...
       TreePath selectedPath = tree.getSelectionPath();
       DefaultMutableTreeNode selectedNode =
           ((DefaultMutableTreeNode)selectedPath.getLastPathComponent()).
           getUserObject();

Subclasses typically need override only `getLastPathComponent`, and `getParentPath`. As `JTree` internally creates `TreePath`s at various points, it's generally not useful to subclass `TreePath` and use with `JTree`.

While `TreePath` is serializable, a `NotSerializableException` is thrown if any elements of the path are not serializable.

For further information and examples of using tree paths, see How to Use Trees in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans has been added to the `java.beans` package. Please see `XMLEncoder`.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `TreePath()`
  Creates an empty `TreePath`.
  ``
  `TreePath(Object lastPathComponent)`
  Creates a `TreePath` containing a single element.
  ``
  `TreePath(Object[] path)`
  Creates a `TreePath` from an array.
  `protected`
  `TreePath(Object[] path, int length)`
  Creates a `TreePath` from an array.
  `protected`
  `TreePath(TreePath parent, Object lastPathComponent)`
  Creates a `TreePath` with the specified parent and element.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object o)`
  Compares this `TreePath` to the specified object.
  `Object`
  `getLastPathComponent()`
  Returns the last element of this path.
  `TreePath`
  `getParentPath()`
  Returns the `TreePath` of the parent.
  `Object[]`
  `getPath()`
  Returns an ordered array of the elements of this `TreePath`.
  `Object`
  `getPathComponent(int index)`
  Returns the path element at the specified index.
  `int`
  `getPathCount()`
  Returns the number of elements in the path.
  `int`
  `hashCode()`
  Returns the hash code of this `TreePath`.
  `boolean`
  `isDescendant(TreePath aTreePath)`
  Returns true if `aTreePath` is a descendant of this `TreePath`.
  `TreePath`
  `pathByAddingChild(Object child)`
  Returns a new path containing all the elements of this path plus `child`.
  `String`
  `toString()`
  Returns a string that displays and identifies this object's properties.

  ### Methods declared in class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### TreePath

    @ConstructorProperties("path") public TreePath(Object[] path)
    Creates a `TreePath` from an array. The array uniquely identifies the path to a node.
    Parameters:
      `path` - an array of objects representing the path to a node
    Throws:
      `IllegalArgumentException` - if `path` is `null`, empty, or contains a `null` value

  - ### TreePath

    public TreePath(Object lastPathComponent)
    Creates a `TreePath` containing a single element. This is used to construct a `TreePath` identifying the root.
    Parameters:
      `lastPathComponent` - the root
    Throws:
      `IllegalArgumentException` - if `lastPathComponent` is `null`
    See Also:
      - `TreePath(Object[])`

  - ### TreePath

    protected TreePath(TreePath parent, Object lastPathComponent)
    Creates a `TreePath` with the specified parent and element.
    Parameters:
      `parent` - the path to the parent, or `null` to indicate the root
      `lastPathComponent` - the last path element
    Throws:
      `IllegalArgumentException` - if `lastPathComponent` is `null`

  - ### TreePath

    protected TreePath(Object[] path, int length)
    Creates a `TreePath` from an array. The returned `TreePath` represents the elements of the array from `0` to `length - 1`.

    This constructor is used internally, and generally not useful outside of subclasses.

    Parameters:
      `path` - the array to create the `TreePath` from
      `length` - identifies the number of elements in `path` to create the `TreePath` from
    Throws:
      `NullPointerException` - if `path` is `null`
      `ArrayIndexOutOfBoundsException` - if `length - 1` is outside the range of the array
      `IllegalArgumentException` - if any of the elements from `0` to `length - 1` are `null`

  - ### TreePath

    protected TreePath()
    Creates an empty `TreePath`. This is provided for subclasses that represent paths in a different manner. Subclasses that use this constructor must override `getLastPathComponent`, and `getParentPath`.

- ## Method Details

  - ### getPath

    public Object[] getPath()
    Returns an ordered array of the elements of this `TreePath`. The first element is the root.
    Returns:
      an array of the elements in this `TreePath`

  - ### getLastPathComponent

    public Object getLastPathComponent()
    Returns the last element of this path.
    Returns:
      the last element in the path

  - ### getPathCount

    public int getPathCount()
    Returns the number of elements in the path.
    Returns:
      the number of elements in the path

  - ### getPathComponent

    public Object getPathComponent(int index)
    Returns the path element at the specified index.
    Parameters:
      `index` - the index of the element requested
    Returns:
      the element at the specified index
    Throws:
      `IllegalArgumentException` - if the index is outside the range of this path

  - ### equals

    public boolean equals(Object o)
    Compares this `TreePath` to the specified object. This returns `true` if `o` is a `TreePath` with the exact same elements (as determined by using `equals` on each element of the path).
    Overrides:
      `equals` in class `Object`
    Parameters:
      `o` - the object to compare
    Returns:
      `true` if this object is the same as the obj argument; `false` otherwise.
    See Also:
      - `Object.hashCode()`
      - `HashMap`

  - ### hashCode

    public int hashCode()
    Returns the hash code of this `TreePath`. The hash code of a `TreePath` is the hash code of the last element in the path.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      the hashCode for the object
    See Also:
      - `Object.equals(java.lang.Object)`
      - `System.identityHashCode(java.lang.Object)`

  - ### isDescendant

    public boolean isDescendant(TreePath aTreePath)
    Returns true if `aTreePath` is a descendant of this `TreePath`. A `TreePath` `P1` is a descendant of a `TreePath` `P2` if `P1` contains all of the elements that make up `P2's` path. For example, if this object has the path `[a, b]`, and `aTreePath` has the path `[a, b, c]`, then `aTreePath` is a descendant of this object. However, if `aTreePath` has the path `[a]`, then it is not a descendant of this object. By this definition a `TreePath` is always considered a descendant of itself. That is, `aTreePath.isDescendant(aTreePath)` returns `true`.
    Parameters:
      `aTreePath` - the `TreePath` to check
    Returns:
      true if `aTreePath` is a descendant of this path

  - ### pathByAddingChild

    public TreePath pathByAddingChild(Object child)
    Returns a new path containing all the elements of this path plus `child`. `child` is the last element of the newly created `TreePath`.
    Parameters:
      `child` - the path element to add
    Returns:
      a new path containing all the elements of this path plus `child`
    Throws:
      `NullPointerException` - if `child` is `null`

  - ### getParentPath

    public TreePath getParentPath()
    Returns the `TreePath` of the parent. A return value of `null` indicates this is the root node.
    Returns:
      the parent path

  - ### toString

    public String toString()
    Returns a string that displays and identifies this object's properties.
    Overrides:
      `toString` in class `Object`
    Returns:
      a String representation of this object