001    /* TreePath.java --
002       Copyright (C) 2002, 2005, 2006,  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.swing.tree;
040    
041    import java.io.Serializable;
042    import 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     */
051    public 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    }