* This class operates with a {@link FileFilter} and maximum depth to * limit the files and direcories visited. * Commons IO supplies many common filter implementations in the * filefilter package. *
* The following sections describe: *
FileCleaner implementation.DirectoryWalker.
* public class FileCleaner extends DirectoryWalker {
*
* public FileCleaner() {
* super();
* }
*
* public List clean(File startDirectory) {
* List results = new ArrayList();
* walk(startDirectory, results);
* return results;
* }
*
* protected boolean handleDirectory(File directory, int depth, Collection results) {
* // delete svn directories and then skip
* if (".svn".equals(directory.getName())) {
* directory.delete();
* return false;
* } else {
* return true;
* }
*
* }
*
* protected void handleFile(File file, int depth, Collection results) {
* // delete file and add to list of deleted
* file.delete();
* results.add(file);
* }
* }
*
*
*
* * The first option is to visit all directories and files. * This is achieved via the no-args constructor. *
* The second constructor option is to supply a single {@link FileFilter} * that describes the files and directories to visit. Care must be taken * with this option as the same filter is used for both directories * and files. *
* For example, if you wanted all directories which are not hidden * and files which end in ".txt": *
* public class FooDirectoryWalker extends DirectoryWalker {
* public FooDirectoryWalker(FileFilter filter) {
* super(filter, -1);
* }
* }
*
* // Build up the filters and create the walker
* // Create a filter for Non-hidden directories
* IOFileFilter fooDirFilter =
* FileFilterUtils.andFileFilter(FileFilterUtils.directoryFileFilter,
* HiddenFileFilter.VISIBLE);
*
* // Create a filter for Files ending in ".txt"
* IOFileFilter fooFileFilter =
* FileFilterUtils.andFileFilter(FileFilterUtils.fileFileFilter,
* FileFilterUtils.suffixFileFilter(".txt"));
*
* // Combine the directory and file filters using an OR condition
* java.io.FileFilter fooFilter =
* FileFilterUtils.orFileFilter(fooDirFilter, fooFileFilter);
*
* // Use the filter to construct a DirectoryWalker implementation
* FooDirectoryWalker walker = new FooDirectoryWalker(fooFilter);
*
*
* The third constructor option is to specify separate filters, one for
* directories and one for files. These are combined internally to form
* the correct FileFilter, something which is very easy to
* get wrong when attempted manually, particularly when trying to
* express constructs like 'any file in directories named docs'.
*
* For example, if you wanted all directories which are not hidden * and files which end in ".txt": *
* public class FooDirectoryWalker extends DirectoryWalker {
* public FooDirectoryWalker(IOFileFilter dirFilter, IOFileFilter fileFilter) {
* super(dirFilter, fileFilter, -1);
* }
* }
*
* // Use the filters to construct the walker
* FooDirectoryWalker walker = new FooDirectoryWalker(
* HiddenFileFilter.VISIBLE,
* FileFilterUtils.suffixFileFilter(".txt"),
* );
*
* This is much simpler than the previous example, and is why it is the preferred
* option for filtering.
*
*
*
* What DirectoryWalker does provide for cancellation is:
*
walk() method traps thrown {@link CancelException}
* and calls the handleCancelled() method, providing
* a place for custom cancel processing.* Implementations need to provide: *
handleCancelled() method.
* * Two possible scenarios are envisaged for cancellation: *
* The following sections provide example implementations for these two different * scenarios. * * *
cancel() method that can be
* called by another thread to stop the processing. A typical example use-case
* would be a cancel button on a GUI. Calling this method sets a
*
* volatile flag to ensure it will work properly in a multi-threaded environment.
* The flag is returned by the handleIsCancelled() method, which
* will cause the walk to stop immediately. The handleCancelled()
* method will be the next, and last, callback method received once cancellation
* has occurred.
*
*
* public class FooDirectoryWalker extends DirectoryWalker {
*
* private volatile boolean cancelled = false;
*
* public void cancel() {
* cancelled = true;
* }
*
* private void handleIsCancelled(File file, int depth, Collection results) {
* return cancelled;
* }
*
* protected void handleCancelled(File startDirectory, Collection results, CancelException cancel) {
* // implement processing required when a cancellation occurs
* }
* }
*
*
*
*
* public class BarDirectoryWalker extends DirectoryWalker {
*
* protected boolean handleDirectory(File directory, int depth, Collection results) throws IOException {
* // cancel if hidden directory
* if (directory.isHidden()) {
* throw new CancelException(file, depth);
* }
* return true;
* }
*
* protected void handleFile(File file, int depth, Collection results) throws IOException {
* // cancel if read-only file
* if (!file.canWrite()) {
* throw new CancelException(file, depth);
* }
* results.add(file);
* }
*
* protected void handleCancelled(File startDirectory, Collection results, CancelException cancel) {
* // implement processing required when a cancellation occurs
* }
* }
*
*
* @since Commons IO 1.3
* @version $Revision: 424748 $
*/
public abstract class DirectoryWalker {
/**
* The file filter to use to filter files and directories.
*/
private final FileFilter filter;
/**
* The limit on the directory depth to walk.
*/
private final int depthLimit;
/**
* Construct an instance with no filtering and unlimited depth.
*/
protected DirectoryWalker() {
this(null, -1);
}
/**
* Construct an instance with a filter and limit the depth navigated to.
*
* The filter controls which files and directories will be navigated to as
* part of the walk. The {@link FileFilterUtils} class is useful for combining
* various filters together. A null filter means that no
* filtering should occur and all files and directories will be visited.
*
* @param filter the filter to apply, null means visit all files
* @param depthLimit controls how deep the hierarchy is
* navigated to (less than 0 means unlimited)
*/
protected DirectoryWalker(FileFilter filter, int depthLimit) {
this.filter = filter;
this.depthLimit = depthLimit;
}
/**
* Construct an instance with a directory and a file filter and an optional
* limit on the depth navigated to.
*
* The filters control which files and directories will be navigated to as part
* of the walk. This constructor uses {@link FileFilterUtils#makeDirectoryOnly(IOFileFilter)}
* and {@link FileFilterUtils#makeFileOnly(IOFileFilter)} internally to combine the filters.
* A null filter means that no filtering should occur.
*
* @param directoryFilter the filter to apply to directories, null means visit all directories
* @param fileFilter the filter to apply to files, null means visit all files
* @param depthLimit controls how deep the hierarchy is
* navigated to (less than 0 means unlimited)
*/
protected DirectoryWalker(IOFileFilter directoryFilter, IOFileFilter fileFilter, int depthLimit) {
if (directoryFilter == null && fileFilter == null) {
this.filter = null;
} else {
directoryFilter = (directoryFilter != null ? directoryFilter : TrueFileFilter.TRUE);
fileFilter = (fileFilter != null ? fileFilter : TrueFileFilter.TRUE);
directoryFilter = FileFilterUtils.makeDirectoryOnly(directoryFilter);
fileFilter = FileFilterUtils.makeFileOnly(fileFilter);
this.filter = FileFilterUtils.orFileFilter(directoryFilter, fileFilter);
}
this.depthLimit = depthLimit;
}
//-----------------------------------------------------------------------
/**
* Internal method that walks the directory hierarchy in a depth-first manner.
*
* Users of this class do not need to call this method. This method will * be called automatically by another (public) method on the specific subclass. *
* Writers of subclasses should call this method to start the directory walk.
* Once called, this method will emit events as it walks the hierarchy.
* The event methods have the prefix handle.
*
* @param startDirectory the directory to start from, not null
* @param results the collection of result objects, may be updated
* @throws NullPointerException if the start directory is null
* @throws IOException if an I/O Error occurs
*/
protected final void walk(File startDirectory, Collection results) throws IOException {
if (startDirectory == null) {
throw new NullPointerException("Start Directory is null");
}
try {
handleStart(startDirectory, results);
walk(startDirectory, 0, results);
handleEnd(results);
} catch(CancelException cancel) {
handleCancelled(startDirectory, results, cancel);
}
}
/**
* Main recursive method to examine the directory hierarchy.
*
* @param directory the directory to examine, not null
* @param depth the directory level (starting directory = 0)
* @param results the collection of result objects, may be updated
* @throws IOException if an I/O Error occurs
*/
private void walk(File directory, int depth, Collection results) throws IOException {
checkIfCancelled(directory, depth, results);
if (handleDirectory(directory, depth, results)) {
handleDirectoryStart(directory, depth, results);
int childDepth = depth + 1;
if (depthLimit < 0 || childDepth <= depthLimit) {
checkIfCancelled(directory, depth, results);
File[] childFiles = (filter == null ? directory.listFiles() : directory.listFiles(filter));
if (childFiles == null) {
handleRestricted(directory, childDepth, results);
} else {
for (int i = 0; i < childFiles.length; i++) {
File childFile = childFiles[i];
if (childFile.isDirectory()) {
walk(childFile, childDepth, results);
} else {
checkIfCancelled(childFile, childDepth, results);
handleFile(childFile, childDepth, results);
checkIfCancelled(childFile, childDepth, results);
}
}
}
}
handleDirectoryEnd(directory, depth, results);
}
checkIfCancelled(directory, depth, results);
}
//-----------------------------------------------------------------------
/**
* Checks whether the walk has been cancelled by calling {@link #handleIsCancelled},
* throwing a CancelException if it has.
*
* Writers of subclasses should not normally call this method as it is called * automatically by the walk of the tree. However, sometimes a single method, * typically {@link #handleFile}, may take a long time to run. In that case, * you may wish to check for cancellation by calling this method. * * @param file the current file being processed * @param depth the current file level (starting directory = 0) * @param results the collection of result objects, may be updated * @throws IOException if an I/O Error occurs */ protected final void checkIfCancelled(File file, int depth, Collection results) throws IOException { if (handleIsCancelled(file, depth, results)) { throw new CancelException(file, depth); } } /** * Overridable callback method invoked to determine if the entire walk * operation should be immediately cancelled. *
* This method should be implemented by those subclasses that want to
* provide a public cancel() method available from another
* thread. The design pattern for the subclass should be as follows:
*
* public class FooDirectoryWalker extends DirectoryWalker {
* private volatile boolean cancelled = false;
*
* public void cancel() {
* cancelled = true;
* }
* private void handleIsCancelled(File file, int depth, Collection results) {
* return cancelled;
* }
* protected void handleCancelled(File startDirectory,
* Collection results, CancelException cancel) {
* // implement processing required when a cancellation occurs
* }
* }
*
* * If this method returns true, then the directory walk is immediately * cancelled. The next callback method will be {@link #handleCancelled}. *
* This implementation returns false. * * @param file the file or directory being processed * @param depth the current directory level (starting directory = 0) * @param results the collection of result objects, may be updated * @return true if the walk has been cancelled * @throws IOException if an I/O Error occurs */ protected boolean handleIsCancelled( File file, int depth, Collection results) throws IOException { // do nothing - overridable by subclass return false; // not cancelled } /** * Overridable callback method invoked when the operation is cancelled. * The file being processed when the cancellation occurred can be * obtained from the exception. *
* This implementation just re-throws the {@link CancelException}. * * @param startDirectory the directory that the walk started from * @param results the collection of result objects, may be updated * @param cancel the exception throw to cancel further processing * containing details at the point of cancellation. * @throws IOException if an I/O Error occurs */ protected void handleCancelled(File startDirectory, Collection results, CancelException cancel) throws IOException { // re-throw exception - overridable by subclass throw cancel; } //----------------------------------------------------------------------- /** * Overridable callback method invoked at the start of processing. *
* This implementation does nothing. * * @param startDirectory the directory to start from * @param results the collection of result objects, may be updated * @throws IOException if an I/O Error occurs */ protected void handleStart(File startDirectory, Collection results) throws IOException { // do nothing - overridable by subclass } /** * Overridable callback method invoked to determine if a directory should be processed. *
* This method returns a boolean to indicate if the directory should be examined or not. * If you return false, the entire directory and any subdirectories will be skipped. * Note that this functionality is in addition to the filtering by file filter. *
* This implementation does nothing and returns true. * * @param directory the current directory being processed * @param depth the current directory level (starting directory = 0) * @param results the collection of result objects, may be updated * @return true to process this directory, false to skip this directory * @throws IOException if an I/O Error occurs */ protected boolean handleDirectory(File directory, int depth, Collection results) throws IOException { // do nothing - overridable by subclass return true; // process directory } /** * Overridable callback method invoked at the start of processing each directory. *
* This implementation does nothing. * * @param directory the current directory being processed * @param depth the current directory level (starting directory = 0) * @param results the collection of result objects, may be updated * @throws IOException if an I/O Error occurs */ protected void handleDirectoryStart(File directory, int depth, Collection results) throws IOException { // do nothing - overridable by subclass } /** * Overridable callback method invoked for each (non-directory) file. *
* This implementation does nothing. * * @param file the current file being processed * @param depth the current directory level (starting directory = 0) * @param results the collection of result objects, may be updated * @throws IOException if an I/O Error occurs */ protected void handleFile(File file, int depth, Collection results) throws IOException { // do nothing - overridable by subclass } /** * Overridable callback method invoked for each restricted directory. *
* This implementation does nothing. * * @param directory the restricted directory * @param depth the current directory level (starting directory = 0) * @param results the collection of result objects, may be updated * @throws IOException if an I/O Error occurs */ protected void handleRestricted(File directory, int depth, Collection results) throws IOException { // do nothing - overridable by subclass } /** * Overridable callback method invoked at the end of processing each directory. *
* This implementation does nothing. * * @param directory the directory being processed * @param depth the current directory level (starting directory = 0) * @param results the collection of result objects, may be updated * @throws IOException if an I/O Error occurs */ protected void handleDirectoryEnd(File directory, int depth, Collection results) throws IOException { // do nothing - overridable by subclass } /** * Overridable callback method invoked at the end of processing. *
* This implementation does nothing.
*
* @param results the collection of result objects, may be updated
* @throws IOException if an I/O Error occurs
*/
protected void handleEnd(Collection results) throws IOException {
// do nothing - overridable by subclass
}
//-----------------------------------------------------------------------
/**
* CancelException is thrown in DirectoryWalker to cancel the current
* processing.
*/
public static class CancelException extends IOException {
/** Serialization id. */
private static final long serialVersionUID = 1347339620135041008L;
/** The file being processed when the exception was thrown. */
private File file;
/** The file depth when the exception was thrown. */
private int depth = -1;
/**
* Constructs a CancelException with
* the file and depth when cancellation occurred.
*
* @param file the file when the operation was cancelled, may be null
* @param depth the depth when the operation was cancelled, may be null
*/
public CancelException(File file, int depth) {
this("Operation Cancelled", file, depth);
}
/**
* Constructs a CancelException with
* an appropriate message and the file and depth when
* cancellation occurred.
*
* @param message the detail message
* @param file the file when the operation was cancelled
* @param depth the depth when the operation was cancelled
*/
public CancelException(String message, File file, int depth) {
super(message);
this.file = file;
this.depth = depth;
}
/**
* Return the file when the operation was cancelled.
*
* @return the file when the operation was cancelled
*/
public File getFile() {
return file;
}
/**
* Return the depth when the operation was cancelled.
*
* @return the depth when the operation was cancelled
*/
public int getDepth() {
return depth;
}
}
}