File	Doc	Category	Size	Date	Package
DirectoryWalker.java	API Doc	Android 1.5 API	25545	Wed May 06 22:42:46 BST 2009	org.apache.commons.io

DirectoryWalker

• java.lang.Object

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);
}
}

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);

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"),
);

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
}
}

Fields Summary
private final FileFilter	filter The file filter to use to filter files and directories.
private final int	depthLimit The limit on the directory depth to walk.

Constructors Summary
protected DirectoryWalker() Construct an instance with no filtering and unlimited depth. this(null, -1);
protected DirectoryWalker(FileFilter filter, int depthLimit) 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) this.filter = filter; this.depthLimit = depthLimit;
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. 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) 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;

Methods Summary
protected final void	checkIfCancelled(java.io.File file, int depth, java.util.Collection 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 if (handleIsCancelled(file, depth, results)) { throw new CancelException(file, depth); }
protected void	handleCancelled(java.io.File startDirectory, java.util.Collection results, org.apache.commons.io.DirectoryWalker$CancelException cancel) 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 // re-throw exception - overridable by subclass throw cancel;
protected boolean	handleDirectory(java.io.File directory, int depth, java.util.Collection results) 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 // do nothing - overridable by subclass return true; // process directory
protected void	handleDirectoryEnd(java.io.File directory, int depth, java.util.Collection results) 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 // do nothing - overridable by subclass
protected void	handleDirectoryStart(java.io.File directory, int depth, java.util.Collection results) 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 // do nothing - overridable by subclass
protected void	handleEnd(java.util.Collection results) 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 // do nothing - overridable by subclass
protected void	handleFile(java.io.File file, int depth, java.util.Collection results) 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 // do nothing - overridable by subclass
protected boolean	handleIsCancelled(java.io.File file, int depth, java.util.Collection results) 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 // do nothing - overridable by subclass return false; // not cancelled
protected void	handleRestricted(java.io.File directory, int depth, java.util.Collection results) 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 // do nothing - overridable by subclass
protected void	handleStart(java.io.File startDirectory, java.util.Collection results) 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 // do nothing - overridable by subclass
protected final void	walk(java.io.File startDirectory, java.util.Collection results) 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 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); }
private void	walk(java.io.File directory, int depth, java.util.Collection results) 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 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);