1 /* 2 * Copyright (c) 2007, 2011, 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 */ preVisitDirectory(T dir, BasicFileAttributes attrs)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 */ visitFile(T file, BasicFileAttributes attrs)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 */ visitFileFailed(T file, IOException exc)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 */ postVisitDirectory(T dir, IOException exc)175 FileVisitResult postVisitDirectory(T dir, IOException exc) 176 throws IOException; 177 } 178