Showing the changes to java/pkg/javax/swing/tree/TreePath.java (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,360 @@ | |||
| 1 | /* | ||
| 2 | * Copyright (c) 1997, 2007, Oracle and/or its affiliates. All rights reserved. | ||
| 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | ||
| 4 | * | ||
| 5 | * This code is free software; you can redistribute it and/or modify it | ||
| 6 | * under the terms of the GNU General Public License version 2 only, as | ||
| 7 | * published by the Free Software Foundation. Oracle designates this | ||
| 8 | * particular file as subject to the "Classpath" exception as provided | ||
| 9 | * by Oracle in the LICENSE file that accompanied this code. | ||
| 10 | * | ||
| 11 | * This code is distributed in the hope that it will be useful, but WITHOUT | ||
| 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | ||
| 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | ||
| 14 | * version 2 for more details (a copy is included in the LICENSE file that | ||
| 15 | * accompanied this code). | ||
| 16 | * | ||
| 17 | * You should have received a copy of the GNU General Public License version | ||
| 18 | * 2 along with this work; if not, write to the Free Software Foundation, | ||
| 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | ||
| 20 | * | ||
| 21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | ||
| 22 | * or visit www.oracle.com if you need additional information or have any | ||
| 23 | * questions. | ||
| 24 | */ | ||
| 25 | |||
| 26 | package javax.swing.tree; | ||
| 27 | |||
| 28 | import java.io.*; | ||
| 29 | import java.beans.ConstructorProperties; | ||
| 30 | |||
| 31 | /** | ||
| 32 | * {@code TreePath} represents an array of objects that uniquely | ||
| 33 | * identify the path to a node in a tree. The elements of the array | ||
| 34 | * are ordered with the root as the first element of the array. For | ||
| 35 | * example, a file on the file system is uniquely identified based on | ||
| 36 | * the array of parent directories and the name of the file. The path | ||
| 37 | * {@code /tmp/foo/bar} could be represented by a {@code TreePath} as | ||
| 38 | * {@code new TreePath(new Object[] {"tmp", "foo", "bar"})}. | ||
| 39 | * <p> | ||
| 40 | * {@code TreePath} is used extensively by {@code JTree} and related classes. | ||
| 41 | * For example, {@code JTree} represents the selection as an array of | ||
| 42 | * {@code TreePath}s. When used with {@code JTree}, the elements of the | ||
| 43 | * path are the objects returned from the {@code TreeModel}. When {@code JTree} | ||
| 44 | * is paired with {@code DefaultTreeModel}, the elements of the | ||
| 45 | * path are {@code TreeNode}s. The following example illustrates extracting | ||
| 46 | * the user object from the selection of a {@code JTree}: | ||
| 47 | * <pre> | ||
| 48 | * DefaultMutableTreeNode root = ...; | ||
| 49 | * DefaultTreeModel model = new DefaultTreeModel(root); | ||
| 50 | * JTree tree = new JTree(model); | ||
| 51 | * ... | ||
| 52 | * TreePath selectedPath = tree.getSelectionPath(); | ||
| 53 | * DefaultMutableTreeNode selectedNode = | ||
| 54 | * ((DefaultMutableTreeNode)selectedPath.getLastPathComponent()). | ||
| 55 | * getUserObject(); | ||
| 56 | * </pre> | ||
| 57 | * Subclasses typically need override only {@code | ||
| 58 | * getLastPathComponent}, and {@code getParentPath}. As {@code JTree} | ||
| 59 | * internally creates {@code TreePath}s at various points, it's | ||
| 60 | * generally not useful to subclass {@code TreePath} and use with | ||
| 61 | * {@code JTree}. | ||
| 62 | * <p> | ||
| 63 | * While {@code TreePath} is serializable, a {@code | ||
| 64 | * NotSerializableException} is thrown if any elements of the path are | ||
| 65 | * not serializable. | ||
| 66 | * <p> | ||
| 67 | * For further information and examples of using tree paths, | ||
| 68 | * see <a | ||
| 69 | href="http://java.sun.com/docs/books/tutorial/uiswing/components/tree.html">How to Use Trees</a> | ||
| 70 | * in <em>The Java Tutorial.</em> | ||
| 71 | * <p> | ||
| 72 | * <strong>Warning:</strong> | ||
| 73 | * Serialized objects of this class will not be compatible with | ||
| 74 | * future Swing releases. The current serialization support is | ||
| 75 | * appropriate for short term storage or RMI between applications running | ||
| 76 | * the same version of Swing. As of 1.4, support for long term storage | ||
| 77 | * of all JavaBeans<sup><font size="-2">TM</font></sup> | ||
| 78 | * has been added to the <code>java.beans</code> package. | ||
| 79 | * Please see {@link java.beans.XMLEncoder}. | ||
| 80 | * | ||
| 81 | * @author Scott Violet | ||
| 82 | * @author Philip Milne | ||
| 83 | */ | ||
| 84 | public class TreePath extends Object implements Serializable { | ||
| 85 | /** Path representing the parent, null if lastPathComponent represents | ||
| 86 | * the root. */ | ||
| 87 | private TreePath parentPath; | ||
| 88 | /** Last path component. */ | ||
| 89 | private Object lastPathComponent; | ||
| 90 | |||
| 91 | /** | ||
| 92 | * Creates a {@code TreePath} from an array. The array uniquely | ||
| 93 | * identifies the path to a node. | ||
| 94 | * | ||
| 95 | * @param path an array of objects representing the path to a node | ||
| 96 | * @throws IllegalArgumentException if {@code path} is {@code null}, | ||
| 97 | * empty, or contains a {@code null} value | ||
| 98 | */ | ||
| 99 | @ConstructorProperties({"path"}) | ||
| 100 | public TreePath(Object[] path) { | ||
| 101 | if(path == null || path.length == 0) | ||
| 102 | throw new IllegalArgumentException("path in TreePath must be non null and not empty."); | ||
| 103 | lastPathComponent = path[path.length - 1]; | ||
| 104 | if (lastPathComponent == null) { | ||
| 105 | throw new IllegalArgumentException( | ||
| 106 | "Last path component must be non-null"); | ||
| 107 | } | ||
| 108 | if(path.length > 1) | ||
| 109 | parentPath = new TreePath(path, path.length - 1); | ||
| 110 | } | ||
| 111 | |||
| 112 | /** | ||
| 113 | * Creates a {@code TreePath} containing a single element. This is | ||
| 114 | * used to construct a {@code TreePath} identifying the root. | ||
| 115 | * | ||
| 116 | * @param lastPathComponent the root | ||
| 117 | * @see #TreePath(Object[]) | ||
| 118 | * @throws IllegalArgumentException if {@code lastPathComponent} is | ||
| 119 | * {@code null} | ||
| 120 | */ | ||
| 121 | public TreePath(Object lastPathComponent) { | ||
| 122 | if(lastPathComponent == null) | ||
| 123 | throw new IllegalArgumentException("path in TreePath must be non null."); | ||
| 124 | this.lastPathComponent = lastPathComponent; | ||
| 125 | parentPath = null; | ||
| 126 | } | ||
| 127 | |||
| 128 | /** | ||
| 129 | * Creates a {@code TreePath} with the specified parent and element. | ||
| 130 | * | ||
| 131 | * @param parent the path to the parent, or {@code null} to indicate | ||
| 132 | * the root | ||
| 133 | * @param lastPathComponent the last path element | ||
| 134 | * @throws IllegalArgumentException if {@code lastPathComponent} is | ||
| 135 | * {@code null} | ||
| 136 | */ | ||
| 137 | protected TreePath(TreePath parent, Object lastPathComponent) { | ||
| 138 | if(lastPathComponent == null) | ||
| 139 | throw new IllegalArgumentException("path in TreePath must be non null."); | ||
| 140 | parentPath = parent; | ||
| 141 | this.lastPathComponent = lastPathComponent; | ||
| 142 | } | ||
| 143 | |||
| 144 | /** | ||
| 145 | * Creates a {@code TreePath} from an array. The returned | ||
| 146 | * {@code TreePath} represents the elements of the array from | ||
| 147 | * {@code 0} to {@code length - 1}. | ||
| 148 | * <p> | ||
| 149 | * This constructor is used internally, and generally not useful outside | ||
| 150 | * of subclasses. | ||
| 151 | * | ||
| 152 | * @param path the array to create the {@code TreePath} from | ||
| 153 | * @param length identifies the number of elements in {@code path} to | ||
| 154 | * create the {@code TreePath} from | ||
| 155 | * @throws NullPointerException if {@code path} is {@code null} | ||
| 156 | * @throws ArrayIndexOutOfBoundsException if {@code length - 1} is | ||
| 157 | * outside the range of the array | ||
| 158 | * @throws IllegalArgumentException if any of the elements from | ||
| 159 | * {@code 0} to {@code length - 1} are {@code null} | ||
| 160 | */ | ||
| 161 | protected TreePath(Object[] path, int length) { | ||
| 162 | lastPathComponent = path[length - 1]; | ||
| 163 | if (lastPathComponent == null) { | ||
| 164 | throw new IllegalArgumentException( | ||
| 165 | "Path elements must be non-null"); | ||
| 166 | } | ||
| 167 | if(length > 1) | ||
| 168 | parentPath = new TreePath(path, length - 1); | ||
| 169 | } | ||
| 170 | |||
| 171 | /** | ||
| 172 | * Creates an empty {@code TreePath}. This is provided for | ||
| 173 | * subclasses that represent paths in a different | ||
| 174 | * manner. Subclasses that use this constructor must override | ||
| 175 | * {@code getLastPathComponent}, and {@code getParentPath}. | ||
| 176 | */ | ||
| 177 | protected TreePath() { | ||
| 178 | } | ||
| 179 | |||
| 180 | /** | ||
| 181 | * Returns an ordered array of the elements of this {@code TreePath}. | ||
| 182 | * The first element is the root. | ||
| 183 | * | ||
| 184 | * @return an array of the elements in this {@code TreePath} | ||
| 185 | */ | ||
| 186 | public Object[] getPath() { | ||
| 187 | int i = getPathCount(); | ||
| 188 | Object[] result = new Object[i--]; | ||
| 189 | |||
| 190 | for(TreePath path = this; path != null; path = path.getParentPath()) { | ||
| 191 | result[i--] = path.getLastPathComponent(); | ||
| 192 | } | ||
| 193 | return result; | ||
| 194 | } | ||
| 195 | |||
| 196 | /** | ||
| 197 | * Returns the last element of this path. | ||
| 198 | * | ||
| 199 | * @return the last element in the path | ||
| 200 | */ | ||
| 201 | public Object getLastPathComponent() { | ||
| 202 | return lastPathComponent; | ||
| 203 | } | ||
| 204 | |||
| 205 | /** | ||
| 206 | * Returns the number of elements in the path. | ||
| 207 | * | ||
| 208 | * @return the number of elements in the path | ||
| 209 | */ | ||
| 210 | public int getPathCount() { | ||
| 211 | int result = 0; | ||
| 212 | for(TreePath path = this; path != null; path = path.getParentPath()) { | ||
| 213 | result++; | ||
| 214 | } | ||
| 215 | return result; | ||
| 216 | } | ||
| 217 | |||
| 218 | /** | ||
| 219 | * Returns the path element at the specified index. | ||
| 220 | * | ||
| 221 | * @param index the index of the element requested | ||
| 222 | * @return the element at the specified index | ||
| 223 | * @throws IllegalArgumentException if the index is outside the | ||
| 224 | * range of this path | ||
| 225 | */ | ||
| 226 | public Object getPathComponent(int index) { | ||
| 227 | int pathLength = getPathCount(); | ||
| 228 | |||
| 229 | if(index < 0 || index >= pathLength) | ||
| 230 | throw new IllegalArgumentException("Index " + index + | ||
| 231 | " is out of the specified range"); | ||
| 232 | |||
| 233 | TreePath path = this; | ||
| 234 | |||
| 235 | for(int i = pathLength-1; i != index; i--) { | ||
| 236 | path = path.getParentPath(); | ||
| 237 | } | ||
| 238 | return path.getLastPathComponent(); | ||
| 239 | } | ||
| 240 | |||
| 241 | /** | ||
| 242 | * Compares this {@code TreePath} to the specified object. This returns | ||
| 243 | * {@code true} if {@code o} is a {@code TreePath} with the exact | ||
| 244 | * same elements (as determined by using {@code equals} on each | ||
| 245 | * element of the path). | ||
| 246 | * | ||
| 247 | * @param o the object to compare | ||
| 248 | */ | ||
| 249 | public boolean equals(Object o) { | ||
| 250 | if(o == this) | ||
| 251 | return true; | ||
| 252 | if(o instanceof TreePath) { | ||
| 253 | TreePath oTreePath = (TreePath)o; | ||
| 254 | |||
| 255 | if(getPathCount() != oTreePath.getPathCount()) | ||
| 256 | return false; | ||
| 257 | for(TreePath path = this; path != null; | ||
| 258 | path = path.getParentPath()) { | ||
| 259 | if (!(path.getLastPathComponent().equals | ||
| 260 | (oTreePath.getLastPathComponent()))) { | ||
| 261 | return false; | ||
| 262 | } | ||
| 263 | oTreePath = oTreePath.getParentPath(); | ||
| 264 | } | ||
| 265 | return true; | ||
| 266 | } | ||
| 267 | return false; | ||
| 268 | } | ||
| 269 | |||
| 270 | /** | ||
| 271 | * Returns the hash code of this {@code TreePath}. The hash code of a | ||
| 272 | * {@code TreePath} is the hash code of the last element in the path. | ||
| 273 | * | ||
| 274 | * @return the hashCode for the object | ||
| 275 | */ | ||
| 276 | public int hashCode() { | ||
| 277 | return getLastPathComponent().hashCode(); | ||
| 278 | } | ||
| 279 | |||
| 280 | /** | ||
| 281 | * Returns true if <code>aTreePath</code> is a | ||
| 282 | * descendant of this | ||
| 283 | * {@code TreePath}. A {@code TreePath} {@code P1} is a descendant of a | ||
| 284 | * {@code TreePath} {@code P2} | ||
| 285 | * if {@code P1} contains all of the elements that make up | ||
| 286 | * {@code P2's} path. | ||
| 287 | * For example, if this object has the path {@code [a, b]}, | ||
| 288 | * and <code>aTreePath</code> has the path {@code [a, b, c]}, | ||
| 289 | * then <code>aTreePath</code> is a descendant of this object. | ||
| 290 | * However, if <code>aTreePath</code> has the path {@code [a]}, | ||
| 291 | * then it is not a descendant of this object. By this definition | ||
| 292 | * a {@code TreePath} is always considered a descendant of itself. | ||
| 293 | * That is, <code>aTreePath.isDescendant(aTreePath)</code> returns | ||
| 294 | * {@code true}. | ||
| 295 | * | ||
| 296 | * @param aTreePath the {@code TreePath} to check | ||
| 297 | * @return true if <code>aTreePath</code> is a descendant of this path | ||
| 298 | */ | ||
| 299 | public boolean isDescendant(TreePath aTreePath) { | ||
| 300 | if(aTreePath == this) | ||
| 301 | return true; | ||
| 302 | |||
| 303 | if(aTreePath != null) { | ||
| 304 | int pathLength = getPathCount(); | ||
| 305 | int oPathLength = aTreePath.getPathCount(); | ||
| 306 | |||
| 307 | if(oPathLength < pathLength) | ||
| 308 | // Can't be a descendant, has fewer components in the path. | ||
| 309 | return false; | ||
| 310 | while(oPathLength-- > pathLength) | ||
| 311 | aTreePath = aTreePath.getParentPath(); | ||
| 312 | return equals(aTreePath); | ||
| 313 | } | ||
| 314 | return false; | ||
| 315 | } | ||
| 316 | |||
| 317 | /** | ||
| 318 | * Returns a new path containing all the elements of this path | ||
| 319 | * plus <code>child</code>. <code>child</code> is the last element | ||
| 320 | * of the newly created {@code TreePath}. | ||
| 321 | * | ||
| 322 | * @param child the path element to add | ||
| 323 | * @throws NullPointerException if {@code child} is {@code null} | ||
| 324 | */ | ||
| 325 | public TreePath pathByAddingChild(Object child) { | ||
| 326 | if(child == null) | ||
| 327 | throw new NullPointerException("Null child not allowed"); | ||
| 328 | |||
| 329 | return new TreePath(this, child); | ||
| 330 | } | ||
| 331 | |||
| 332 | /** | ||
| 333 | * Returns the {@code TreePath} of the parent. A return value of | ||
| 334 | * {@code null} indicates this is the root node. | ||
| 335 | * | ||
| 336 | * @return the parent path | ||
| 337 | */ | ||
| 338 | public TreePath getParentPath() { | ||
| 339 | return parentPath; | ||
| 340 | } | ||
| 341 | |||
| 342 | /** | ||
| 343 | * Returns a string that displays and identifies this | ||
| 344 | * object's properties. | ||
| 345 | * | ||
| 346 | * @return a String representation of this object | ||
| 347 | */ | ||
| 348 | public String toString() { | ||
| 349 | StringBuffer tempSpot = new StringBuffer("["); | ||
| 350 | |||
| 351 | for(int counter = 0, maxCounter = getPathCount();counter < maxCounter; | ||
| 352 | counter++) { | ||
| 353 | if(counter > 0) | ||
| 354 | tempSpot.append(", "); | ||
| 355 | tempSpot.append(getPathComponent(counter)); | ||
| 356 | } | ||
| 357 | tempSpot.append("]"); | ||
| 358 | return tempSpot.toString(); | ||
| 359 | } | ||
| 360 | } | ||