Improved macOS support

.github/workflows/build.yaml

@@ -6,15 +6,23 @@ on:
   pull_request:
     branches:
       - main
+      - improved-macos-support-main
 
 jobs:
   test:
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os:
+          - image: ubuntu-latest
+          - image: macos-latest
+            mac-backend: jdk
+          - image: macos-latest
+            mac-backend: fsevents
+          - image: windows-latest
         jdk: [11, 17, 21]
+
       fail-fast: false
-    runs-on: ${{ matrix.os }}
+    runs-on: ${{ matrix.os.image }}
     steps:
       - uses: actions/checkout@v4
       - run: echo " " >> pom.xml # make sure the cache is slightly different for these runners
@@ -26,7 +34,7 @@ jobs:
           cache: 'maven'
 
       - name: test
-        run: mvn -B clean test
+        run: mvn -B clean test "-Dwatch.mac.backend=${{ matrix.os.mac-backend }}"
         env:
           DELAY_FACTOR: 3
 

README.md

@@ -3,15 +3,18 @@
 [![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.
+A Java file watcher that works across platforms and supports recursion, single file watches, and tries to make sure no events are missed.
 
 ## Features
 
 Features:
 
 - monitor a single file (or directory) for changes
-- monitor a directory for changes to its direct descendants
+- monitor a directory for changes to its direct children
 - monitor a directory for changes for all its descendants (aka recursive directory watch)
+- backends supported:
+  - the JDK [`WatchService`](https://docs.oracle.com/javase/8/docs/api/java/nio/file/WatchService.html) API on any platform
+  - the native [FSEvents](https://developer.apple.com/documentation/coreservices/file_system_events) API on macOS
 - edge cases dealt with:
   - recursive watches will also continue in new directories
   - multiple watches for the same directory are merged to avoid overloading the kernel
@@ -21,7 +24,6 @@ Features:
 
 Planned features:
 
-- Avoid poll based watcher in macOS/OSX that only detects changes every 2 seconds (see [#4](https://github.com/SWAT-engineering/java-watch/issues/4))
 - 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)
 
@@ -58,6 +60,14 @@ try(var active = watcherSetup.start()) {
 // no new events will be scheduled on the threadpool
 ```
 
+## Backends
+
+On all platforms except macOS, the library internally uses the JDK default implementation of the Java NIO [`WatchService`](https://docs.oracle.com/javase/8/docs/api/java/nio/file/WatchService.html) API.
+
+On macOS, the library internally uses our custom `WatchService` implementation based on macOS's native [FSEvents](https://developer.apple.com/documentation/coreservices/file_system_events) API.
+Generally, it offers better performance than the JDK default implementation (because the latter uses a polling loop to detect changes at fixed time intervals).
+To force the library to use the JDK default implementation on macOS, set system property `engineering.swat.java-watch.mac` to `jdk`.
+
 ## Related work
 
 Before starting this library, we wanted to use existing libraries, but they all lacked proper support for recursive file watches, single file watches or lacked configurability. This library now has a growing collection of tests and a small API that should allow for future improvements without breaking compatibility.

pom.xml

@@ -74,8 +74,10 @@
     <checkerframework.version>3.49.2</checkerframework.version>
     <junit.version>5.12.2</junit.version>
     <log4j.version>2.24.3</log4j.version>
+    <jna.version>5.16.0</jna.version>
     <maven.compiler.source>11</maven.compiler.source>
     <maven.compiler.target>11</maven.compiler.target>
+    <watch.mac.backend>fsevents</watch.mac.backend>
   </properties>
 
   <build>
@@ -103,6 +105,9 @@
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-surefire-plugin</artifactId>
         <version>3.5.3</version>
+        <configuration>
+          <argLine>@{argLine} -Dengineering.swat.java-watch.mac=${watch.mac.backend}</argLine>
+        </configuration>
       </plugin>
       <plugin> <!-- code coverage -->
         <groupId>org.jacoco</groupId>
@@ -223,6 +228,16 @@
       <version>${log4j.version}</version>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>net.java.dev.jna</groupId>
+      <artifactId>jna</artifactId>
+      <version>${jna.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>net.java.dev.jna</groupId>
+      <artifactId>jna-platform</artifactId>
+      <version>${jna.version}</version>
+    </dependency>
   </dependencies>
 
   <profiles>

src/main/checkerframework/nio-file.astub

@@ -0,0 +1,14 @@
+package java.nio.file;
+
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+public interface WatchService {
+    @Nullable WatchKey poll();
+
+    @Nullable WatchKey poll(long timeout, TimeUnit unit)
+        throws InterruptedException;
+}
+
+public interface WatchEvent<T> {
+    @Nullable T context();
+}

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

@@ -34,9 +34,11 @@
 import java.io.Closeable;
 import java.io.IOException;
 import java.nio.file.FileSystems;
+import java.nio.file.Path;
 import java.nio.file.WatchEvent;
 import java.nio.file.WatchKey;
 import java.nio.file.WatchService;
+import java.nio.file.Watchable;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
@@ -53,6 +55,7 @@
 
 import com.sun.nio.file.ExtendedWatchEventModifier;
 
+import engineering.swat.watch.impl.mac.MacWatchService;
 import engineering.swat.watch.impl.util.SubscriptionKey;
 
 /**
@@ -73,7 +76,7 @@
 
     static {
         try {
-            service = FileSystems.getDefault().newWatchService();
+            service = Platform.get().newWatchService();
         } catch (IOException e) {
             throw new RuntimeException("Could not start watcher", e);
         }
@@ -121,12 +124,13 @@
         try {
             return CompletableFuture.supplyAsync(() -> {
                 try {
+                    Watchable watchable = Platform.get().newWatchable(path.getPath());
                     WatchEvent.Kind<?>[] kinds = new WatchEvent.Kind[]{ ENTRY_CREATE, ENTRY_MODIFY, OVERFLOW, ENTRY_DELETE };
                     if (path.isRecursive()) {
-                        return path.getPath().register(service, kinds, ExtendedWatchEventModifier.FILE_TREE);
+                        return watchable.register(service, kinds, ExtendedWatchEventModifier.FILE_TREE);
                     }
                     else {
-                        return path.getPath().register(service, kinds);
+                        return watchable.register(service, kinds);
                     }
                 } catch (IOException e) {
                     throw new RuntimeException(e);
@@ -156,4 +160,56 @@
             throw new IOException("The registration was canceled");
         }
     }
+
+    private static interface Platform {
+        WatchService newWatchService() throws IOException;
+        Watchable newWatchable(Path path);
+
+        static final Platform MAC = new Platform() {
+            @Override
+            public WatchService newWatchService() throws IOException {
+                return new MacWatchService();
+            }
+            @Override
+            public Watchable newWatchable(Path path) {
+                return MacWatchService.newWatchable(path);
+            }
+        };
+
+        static final Platform DEFAULT = new Platform() {
+            @Override
+            public WatchService newWatchService() throws IOException {
+                return FileSystems.getDefault().newWatchService();
+            }
+            @Override
+            public Watchable newWatchable(Path path) {
+                return path;
+            }
+        };
+
+        static final Platform CURRENT = current(); // Assumption: the platform doesn't change
+
+        private static Platform current() {
+            if (com.sun.jna.Platform.isMac()) {
+                var key = "engineering.swat.java-watch.mac";
+                var val = System.getProperty(key);
+                if (val != null) {
+                    if (val.equals("fsevents")) {
+                        return MAC;
+                    } else if (val.equals("jdk")) {
+                        return DEFAULT;
+                    } else {
+                        logger.warn("Unexpected value \"{}\" for system property \"{}\". Using value \"jdk\" instead.", val, key);
+                        return DEFAULT;
+                    }
+                }
+            }
+
+            return DEFAULT;
+        }
+
+        static Platform get() {
+            return CURRENT;
+        }
+    }
 }