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