WatchService

## The lifecycle in detail WatchService follows a deliberate **state machine** on its keys, and getting the loop right is the heart of using it correctly. ### Step 1 — Create the service ```java WatchService ws = FileSystems.getDefault().newWatchService(); ``` A `WatchService` is a closeable resource backed by native OS handles, so it belongs in a try-with-resources or must be explicitly `close()`d. ### Step 2 — Register a directory ```java Path dir = Paths.get("/var/inbox"); WatchKey key = dir.register(ws, StandardWatchEventKinds.ENTRY_CREATE, StandardWatchEventKinds.ENTRY_MODIFY, StandardWatchEventKinds.ENTRY_DELETE); ``` `register` is a method on **Path**, taking the service and a varargs of **event kinds**. It returns a **WatchKey** representing this registration. Re-registering the same directory updates the existing key's event set rather than creating a duplicate. ### The WatchKey state machine A WatchKey is always in one of three states: - **Ready** — registered and waiting; events accumulate but the key is not yet queued to the service. - **Signalled** — at least one event is pending; the key has been queued so `take()`/`poll()` can return it. Crucially, **once signalled it stays signalled** and will not be re-queued for new events until you reset it. - **Invalid** — no longer watching (directory deleted, key cancelled, or service closed). ### Step 3 — Retrieve a signalled key Three retrieval methods on the service: - `take()` — **blocks** until a key is signalled (like a blocking queue's take). Throws `InterruptedException`. - `poll()` — returns a signalled key immediately, or `null` if none. - `poll(long timeout, TimeUnit unit)` — waits up to the timeout, then returns `null`. ### Step 4 — Drain the events ```java for (WatchEvent<?> event : key.pollEvents()) { WatchEvent.Kind<?> kind = event.kind(); if (kind == StandardWatchEventKinds.OVERFLOW) { /* re-scan, continue */ } Path name = (Path) event.context(); // file name relative to dir Path full = dir.resolve(name); // absolute/resolved path } ``` `pollEvents()` **retrieves and removes** the pending events for that key (it drains the queue). Each `WatchEvent` carries a `kind()`, a `count()` (repeat count for coalesced events), and a `context()` (the entry name as a Path **relative to the watched directory** — resolve it against the dir to get the real path). ### Step 5 — reset() (the critical step) ```java boolean valid = key.reset(); if (!valid) { // directory inaccessible / key no longer valid → stop watching it } ``` `reset()` transitions the key from **signalled** back to **ready**, so it can be queued again for future events. **This is the single most common mistake:** if you do not call reset(), the key stays signalled, never gets re-queued, and your loop blocks forever on the next `take()` even though files keep changing. reset() returns `false` if the key is no longer valid — that is your cue to remove it from any map of watched directories and stop processing it. ### The canonical loop ```java for (;;) { WatchKey key = ws.take(); // 3: block for (WatchEvent<?> e : key.pollEvents()) { /* 4: handle */ } if (!key.reset()) break; // 5: re-arm or exit } ``` ### Cleanup When done, `ws.close()` releases the native resources and invalidates all keys; an active `take()` will then throw `ClosedWatchServiceException`. You can also stop watching one directory with `key.cancel()` without closing the whole service. ## Why reset() exists at all The signalled-until-reset design lets you safely drain a key's events on one thread while the service keeps accumulating new events behind it; resetting is your explicit acknowledgement that you have consumed the batch and are ready for the next. It mirrors the ack pattern of message queues.