java-watch
a java file watcher that works across platforms and supports recursion and single file watches
Related work
After reading the documentation of the following discussion on file system watches:
- Paul Millr's nodejs chokidar
- Enrico Maria Crisostomo's c++ fswatch/libfswatch
- work by rjeczalik in the go notify package
- Greg Methvin's java library directory-watcher
- Pathikrit Bhowmick's scala library better-files
- Java's documentation on a recursive file watcher
- openjdk's PR 10140/8293067 to try and use FSEventStream on macOS
- nodejs watch function caveats
- Overview in 2012 by regedit
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 |
|---|---|---|---|---|---|---|---|
| Windows | ReadDirectoryChangesW |
❌ | ✅ | ✅ | 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.