A Java file watcher that works across platforms and supports recursion, single file watches, and tries to make sure no events are missed.
Features:
Planned features:
Import dependency in pom.xml:
<dependency>
<groupId>engineering.swat</groupId>
<artifactId>java-watch</artifactId>
<version>${java-watch-version}</version>
</dependency>
Start using java-watch:
var directory = Path.of("tmp", "test-dir");
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 -> {
System.err.println(watchEvent);
});
try(var active = watcherSetup.start()) {
System.out.println("Monitoring files, press any key to stop");
System.in.read();
}
// after active.close(), the watch is stopped and
// no new events will be scheduled on the threadpool
On all platforms except macOS, the library internally uses the JDK default implementation of the Java NIO WatchService API.
On macOS, the library internally uses our custom WatchService implementation based on macOS's native FSEvents 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.
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.
The following section describes the related work research on the libraries and underlying limitations.
After reading the documentation of the following discussion on file system watches:
We can come to the following conclusion: file system watches are hard and have platform specific limitations. In summary:
OS API file directory recursive directory overflow network notes WindowsReadDirectoryChangesW ❌ ✅ ✅ generic error marker some, error in case not supported hard to correctly setup (there are multiple ways to get updates), can be chatty with it's events. can lock the directory it's monitoring. Linux inotify ✅ ✅ ❌ generic error marker only local changes, no error note that the new fanotify supports recursive watches, but only at mount points, not for arbitrary directories. macOS & BSD kqueue ? ✅ ❌ can quickly run out of file descriptors ? implementing recursive directory watches this way will quickly run out of file descriptors macOS FSEvents ✅ ✅ ✅ generic error marker ? Some report it works great, but openjdk stopped doing this direction of the implementation as it consistently failed a test with a lot of IO operations and register and unregisters of watches. Reporting that the API would just stop reporting any events
To avoid licensing conflicts we have not read the source code of any of these libraries/frameworks. The related work study is based purely on public documentation and discussions.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4