|
1 /* |
|
2 * Copyright 2007-2009 Sun Microsystems, Inc. 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. Sun designates this |
|
8 * particular file as subject to the "Classpath" exception as provided |
|
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
22 * CA 95054 USA or visit www.sun.com if you need additional information or |
|
23 * have any questions. |
|
24 */ |
|
25 |
|
26 package java.nio.file; |
|
27 |
|
28 import java.nio.file.attribute.BasicFileAttributes; |
|
29 import java.io.IOException; |
|
30 |
|
31 /** |
|
32 * A visitor of files. An implementation of this interface is provided to the |
|
33 * {@link Files#walkFileTree walkFileTree} utility method to visit each file |
|
34 * in a tree. |
|
35 * |
|
36 * <p> <b>Usage Examples:</b> |
|
37 * Suppose we want to delete a file tree. In that case, each directory should |
|
38 * be deleted after the entries in the directory are deleted. |
|
39 * <pre> |
|
40 * Path start = ... |
|
41 * Files.walkFileTree(start, new SimpleFileVisitor<Path>() { |
|
42 * @Override |
|
43 * public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) { |
|
44 * try { |
|
45 * file.delete(false); |
|
46 * } catch (IOException exc) { |
|
47 * // failed to delete |
|
48 * } |
|
49 * return FileVisitResult.CONTINUE; |
|
50 * } |
|
51 * @Override |
|
52 * public FileVisitResult postVisitDirectory(Path dir, IOException e) { |
|
53 * if (e == null) { |
|
54 * try { |
|
55 * dir.delete(false); |
|
56 * } catch (IOException exc) { |
|
57 * // failed to delete |
|
58 * } |
|
59 * } else { |
|
60 * // directory iteration failed |
|
61 * } |
|
62 * return FileVisitResult.CONTINUE; |
|
63 * } |
|
64 * }); |
|
65 * </pre> |
|
66 * <p> Furthermore, suppose we want to copy a file tree rooted at a source |
|
67 * directory to a target location. In that case, symbolic links should be |
|
68 * followed and the target directory should be created before the entries in |
|
69 * the directory are copied. |
|
70 * <pre> |
|
71 * final Path source = ... |
|
72 * final Path target = ... |
|
73 * |
|
74 * Files.walkFileTree(source, EnumSet.of(FileVisitOption.FOLLOW_LINKS), Integer.MAX_VALUE, |
|
75 * new SimpleFileVisitor<Path>() { |
|
76 * @Override |
|
77 * public FileVisitResult preVisitDirectory(Path dir) { |
|
78 * try { |
|
79 * dir.copyTo(target.resolve(source.relativize(dir))); |
|
80 * } catch (FileAlreadyExistsException e) { |
|
81 * // ignore |
|
82 * } catch (IOException e) { |
|
83 * // copy failed, skip rest of directory and descendants |
|
84 * return SKIP_SUBTREE; |
|
85 * } |
|
86 * return CONTINUE; |
|
87 * } |
|
88 * @Override |
|
89 * public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) { |
|
90 * try { |
|
91 * file.copyTo(target.resolve(source.relativize(file))); |
|
92 * } catch (IOException e) { |
|
93 * // copy failed |
|
94 * } |
|
95 * return CONTINUE; |
|
96 * } |
|
97 * }); |
|
98 * </pre> |
|
99 * |
|
100 * @since 1.7 |
|
101 */ |
|
102 |
|
103 public interface FileVisitor<T extends FileRef> { |
|
104 |
|
105 /** |
|
106 * Invoked for a directory before entries in the directory are visited. |
|
107 * |
|
108 * <p> If this method returns {@link FileVisitResult#CONTINUE CONTINUE}, |
|
109 * then entries in the directory are visited. If this method returns {@link |
|
110 * FileVisitResult#SKIP_SUBTREE SKIP_SUBTREE} or {@link |
|
111 * FileVisitResult#SKIP_SIBLINGS SKIP_SIBLINGS} then entries in the |
|
112 * directory (and any descendants) will not be visited. |
|
113 * |
|
114 * @param dir |
|
115 * A reference to the directory |
|
116 * |
|
117 * @return the visit result |
|
118 */ |
|
119 FileVisitResult preVisitDirectory(T dir); |
|
120 |
|
121 /** |
|
122 * Invoked for a directory that could not be opened. |
|
123 * |
|
124 * @param dir |
|
125 * A reference to the directory |
|
126 * @param exc |
|
127 * The I/O exception thrown from the attempt to open the directory |
|
128 * |
|
129 * @return the visit result |
|
130 */ |
|
131 FileVisitResult preVisitDirectoryFailed(T dir, IOException exc); |
|
132 |
|
133 /** |
|
134 * Invoked for a file in a directory. |
|
135 * |
|
136 * @param file |
|
137 * A reference to the file |
|
138 * @param attrs |
|
139 * The file's basic attributes |
|
140 * |
|
141 * @return the visit result |
|
142 */ |
|
143 FileVisitResult visitFile(T file, BasicFileAttributes attrs); |
|
144 |
|
145 /** |
|
146 * Invoked for a file when its basic file attributes could not be read. |
|
147 * |
|
148 * @param file |
|
149 * A reference to the file |
|
150 * @param exc |
|
151 * The I/O exception thrown from the attempt to read the file |
|
152 * attributes |
|
153 * |
|
154 * @return the visit result |
|
155 */ |
|
156 FileVisitResult visitFileFailed(T file, IOException exc); |
|
157 |
|
158 /** |
|
159 * Invoked for a directory after entries in the directory, and all of their |
|
160 * descendants, have been visited. This method is also invoked when iteration |
|
161 * of the directory completes prematurely (by a {@link #visitFile visitFile} |
|
162 * method returning {@link FileVisitResult#SKIP_SIBLINGS SKIP_SIBLINGS}, |
|
163 * or an I/O error when iterating over the directory). |
|
164 * |
|
165 * @param dir |
|
166 * A reference to the directory |
|
167 * @param exc |
|
168 * {@code null} if the iteration of the directory completes without |
|
169 * an error; otherwise the I/O exception that caused the iteration |
|
170 * of the directory to complete prematurely |
|
171 * |
|
172 * @return the visit result |
|
173 */ |
|
174 FileVisitResult postVisitDirectory(T dir, IOException exc); |
|
175 } |