What is the Java WatchService API and what problem does it solve?

## The problem Applications often need to react when files appear, change, or vanish on disk: a build tool recompiling on edit, a server picking up dropped config files, an importer ingesting CSVs dropped into an inbox folder. The naive solution is **polling**: every few seconds, list the directory, compare it to a remembered snapshot, and diff. Polling is wasteful (it runs even when nothing changes), laggy (you only notice on the next tick), and it hammers the disk on large directories. ## What WatchService is `WatchService` is an interface in the `java.nio.file` package, added in **Java 7** as part of the **NIO.2** file API. It exposes the operating system's native file-change notification facility through a uniform Java API. On Linux it sits on top of **inotify**; on Windows it uses **ReadDirectoryChangesW**; on platforms with no native support (historically macOS) the JDK falls back to a polling implementation under the hood, so the API still works but is less efficient. ## Key vocabulary - **Path** — a `java.nio.file.Path` is an object representing a file or directory location (e.g. `Paths.get("/var/inbox")`). You register a *directory* Path, never a single file. - **WatchService** — the monitor object itself; created via `FileSystems.getDefault().newWatchService()`. - **WatchKey** — a token returned when you register a directory. It represents that registration and, when changes occur, becomes *signalled* and carries the pending events. - **WatchEvent** — one change: it has a *kind* (what happened) and a *context* (which file, as a Path relative to the watched directory). - **event kind** — `StandardWatchEventKinds.ENTRY_CREATE`, `ENTRY_MODIFY`, `ENTRY_DELETE`, plus the special `OVERFLOW`. ## How it works, step by step 1. **Create** the service: `WatchService ws = FileSystems.getDefault().newWatchService();` 2. **Register** a directory and the kinds you want: `Path dir = Paths.get("/var/inbox"); dir.register(ws, ENTRY_CREATE, ENTRY_MODIFY, ENTRY_DELETE);` This returns a WatchKey. 3. **Wait** for a key to be signalled. `ws.take()` blocks until a key has events; `ws.poll()` returns immediately (or `null`); `ws.poll(timeout, unit)` waits up to a bound. 4. **Drain** the events: `for (WatchEvent<?> ev : key.pollEvents()) { ... }`. Each event's `kind()` tells you what happened and `context()` gives the affected file name (relative to the watched dir). 5. **Reset** the key: `boolean valid = key.reset();` This re-arms the key so it can fire again. **If you skip reset(), you will never get further events for that directory.** `reset()` returns `false` when the key is no longer valid (e.g. the directory was deleted), at which point you should stop watching it. ## Why it beats polling With native backing, the OS pushes notifications to the JVM only when something actually changes, so an idle directory costs essentially nothing and you react near-instantly. Polling, by contrast, burns CPU and I/O on every tick regardless. ## Important limitations (interview-relevant) - **Not recursive.** Registering `/var/inbox` does NOT watch its subdirectories. To watch a tree you must walk it and register each directory, and register newly created subdirectories as you observe their ENTRY_CREATE events. - **Directory granularity.** You register directories, not individual files; you then filter events by `context()`. - **OVERFLOW.** If events arrive faster than you consume them, the service may emit a single `OVERFLOW` event meaning "some events were lost" — you should re-scan the directory to recover state. - **Platform variance.** Native on Linux/Windows; historically polling-based (so higher latency) on macOS. - **Duplicate/multiple MODIFY events.** A single logical save can produce several ENTRY_MODIFY events; consumers usually debounce. Put together, WatchService is the idiomatic, efficient way in modern Java to react to filesystem changes, with the cost of remembering to reset keys, handle OVERFLOW, and manage recursion yourself.