KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > swing > tree > 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 JavaDoc;
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 JavaDoc implements Serializable {
40     /** Path representing the parent, null if lastPathComponent represents
41      * the root. */

42     private TreePath JavaDoc parentPath;
43     /** Last path component. */
44     transient private Object JavaDoc 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 JavaDoc[] path) {
59         if(path == null || path.length == 0)
60             throw new IllegalArgumentException JavaDoc("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 JavaDoc(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 JavaDoc singlePath) {
74         if(singlePath == null)
75             throw new IllegalArgumentException JavaDoc("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 JavaDoc parent, Object JavaDoc lastElement) {
85     if(lastElement == null)
86             throw new IllegalArgumentException JavaDoc("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 JavaDoc[] path, int length) {
96     lastPathComponent = path[length - 1];
97     if(length > 1)
98         parentPath = new TreePath JavaDoc(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 JavaDoc[] getPath() {
121     int i = getPathCount();
122         Object JavaDoc[] result = new Object JavaDoc[i--];
123
124         for(TreePath JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getPathComponent(int element) {
165         int pathLength = getPathCount();
166
167         if(element < 0 || element >= pathLength)
168             throw new IllegalArgumentException JavaDoc("Index " + element + " is out of the specified range");
169
170         TreePath JavaDoc 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 JavaDoc o) {
187     if(o == this)
188         return true;
189         if(o instanceof TreePath JavaDoc) {
190             TreePath JavaDoc oTreePath = (TreePath JavaDoc)o;
191
192         if(getPathCount() != oTreePath.getPathCount())
193         return false;
194         for(TreePath JavaDoc 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 JavaDoc 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 JavaDoc pathByAddingChild(Object JavaDoc child) {
256     if(child == null)
257         throw new NullPointerException JavaDoc("Null child not allowed");
258
259     return new TreePath JavaDoc(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 JavaDoc 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 JavaDoc toString() {
277         StringBuffer JavaDoc tempSpot = new StringBuffer JavaDoc("[");
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 JavaDoc values = new Vector JavaDoc();
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 JavaDoc {
306         s.defaultReadObject();
307
308         Vector JavaDoc values = (Vector JavaDoc)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
Popular Tags