This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-io.git
commit 25c09bc20b639bde3879745325c89299f44a4d20 Author: Gary Gregory <gardgreg...@gmail.com> AuthorDate: Thu May 16 09:55:19 2019 -0400 Javadoc. Remove Subversion's "@version $Id$". --- .../org/apache/commons/io/DirectoryWalker.java | 49 +++++++++++++++++++--- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/src/main/java/org/apache/commons/io/DirectoryWalker.java b/src/main/java/org/apache/commons/io/DirectoryWalker.java index a897c38..b04a204 100644 --- a/src/main/java/org/apache/commons/io/DirectoryWalker.java +++ b/src/main/java/org/apache/commons/io/DirectoryWalker.java @@ -33,8 +33,10 @@ import org.apache.commons.io.filefilter.TrueFileFilter; * 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> @@ -82,20 +84,25 @@ import org.apache.commons.io.filefilter.TrueFileFilter; * * <h3 id="filter">2. Filter Example</h3> * + * <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. + * </p> * <p> * 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. + * </p> * <p> * 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) { @@ -127,9 +134,11 @@ import org.apache.commons.io.filefilter.TrueFileFilter; * 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": + * </p> * <pre> * public class FooDirectoryWalker extends DirectoryWalker { * public FooDirectoryWalker(IOFileFilter dirFilter, IOFileFilter fileFilter) { @@ -143,15 +152,20 @@ import org.apache.commons.io.filefilter.TrueFileFilter; * FileFilterUtils.suffixFileFilter(".txt"), * ); * </pre> + * <p> * This is much simpler than the previous example, and is why it is the preferred * option for filtering. + * </p> * * <h3 id="cancel">3. Cancellation</h3> * + * <p> * 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> @@ -161,6 +175,7 @@ import org.apache.commons.io.filefilter.TrueFileFilter; * </ul> * <p> * Implementations need to provide: + * </p> * <ul> * <li>The decision logic on whether to cancel processing or not.</li> * <li>Constructing and throwing a {@link CancelException}.</li> @@ -168,6 +183,7 @@ import org.apache.commons.io.filefilter.TrueFileFilter; * </ul> * <p> * 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> @@ -177,9 +193,11 @@ import org.apache.commons.io.filefilter.TrueFileFilter; * <p> * The following sections provide example implementations for these two different * scenarios. + * </p> * * <h4 id="external">3.1 External / Multi-threaded</h4> * + * <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 @@ -189,6 +207,7 @@ import org.apache.commons.io.filefilter.TrueFileFilter; * 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> * public class FooDirectoryWalker extends DirectoryWalker { @@ -211,9 +230,11 @@ import org.apache.commons.io.filefilter.TrueFileFilter; * * <h4 id="internal">3.2 Internal</h4> * + * <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. + * </p> * * <pre> * public class BarDirectoryWalker extends DirectoryWalker { @@ -241,7 +262,7 @@ import org.apache.commons.io.filefilter.TrueFileFilter; * </pre> * * @since 1.3 - * @version $Id$ + * */ public abstract class DirectoryWalker<T> { @@ -262,12 +283,13 @@ public abstract class DirectoryWalker<T> { } /** - * Construct an instance with a filter and limit the <i>depth</i> navigated to. + * Constructs an instance with a filter and limit the <i>depth</i> navigated to. * <p> * 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 {@code null} filter means that no * filtering should occur and all files and directories will be visited. + * </p> * * @param filter the filter to apply, null means visit all files * @param depthLimit controls how <i>deep</i> the hierarchy is @@ -279,13 +301,14 @@ public abstract class DirectoryWalker<T> { } /** - * Construct an instance with a directory and a file filter and an optional + * Constructs an instance with a directory and a file filter and an optional * limit on the <i>depth</i> navigated to. * <p> * 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 {@code null} filter means that no filtering should occur. + * </p> * * @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 @@ -311,10 +334,12 @@ public abstract class DirectoryWalker<T> { * <p> * 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. + * </p> * <p> * 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 <code>handle</code>. + * </p> * * @param startDirectory the directory to start from, not null * @param results the collection of result objects, may be updated @@ -379,6 +404,7 @@ public abstract class DirectoryWalker<T> { * 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. + * </p> * * @param file the current file being processed * @param depth the current file level (starting directory = 0) @@ -399,6 +425,7 @@ public abstract class DirectoryWalker<T> { * This method should be implemented by those subclasses that want to * provide a public <code>cancel()</code> method available from another * thread. The design pattern for the subclass should be as follows: + * </p> * <pre> * public class FooDirectoryWalker extends DirectoryWalker { * private volatile boolean cancelled = false; @@ -418,8 +445,10 @@ public abstract class DirectoryWalker<T> { * <p> * If this method returns true, then the directory walk is immediately * cancelled. The next callback method will be {@link #handleCancelled}. + * </p> * <p> * This implementation returns false. + * </p> * * @param file the file or directory being processed * @param depth the current directory level (starting directory = 0) @@ -439,6 +468,7 @@ public abstract class DirectoryWalker<T> { * obtained from the exception. * <p> * This implementation just re-throws the {@link CancelException}. + * </p> * * @param startDirectory the directory that the walk started from * @param results the collection of result objects, may be updated @@ -457,6 +487,7 @@ public abstract class DirectoryWalker<T> { * Overridable callback method invoked at the start of processing. * <p> * This implementation does nothing. + * </p> * * @param startDirectory the directory to start from * @param results the collection of result objects, may be updated @@ -472,8 +503,10 @@ public abstract class DirectoryWalker<T> { * 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. + * </p> * <p> * This implementation does nothing and returns true. + * </p> * * @param directory the current directory being processed * @param depth the current directory level (starting directory = 0) @@ -491,6 +524,7 @@ public abstract class DirectoryWalker<T> { * Overridable callback method invoked at the start of processing each directory. * <p> * This implementation does nothing. + * </p> * * @param directory the current directory being processed * @param depth the current directory level (starting directory = 0) @@ -506,6 +540,7 @@ public abstract class DirectoryWalker<T> { * Overridable callback method invoked with the contents of each directory. * <p> * This implementation returns the files unchanged + * </p> * * @param directory the current directory being processed * @param depth the current directory level (starting directory = 0) @@ -523,6 +558,7 @@ public abstract class DirectoryWalker<T> { * Overridable callback method invoked for each (non-directory) file. * <p> * This implementation does nothing. + * </p> * * @param file the current file being processed * @param depth the current directory level (starting directory = 0) @@ -537,6 +573,7 @@ public abstract class DirectoryWalker<T> { * Overridable callback method invoked for each restricted directory. * <p> * This implementation does nothing. + * </p> * * @param directory the restricted directory * @param depth the current directory level (starting directory = 0) @@ -552,6 +589,7 @@ public abstract class DirectoryWalker<T> { * Overridable callback method invoked at the end of processing each directory. * <p> * This implementation does nothing. + * </p> * * @param directory the directory being processed * @param depth the current directory level (starting directory = 0) @@ -567,6 +605,7 @@ public abstract class DirectoryWalker<T> { * Overridable callback method invoked at the end of processing. * <p> * This implementation does nothing. + * </p> * * @param results the collection of result objects, may be updated * @throws IOException if an I/O Error occurs @@ -617,7 +656,7 @@ public abstract class DirectoryWalker<T> { } /** - * Return the file when the operation was cancelled. + * Returns the file when the operation was cancelled. * * @return the file when the operation was cancelled */ @@ -626,7 +665,7 @@ public abstract class DirectoryWalker<T> { } /** - * Return the depth when the operation was cancelled. + * Returns the depth when the operation was cancelled. * * @return the depth when the operation was cancelled */