001/* TreePath.java --
002   Copyright (C) 2002, 2005, 2006,  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.swing.tree;
040
041import java.io.Serializable;
042import java.util.Arrays;
043
044/**
045 * A <code>TreePath</code> represents a sequence of tree elements that form
046 * a path starting from the root of a tree.  A tree element can be represented
047 * by any {@link Object}.
048 * 
049 * @author Andrew Selkirk
050 */
051public class TreePath implements Serializable
052{
053  static final long serialVersionUID = 4380036194768077479L;
054
055  /**
056   * The actual patch. The {@link DefaultTreeSelectionModel#clone()}
057   * assumes that the TreePath is immutable, so it is marked final here.
058   */
059  private final Object[] path;
060  
061  /**
062   * The parent path (to be reused).
063   */
064  private transient TreePath parentPath;
065
066
067  /**
068   * Creates a path from the list of objects representing tree elements.  The
069   * incoming array is copied so that subsequent changes do not affect this
070   * tree path.
071   * 
072   * @param path  the elements in the path (<code>null</code> not permitted).
073   * 
074   * @throws IllegalArgumentException if <code>path</code> is <code>null</code>.
075   */
076  public TreePath(Object[] path)
077  {
078    if (path == null)
079      throw new IllegalArgumentException("Null 'path' not permitted.");
080    this.path = new Object[path.length];
081    System.arraycopy(path, 0, this.path, 0, path.length);
082  }
083
084  /**
085   * Creates a new path from a single element.
086   * 
087   * @param element the element (<code>null</code> not permitted).
088   * 
089   * @throws IllegalArgumentException if <code>element</code> is 
090   *         <code>null</code>.
091   */
092  public TreePath(Object element)
093  {
094    path = new Object[1];
095    path[0] = element;
096  }
097
098  /**
099   * Creates a new tree path by adding the specified <code>element</code> to
100   * the <code>path</code>.
101   * 
102   * @param path  a tree path.
103   * @param element  a path element.
104   */
105  protected TreePath(TreePath path, Object element)
106  {
107    if (element == null)
108      throw new NullPointerException("Null 'element' argument.");
109    Object[] treepath = path.getPath();
110
111    // Create Tree Path
112    this.path = new Object[treepath.length + 1];
113    System.arraycopy(treepath, 0, this.path, 0, treepath.length);
114    this.path[treepath.length] = element;
115  }
116
117  /**
118   * Creates a new tree path using the first <code>length</code> elements
119   * from the given array.
120   * 
121   * @param path  the path elements.
122   * @param length  the path length.
123   */
124  protected TreePath(Object[] path, int length)
125  {
126    // Create Path
127    this.path = new Object[length];
128    System.arraycopy(path, 0, this.path, 0, length);
129  }
130
131  /**
132   * Default constructor.
133   */
134  protected TreePath()
135  {
136    path = new Object[0];
137  }
138
139
140  /**
141   * Returns a hashcode for the path.
142   * 
143   * @return A hashcode.
144   */
145  public int hashCode()
146  {
147    return getLastPathComponent().hashCode();
148  }
149
150  /**
151   * Tests this path for equality with an arbitrary object.  An object is 
152   * considered equal to this path if and only if:
153   * <ul>
154   * <li>the object is not <code>null</code>;</li>
155   * <li>the object is an instanceof {@link TreePath};</li>
156   * <li>the object contains the same elements in the same order as this
157   * {@link TreePath};</li>
158   * </ul>
159   * 
160   * @param object  the object (<code>null</code> permitted).
161   * 
162   * @return <code>true</code> if <code>obj</code> is equal to this tree path,
163   *         and <code>false</code> otherwise.
164   */
165  public boolean equals(Object object)
166  {
167    Object[] treepath;
168    int index;
169
170    if (object instanceof TreePath)
171      {
172        treepath = ((TreePath) object).getPath();
173        if (treepath.length != path.length)
174          return false;
175        for (index = 0; index < path.length; index++)
176          {
177            if (!path[index].equals(treepath[index]))
178              return false;
179          }
180
181        // Tree Path's are equals
182        return true;
183      }
184
185    // Unequal
186    return false;
187  }
188
189  /**
190   * Returns a string representation of this path.
191   * 
192   * @return A string representation of this path.
193   */
194  public String toString()
195  {
196    if (path.length == 1)
197      return String.valueOf(path[0]);
198    else
199      return Arrays.asList(path).toString();
200  }
201
202  /**
203   * Returns an array containing the path elements.
204   * 
205   * @return An array containing the path elements.
206   */
207  public Object[] getPath()
208  {
209    return (Object[]) path.clone();
210  }
211
212  /**
213   * Returns the last object in the path.
214   * 
215   * @return The last object in the path.
216   */
217  public Object getLastPathComponent()
218  {
219    return path[path.length - 1];
220  }
221
222  /**
223   * Returns the number of elements in the path.
224   * 
225   * @return The number of elements in the path.
226   */
227  public int getPathCount()
228  {
229    return path.length;
230  }
231
232  /**
233   * Returns the element at the specified position in the path.
234   * 
235   * @param position the element position (<code>0 &lt N - 1</code>, where 
236   *                 <code>N</code> is the number of elements in the path).
237   * 
238   * @return The element at the specified position.
239   * 
240   * @throws IllegalArgumentException if <code>position</code> is outside the
241   *         valid range.
242   */
243  public Object getPathComponent(int position)
244  {
245    if (position < 0 || position >= getPathCount()) 
246      throw new IllegalArgumentException("Invalid position: " + position);
247    return path[position];
248  }
249
250  /**
251   * Returns <code>true</code> if <code>path</code> is a descendant of this
252   * path, and <code>false</code> otherwise.  If <code>path</code> is 
253   * <code>null</code>, this method returns <code>false</code>.
254   * 
255   * @param path  the path to check (<code>null</code> permitted).
256   * 
257   * @return <code>true</code> if <code>path</code> is a descendant of this
258   *         path, and <code>false</code> otherwise
259   */
260  public boolean isDescendant(TreePath path)
261  {
262    if (path == null)
263      return false;
264    int count = getPathCount();
265    int otherPathLength = path.getPathCount();
266    if (otherPathLength < count)
267      return false;
268    while (otherPathLength > count)
269      {
270        otherPathLength--;
271        path = path.getParentPath();
272      }
273    
274    return equals(path);
275  }
276
277  /**
278   * Creates a new path that is equivalent to this path plus the specified
279   * element.
280   * 
281   * @param element  the element.
282   * 
283   * @return A tree path.
284   */
285  public TreePath pathByAddingChild(Object element)
286  {
287    return new TreePath(this, element);
288  }
289
290  /**
291   * Returns the parent path, which is a path containing all the same elements
292   * as this path, except for the last one.  If this path contains only one
293   * element, the method returns <code>null</code>.
294   * 
295   * @return The parent path, or <code>null</code> if this path has only one
296   *         element.
297   */
298  public TreePath getParentPath()
299  {
300    // If this path has only one element, then we return null. That
301    // is what the JDK does.
302    if (path.length <= 1)
303      return null;
304    
305    // Reuse the parent path, if possible. The parent path is requested
306    // during the tree repainting, so reusing generates a lot less garbage.
307    if (parentPath == null)
308      parentPath = new TreePath(this.getPath(), path.length - 1);
309    
310    return parentPath;
311  }
312}