49 lines
2.8 KiB
Markdown
49 lines
2.8 KiB
Markdown
---
|
|
nav_order: 30
|
|
parent: Decision Records
|
|
---
|
|
# Use Apache Commons IO for directory monitoring
|
|
|
|
## Context and Problem Statement
|
|
|
|
In JabRef, there is a need to add a directory monitor that will listen for changes in a specified directory.
|
|
|
|
Currently, the monitor is used to automatically update the [LaTeX Citations](https://docs.jabref.org/advanced/entryeditor/latex-citations) when a LaTeX file in the LaTeX directory is created, removed, or modified ([#10585](https://github.com/JabRef/jabref/issues/10585)).
|
|
Additionally, this monitor will be used to create a dynamic group that mirrors the file system structure ([#10930](https://github.com/JabRef/jabref/issues/10930)).
|
|
|
|
## Considered Options
|
|
|
|
* Use [java.nio.file.WatchService](https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/nio/file/WatchService.html)
|
|
* Use [io.methvin.watcher.DirectoryWatcher](https://github.com/gmethvin/directory-watcher)
|
|
* Use [org.apache.commons.io.monitor](https://commons.apache.org/proper/commons-io/apidocs/org/apache/commons/io/monitor/package-summary.html)
|
|
|
|
## Decision Outcome
|
|
|
|
Chosen option: "Use [org.apache.commons.io.monitor](https://commons.apache.org/proper/commons-io/apidocs/org/apache/commons/io/monitor/package-summary.html)", because comes out best (see below).
|
|
|
|
## Pros and Cons of the Options
|
|
|
|
### java.nio.file.WatchService
|
|
|
|
* Good, because it is a standard Java API for watching directories.
|
|
* Good, because it does not need polling, it is event-based for most operating systems.
|
|
* Bad, because:
|
|
1. Does not detect files coming together with a new folder (JDK issue: [JDK-8162948](https://bugs.openjdk.org/browse/JDK-8162948)).
|
|
2. Deleting a subdirectory does not detect deleted files in that directory.
|
|
3. Access denied when trying to delete the recursively watched directory on Windows (JDK issue: [JDK-6972833](https://bugs.openjdk.org/browse/JDK-6972833)).
|
|
4. Implemented on macOS by the generic `PollingWatchService`. (JDK issue: [JDK-8293067](https://bugs.openjdk.org/browse/JDK-8293067))
|
|
|
|
### io.methvin.watcher.DirectoryWatcher
|
|
|
|
* Good, because it implemented on top of the `java.nio.file.WatchService`, which is a standard Java API for watching directories.
|
|
* Good, because it resolves some of the issues of the `java.nio.file.WatchService`.
|
|
* Uses`ExtendedWatchEventModifier.FILE_TREE` on Windows, which resolves issues (1, 3) of the `java.nio.file.WatchService`.
|
|
* On macOS have native implementation based on the Carbon File System Events API, this resolves issue (4) of the `java.nio.file.WatchService`.
|
|
* Bad, because issue (2) of the `java.nio.file.WatchService` is not resolved.
|
|
|
|
### org.apache.commons.io.monitor
|
|
|
|
* Good, because there are no observed issues.
|
|
* Good, because can handle huge amount of files without overflowing.
|
|
* Bad, because it uses a polling mechanism at fixed intervals, which can waste CPU cycles if no change occurs.
|