org.apache.commons.io
public abstract class DirectoryWalker extends Object
This class operates with a 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 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 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 $
Nested Class Summary | |
---|---|
static class | DirectoryWalker.CancelException
CancelException is thrown in DirectoryWalker to cancel the current
processing. |
Field Summary | |
---|---|
int | depthLimit
The limit on the directory depth to walk. |
FileFilter | filter
The file filter to use to filter files and directories. |
Constructor Summary | |
---|---|
protected | DirectoryWalker()
Construct an instance with no filtering and unlimited depth. |
protected | DirectoryWalker(FileFilter filter, int depthLimit)
Construct an instance with a filter and limit the depth navigated to.
|
protected | DirectoryWalker(IOFileFilter directoryFilter, IOFileFilter fileFilter, int depthLimit)
Construct an instance with a directory and a file filter and an optional
limit on the depth navigated to.
|
Method Summary | |
---|---|
protected void | checkIfCancelled(File file, int depth, Collection results)
Checks whether the walk has been cancelled by calling DirectoryWalker,
throwing a CancelException if it has.
|
protected void | handleCancelled(File startDirectory, Collection results, DirectoryWalker.CancelException cancel)
Overridable callback method invoked when the operation is cancelled.
|
protected boolean | handleDirectory(File directory, int depth, Collection results)
Overridable callback method invoked to determine if a directory should be processed.
|
protected void | handleDirectoryEnd(File directory, int depth, Collection results)
Overridable callback method invoked at the end of processing each directory.
|
protected void | handleDirectoryStart(File directory, int depth, Collection results)
Overridable callback method invoked at the start of processing each directory.
|
protected void | handleEnd(Collection results)
Overridable callback method invoked at the end of processing.
|
protected void | handleFile(File file, int depth, Collection results)
Overridable callback method invoked for each (non-directory) file.
|
protected boolean | handleIsCancelled(File file, int depth, Collection results)
Overridable callback method invoked to determine if the entire walk
operation should be immediately cancelled.
|
protected void | handleRestricted(File directory, int depth, Collection results)
Overridable callback method invoked for each restricted directory.
|
protected void | handleStart(File startDirectory, Collection results)
Overridable callback method invoked at the start of processing.
|
protected void | walk(File startDirectory, Collection results)
Internal method that walks the directory hierarchy in a depth-first manner.
|
void | walk(File directory, int depth, Collection results)
Main recursive method to examine the directory hierarchy.
|
The filter controls which files and directories will be navigated to as
part of the walk. The 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.
Parameters: filter the filter to apply, null means visit all files depthLimit controls how deep the hierarchy is navigated to (less than 0 means unlimited)
The filters control which files and directories will be navigated to as part
of the walk. This constructor uses makeDirectoryOnly
and makeFileOnly internally to combine the filters.
A null
filter means that no filtering should occur.
Parameters: directoryFilter the filter to apply to directories, null means visit all directories fileFilter the filter to apply to files, null means visit all files depthLimit controls how deep the hierarchy is navigated to (less than 0 means unlimited)
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 DirectoryWalker, may take a long time to run. In that case, you may wish to check for cancellation by calling this method.
Parameters: file the current file being processed depth the current file level (starting directory = 0) results the collection of result objects, may be updated
Throws: IOException if an I/O Error occurs
This implementation just re-throws the CancelException.
Parameters: startDirectory the directory that the walk started from results the collection of result objects, may be updated cancel the exception throw to cancel further processing containing details at the point of cancellation.
Throws: IOException if an I/O Error occurs
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.
Parameters: directory the current directory being processed depth the current directory level (starting directory = 0) results the collection of result objects, may be updated
Returns: true to process this directory, false to skip this directory
Throws: IOException if an I/O Error occurs
This implementation does nothing.
Parameters: directory the directory being processed depth the current directory level (starting directory = 0) results the collection of result objects, may be updated
Throws: IOException if an I/O Error occurs
This implementation does nothing.
Parameters: directory the current directory being processed depth the current directory level (starting directory = 0) results the collection of result objects, may be updated
Throws: IOException if an I/O Error occurs
This implementation does nothing.
Parameters: results the collection of result objects, may be updated
Throws: IOException if an I/O Error occurs
This implementation does nothing.
Parameters: file the current file being processed depth the current directory level (starting directory = 0) results the collection of result objects, may be updated
Throws: IOException if an I/O Error occurs
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 DirectoryWalker.
This implementation returns false.
Parameters: file the file or directory being processed depth the current directory level (starting directory = 0) results the collection of result objects, may be updated
Returns: true if the walk has been cancelled
Throws: IOException if an I/O Error occurs
This implementation does nothing.
Parameters: directory the restricted directory depth the current directory level (starting directory = 0) results the collection of result objects, may be updated
Throws: IOException if an I/O Error occurs
This implementation does nothing.
Parameters: startDirectory the directory to start from results the collection of result objects, may be updated
Throws: IOException if an I/O Error occurs
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
.
Parameters: startDirectory the directory to start from, not null results the collection of result objects, may be updated
Throws: NullPointerException if the start directory is null IOException if an I/O Error occurs
Parameters: directory the directory to examine, not null depth the directory level (starting directory = 0) results the collection of result objects, may be updated
Throws: IOException if an I/O Error occurs