Why register method in Path class returns WatchKey? (Watch Service Api, Java SE 7)

Question

Watching Service api (https://docs.oracle.com/javase/tutorial/essential/io/notification.html) looks little bit complicated and counter-intuitive. So I'm confused how to use it right. Lets follow the guide from the url above.

WatchService watcher = FileSystems.getDefault().newWatchService();
Paths.get("C:/Path").register(watcher, 
  ENTRY_CREATE, 
  ENTRY_DELETE, 
  ENTRY_MODIFY) //return WatchKey object

register method returns WatchKey object. In the guides it usually omitted. Its very strange. How can use it? What is a reson in its returning from register? Because normal way of getting WatchKey looks like that:

for (;;) {
    // wait for key to be signaled
    WatchKey key;
    try {
        key = watcher.take();
    } catch (InterruptedException x) {
        return;
    }

    for (WatchEvent<?> event: key.pollEvents()) {
        WatchEvent.Kind<?> kind = event.kind();

        //procees all kinds of events there
        if (kind == OVERFLOW) {
            continue;
        }
    }
    boolean valid = key.reset();
    if (!valid) {
      break;
    }
}

Answer 1

You are right that a key is only useful when it has events, and this is usually done by polling the watcher. But I guess it is also possible to directly polling the keys periodically, without going through the watcher. The javadoc is not very clear on this.

The API is indeed a little hard to use. I made a utility class _FileMonitor, and if you read the source, correctly using watcher API is not trivial at all. You may consider using my utility class instead.