org.eclipse.jetty.util

Class PathWatcher

java.lang.Object

org.eclipse.jetty.util.component.AbstractLifeCycle

org.eclipse.jetty.util.PathWatcher

All Implemented Interfaces:

Runnable, LifeCycle

public class PathWatcher
extends AbstractLifeCycle
implements Runnable

Watch a Path (and sub directories) for Path changes.

Suitable replacement for the old Scanner implementation.

Allows for configured Excludes and Includes using FileSystem.getPathMatcher(String) syntax.

Reports activity via registered PathWatcher.Listeners

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PathWatcher.Config
static class	PathWatcher.DepthLimitedFileVisitor
static interface	PathWatcher.EventListListener EventListListener Listener that reports accumulated events in one shot
static interface	PathWatcher.Listener Listener for path change events
static class	PathWatcher.PathPendingEvents PathPendingEvents For a given path, a list of events that are awaiting the quiet time.
static class	PathWatcher.PathWatchEvent PathWatchEvent Represents a file event.
static class	PathWatcher.PathWatchEventType PathWatchEventType Type of an event

Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

AbstractLifeCycle.AbstractLifeCycleListener

Field Summary

Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

FAILED, RUNNING, STARTED, STARTING, STOPPED, STOPPING

Constructor Summary

Constructors

Constructor and Description
PathWatcher() Construct new PathWatcher

Method Summary

Modifier and Type	Method and Description
void	addListener(EventListener listener) Add a listener for changes the watcher notices.
void	addToPendingList(Path path, PathWatcher.PathWatchEvent event) Add an event reported by the WatchService to list of pending events that will be sent after their quiet time has expired.
protected static <T> WatchEvent<T>	cast(WatchEvent<?> event)
protected void	doStart()
protected void	doStop()
Iterator<EventListener>	getListeners() Get an iterator over the listeners.
long	getUpdateQuietTimeMillis() Change the quiet time.
protected boolean	isNotifiable() Check to see if the watcher is in a state where it should generate watch events to the listeners.
boolean	isNotifyExistingOnStart()
protected void	notifyOnPathWatchEvents(List<PathWatcher.PathWatchEvent> events) Generate events to the listeners.
protected void	prepareConfig(PathWatcher.Config baseDir) Register path in the config with the file watch service, walking the tree if it happens to be a directory.
protected void	register(Path dir, PathWatcher.Config root) Register a path (directory) with the WatchService.
boolean	removeListener(PathWatcher.Listener listener) Delete a listener
void	reset() Remove all current configs and listeners.
void	run() Forever loop.
void	setNotifyExistingOnStart(boolean notify) Whether or not to issue notifications for directories and files that already exist when the watcher starts.
void	setUpdateQuietTime(long duration, TimeUnit unit) Set the quiet time.
String	toString()
void	watch(Path file) Request watch on a the given path (either file or dir) using all Config defaults.
void	watch(PathWatcher.Config config) Request watch on a path with custom Config provided.

Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

addLifeCycleListener, getState, getState, getStopTimeout, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, setStopTimeout, start, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PathWatcher

public PathWatcher()

Construct new PathWatcher

Method Detail

cast

protected static <T> WatchEvent<T> cast(WatchEvent<?> event)

watch

public void watch(Path file)

Request watch on a the given path (either file or dir) using all Config defaults. In the case of a dir, the default is not to recurse into subdirs for watching.

Parameters:

file - the path to watch

watch

public void watch(PathWatcher.Config config)

Request watch on a path with custom Config provided.

Parameters:

config - the configuration to watch

prepareConfig

protected void prepareConfig(PathWatcher.Config baseDir)
                      throws IOException

Register path in the config with the file watch service, walking the tree if it happens to be a directory.

Parameters:

baseDir - the base directory configuration to watch

Throws:

IOException - if unable to walk the filesystem tree

addListener

public void addListener(EventListener listener)

Add a listener for changes the watcher notices.

Parameters:

listener - change listener

doStart

protected void doStart()
                throws Exception

Overrides:

doStart in class AbstractLifeCycle

Throws:

Exception

See Also:

AbstractLifeCycle.doStart()

doStop

protected void doStop()
               throws Exception

Overrides:

doStop in class AbstractLifeCycle

Throws:

Exception

See Also:

AbstractLifeCycle.doStop()

reset

public void reset()

Remove all current configs and listeners.

isNotifiable

protected boolean isNotifiable()

Check to see if the watcher is in a state where it should generate watch events to the listeners. Used to determine if watcher should generate events for existing files and dirs on startup.

Returns:

true if the watcher should generate events to the listeners.

getListeners

public Iterator<EventListener> getListeners()

Get an iterator over the listeners.

Returns:

iterator over the listeners.

getUpdateQuietTimeMillis

public long getUpdateQuietTimeMillis()

Change the quiet time.

Returns:

the quiet time in millis

notifyOnPathWatchEvents

protected void notifyOnPathWatchEvents(List<PathWatcher.PathWatchEvent> events)

Generate events to the listeners.

Parameters:

events - the events captured

register

protected void register(Path dir,
                        PathWatcher.Config root)
                 throws IOException

Register a path (directory) with the WatchService.

Parameters:

dir - the directory to register

root - the configuration root

Throws:

IOException - if unable to register the path with the watch service.

removeListener

public boolean removeListener(PathWatcher.Listener listener)

Delete a listener

Parameters:

listener - the listener to remove

Returns:

true if the listener existed and was removed

run

public void run()

Forever loop. Wait for the WatchService to report some filesystem events for the watched paths. When an event for a path first occurs, it is subjected to a quiet time. Subsequent events that arrive for the same path during this quiet time are accumulated and the timer reset. Only when the quiet time has expired are the accumulated events sent. MODIFY events are handled slightly differently - multiple MODIFY events arriving within a quiet time are coalesced into a single MODIFY event. Both the accumulation of events and coalescing of MODIFY events reduce the number and frequency of event reporting for "noisy" files (ie those that are undergoing rapid change).

Specified by:

run in interface Runnable

See Also:

Runnable.run()

addToPendingList

public void addToPendingList(Path path,
                             PathWatcher.PathWatchEvent event)

Add an event reported by the WatchService to list of pending events that will be sent after their quiet time has expired.

Parameters:

path - the path to add to the pending list

event - the pending event

setNotifyExistingOnStart

public void setNotifyExistingOnStart(boolean notify)

Whether or not to issue notifications for directories and files that already exist when the watcher starts.

Parameters:

notify - true if existing paths should be notified or not

isNotifyExistingOnStart

public boolean isNotifyExistingOnStart()

setUpdateQuietTime

public void setUpdateQuietTime(long duration,
                               TimeUnit unit)

Set the quiet time.

Parameters:

duration - the quiet time duration

unit - the quite time unit

toString

public String toString()

Overrides:

toString in class Object