gomp-20050608-branch/libjava/classpath/javax/swing/tree/TreePath.java

   1 /* TreePath.java --
   2    Copyright (C) 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.swing.tree;
  40
  41 import java.io.Serializable;
  42 import java.util.Arrays;
  43
  44 /**
  45  * A <code>TreePath</code> represents a sequence of tree elements that form
  46  * a path starting from the root of a tree.  A tree element can be represented
  47  * by any {@link Object}.
  48  *
  49  * @author Andrew Selkirk
  50  */
  51 public class TreePath implements Serializable
  52 {
  53   static final long serialVersionUID = 4380036194768077479L;
  54
  55   /**
  56    * path
  57    */
  58   private Object[] path = null;
  59
  60
  61   /**
  62    * Creates a path from the list of objects representing tree elements.  The
  63    * incoming array is copied so that subsequent changes do not affect this
  64    * tree path.
  65    *
  66    * @param path  the elements in the path (<code>null</code> not permitted).
  67    *
  68    * @throws IllegalArgumentException if <code>path</code> is <code>null</code>.
  69    */
  70   public TreePath(Object[] path)
  71   {
  72     if (path == null)
  73       throw new IllegalArgumentException("Null 'path' not permitted.");
  74     this.path = new Object[path.length];
  75     System.arraycopy(path, 0, this.path, 0, path.length);
  76   }
  77
  78   /**
  79    * Creates a new path from a single element.
  80    *
  81    * @param element the element (<code>null</code> not permitted).
  82    *
  83    * @throws IllegalArgumentException if <code>element</code> is
  84    *         <code>null</code>.
  85    */
  86   public TreePath(Object element)
  87   {
  88     path = new Object[1];
  89     path[0] = element;
  90   }
  91
  92   /**
  93    * Creates a new tree path by adding the specified <code>element</code> to
  94    * the <code>path</code>.
  95    *
  96    * @param path  a tree path.
  97    * @param element  a path element.
  98    */
  99   protected TreePath(TreePath path, Object element)
 100   {
 101     if (element == null)
 102       throw new NullPointerException("Null 'element' argument.");
 103     Object[] treepath = path.getPath();
 104
 105     // Create Tree Path
 106     this.path = new Object[treepath.length + 1];
 107     System.arraycopy(treepath, 0, this.path, 0, treepath.length);
 108     this.path[treepath.length] = element;
 109   }
 110
 111   /**
 112    * Creates a new tree path using the first <code>length</code> elements
 113    * from the given array.
 114    *
 115    * @param path  the path elements.
 116    * @param length  the path length.
 117    */
 118   protected TreePath(Object[] path, int length)
 119   {
 120     // Create Path
 121     this.path = new Object[length];
 122     System.arraycopy(path, 0, this.path, 0, length);
 123   }
 124
 125   /**
 126    * Default constructor.
 127    */
 128   protected TreePath()
 129   {
 130     path = new Object[0];
 131   }
 132
 133
 134   /**
 135    * Returns a hashcode for the path.
 136    *
 137    * @return A hashcode.
 138    */
 139   public int hashCode()
 140   {
 141     return getLastPathComponent().hashCode();
 142   }
 143
 144   /**
 145    * Tests this path for equality with an arbitrary object.  An object is
 146    * considered equal to this path if and only if:
 147    * <ul>
 148    * <li>the object is not <code>null</code>;</li>
 149    * <li>the object is an instanceof {@link TreePath};</li>
 150    * <li>the object contains the same elements in the same order as this
 151    * {@link TreePath};</li>
 152    * </ul>
 153    *
 154    * @param object  the object (<code>null</code> permitted).
 155    *
 156    * @returns <code>true</code> if <code>obj</code> is equal to this tree path,
 157    *          and <code>false</code> otherwise.
 158    */
 159   public boolean equals(Object object)
 160   {
 161     Object[] treepath;
 162     int index;
 163
 164     if (object instanceof TreePath)
 165       {
 166         treepath = ((TreePath) object).getPath();
 167         if (treepath.length != path.length)
 168           return false;
 169         for (index = 0; index < path.length; index++)
 170           {
 171             if (!treepath[index].equals(path[index]))
 172               return false;
 173           }
 174
 175         // Tree Path's are equals
 176         return true;
 177       }
 178
 179     // Unequal
 180     return false;
 181   }
 182
 183   /**
 184    * Returns a string representation of this path.
 185    *
 186    * @return A string representation of this path.
 187    */
 188   public String toString()
 189   {
 190     if (path.length == 1)
 191       return String.valueOf(path[0]);
 192     else
 193       return Arrays.asList(path).toString();
 194   }
 195
 196   /**
 197    * Returns an array containing the path elements.
 198    *
 199    * @returns An array containing the path elements.
 200    */
 201   public Object[] getPath()
 202   {
 203     return (Object[]) path.clone();
 204   }
 205
 206   /**
 207    * Returns the last object in the path.
 208    *
 209    * @return The last object in the path.
 210    */
 211   public Object getLastPathComponent()
 212   {
 213     return path[path.length - 1];
 214   }
 215
 216   /**
 217    * Returns the number of elements in the path.
 218    *
 219    * @returns The number of elements in the path.
 220    */
 221   public int getPathCount()
 222   {
 223     return path.length;
 224   }
 225
 226   /**
 227    * Returns the element at the specified position in the path.
 228    *
 229    * @param position the element position (<code>0 &lt N - 1</code>, where
 230    *                 <code>N</code> is the number of elements in the path).
 231    *
 232    * @return The element at the specified position.
 233    *
 234    * @throws IllegalArgumentException if <code>position</code> is outside the
 235    *         valid range.
 236    */
 237   public Object getPathComponent(int position)
 238   {
 239     if (position < 0 || position >= getPathCount())
 240       throw new IllegalArgumentException("Invalid position: " + position);
 241     return path[position];
 242   }
 243
 244   /**
 245    * Returns <code>true</code> if <code>path</code> is a descendant of this
 246    * path, and <code>false</code> otherwise.  If <code>path</code> is
 247    * <code>null</code>, this method returns <code>false</code>.
 248    *
 249    * @param path  the path to check (<code>null</code> permitted).
 250    *
 251    * @returns <code>true</code> if <code>path</code> is a descendant of this
 252    *          path, and <code>false</code> otherwise
 253    */
 254   public boolean isDescendant(TreePath path)
 255   {
 256     if (path == null)
 257       return false;
 258     int count = getPathCount();
 259     if (path.getPathCount() < count)
 260       return false;
 261     for (int i = 0; i < count; i++)
 262     {
 263       if (!this.path[i].equals(path.getPathComponent(i)))
 264         return false;
 265     }
 266     return true;
 267   }
 268
 269   /**
 270    * Creates a new path that is equivalent to this path plus the specified
 271    * element.
 272    *
 273    * @param element  the element.
 274    *
 275    * @returns A tree path.
 276    */
 277   public TreePath pathByAddingChild(Object element)
 278   {
 279     return new TreePath(this, element);
 280   }
 281
 282   /**
 283    * Returns the parent path, which is a path containing all the same elements
 284    * as this path, except for the last one.  If this path contains only one
 285    * element, the method returns <code>null</code>.
 286    *
 287    * @returns The parent path, or <code>null</code> if this path has only one
 288    *          element.
 289    */
 290   public TreePath getParentPath()
 291   {
 292     // If this path has only one element, then we return null. That
 293     // is what the JDK does.
 294     if (path.length <= 1)
 295       return null;
 296
 297     return new TreePath(this.getPath(), path.length - 1);
 298   }
 299 }