FileVisitor

AI-generated Key Takeaways

• The FileVisitor interface provides a mechanism to visit each file in a file tree, commonly used with Files.walkFileTree.

• It defines methods to handle events for directories before (preVisitDirectory) and after (postVisitDirectory) their entries are visited, as well as for individual files (visitFile).

• The visitFileFailed method is invoked when a file cannot be visited due to errors like inaccessible attributes or unopenable directories.

• SimpleFileVisitor provides a basic implementation with default behaviors for these methods, often used as a starting point for custom visitors.

• Using FileVisitor allows operations like deleting or copying entire file trees with fine-grained control over how each file and directory is handled.

public interface FileVisitor

Known Indirect Subclasses SimpleFileVisitor<T> SimpleFileVisitor<T> A simple visitor of files with default behavior to visit all files and to re-throw I/O errors.

A visitor of files. An implementation of this interface is provided to the Files.walkFileTree methods to visit each file in a file tree.

Usage Examples: Suppose we want to delete a file tree. In that case, each directory should be deleted after the entries in the directory are deleted.

     Path start = ...
     Files.walkFileTree(start, new SimpleFileVisitor<Path>() {
         @Override
         public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
             throws IOException
         {
             Files.delete(file);
             return FileVisitResult.CONTINUE;
         }
         @Override
         public FileVisitResult postVisitDirectory(Path dir, IOException e)
             throws IOException
         {
             if (e == null) {
                 Files.delete(dir);
                 return FileVisitResult.CONTINUE;
             } else {
                 // directory iteration failed
                 throw e;
             }
         }
     });
 

Furthermore, suppose we want to copy a file tree to a target location. In that case, symbolic links should be followed and the target directory should be created before the entries in the directory are copied.

     final Path source = ...
     final Path target = ...

     Files.walkFileTree(source, EnumSet.of(FileVisitOption.FOLLOW_LINKS), Integer.MAX_VALUE,
         new SimpleFileVisitor<Path>() {
             @Override
             public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs)
                 throws IOException
             {
                 Path targetdir = target.resolve(source.relativize(dir));
                 try {
                     Files.copy(dir, targetdir);
                 } catch (FileAlreadyExistsException e) {
                      if (!Files.isDirectory(targetdir))
                          throw e;
                 }
                 return CONTINUE;
             }
             @Override
             public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
                 throws IOException
             {
                 Files.copy(file, target.resolve(source.relativize(file)));
                 return CONTINUE;
             }
         });
 

Public Method Summary

abstract FileVisitResult	postVisitDirectory(T dir, IOException exc) Invoked for a directory after entries in the directory, and all of their descendants, have been visited.
abstract FileVisitResult	preVisitDirectory(T dir, BasicFileAttributes attrs) Invoked for a directory before entries in the directory are visited.
abstract FileVisitResult	visitFile(T file, BasicFileAttributes attrs) Invoked for a file in a directory.
abstract FileVisitResult	visitFileFailed(T file, IOException exc) Invoked for a file that could not be visited.

Public Methods

public abstract FileVisitResult postVisitDirectory (T dir, IOException exc)

Invoked for a directory after entries in the directory, and all of their descendants, have been visited. This method is also invoked when iteration of the directory completes prematurely (by a visitFile method returning SKIP_SIBLINGS, or an I/O error when iterating over the directory).

Parameters

dir	a reference to the directory
exc	null if the iteration of the directory completes without an error; otherwise the I/O exception that caused the iteration of the directory to complete prematurely

Returns

• the visit result

Throws

IOException	if an I/O error occurs

public abstract FileVisitResult preVisitDirectory (T dir, BasicFileAttributes attrs)

Invoked for a directory before entries in the directory are visited.

If this method returns CONTINUE, then entries in the directory are visited. If this method returns SKIP_SUBTREE or SKIP_SIBLINGS then entries in the directory (and any descendants) will not be visited.

Parameters

dir	a reference to the directory
attrs	the directory's basic attributes

Returns

• the visit result

Throws

IOException	if an I/O error occurs

public abstract FileVisitResult visitFile (T file, BasicFileAttributes attrs)

Invoked for a file in a directory.

Parameters

file	a reference to the file
attrs	the file's basic attributes

Returns

• the visit result

Throws

IOException	if an I/O error occurs

public abstract FileVisitResult visitFileFailed (T file, IOException exc)

Invoked for a file that could not be visited. This method is invoked if the file's attributes could not be read, the file is a directory that could not be opened, and other reasons.

Parameters

file	a reference to the file
exc	the I/O exception that prevented the file from being visited

Returns

• the visit result

Throws

IOException	if an I/O error occurs