Merge pull request #37 from SWAT-engineering/feat/better-top-level-name

DavyLandman · web-flow · commit 0acdfcb0436c · 2025-04-15T15:53:35.000+02:00
Refactored top level name of the watcher function
diff --git a/README.md b/README.md
@@ -43,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 -> {
diff --git a/src/main/java/engineering/swat/watch/Watch.java b/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;
     }
diff --git a/src/test/java/engineering/swat/watch/APIErrorsTests.java b/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);
     }
diff --git a/src/test/java/engineering/swat/watch/DeleteLockTests.java b/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");
         }
diff --git a/src/test/java/engineering/swat/watch/RecursiveWatchTests.java b/src/test/java/engineering/swat/watch/RecursiveWatchTests.java
@@ -77,7 +77,7 @@ void newDirectoryWithFilesChangesDetected() throws IOException {
         var target = new AtomicReference<Path>();
         var created = new AtomicBoolean(false);
         var changed = new AtomicBoolean(false);
-        var watchConfig = Watcher.watch(testDir.getTestDirectory(), WatchScope.PATH_AND_ALL_DESCENDANTS)
+        var watchConfig = Watch.build(testDir.getTestDirectory(), WatchScope.PATH_AND_ALL_DESCENDANTS)
             .on(ev -> {
                     logger.debug("Event received: {}", ev);
                     if (ev.calculateFullPath().equals(target.get())) {
@@ -109,7 +109,7 @@ void newDirectoryWithFilesChangesDetected() throws IOException {
     void correctRelativePathIsReported() throws IOException {
         Path relative = Path.of("a","b", "c", "d.txt");
         var seen = new AtomicBoolean(false);
-        var watcher = Watcher.watch(testDir.getTestDirectory(), WatchScope.PATH_AND_ALL_DESCENDANTS)
+        var watcher = Watch.build(testDir.getTestDirectory(), WatchScope.PATH_AND_ALL_DESCENDANTS)
             .on(ev -> {
                 logger.debug("Seen event: {}", ev);
                 if (ev.getRelativePath().equals(relative)) {
@@ -134,7 +134,7 @@ void deleteOfFileInDirectoryShouldBeVisible() throws IOException {
             .findAny()
             .orElseThrow();
         var seen = new AtomicBoolean(false);
-        var watchConfig = Watcher.watch(target.getParent(), WatchScope.PATH_AND_CHILDREN)
+        var watchConfig = Watch.build(target.getParent(), WatchScope.PATH_AND_CHILDREN)
             .on(ev -> {
                 if (ev.getKind() == Kind.DELETED && ev.calculateFullPath().equals(target)) {
                     seen.set(true);
@@ -160,7 +160,7 @@ void overflowsAreRecoveredFrom(Approximation whichFiles) throws IOException, Int
         // Configure and start watch
         var dropEvents = new AtomicBoolean(false); // Toggles overflow simulation
         var bookkeeper = new TestHelper.Bookkeeper();
-        var watchConfig = Watcher.watch(parent, WatchScope.PATH_AND_ALL_DESCENDANTS)
+        var watchConfig = Watch.build(parent, WatchScope.PATH_AND_ALL_DESCENDANTS)
             .withExecutor(ForkJoinPool.commonPool())
             .filter(e -> !dropEvents.get())
             .onOverflow(whichFiles)
diff --git a/src/test/java/engineering/swat/watch/SingleDirectoryTests.java b/src/test/java/engineering/swat/watch/SingleDirectoryTests.java
@@ -71,7 +71,7 @@ void deleteOfFileInDirectoryShouldBeVisible() throws IOException {
         var target = testDir.getTestFiles().get(0);
         var seenDelete = new AtomicBoolean(false);
         var seenCreate = new AtomicBoolean(false);
-        var watchConfig = Watcher.watch(target.getParent(), WatchScope.PATH_AND_CHILDREN)
+        var watchConfig = Watch.build(target.getParent(), WatchScope.PATH_AND_CHILDREN)
             .on(ev -> {
                 if (ev.getKind() == Kind.DELETED && ev.calculateFullPath().equals(target)) {
                     seenDelete.set(true);
@@ -99,7 +99,7 @@ void alternativeAPITest() throws IOException {
         var target = testDir.getTestFiles().get(0);
         var seenDelete = new AtomicBoolean(false);
         var seenCreate = new AtomicBoolean(false);
-        var watchConfig = Watcher.watch(target.getParent(), WatchScope.PATH_AND_CHILDREN)
+        var watchConfig = Watch.build(target.getParent(), WatchScope.PATH_AND_CHILDREN)
             .on(new WatchEventListener() {
                 @Override
                 public void onCreated(WatchEvent ev) {
@@ -132,7 +132,7 @@ void memorylessRescanOnOverflow() throws IOException, InterruptedException {
         Files.writeString(directory.resolve("b.txt"), "bar");
 
         var bookkeeper = new TestHelper.Bookkeeper();
-        var watchConfig = Watcher.watch(directory, WatchScope.PATH_AND_CHILDREN)
+        var watchConfig = Watch.build(directory, WatchScope.PATH_AND_CHILDREN)
             .onOverflow(Approximation.ALL)
             .on(bookkeeper);
 
@@ -169,7 +169,7 @@ void indexingRescanOnOverflow() throws IOException, InterruptedException {
 
         var bookkeeper = new TestHelper.Bookkeeper();
         var dropEvents = new AtomicBoolean(false); // Toggles overflow simulation
-        var watchConfig = Watcher.watch(directory, WatchScope.PATH_AND_CHILDREN)
+        var watchConfig = Watch.build(directory, WatchScope.PATH_AND_CHILDREN)
             .filter(e -> !dropEvents.get())
             .onOverflow(Approximation.DIFF)
             .on(bookkeeper);
diff --git a/src/test/java/engineering/swat/watch/SingleFileTests.java b/src/test/java/engineering/swat/watch/SingleFileTests.java
@@ -71,7 +71,7 @@ void singleFileShouldNotTriggerOnOtherFilesInSameDir() throws IOException, Inter
         var target = testDir.getTestFiles().get(0);
         var seen = new AtomicBoolean(false);
         var others = new AtomicBoolean(false);
-        var watchConfig = Watcher.watch(target, WatchScope.PATH_ONLY)
+        var watchConfig = Watch.build(target, WatchScope.PATH_ONLY)
             .on(ev -> {
                 if (ev.calculateFullPath().equals(target)) {
                     seen.set(true);
@@ -100,7 +100,7 @@ void singleFileThatMonitorsOnlyADirectory() throws IOException, InterruptedExcep
         var target = testDir.getTestDirectory();
         var seen = new AtomicBoolean(false);
         var others = new AtomicBoolean(false);
-        var watchConfig = Watcher.watch(target, WatchScope.PATH_ONLY)
+        var watchConfig = Watch.build(target, WatchScope.PATH_ONLY)
             .on(ev -> {
                 if (ev.calculateFullPath().equals(target)) {
                     seen.set(true);
@@ -161,8 +161,8 @@ private ActiveWatch startWatchAndTriggerOverflow(Approximation whichFiles, TestH
         var parent = testDir.getTestDirectory();
         var file = parent.resolve("a.txt");
 
-        var watch = Watcher
-            .watch(file, WatchScope.PATH_ONLY)
+        var watch = Watch
+            .build(file, WatchScope.PATH_ONLY)
             .onOverflow(whichFiles)
             .on(bookkeeper)
             .start();
diff --git a/src/test/java/engineering/swat/watch/SmokeTests.java b/src/test/java/engineering/swat/watch/SmokeTests.java
@@ -65,7 +65,7 @@ static void setupEverything() {
     void watchDirectory() throws IOException {
         var changed = new AtomicBoolean(false);
         var target = testDir.getTestFiles().get(0);
-        var watchConfig = Watcher.watch(testDir.getTestDirectory(), WatchScope.PATH_AND_CHILDREN)
+        var watchConfig = Watch.build(testDir.getTestDirectory(), WatchScope.PATH_AND_CHILDREN)
             .on(ev -> {if (ev.getKind() == MODIFIED && ev.calculateFullPath().equals(target)) { changed.set(true); }})
             ;
 
@@ -82,7 +82,7 @@ void watchRecursiveDirectory() throws IOException {
             .filter(p -> !p.getParent().equals(testDir.getTestDirectory()))
             .findFirst()
             .orElseThrow();
-        var watchConfig = Watcher.watch(testDir.getTestDirectory(), WatchScope.PATH_AND_ALL_DESCENDANTS)
+        var watchConfig = Watch.build(testDir.getTestDirectory(), WatchScope.PATH_AND_ALL_DESCENDANTS)
             .on(ev -> { if (ev.getKind() == MODIFIED && ev.calculateFullPath().equals(target)) { changed.set(true);}})
             ;
 
@@ -100,7 +100,7 @@ void watchSingleFile() throws IOException {
             .findFirst()
             .orElseThrow();
 
-        var watchConfig = Watcher.watch(target, WatchScope.PATH_ONLY)
+        var watchConfig = Watch.build(target, WatchScope.PATH_ONLY)
             .on(ev -> {
                 if (ev.calculateFullPath().equals(target)) {
                     changed.set(true);
diff --git a/src/test/java/engineering/swat/watch/TortureTests.java b/src/test/java/engineering/swat/watch/TortureTests.java
@@ -153,7 +153,7 @@ void pressureOnFSShouldNotMissNewFilesAnything(Approximation whichFiles) throws
         var io = new IOGenerator(THREADS, root, pool);
 
         var seenCreates = ConcurrentHashMap.<Path>newKeySet();
-        var watchConfig = Watcher.watch(testDir.getTestDirectory(), WatchScope.PATH_AND_ALL_DESCENDANTS)
+        var watchConfig = Watch.build(testDir.getTestDirectory(), WatchScope.PATH_AND_ALL_DESCENDANTS)
             .withExecutor(pool)
             .onOverflow(whichFiles)
             .on(ev -> {
@@ -222,8 +222,8 @@ void manyRegistrationsForSamePath() throws InterruptedException, IOException {
         for (int t = 0; t < TORTURE_REGISTRATION_THREADS; t++) {
             var r = new Thread(() -> {
                 try {
-                    var watcher = Watcher
-                        .watch(testDir.getTestDirectory(), WatchScope.PATH_AND_CHILDREN)
+                    var watcher = Watch
+                        .build(testDir.getTestDirectory(), WatchScope.PATH_AND_CHILDREN)
                         .on(e -> seen.add(e.calculateFullPath()));
                     startRegistering.acquire();
                     try (var c = watcher.start()) {
@@ -294,8 +294,8 @@ void manyRegisterAndUnregisterSameTime(Approximation whichFiles) throws Interrup
                         var id = Thread.currentThread().getId();
                         startRegistering.acquire();
                         for (int k = 0; k < 1000; k++) {
-                            var watcher = Watcher
-                                .watch(testDir.getTestDirectory(), WatchScope.PATH_AND_CHILDREN)
+                            var watcher = Watch
+                                .build(testDir.getTestDirectory(), WatchScope.PATH_AND_CHILDREN)
                                 .onOverflow(whichFiles)
                                 .on(e -> {
                                     if (e.calculateFullPath().equals(target)) {
@@ -359,7 +359,7 @@ void pressureOnFSShouldNotMissDeletes(Approximation whichFiles) throws Interrupt
 
             final var events = new AtomicInteger(0);
             final var happened = new Semaphore(0);
-            var watchConfig = Watcher.watch(testDir.getTestDirectory(), WatchScope.PATH_AND_ALL_DESCENDANTS)
+            var watchConfig = Watch.build(testDir.getTestDirectory(), WatchScope.PATH_AND_ALL_DESCENDANTS)
                 .withExecutor(pool)
                 .onOverflow(whichFiles)
                 .on(ev -> {
diff --git a/src/test/java/engineering/swat/watch/impl/overflows/IndexingRescannerTests.java b/src/test/java/engineering/swat/watch/impl/overflows/IndexingRescannerTests.java
@@ -43,7 +43,7 @@
 import engineering.swat.watch.TestHelper;
 import engineering.swat.watch.WatchEvent;
 import engineering.swat.watch.WatchScope;
-import engineering.swat.watch.Watcher;
+import engineering.swat.watch.Watch;
 import engineering.swat.watch.impl.EventHandlingWatch;
 
 class IndexingRescannerTests {
@@ -74,7 +74,7 @@ void onlyEventsForFilesInScopeAreIssued() throws IOException, InterruptedExcepti
         // Configure a non-recursive directory watch that monitors only the
         // children (not all descendants) of `path`
         var eventsOnlyForChildren = new AtomicBoolean(true);
-        var watchConfig = Watcher.watch(path, WatchScope.PATH_AND_CHILDREN)
+        var watchConfig = Watch.build(path, WatchScope.PATH_AND_CHILDREN)
             .onOverflow(Approximation.NONE) // Disable the auto-handler here; we'll have an explicit one below
             .on(e -> {
                 if (e.getRelativePath().getNameCount() > 1) {

Original file line number	Diff line number	Diff line change
`@@ -76,7 +76,7 @@ private static void recursiveDelete(Path target) throws IOException {`
`76`	`76`	`}`
`77`	`77`
`78`	`78`	`private void deleteAndVerify(Path target, WatchScope scope) throws IOException {`
`79`		`- try (var watch = Watcher.watch(target, scope).on(ev -> {}).start()) {`
	`79`	`+ try (var watch = Watch.build(target, scope).on(ev -> {}).start()) {`
`80`	`80`	`recursiveDelete(target);`
`81`	`81`	`assertFalse(Files.exists(target), "The file/directory shouldn't exist anymore");`
`82`	`82`	`}`