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