1 /*
2 * Copyright (c) 2007, 2009, 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 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 * throws IOException
45 * {
46 * file.delete();
47 * return FileVisitResult.CONTINUE;
48 * }
49 * @Override
50 * public FileVisitResult postVisitDirectory(Path dir, IOException e)
51 * throws IOException
52 * {
53 * if (e != null) {
54 * // directory iteration failed
55 * throw e;
56 * }
57 * dir.delete();
58 * return FileVisitResult.CONTINUE;
59 * }
60 * });
61 * </pre>
62 * <p> Furthermore, suppose we want to copy a file tree to a target location.
63 * In that case, symbolic links should be followed and the target directory
64 * should be created before the entries in the directory are copied.
65 * <pre>
66 * final Path source = ...
67 * final Path target = ...
68 *
69 * Files.walkFileTree(source, EnumSet.of(FileVisitOption.FOLLOW_LINKS), Integer.MAX_VALUE,
70 * new SimpleFileVisitor<Path>() {
71 * @Override
72 * public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs)
73 * throws IOException
74 * {
75 * try {
76 * dir.copyTo(target.resolve(source.relativize(dir)));
77 * } catch (FileAlreadyExistsException e) {
78 * // ignore
79 * }
80 * return CONTINUE;
81 * }
82 * @Override
83 * public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
84 * throws IOException
85 * {
86 * file.copyTo(target.resolve(source.relativize(file)));
87 * return CONTINUE;
88 * }
89 * });
90 * </pre>
91 *
92 * @since 1.7
93 */
94
95 public interface FileVisitor<T> {
96
97 /**
98 * Invoked for a directory before entries in the directory are visited.
99 *
100 * <p> If this method returns {@link FileVisitResult#CONTINUE CONTINUE},
101 * then entries in the directory are visited. If this method returns {@link
102 * FileVisitResult#SKIP_SUBTREE SKIP_SUBTREE} or {@link
103 * FileVisitResult#SKIP_SIBLINGS SKIP_SIBLINGS} then entries in the
104 * directory (and any descendants) will not be visited.
105 *
106 * @param dir
107 * a reference to the directory
108 * @param attrs
109 * the directory's basic attributes
110 *
111 * @return the visit result
112 *
113 * @throws IOException
114 * if an I/O error occurs
115 */
116 FileVisitResult preVisitDirectory(T dir, BasicFileAttributes attrs)
117 throws IOException;
118
119 /**
120 * Invoked for a file in a directory.
121 *
122 * @param file
123 * a reference to the file
124 * @param attrs
125 * the file's basic attributes
126 *
127 * @return the visit result
128 *
129 * @throws IOException
130 * if an I/O error occurs
131 */
132 FileVisitResult visitFile(T file, BasicFileAttributes attrs)
133 throws IOException;
134
135 /**
136 * Invoked for a file that could not be visited. This method is invoked
137 * if the file's attributes could not be read, the file is a directory
138 * that could not be opened, and other reasons.
139 *
140 * @param file
141 * a reference to the file
142 * @param exc
143 * the I/O exception that prevented the file from being visited
144 *
145 * @return the visit result
146 *
147 * @throws IOException
148 * if an I/O error occurs
149 */
150 FileVisitResult visitFileFailed(T file, IOException exc)
151 throws IOException;
152
153 /**
154 * Invoked for a directory after entries in the directory, and all of their
155 * descendants, have been visited. This method is also invoked when iteration
156 * of the directory completes prematurely (by a {@link #visitFile visitFile}
157 * method returning {@link FileVisitResult#SKIP_SIBLINGS SKIP_SIBLINGS},
158 * or an I/O error when iterating over the directory).
159 *
160 * @param dir
161 * a reference to the directory
162 * @param exc
163 * {@code null} if the iteration of the directory completes without
164 * an error; otherwise the I/O exception that caused the iteration
165 * of the directory to complete prematurely
166 *
167 * @return the visit result
168 *
169 * @throws IOException
170 * if an I/O error occurs
171 */
172 FileVisitResult postVisitDirectory(T dir, IOException exc)
173 throws IOException;
174 }