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 and 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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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 inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### TreePath

          @ConstructorProperties(value="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 Detail

    - #### 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
      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

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2016, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.