Source for javax.swing.tree.TreePath

   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: }