From d6c7f99d85b5f9573e3a177b6ad0cc7a6fbd6fa6 Mon Sep 17 00:00:00 2001 From: WalkerWatch Date: Thu, 15 Dec 2016 13:48:48 -0500 Subject: [PATCH 1/2] Issue #1061 Documentation Signed-off-by: WalkerWatch --- .../reference/troubleshooting/chapter.adoc | 3 +- .../troubleshooting/watchservice.adoc | 29 +++++++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 jetty-documentation/src/main/asciidoc/reference/troubleshooting/watchservice.adoc diff --git a/jetty-documentation/src/main/asciidoc/reference/troubleshooting/chapter.adoc b/jetty-documentation/src/main/asciidoc/reference/troubleshooting/chapter.adoc index 404712843ad..cc16d9dd02c 100644 --- a/jetty-documentation/src/main/asciidoc/reference/troubleshooting/chapter.adoc +++ b/jetty-documentation/src/main/asciidoc/reference/troubleshooting/chapter.adoc @@ -23,4 +23,5 @@ include::troubleshooting-zip-exceptions.adoc[] include::troubleshooting-locked-files.adoc[] include::preventing-memory-leaks.adoc[] include::slow-deployment.adoc[] -include::security-reports.adoc[] \ No newline at end of file +include::security-reports.adoc[] +include::watchservice.adoc[] diff --git a/jetty-documentation/src/main/asciidoc/reference/troubleshooting/watchservice.adoc b/jetty-documentation/src/main/asciidoc/reference/troubleshooting/watchservice.adoc new file mode 100644 index 00000000000..3b2ef1e280a --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/reference/troubleshooting/watchservice.adoc @@ -0,0 +1,29 @@ +// ======================================================================== +// Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd. +// ======================================================================== +// All rights reserved. This program and the accompanying materials +// are made available under the terms of the Eclipse Public License v1.0 +// and Apache License v2.0 which accompanies this distribution. +// +// The Eclipse Public License is available at +// http://www.eclipse.org/legal/epl-v10.html +// +// The Apache License v2.0 is available at +// http://www.opensource.org/licenses/apache2.0.php +// +// You may elect to redistribute this code under either of these licenses. +// ======================================================================== + +[[watchservice]] +=== Java WatchService + +The JVM link:https://docs.oracle.com/javase/7/docs/api/java/nio/file/WatchService.html[WatchService] is in place to monitor objects, like a directory, for changes and update it's contents. +This service is useful for features like link:#hot-deployment[Hot Deployment]. +When a change is made the system will wait to post the update and pause to see if there are any other changes. +While some operating systems such as Windows have a native value for this quiet time, not all do, notably OSX. +At the core this is a limitation of the JVM's FileSystem-specific implementation, but one that has been raised to the link:https://bugs.openjdk.java.net/browse/JDK-7133447[attention of the project.] + +==== Remedy + +To help offset the delay in systems like OSX, Jetty defaults the value for non-native implementations to a link:{GITBROWSEURL}/jetty-util/src/main/java/org/eclipse/jetty/util/PathWatcher.java#L1431[time of 5000ms.] +Using values lower than 5000ms is not recommended and has shown to frequently fail. From 8aacd26e758fb785cbbe5ee27f07efa9049f93a4 Mon Sep 17 00:00:00 2001 From: WalkerWatch Date: Mon, 19 Dec 2016 13:20:35 -0500 Subject: [PATCH 2/2] Documentation changes for WatchService. Signed-off-by: WalkerWatch --- .../reference/troubleshooting/watchservice.adoc | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/jetty-documentation/src/main/asciidoc/reference/troubleshooting/watchservice.adoc b/jetty-documentation/src/main/asciidoc/reference/troubleshooting/watchservice.adoc index 3b2ef1e280a..bfbefb03202 100644 --- a/jetty-documentation/src/main/asciidoc/reference/troubleshooting/watchservice.adoc +++ b/jetty-documentation/src/main/asciidoc/reference/troubleshooting/watchservice.adoc @@ -17,9 +17,15 @@ [[watchservice]] === Java WatchService -The JVM link:https://docs.oracle.com/javase/7/docs/api/java/nio/file/WatchService.html[WatchService] is in place to monitor objects, like a directory, for changes and update it's contents. +The JVM link:https://docs.oracle.com/javase/7/docs/api/java/nio/file/WatchService.html[`WatchService`] is in place to monitor objects like a directory for changes, and then update it's contents and notify the application of those changes. This service is useful for features like link:#hot-deployment[Hot Deployment]. -When a change is made the system will wait to post the update and pause to see if there are any other changes. +When a change is detected, the `WatchService` will enter a "quiet time" where it is waiting for the change (or changes) to be made and completed before notifying the application of the change. + +Example: +A new war file is copied into `/webapps`. +The `WatchService` can (depending on implementation) see that the file was created (which is registered as an event!, and that its growing in size (another event). +With the quiet time, each of the events are gated behind that timeout before the aggregated events are sent to the application. + While some operating systems such as Windows have a native value for this quiet time, not all do, notably OSX. At the core this is a limitation of the JVM's FileSystem-specific implementation, but one that has been raised to the link:https://bugs.openjdk.java.net/browse/JDK-7133447[attention of the project.]