TreePath


1   /*
2    * @(#)TreePath.java    1.29 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.swing.tree;
9   
10  import java.io.*;
11  import java.util.Vector  ;
12  
13  /**
14   * Represents a path to a node. A TreePath is an array of Objects that are
15   * vended from a TreeModel. The elements of the array are ordered such
16   * that the root is always the first element (index 0) of the array.
17   * TreePath is Serializable, but if any 
18   * components of the path are not serializable, it will not be written 
19   * out.
20   * <p>
21   * For further information and examples of using tree paths,
22   * see <a
23   href="http://java.sun.com/docs/books/tutorial/uiswing/components/tree.html">How to Use Trees</a>
24   * in <em>The Java Tutorial.</em>
25   * <p>
26   * <strong>Warning:</strong>
27   * Serialized objects of this class will not be compatible with
28   * future Swing releases. The current serialization support is
29   * appropriate for short term storage or RMI between applications running
30   * the same version of Swing.  As of 1.4, support for long term storage
31   * of all JavaBeans<sup><font size="-2">TM</font></sup>
32   * has been added to the <code>java.beans</code> package.
33   * Please see {@link java.beans.XMLEncoder}.
34   *
35   * @version 1.29 12/19/03
36   * @author Scott Violet
37   * @author Philip Milne
38   */
39  public class TreePath extends Object   implements Serializable {
40      /** Path representing the parent, null if lastPathComponent represents
41       * the root. */
42      private TreePath             parentPath;
43      /** Last path component. */
44      transient private Object     lastPathComponent;
45  
46      /**
47       * Constructs a path from an array of Objects, uniquely identifying 
48       * the path from the root of the tree to a specific node, as returned
49       * by the tree's data model.
50       * <p>
51       * The model is free to return an array of any Objects it needs to 
52       * represent the path. The DefaultTreeModel returns an array of 
53       * TreeNode objects. The first TreeNode in the path is the root of the
54       * tree, the last TreeNode is the node identified by the path.
55       *
56       * @param path  an array of Objects representing the path to a node
57       */
58      public TreePath(Object  [] path) {
59          if(path == null || path.length == 0)
60              throw new IllegalArgumentException  ("path in TreePath must be non null and not empty.");
61      lastPathComponent = path[path.length - 1];
62      if(path.length > 1)
63          parentPath = new TreePath  (path, path.length - 1);
64      }
65  
66      /**
67       * Constructs a TreePath containing only a single element. This is
68       * usually used to construct a TreePath for the the root of the TreeModel.
69       * <p>
70       * @param singlePath  an Object representing the path to a node
71       * @see #TreePath(Object[])
72       */
73      public TreePath(Object   singlePath) {
74          if(singlePath == null)
75              throw new IllegalArgumentException  ("path in TreePath must be non null.");
76      lastPathComponent = singlePath;
77      parentPath = null;
78      }
79  
80      /**
81       * Constructs a new TreePath, which is the path identified by
82       * <code>parent</code> ending in <code>lastElement</code>.
83       */
84      protected TreePath(TreePath   parent, Object   lastElement) {
85      if(lastElement == null)
86              throw new IllegalArgumentException  ("path in TreePath must be non null.");
87      parentPath = parent;
88      lastPathComponent = lastElement;
89      }
90  
91      /**
92       * Constructs a new TreePath with the identified path components of
93       * length <code>length</code>.
94       */
95      protected TreePath(Object  [] path, int length) {
96      lastPathComponent = path[length - 1];
97      if(length > 1)
98          parentPath = new TreePath  (path, length - 1);
99      }
100 
101     /**
102      * Primarily provided for subclasses 
103      * that represent paths in a different manner.
104      * If a subclass uses this constructor, it should also override 
105      * the <code>getPath</code>,
106      * <code>getPathCount</code>, and
107      * <code>getPathComponent</code> methods,
108      * and possibly the <code>equals</code> method.
109      */
110     protected TreePath() {
111     }
112 
113     /**
114      * Returns an ordered array of Objects containing the components of this
115      * TreePath. The first element (index 0) is the root.
116      *
117      * @return an array of Objects representing the TreePath
118      * @see #TreePath(Object[])
119      */
120     public Object  [] getPath() {
121     int            i = getPathCount();
122         Object  []       result = new Object  [i--];
123 
124         for(TreePath   path = this; path != null; path = path.parentPath) {
125             result[i--] = path.lastPathComponent;
126         }
127     return result;
128     }
129 
130     /**
131      * Returns the last component of this path. For a path returned by
132      * DefaultTreeModel this will return an instance of TreeNode.
133      *
134      * @return the Object at the end of the path
135      * @see #TreePath(Object[])
136      */
137     public Object   getLastPathComponent() {
138     return lastPathComponent;
139     }
140 
141     /**
142      * Returns the number of elements in the path.
143      *
144      * @return an int giving a count of items the path
145      */
146     public int getPathCount() {
147         int        result = 0;
148         for(TreePath   path = this; path != null; path = path.parentPath) {
149             result++;
150         }
151     return result;
152     }
153 
154     /**
155      * Returns the path component at the specified index.
156      *
157      * @param element  an int specifying an element in the path, where
158      *                 0 is the first element in the path
159      * @return the Object at that index location
160      * @throws IllegalArgumentException if the index is beyond the length
161      *         of the path
162      * @see #TreePath(Object[])
163      */
164     public Object   getPathComponent(int element) {
165         int          pathLength = getPathCount();
166 
167         if(element < 0 || element >= pathLength)
168             throw new IllegalArgumentException  ("Index " + element + " is out of the specified range");
169 
170         TreePath           path = this;
171 
172         for(int i = pathLength-1; i != element; i--) {
173            path = path.parentPath;
174         }
175     return path.lastPathComponent;
176     }
177 
178     /**
179      * Tests two TreePaths for equality by checking each element of the
180      * paths for equality. Two paths are considered equal if they are of
181      * the same length, and contain
182      * the same elements (<code>.equals</code>).
183      *
184      * @param o the Object to compare
185      */
186     public boolean equals(Object   o) {
187     if(o == this)
188         return true;
189         if(o instanceof TreePath  ) {
190             TreePath              oTreePath = (TreePath  )o;
191 
192         if(getPathCount() != oTreePath.getPathCount())
193         return false;
194         for(TreePath   path = this; path != null; path = path.parentPath) {
195         if (!(path.lastPathComponent.equals
196               (oTreePath.lastPathComponent))) {
197             return false;
198         }
199         oTreePath = oTreePath.parentPath;
200         }
201         return true;
202         }
203         return false;
204     }
205 
206     /**
207      * Returns the hashCode for the object. The hash code of a TreePath
208      * is defined to be the hash code of the last component in the path.
209      *
210      * @return the hashCode for the object
211      */
212     public int hashCode() { 
213     return lastPathComponent.hashCode();
214     }
215 
216     /**
217      * Returns true if <code>aTreePath</code> is a
218      * descendant of this
219      * TreePath. A TreePath P1 is a descendent of a TreePath P2
220      * if P1 contains all of the components that make up 
221      * P2's path.
222      * For example, if this object has the path [a, b],
223      * and <code>aTreePath</code> has the path [a, b, c], 
224      * then <code>aTreePath</code> is a descendant of this object.
225      * However, if <code>aTreePath</code> has the path [a],
226      * then it is not a descendant of this object.
227      *
228      * @return true if <code>aTreePath</code> is a descendant of this path
229      */
230     public boolean isDescendant(TreePath   aTreePath) {
231     if(aTreePath == this)
232         return true;
233 
234         if(aTreePath != null) {
235             int                 pathLength = getPathCount();
236         int                 oPathLength = aTreePath.getPathCount();
237 
238         if(oPathLength < pathLength)
239         // Can't be a descendant, has fewer components in the path.
240         return false;
241         while(oPathLength-- > pathLength)
242         aTreePath = aTreePath.getParentPath();
243         return equals(aTreePath);
244         }
245         return false;
246     }
247 
248     /**
249      * Returns a new path containing all the elements of this object
250      * plus <code>child</code>. <code>child</code> will be the last element
251      * of the newly created TreePath.
252      * This will throw a NullPointerException
253      * if child is null.
254      */
255     public TreePath   pathByAddingChild(Object   child) {
256     if(child == null)
257         throw new NullPointerException  ("Null child not allowed");
258 
259     return new TreePath  (this, child);
260     }
261 
262     /**
263      * Returns a path containing all the elements of this object, except
264      * the last path component.
265      */
266     public TreePath   getParentPath() {
267     return parentPath;
268     }
269 
270     /**
271      * Returns a string that displays and identifies this
272      * object's properties.
273      *
274      * @return a String representation of this object
275      */
276     public String   toString() {
277         StringBuffer   tempSpot = new StringBuffer  ("[");
278 
279         for(int counter = 0, maxCounter = getPathCount();counter < maxCounter;
280         counter++) {
281             if(counter > 0)
282                 tempSpot.append(", ");
283             tempSpot.append(getPathComponent(counter));
284         }
285         tempSpot.append("]");
286         return tempSpot.toString();
287     }
288 
289     // Serialization support.  
290     private void writeObject(ObjectOutputStream s) throws IOException {
291         s.defaultWriteObject();
292 
293         Vector        values = new Vector  ();
294         boolean     writePath = true;
295 
296     if(lastPathComponent != null &&
297        (lastPathComponent instanceof Serializable)) {
298             values.addElement("lastPathComponent");
299             values.addElement(lastPathComponent);
300         }
301         s.writeObject(values);
302     }
303 
304     private void readObject(ObjectInputStream s) 
305         throws IOException, ClassNotFoundException   {
306         s.defaultReadObject();
307 
308         Vector            values = (Vector  )s.readObject();
309         int             indexCounter = 0;
310         int             maxCounter = values.size();
311 
312         if(indexCounter < maxCounter && values.elementAt(indexCounter).
313            equals("lastPathComponent")) {
314             lastPathComponent = values.elementAt(++indexCounter);
315             indexCounter++;
316         }
317     }
318 }
319
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags