Deprecate DirectoryWalker.
MODIFY
src/main/java/org/apache/commons/io/DirectoryWalker.java
src/main/java/org/apache/commons/io/DirectoryWalker.java
import java.io.File;
import java.io.FileFilter;
import java.io.IOException;
+import java.nio.file.Files;
import java.util.Collection;
import java.util.Objects;
+import org.apache.commons.io.file.PathUtils;
import org.apache.commons.io.filefilter.FileFilterUtils;
import org.apache.commons.io.filefilter.IOFileFilter;
import org.apache.commons.io.filefilter.TrueFileFilter;
/**
- * Abstract class that walks through a directory hierarchy and provides
- * subclasses with convenient hooks to add specific behavior.
+ * Abstract class that walks through a directory hierarchy and provides subclasses with convenient hooks to add specific
+ * behavior.
* <p>
- * This class operates with a {@link FileFilter} and maximum depth to
- * limit the files and directories visited.
- * Commons IO supplies many common filter implementations in the
- * <a href="filefilter/package-summary.html"> filefilter</a> package.
+ * This class operates with a {@link FileFilter} and maximum depth to limit the files and directories visited. Commons
+ * IO supplies many common filter implementations in the <a href="filefilter/package-summary.html"> filefilter</a>
+ * package.
* </p>
* <p>
* The following sections describe:
* </p>
* <ul>
- * <li><a href="#example">1. Example Implementation</a> - example
- * <code>FileCleaner</code> implementation.</li>
- * <li><a href="#filter">2. Filter Example</a> - using
- * {@link FileFilter}(s) with <code>DirectoryWalker</code>.</li>
- * <li><a href="#cancel">3. Cancellation</a> - how to implement cancellation
- * behavior.</li>
+ * <li><a href="#example">1. Example Implementation</a> - example <code>FileCleaner</code> implementation.</li>
+ * <li><a href="#filter">2. Filter Example</a> - using {@link FileFilter}(s) with <code>DirectoryWalker</code>.</li>
+ * <li><a href="#cancel">3. Cancellation</a> - how to implement cancellation behavior.</li>
* </ul>
*
* <h2 id="example">1. Example Implementation</h2>
*
- * There are many possible extensions, for example, to delete all
- * files and '.svn' directories, and return a list of deleted files:
+ * There are many possible extensions, for example, to delete all files and '.svn' directories, and return a list of
+ * deleted files:
+ *
* <pre>
* public class FileCleaner extends DirectoryWalker {
*
* <h2 id="filter">2. Filter Example</h2>
*
* <p>
- * Choosing which directories and files to process can be a key aspect
- * of using this class. This information can be setup in three ways,
- * via three different constructors.
+ * Choosing which directories and files to process can be a key aspect of using this class. This information can be
+ * setup in three ways, via three different constructors.
* </p>
* <p>
- * The first option is to visit all directories and files.
- * This is achieved via the no-args constructor.
+ * The first option is to visit all directories and files. This is achieved via the no-args constructor.
* </p>
* <p>
- * 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.
+ * 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.
* </p>
* <p>
- * For example, if you wanted all directories which are not hidden
- * and files which end in ".txt":
+ * For example, if you wanted all directories which are not hidden and files which end in ".txt":
* </p>
+ *
* <pre>
* public class FooDirectoryWalker extends DirectoryWalker {
* public FooDirectoryWalker(FileFilter filter) {
*
* // Build up the filters and create the walker
* // Create a filter for Non-hidden directories
- * IOFileFilter fooDirFilter =
- * FileFilterUtils.andFileFilter(FileFilterUtils.directoryFileFilter,
+ * IOFileFilter fooDirFilter = FileFilterUtils.andFileFilter(FileFilterUtils.directoryFileFilter,
* HiddenFileFilter.VISIBLE);
*
* // Create a filter for Files ending in ".txt"
- * IOFileFilter fooFileFilter =
- * FileFilterUtils.andFileFilter(FileFilterUtils.fileFileFilter,
+ * 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);
+ * java.io.FileFilter fooFilter = FileFilterUtils.orFileFilter(fooDirFilter, fooFileFilter);
*
* // Use the filter to construct a DirectoryWalker implementation
* FooDirectoryWalker walker = new FooDirectoryWalker(fooFilter);
* </pre>
* <p>
- * The third constructor option is to specify separate filters, one for
- * directories and one for files. These are combined internally to form
- * the correct <code>FileFilter</code>, something which is very easy to
- * get wrong when attempted manually, particularly when trying to
- * express constructs like 'any file in directories named docs'.
+ * The third constructor option is to specify separate filters, one for directories and one for files. These are
+ * combined internally to form the correct <code>FileFilter</code>, something which is very easy to get wrong when
+ * attempted manually, particularly when trying to express constructs like 'any file in directories named docs'.
* </p>
* <p>
- * For example, if you wanted all directories which are not hidden
- * and files which end in ".txt":
+ * For example, if you wanted all directories which are not hidden and files which end in ".txt":
* </p>
+ *
* <pre>
* public class FooDirectoryWalker extends DirectoryWalker {
* public FooDirectoryWalker(IOFileFilter dirFilter, IOFileFilter fileFilter) {
* );
* </pre>
* <p>
- * This is much simpler than the previous example, and is why it is the preferred
- * option for filtering.
+ * This is much simpler than the previous example, and is why it is the preferred option for filtering.
* </p>
*
* <h2 id="cancel">3. Cancellation</h2>
*
* <p>
- * The DirectoryWalker contains some of the logic required for cancel processing.
- * Subclasses must complete the implementation.
+ * The DirectoryWalker contains some of the logic required for cancel processing. Subclasses must complete the
+ * implementation.
* </p>
* <p>
* What <code>DirectoryWalker</code> does provide for cancellation is:
* </p>
* <ul>
- * <li>{@link CancelException} which can be thrown in any of the
- * <i>lifecycle</i> methods to stop processing.</li>
- * <li>The <code>walk()</code> method traps thrown {@link CancelException}
- * and calls the <code>handleCancelled()</code> method, providing
- * a place for custom cancel processing.</li>
+ * <li>{@link CancelException} which can be thrown in any of the <i>lifecycle</i> methods to stop processing.</li>
+ * <li>The <code>walk()</code> method traps thrown {@link CancelException} and calls the <code>handleCancelled()</code>
+ * method, providing a place for custom cancel processing.</li>
* </ul>
* <p>
* Implementations need to provide:
* Two possible scenarios are envisaged for cancellation:
* </p>
* <ul>
- * <li><a href="#external">3.1 External / Multi-threaded</a> - cancellation being
- * decided/initiated by an external process.</li>
- * <li><a href="#internal">3.2 Internal</a> - cancellation being decided/initiated
- * from within a DirectoryWalker implementation.</li>
+ * <li><a href="#external">3.1 External / Multi-threaded</a> - cancellation being decided/initiated by an external
+ * process.</li>
+ * <li><a href="#internal">3.2 Internal</a> - cancellation being decided/initiated from within a DirectoryWalker
+ * implementation.</li>
* </ul>
* <p>
- * The following sections provide example implementations for these two different
- * scenarios.
+ * The following sections provide example implementations for these two different scenarios.
* </p>
*
* <h3 id="external">3.1 External / Multi-threaded</h3>
*
* <p>
- * This example provides a public <code>cancel()</code> 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
- * <a href="http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#36930">
- * volatile</a> flag to ensure it will work properly in a multi-threaded environment.
- * The flag is returned by the <code>handleIsCancelled()</code> method, which
- * will cause the walk to stop immediately. The <code>handleCancelled()</code>
- * method will be the next, and last, callback method received once cancellation
- * has occurred.
+ * This example provides a public <code>cancel()</code> 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
+ * <a href="http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#36930"> volatile</a> flag to ensure
+ * it will work properly in a multi-threaded environment. The flag is returned by the <code>handleIsCancelled()</code>
+ * method, which will cause the walk to stop immediately. The <code>handleCancelled()</code> method will be the next,
+ * and last, callback method received once cancellation has occurred.
* </p>
*
* <pre>
* <h3 id="internal">3.2 Internal</h3>
*
* <p>
- * This shows an example of how internal cancellation processing could be implemented.
- * <b>Note</b> the decision logic and throwing a {@link CancelException} could be implemented
- * in any of the <i>lifecycle</i> methods.
+ * This shows an example of how internal cancellation processing could be implemented. <b>Note</b> the decision logic
+ * and throwing a {@link CancelException} could be implemented in any of the <i>lifecycle</i> methods.
* </p>
*
* <pre>
*
* @param <T> The result type, like {@link File}.
* @since 1.3
+ * @deprecated Apache Commons IO no longer uses this class. Instead, use
+ * {@link PathUtils#walk(java.nio.file.Path, org.apache.commons.io.file.PathFilter, int, boolean, java.nio.file.FileVisitOption...)}
+ * or {@link Files#walkFileTree(java.nio.file.Path, java.util.Set, int, java.nio.file.FileVisitor)}, and
+ * friends.
*/
+@Deprecated
public abstract class DirectoryWalker<T> {
/**

Deprecate DirectoryWalker.