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
The following commit(s) were added to refs/heads/master by this push:
new 062eab5a0 Javadoc
062eab5a0 is described below
commit 062eab5a0a7dd3e18e69c26899133e77bb4dcfad
Author: Gary Gregory <garydgreg...@gmail.com>
AuthorDate: Tue Jan 30 08:33:23 2024 -0500
Javadoc
- Close HTML tags
- Add missing HTML tags
---
.../commons/io/monitor/FileAlterationObserver.java | 98 ++++++++++------------
1 file changed, 45 insertions(+), 53 deletions(-)
diff --git
a/src/main/java/org/apache/commons/io/monitor/FileAlterationObserver.java
b/src/main/java/org/apache/commons/io/monitor/FileAlterationObserver.java
index e862f36ee..34fe60e39 100644
--- a/src/main/java/org/apache/commons/io/monitor/FileAlterationObserver.java
+++ b/src/main/java/org/apache/commons/io/monitor/FileAlterationObserver.java
@@ -18,6 +18,7 @@ package org.apache.commons.io.monitor;
import java.io.File;
import java.io.FileFilter;
+import java.io.IOException;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.Arrays;
@@ -29,34 +30,32 @@ import java.util.stream.Stream;
import org.apache.commons.io.FileUtils;
import org.apache.commons.io.IOCase;
+import org.apache.commons.io.build.AbstractSupplier;
+import org.apache.commons.io.comparator.DefaultFileComparator;
import org.apache.commons.io.comparator.NameFileComparator;
import org.apache.commons.io.filefilter.TrueFileFilter;
/**
- * FileAlterationObserver represents the state of files below a root directory,
- * checking the file system and notifying listeners of create, change or
- * delete events.
+ * FileAlterationObserver represents the state of files below a root
directory, checking the file system and notifying listeners of create, change
or delete
+ * events.
* <p>
* To use this implementation:
+ * </p>
* <ul>
- * <li>Create {@link FileAlterationListener} implementation(s) that process
- * the file/directory create, change and delete events</li>
- * <li>Register the listener(s) with a {@link FileAlterationObserver} for
- * the appropriate directory.</li>
- * <li>Either register the observer(s) with a {@link FileAlterationMonitor}
or
- * run manually.</li>
+ * <li>Create {@link FileAlterationListener} implementation(s) that process
the file/directory create, change and delete events</li>
+ * <li>Register the listener(s) with a {@link FileAlterationObserver} for the
appropriate directory.</li>
+ * <li>Either register the observer(s) with a {@link FileAlterationMonitor} or
run manually.</li>
* </ul>
- *
- * <h2>Basic Usage</h2>
- * Create a {@link FileAlterationObserver} for the directory and register the
listeners:
+ * <h2>Basic Usage</h2> Create a {@link FileAlterationObserver} for the
directory and register the listeners:
* <pre>
* File directory = new File(FileUtils.current(), "src");
* FileAlterationObserver observer = new
FileAlterationObserver(directory);
* observer.addListener(...);
* observer.addListener(...);
* </pre>
- * To manually observe a directory, initialize the observer and invoked the
- * {@link #checkAndNotify()} method as required:
+ * <p>
+ * To manually observe a directory, initialize the observer and invoked the
{@link #checkAndNotify()} method as required:
+ * </p>
* <pre>
* // initialize
* observer.init();
@@ -69,8 +68,9 @@ import org.apache.commons.io.filefilter.TrueFileFilter;
* // finished
* observer.finish();
* </pre>
- * Alternatively, register the observer(s) with a {@link
FileAlterationMonitor},
- * which creates a new thread, invoking the observer at the specified interval:
+ * <p>
+ * Alternatively, register the observer(s) with a {@link
FileAlterationMonitor}, which creates a new thread, invoking the observer at
the specified interval:
+ * </p>
* <pre>
* long interval = ...
* FileAlterationMonitor monitor = new FileAlterationMonitor(interval);
@@ -79,21 +79,16 @@ import org.apache.commons.io.filefilter.TrueFileFilter;
* ...
* monitor.stop();
* </pre>
- *
- * <h2>File Filters</h2>
- * This implementation can monitor portions of the file system
- * by using {@link FileFilter}s to observe only the files and/or directories
- * that are of interest. This makes it more efficient and reduces the
- * noise from <i>unwanted</i> file system events.
+ * <h2>File Filters</h2> This implementation can monitor portions of the file
system by using {@link FileFilter}s to observe only the files and/or directories
+ * that are of interest. This makes it more efficient and reduces the noise
from <i>unwanted</i> file system events.
* <p>
- * <a href="https://commons.apache.org/io/";>Commons IO</a> has a good range of
- * useful, ready-made
- * <a href="../filefilter/package-summary.html">File Filter</a>
+ * <a href="https://commons.apache.org/io/";>Commons IO</a> has a good range of
useful, ready-made <a href="../filefilter/package-summary.html">File Filter</a>
* implementations for this purpose.
+ * </p>
* <p>
- * For example, to only observe 1) visible directories and 2) files with a
".java" suffix
- * in a root directory called "src" you could set up a {@link
FileAlterationObserver} in the following
- * way:
+ * For example, to only observe 1) visible directories and 2) files with a
".java" suffix in a root directory called "src" you could set up a
+ * {@link FileAlterationObserver} in the following way:
+ * </p>
* <pre>
* // Create a FileFilter
* IOFileFilter directories = FileFilterUtils.and(
@@ -109,14 +104,13 @@ import org.apache.commons.io.filefilter.TrueFileFilter;
* observer.addListener(...);
* observer.addListener(...);
* </pre>
- *
* <h2>FileEntry</h2>
- * {@link FileEntry} represents the state of a file or directory, capturing
- * {@link File} attributes at a point in time. Custom implementations of
- * {@link FileEntry} can be used to capture additional properties that the
- * basic implementation does not support. The {@link FileEntry#refresh(File)}
- * method is used to determine if a file or directory has changed since the
last
- * check and stores the current state of the {@link File}'s properties.
+ * <p>
+ * {@link FileEntry} represents the state of a file or directory, capturing
{@link File} attributes at a point in time. Custom
+ * implementations of {@link FileEntry} can be used to capture additional
properties that the basic implementation does not support. The
+ * {@link FileEntry#refresh(File)} method is used to determine if a file or
directory has changed since the last check and stores the current state of the
+ * {@link File}'s properties.
+ * </p>
* <h2>Deprecating Serialization</h2>
* <p>
* <em>Serialization is deprecated and will be removed in 3.0.</em>
@@ -174,7 +168,7 @@ public class FileAlterationObserver implements Serializable
{
/**
* Constructs an observer for the specified directory and file filter.
*
- * @param directory the directory to observe
+ * @param directory the directory to observe
* @param fileFilter The file filter or null if none
*/
public FileAlterationObserver(final File directory, final FileFilter
fileFilter) {
@@ -182,12 +176,11 @@ public class FileAlterationObserver implements
Serializable {
}
/**
- * Constructs an observer for the specified directory, file filter and
- * file comparator.
+ * Constructs an observer for the specified directory, file filter and
file comparator.
*
- * @param directory the directory to observe.
+ * @param directory the directory to observe.
* @param fileFilter The file filter or null if none.
- * @param ioCase what case sensitivity to use comparing file names, null
means system sensitive.
+ * @param ioCase what case sensitivity to use comparing file names,
null means system sensitive.
*/
public FileAlterationObserver(final File directory, final FileFilter
fileFilter, final IOCase ioCase) {
this(new FileEntry(directory), fileFilter, ioCase);
@@ -196,7 +189,7 @@ public class FileAlterationObserver implements Serializable
{
/**
* Constructs an observer for the specified directory, file filter and
file comparator.
*
- * @param rootEntry the root directory to observe.
+ * @param rootEntry the root directory to observe.
* @param fileFilter The file filter or null if none.
* @param comparator how to compare files.
*/
@@ -211,9 +204,9 @@ public class FileAlterationObserver implements Serializable
{
/**
* Constructs an observer for the specified directory, file filter and
file comparator.
*
- * @param rootEntry the root directory to observe.
+ * @param rootEntry the root directory to observe.
* @param fileFilter The file filter or null if none.
- * @param ioCase what case sensitivity to use comparing file names, null
means system sensitive.
+ * @param ioCase what case sensitivity to use comparing file names,
null means system sensitive.
*/
protected FileAlterationObserver(final FileEntry rootEntry, final
FileFilter fileFilter, final IOCase ioCase) {
this(rootEntry, fileFilter, toComparator(ioCase));
@@ -232,7 +225,7 @@ public class FileAlterationObserver implements Serializable
{
* Constructs an observer for the specified directory and file filter.
*
* @param directoryName the name of the directory to observe
- * @param fileFilter The file filter or null if none
+ * @param fileFilter The file filter or null if none
*/
public FileAlterationObserver(final String directoryName, final FileFilter
fileFilter) {
this(new File(directoryName), fileFilter);
@@ -242,8 +235,8 @@ public class FileAlterationObserver implements Serializable
{
* Constructs an observer for the specified directory, file filter and
file comparator.
*
* @param directoryName the name of the directory to observe
- * @param fileFilter The file filter or null if none
- * @param ioCase what case sensitivity to use comparing file names, null
means system sensitive
+ * @param fileFilter The file filter or null if none
+ * @param ioCase what case sensitivity to use comparing file names,
null means system sensitive
*/
public FileAlterationObserver(final String directoryName, final FileFilter
fileFilter, final IOCase ioCase) {
this(new File(directoryName), fileFilter, ioCase);
@@ -284,9 +277,9 @@ public class FileAlterationObserver implements Serializable
{
/**
* Compares two file lists for files which have been created, modified or
deleted.
*
- * @param parent The parent entry
+ * @param parent The parent entry
* @param previous The original list of files
- * @param files The current list of files
+ * @param files The current list of files
*/
private void checkAndNotify(final FileEntry parent, final FileEntry[]
previous, final File[] files) {
int c = 0;
@@ -318,7 +311,7 @@ public class FileAlterationObserver implements Serializable
{
* Creates a new file entry for the specified file.
*
* @param parent The parent file entry
- * @param file The file to create an entry for
+ * @param file The file to create an entry for
* @return A new file entry
*/
private FileEntry createFileEntry(final FileEntry parent, final File file)
{
@@ -372,7 +365,7 @@ public class FileAlterationObserver implements Serializable
{
/**
* Lists the files in {@code file}.
*
- * @param file The file to list files for
+ * @param file The file to list files for
* @param entry the parent entry
* @return The child files
*/
@@ -387,7 +380,7 @@ public class FileAlterationObserver implements Serializable
{
* Fires directory/file change events to the registered listeners.
*
* @param entry The previous file system entry
- * @param file The current file
+ * @param file The current file
*/
private void doMatch(final FileEntry entry, final File file) {
if (entry.refresh(file)) {
@@ -444,8 +437,7 @@ public class FileAlterationObserver implements Serializable
{
* Lists the contents of a directory
*
* @param directory The directory to list.
- * @return the directory contents or a zero length array if
- * the empty or the file is not a directory
+ * @return the directory contents or a zero length array if the empty or
the file is not a directory
*/
private File[] listFiles(final File directory) {
File[] children = null;
