Merge branch 'main' into improved-macos-support-main

Author: sungshik

.github/dependabot.yml

@@ -0,0 +1,29 @@
+version: 2
+updates:
+- package-ecosystem: "maven"
+  directory: "/"
+  schedule:
+    interval: "monthly"
+  open-pull-requests-limit: 10
+  groups:
+    upstream-libs:
+      patterns:
+      - "*"
+      exclude-patterns:
+      - "*checkerframework*"
+      - "*maven.plugins*"
+    checker-framework:
+      patterns:
+      - "*checkerframework*"
+    maven-plugins:
+      patterns:
+      - "*maven.plugins*"
+
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "monthly"
+  groups:
+    gh-actions:
+      patterns:
+      - "*" # group all GH action upgrades in a single PR

.github/workflows/build.yaml

@@ -32,7 +32,7 @@ jobs:
           DELAY_FACTOR: 3
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v5
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_ORG_TOKEN }}
 

README.md

@@ -1,4 +1,7 @@
 # java-watch
+[![Maven Central Version](https://img.shields.io/maven-central/v/engineering.swat/java-watch?style=flat-square&label=maven)](https://central.sonatype.com/artifact/engineering.swat/java-watch)
+[![javadoc](https://javadoc.io/badge2/engineering.swat/java-watch/docs.svg?style=flat-square)](https://javadoc.io/doc/engineering.swat/java-watch)
+[![Codecov](https://img.shields.io/codecov/c/github/SWAT-engineering/java-watch?style=flat-square)](https://codecov.io/gh/SWAT-engineering/java-watch)
 
 a java file watcher that works across platforms and supports recursion, single file watches, and tries to make sure no events are missed. Where possible it uses Java's NIO WatchService.
 
@@ -22,7 +25,7 @@ Planned features:
 - Support single file watches natively in linux (see [#11](https://github.com/SWAT-engineering/java-watch/issues/11))
 - Monitor only specific events (such as only CREATE events)
 
-[![codecov](https://codecov.io/gh/SWAT-engineering/java-watch/graph/badge.svg?token=XL29SDYAF0)](https://codecov.io/gh/SWAT-engineering/java-watch)
+
 
 ## Usage
 
@@ -40,7 +43,7 @@ Start using java-watch:
 
 ```java
 var directory = Path.of("tmp", "test-dir");
-var watcherSetup = Watcher.watch(directory, WatchScope.PATH_AND_CHILDREN)
+var watcherSetup = Watch.build(directory, WatchScope.PATH_AND_CHILDREN)
     .withExecutor(Executors.newCachedThreadPool()) // optionally configure a custom thread pool
     .onOverflow(Approximation.DIFF) // optionally configure a handler for overflows
     .on(watchEvent -> {

RELEASE-NOTES.md

@@ -0,0 +1,15 @@
+# Release notes for java-watch
+
+## 0.5.0 - 2025-04-15 - first release
+
+First version of java-watch. Included features:
+
+- Monitor changes at:
+  - single entry level
+  - directory level (only direct descendants)
+  - all descendants level
+- Handle `OVERFLOW` events:
+  - Yourself
+  - We generate events for all current entries on disk
+  - We keep track of changes in a map, and based on modification stamp generate a most likely events
+- extensive tests for Linux/Windows/OSX support

pom.xml

@@ -32,7 +32,7 @@
 
   <groupId>engineering.swat</groupId>
   <artifactId>java-watch</artifactId>
-  <version>0.5.0-RC5-SNAPSHOT</version>
+  <version>0.5.1-SNAPSHOT</version>
   <packaging>jar</packaging>
 
   <name>${project.groupId}:${project.artifactId}</name>
@@ -71,9 +71,9 @@
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <checkerframework.version>3.42.0</checkerframework.version>
-    <junit.version>5.10.2</junit.version>
-    <log4j.version>2.23.0</log4j.version>
+    <checkerframework.version>3.49.2</checkerframework.version>
+    <junit.version>5.12.2</junit.version>
+    <log4j.version>2.24.3</log4j.version>
     <maven.compiler.source>11</maven.compiler.source>
     <maven.compiler.target>11</maven.compiler.target>
   </properties>
@@ -204,7 +204,7 @@
     <dependency>
       <groupId>org.awaitility</groupId>
       <artifactId>awaitility</artifactId>
-      <version>4.2.2</version>
+      <version>4.3.0</version>
       <scope>test</scope>
     </dependency>
     <dependency>
@@ -221,6 +221,7 @@
       <groupId>org.apache.logging.log4j</groupId>
       <artifactId>log4j-core</artifactId>
       <version>${log4j.version}</version>
+      <scope>test</scope>
     </dependency>
   </dependencies>
 
@@ -236,6 +237,7 @@
             <extensions>true</extensions>
             <configuration>
               <publishingServerId>central</publishingServerId>
+              <autoPublish>true</autoPublish>
             </configuration>
           </plugin>
           <plugin> <!-- sign jar for maven central-->

src/main/java/engineering/swat/watch/Watcher.java renamed to src/main/java/engineering/swat/watch/Watch.java

@@ -53,7 +53,7 @@
  * <p>It will avoid common errors using the raw apis, and will try to use the most native api where possible.</p>
  * Note, there are differences per platform that cannot be avoided, please review the readme of the library.
  */
-public class Watcher {
+public class Watch {
     private final Logger logger = LogManager.getLogger();
     private final Path path;
     private final WatchScope scope;
@@ -65,7 +65,7 @@ public class Watcher {
     private static final Predicate<WatchEvent> TRUE_FILTER = e -> true;
     private volatile Predicate<WatchEvent> eventFilter = TRUE_FILTER;
 
-    private Watcher(Path path, WatchScope scope) {
+    private Watch(Path path, WatchScope scope) {
         this.path = path;
         this.scope = scope;
     }
@@ -76,7 +76,7 @@ private Watcher(Path path, WatchScope scope) {
      * @param scope for directories you can also choose to monitor it's direct children or all it's descendants
      * @throws IllegalArgumentException in case a path is not supported (in relation to the scope)
      */
-    public static Watcher watch(Path path, WatchScope scope) {
+    public static Watch build(Path path, WatchScope scope) {
         if (!path.isAbsolute()) {
             throw new IllegalArgumentException("We can only watch absolute paths");
         }
@@ -95,7 +95,7 @@ public static Watcher watch(Path path, WatchScope scope) {
             default:
                 throw new IllegalArgumentException("Unsupported scope: " + scope);
         }
-        return new Watcher(path, scope);
+        return new Watch(path, scope);
     }
 
     /**
@@ -105,7 +105,7 @@ public static Watcher watch(Path path, WatchScope scope) {
      * @param eventHandler a callback that handles the watch event, will be called once per event.
      * @return this for optional method chaining
      */
-    public Watcher on(Consumer<WatchEvent> eventHandler) {
+    public Watch on(Consumer<WatchEvent> eventHandler) {
         if (this.eventHandler != EMPTY_HANDLER) {
             throw new IllegalArgumentException("on handler cannot be set more than once");
         }
@@ -116,7 +116,7 @@ public Watcher on(Consumer<WatchEvent> eventHandler) {
     /**
      * Convenience variant of {@link #on(Consumer)}, which allows you to only respond to certain events
      */
-    public Watcher on(WatchEventListener listener) {
+    public Watch on(WatchEventListener listener) {
         if (this.eventHandler != EMPTY_HANDLER) {
             throw new IllegalArgumentException("on handler cannot be set more than once");
         }
@@ -149,7 +149,7 @@ public Watcher on(WatchEventListener listener) {
      * ({@code true}) or dropped ({@code false})
      * @return {@code this} (to support method chaining)
      */
-    Watcher filter(Predicate<WatchEvent> predicate) {
+    Watch filter(Predicate<WatchEvent> predicate) {
         if (this.eventFilter != TRUE_FILTER) {
             throw new IllegalArgumentException("filter cannot be set more than once");
         }
@@ -163,7 +163,7 @@ Watcher filter(Predicate<WatchEvent> predicate) {
      * @param callbackHandler worker pool to use
      * @return this for optional method chaining
      */
-    public Watcher withExecutor(Executor callbackHandler) {
+    public Watch withExecutor(Executor callbackHandler) {
         this.executor = callbackHandler;
         return this;
     }
@@ -179,7 +179,7 @@ public Watcher withExecutor(Executor callbackHandler) {
      * files/directories to approximate
      * @return This watcher for optional method chaining
      */
-    public Watcher onOverflow(Approximation whichFiles) {
+    public Watch onOverflow(Approximation whichFiles) {
         this.approximateOnOverflow = whichFiles;
         return this;
     }

src/main/java/engineering/swat/watch/impl/jdk/JDKFileWatch.java

@@ -61,12 +61,9 @@ public JDKFileWatch(Path file, Executor exec,
         assert !parent.equals(file);
 
         this.internal = new JDKDirectoryWatch(parent, exec, (w, e) -> {
-            if (e.getKind() == WatchEvent.Kind.OVERFLOW) {
-                var overflow = new WatchEvent(WatchEvent.Kind.OVERFLOW, file);
-                eventHandler.accept(w, overflow);
-            }
-            if (fileName.equals(e.getRelativePath())) {
-                eventHandler.accept(w, e);
+            var kind = e.getKind();
+            if (kind == WatchEvent.Kind.OVERFLOW || e.getRelativePath().equals(fileName)) {
+                eventHandler.accept(w, new WatchEvent(kind, file));
             }
         }, eventFilter);
 

src/main/java/engineering/swat/watch/impl/overflows/IndexingRescanner.java

@@ -44,6 +44,7 @@
 
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
+import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 import engineering.swat.watch.WatchEvent;
@@ -59,7 +60,7 @@ public IndexingRescanner(Executor exec, Path path, WatchScope scope) {
         new Indexer(path, scope).walkFileTree(); // Make an initial scan to populate the index
     }
 
-    private static class PathMap<V> {
+    private static class PathMap<V extends @NonNull Object > {
         private final Map<Path, Map<Path, V>> values = new ConcurrentHashMap<>();
         //                ^^^^      ^^^^
         //                Parent    File name (regular file or directory)
@@ -85,7 +86,7 @@ public Set<Path> getFileNames(Path parent) {
             return apply(this::remove, p);
         }
 
-        private static <V> @Nullable V apply(BiFunction<Path, Path, @Nullable V> action, Path p) {
+        private static <V extends @Nullable Object> V apply(BiFunction<Path, Path, V> action, Path p) {
             var parent = p.getParent();
             var fileName = p.getFileName();
             if (parent != null && fileName != null) {

src/test/java/engineering/swat/watch/APIErrorsTests.java

@@ -61,8 +61,8 @@ static void setupEverything() {
     @Test
     void noDuplicateEvents() {
         assertThrowsExactly(IllegalArgumentException.class, () ->
-            Watcher
-                .watch(testDir.getTestDirectory(), WatchScope.PATH_AND_CHILDREN)
+            Watch
+                .build(testDir.getTestDirectory(), WatchScope.PATH_AND_CHILDREN)
                 .on(System.out::println)
                 .on(System.err::println)
         );
@@ -71,16 +71,16 @@ void noDuplicateEvents() {
     @Test
     void onlyDirectoryWatchingOnDirectories() {
         assertThrowsExactly(IllegalArgumentException.class, () ->
-            Watcher
-                .watch(testDir.getTestFiles().get(0), WatchScope.PATH_AND_CHILDREN)
+            Watch
+                .build(testDir.getTestFiles().get(0), WatchScope.PATH_AND_CHILDREN)
         );
     }
 
     @Test
     void doNotStartWithoutEventHandler() {
         assertThrowsExactly(IllegalStateException.class, () ->
-            Watcher
-                .watch(testDir.getTestDirectory(), WatchScope.PATH_AND_CHILDREN)
+            Watch
+                .build(testDir.getTestDirectory(), WatchScope.PATH_AND_CHILDREN)
                 .start()
         );
     }
@@ -90,8 +90,8 @@ void noRelativePaths() {
         var relativePath = testDir.getTestDirectory().resolve("d1").relativize(testDir.getTestDirectory());
 
         assertThrowsExactly(IllegalArgumentException.class, () ->
-            Watcher
-                .watch(relativePath, WatchScope.PATH_AND_CHILDREN)
+            Watch
+                .build(relativePath, WatchScope.PATH_AND_CHILDREN)
                 .start()
         );
     }
@@ -100,7 +100,7 @@ void noRelativePaths() {
     void nonExistingDirectory() throws IOException {
         var nonExistingDir = testDir.getTestDirectory().resolve("testd1");
         Files.createDirectory(nonExistingDir);
-        var w = Watcher.watch(nonExistingDir, WatchScope.PATH_AND_CHILDREN);
+        var w = Watch.build(nonExistingDir, WatchScope.PATH_AND_CHILDREN);
         Files.delete(nonExistingDir);
         assertThrowsExactly(IllegalStateException.class, w::start);
     }

src/test/java/engineering/swat/watch/DeleteLockTests.java

@@ -76,7 +76,7 @@ private static void recursiveDelete(Path target) throws IOException {
     }
 
     private void deleteAndVerify(Path target, WatchScope scope) throws IOException {
-        try (var watch = Watcher.watch(target, scope).on(ev -> {}).start()) {
+        try (var watch = Watch.build(target, scope).on(ev -> {}).start()) {
             recursiveDelete(target);
             assertFalse(Files.exists(target), "The file/directory shouldn't exist anymore");
         }