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
*/
