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-jci.git
The following commit(s) were added to refs/heads/master by this push:
new d4d942e Fix Javadoc warnings in the commons-jci2-fam module
d4d942e is described below
commit d4d942efaecae164dd7e6dccec4cea1f7e5796e1
Author: Gary Gregory <[email protected]>
AuthorDate: Sun Nov 16 09:44:10 2025 -0500
Fix Javadoc warnings in the commons-jci2-fam module
---
.../AbstractFilesystemAlterationListener.java | 60 ++++++++++++++++---
.../fam/monitor/FilesystemAlterationListener.java | 69 ++++++++++++++++++----
.../fam/monitor/FilesystemAlterationMonitor.java | 30 +++++++++-
.../fam/monitor/FilesystemAlterationObserver.java | 36 ++++++++---
.../monitor/FilesystemAlterationObserverImpl.java | 5 ++
5 files changed, 169 insertions(+), 31 deletions(-)
diff --git
a/fam/src/main/java/org/apache/commons/jci2/fam/listeners/AbstractFilesystemAlterationListener.java
b/fam/src/main/java/org/apache/commons/jci2/fam/listeners/AbstractFilesystemAlterationListener.java
index c7897e7..ca3e1f9 100644
---
a/fam/src/main/java/org/apache/commons/jci2/fam/listeners/AbstractFilesystemAlterationListener.java
+++
b/fam/src/main/java/org/apache/commons/jci2/fam/listeners/AbstractFilesystemAlterationListener.java
@@ -27,8 +27,7 @@ import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
/**
- * AbstractFilesystemAlterationListener provides some convenience methods
helping to
- * implement a FilesystemAlterationListener.
+ * Provides convenience methods helping to implement a {@link
FilesystemAlterationListener}.
*/
public abstract class AbstractFilesystemAlterationListener implements
FilesystemAlterationListener {
@@ -48,6 +47,16 @@ public abstract class AbstractFilesystemAlterationListener
implements Filesystem
private final Signal eventSignal = new Signal();
private final Signal checkSignal = new Signal();
+ /**
+ * Constructs a new instance.
+ */
+ public AbstractFilesystemAlterationListener() {
+ // empty
+ }
+
+ /**
+ * The observer called on file changes.
+ */
protected FilesystemAlterationObserver observer;
@Override
@@ -76,46 +85,75 @@ public abstract class AbstractFilesystemAlterationListener
implements Filesystem
deletedFiles.add(pFile);
}
+ /**
+ * Gets the changed directories.
+ *
+ * @return the changed directories.
+ */
public Collection<File> getChangedDirectories() {
return changedDirectories;
}
+ /**
+ * Gets the changed files.
+ *
+ * @return the changed files.
+ */
public Collection<File> getChangedFiles() {
return changedFiles;
}
+ /**
+ * Gets the changed directories.
+ *
+ * @return the changed directories.
+ */
public Collection<File> getCreatedDirectories() {
return createdDirectories;
}
+ /**
+ * Gets the changed files.
+ *
+ * @return the changed files.
+ */
public Collection<File> getCreatedFiles() {
return createdFiles;
}
+ /**
+ * Gets the deleted directories.
+ *
+ * @return the deleted directories.
+ */
public Collection<File> getDeletedDirectories() {
return deletedDirectories;
}
+ /**
+ * Gets the deleted files.
+ *
+ * @return the deleted files.
+ */
public Collection<File> getDeletedFiles() {
return deletedFiles;
}
+ /**
+ * Notifies the internal signal if enabled.
+ */
protected void signals() {
if (!createdFiles.isEmpty() || !createdDirectories.isEmpty() ||
!changedFiles.isEmpty() || !changedDirectories.isEmpty() ||
!deletedFiles.isEmpty() || !deletedDirectories.isEmpty()) {
-
log.debug("event signal");
-
- synchronized(eventSignal) {
+ synchronized (eventSignal) {
eventSignal.triggered = true;
eventSignal.notifyAll();
}
}
-
log.debug("check signal");
-
- synchronized(checkSignal) {
+ synchronized (checkSignal) {
checkSignal.triggered = true;
checkSignal.notifyAll();
}
@@ -124,7 +162,6 @@ public abstract class AbstractFilesystemAlterationListener
implements Filesystem
@Override
public void onStart( final FilesystemAlterationObserver pObserver ) {
observer = pObserver;
-
createdFiles.clear();
changedFiles.clear();
deletedFiles.clear();
@@ -139,6 +176,11 @@ public abstract class AbstractFilesystemAlterationListener
implements Filesystem
observer = null;
}
+ /**
+ * Waits of the signal to be triggered.
+ *
+ * @throws Exception Throws on timeout.
+ */
public void waitForEvent() throws Exception {
synchronized(eventSignal) {
eventSignal.triggered = false;
diff --git
a/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationListener.java
b/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationListener.java
index 4786021..8e14fea 100644
---
a/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationListener.java
+++
b/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationListener.java
@@ -20,18 +20,65 @@ package org.apache.commons.jci2.fam.monitor;
import java.io.File;
/**
- * A listener that receives events of filesystem modifications.
- * The observer basically represents the source of the events.
- * The file root and its state. (see FilesystemAlterationObserver)
+ * A listener that receives events of file system modifications. The observer
basically represents the source of the events. The file root and its state.
+ *
+ * @see FilesystemAlterationObserver
*/
public interface FilesystemAlterationListener {
- void onStart( final FilesystemAlterationObserver pObserver );
- void onFileCreate( final File pFile );
- void onFileChange( final File pFile );
- void onFileDelete( final File pFile );
- void onDirectoryCreate( final File pDir );
- void onDirectoryChange( final File pDir );
- void onDirectoryDelete( final File pDir );
- void onStop( final FilesystemAlterationObserver pObserver );
+ /**
+ * Receives notification that we are starting to observe.
+ *
+ * @param observer the observer.
+ */
+ void onStart(final FilesystemAlterationObserver observer);
+
+ /**
+ * Receives notification that a file was created.
+ *
+ * @param file the file.
+ */
+ void onFileCreate(final File file);
+
+ /**
+ * Receives notification that a file was changed.
+ *
+ * @param file the file.
+ */
+ void onFileChange(final File file);
+
+ /**
+ * Receives notification that a file was deleted.
+ *
+ * @param file the file.
+ */
+ void onFileDelete(final File file);
+
+ /**
+ * Receives notification that a directory was created.
+ *
+ * @param directory the directory.
+ */
+ void onDirectoryCreate(final File directory);
+
+ /**
+ * Receives notification that a directory was changed.
+ *
+ * @param directory the directory.
+ */
+ void onDirectoryChange(final File directory);
+
+ /**
+ * Receives notification that a directory was deleted.
+ *
+ * @param directory the directory.
+ */
+ void onDirectoryDelete(final File directory);
+
+ /**
+ * Receives notification that we are stopping to observe.
+ *
+ * @param observer the observer.
+ */
+ void onStop(final FilesystemAlterationObserver observer);
}
diff --git
a/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationMonitor.java
b/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationMonitor.java
index c96ff09..560cfc6 100644
---
a/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationMonitor.java
+++
b/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationMonitor.java
@@ -26,8 +26,7 @@ import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
/**
- * It's a runnable that spawns of a monitoring thread triggering the
- * the observers and managing the their listeners.
+ * Spawns of a monitoring thread triggering the the observers and managing the
their listeners.
*/
public final class FilesystemAlterationMonitor implements Runnable {
@@ -42,9 +41,15 @@ public final class FilesystemAlterationMonitor implements
Runnable {
private volatile boolean running = true;
+ /**
+ * Constructs a new instance.
+ */
public FilesystemAlterationMonitor() {
}
+ /**
+ * Starts the internal thread.
+ */
public void start() {
thread = new Thread(this);
thread.setName("Filesystem Alteration Monitor");
@@ -52,9 +57,11 @@ public final class FilesystemAlterationMonitor implements
Runnable {
thread.start();
}
+ /**
+ * Joins the internal running thread.
+ */
public void stop() {
running = false;
-
if (thread != null) {
try {
thread.join(delay);
@@ -72,6 +79,12 @@ public final class FilesystemAlterationMonitor implements
Runnable {
delay = pDelay;
}
+ /**
+ * Adds the given listener for the given file.
+ *
+ * @param pRoot The file to observe.
+ * @param pListener The listener.
+ */
public void addListener( final File pRoot, final
FilesystemAlterationListener pListener ) {
FilesystemAlterationObserver observer;
@@ -90,6 +103,11 @@ public final class FilesystemAlterationMonitor implements
Runnable {
observer.addListener(pListener);
}
+ /**
+ * Removes the given listener.
+ *
+ * @param pListener The listener to remove.
+ */
public void removeListener( final FilesystemAlterationListener pListener )
{
synchronized (observersLock) {
for (final FilesystemAlterationObserver observer :
observers.values()) {
@@ -99,6 +117,12 @@ public final class FilesystemAlterationMonitor implements
Runnable {
}
}
+ /**
+ * Gets the array of listeners for the given file.
+ *
+ * @param pRoot the file to query.
+ * @return the array of listeners for the given file or an empty array.
+ */
public FilesystemAlterationListener[] getListenersFor( final File pRoot )
{
final FilesystemAlterationObserver observer = observers.get(pRoot);
diff --git
a/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationObserver.java
b/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationObserver.java
index 229bd0b..7f5ac17 100644
---
a/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationObserver.java
+++
b/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationObserver.java
@@ -20,20 +20,40 @@ package org.apache.commons.jci2.fam.monitor;
import java.io.File;
/**
- * FilesystemAlterationObserver represents the state of files
- * below a certain root directory. It implements the code to
- * check the filesystem and notify listeners.
+ * Represents the state of files below a certain root directory. Implementors
check the file system and notify listeners.
*/
public interface FilesystemAlterationObserver {
+ /**
+ * Gets the root directory.
+ *
+ * @return the root directory.
+ */
File getRootDirectory();
+ /**
+ * Notifies listeners.
+ */
void checkAndNotify();
- void addListener( final FilesystemAlterationListener pListener );
-
- void removeListener( final FilesystemAlterationListener pListener );
-
+ /**
+ * Add a listener.
+ *
+ * @param listener a listener.
+ */
+ void addListener(final FilesystemAlterationListener listener);
+
+ /**
+ * Removes the given listener.
+ *
+ * @param listener a listener
+ */
+ void removeListener(final FilesystemAlterationListener listener);
+
+ /**
+ * Gets listeners.
+ *
+ * @return The listeners.
+ */
FilesystemAlterationListener[] getListeners();
-
}
\ No newline at end of file
diff --git
a/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationObserverImpl.java
b/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationObserverImpl.java
index be50361..f967eb5 100644
---
a/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationObserverImpl.java
+++
b/fam/src/main/java/org/apache/commons/jci2/fam/monitor/FilesystemAlterationObserverImpl.java
@@ -242,6 +242,11 @@ public class FilesystemAlterationObserverImpl implements
FilesystemAlterationObs
private FilesystemAlterationListener[] listeners = {};
private final Set<FilesystemAlterationListener> listenersSet = new
HashSet<>();
+ /**
+ * Constructs a new instance.
+ *
+ * @param pRootDirectory The root directory to observe.
+ */
public FilesystemAlterationObserverImpl( final File pRootDirectory ) {
rootDirectory = pRootDirectory;
rootEntry = new Entry(new MonitorFileImpl(pRootDirectory));
