Summary

Define a new system property "jdk.nio.file.WatchService.maxEventsPerPoll" to set the maximum number of java.nio.file.WatchEvents which a java.nio.file.WatchService can emit before dropping events and emitting an OVERFLOW event.

Problem

There is presently a hard limit of 512 on the number of watch events which can be emitted before some events are discarded and an OVERFLOW event emitted. In some use cases this can become problematic, for example watching the contents of a very large repository.

Solution

Add a system property "jdk.nio.file.WatchService.maxEventsPerPoll" to control the maximum number of events allowed before discarding events and emitting an OVERFLOW event. The default value of the new property is the same as the previous hard-coded event limit.

Specification

--- a/src/java.base/share/classes/java/nio/file/WatchService.java
+++ b/src/java.base/share/classes/java/nio/file/WatchService.java
@@ -98,6 +98,20 @@
  * it is not required that changes to files carried out on remote systems be
  * detected.
  *
+ * @implNote
+ * The JDK's {@code WatchService} implementations buffer up to 512 pending
+ * events for each registered watchable object. If this limit is exceeded,
+ * pending events are discarded and the special
+ * {@link StandardWatchEventKinds#OVERFLOW OVERFLOW} event is queued. This
+ * special event is the trigger to re-examine the state of the object, e.g.
+ * scan a watched directory to get an updated list of the files in the
+ * directory. The limit for the pending events can be changed from its default
+ * with the system property
+ * {@systemProperty jdk.nio.file.WatchService.maxEventsPerPoll}
+ * set to a value that parses as a positive integer. This may be useful in
+ * environments where there is a high volume of changes and where the impact
+ * of discarded events is high.
+ *
  * @since 1.7
  *
  * @see FileSystem#newWatchService