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	Description
static class	PathWatcher.Config
static enum	PathWatcher.DirAction
static interface	PathWatcher.EventListListener	EventListListener Listener that reports accumulated events in one shot
private static class	PathWatcher.ExactPathMatcher
static interface	PathWatcher.Listener	Listener for path change events
static class	PathWatcher.PathMatcherSet
class	PathWatcher.PathWatchEvent	PathWatchEvent Represents a file event.
static enum	PathWatcher.PathWatchEventType	PathWatchEventType Type of an event

Nested classes/interfaces inherited from class AbstractLifeCycle

AbstractLifeCycle.AbstractLifeCycleListener

Field Summary

Fields

Modifier and Type	Field	Description
private boolean	_notifyExistingOnStart
private final List<PathWatcher.Config>	configs
private final List<PathWatcher.PathWatchEvent>	events
private static final boolean	IS_WINDOWS
private final Map<WatchKey, PathWatcher.Config>	keys
private final List<EventListener>	listeners
(package private) static final Logger	LOG
private final Map<Path, PathWatcher.PathWatchEvent>	pending
private Thread	thread
private long	updateQuietTimeDuration	Update Quiet Time - set to 1000 ms as default (a lower value in Windows is not supported)
private TimeUnit	updateQuietTimeUnit
private static final WatchEvent.Kind<?>[]	WATCH_DIR_KINDS
private static final WatchEvent.Kind<?>[]	WATCH_EVENT_KINDS
private WatchService	watchService

Fields inherited from class AbstractLifeCycle

FAILED, RUNNING, STARTED, STARTING, STOPPED, STOPPING

Constructor Summary

Constructors

Constructor	Description
PathWatcher()	Construct new PathWatcher

Method Summary

Modifier and Type	Method	Description
void	addListener(EventListener listener)	Add a listener for changes the watcher notices.
private void	appendConfigId(StringBuilder s)	Append some info on the paths that we are watching.
protected static <T> WatchEvent<T>	cast(WatchEvent<?> event)
protected void	doStart()
protected void	doStop()
Collection<PathWatcher.Config>	getConfigs()
Iterator<EventListener>	getListeners()	Get an iterator over the listeners.
long	getUpdateQuietTimeMillis()	Change the quiet time.
private void	handleKey(WatchKey key)
void	handleWatchEvent(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 boolean	isNotifiable()	Check to see if the watcher is in a state where it should generate watch events to the listeners.
boolean	isNotifyExistingOnStart()
private void	notifyEvents()
private long	processPending()
protected void	register(Path path, PathWatcher.Config config)
private void	register(Path path, PathWatcher.Config config, WatchEvent.Kind<?>[] kinds)
private void	registerDir(Path path, PathWatcher.Config config)
private void	registerTree(Path dir, PathWatcher.Config config, boolean notify)
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 AbstractLifeCycle

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

Methods inherited from class Object

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

Field Details

IS_WINDOWS

private static final boolean IS_WINDOWS

LOG

static final Logger LOG

WATCH_EVENT_KINDS

private static final WatchEvent.Kind<?>[] WATCH_EVENT_KINDS

WATCH_DIR_KINDS

private static final WatchEvent.Kind<?>[] WATCH_DIR_KINDS

watchService

private WatchService watchService

configs

private final List<PathWatcher.Config> configs

keys

private final Map<WatchKey, PathWatcher.Config> keys

listeners

private final List<EventListener> listeners

pending

private final Map<Path, PathWatcher.PathWatchEvent> pending

events

private final List<PathWatcher.PathWatchEvent> events

updateQuietTimeDuration

private long updateQuietTimeDuration

Update Quiet Time - set to 1000 ms as default (a lower value in Windows is not supported)

updateQuietTimeUnit

private TimeUnit updateQuietTimeUnit

thread

private Thread thread

_notifyExistingOnStart

private boolean _notifyExistingOnStart

Constructor Details

PathWatcher

public PathWatcher()

Construct new PathWatcher

Method Details

cast

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

getConfigs

public Collection<PathWatcher.Config> getConfigs()

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

addListener

public void addListener(EventListener listener)

Add a listener for changes the watcher notices.

Parameters:

listener - change listener

appendConfigId

private void appendConfigId(StringBuilder s)

Append some info on the paths that we are watching.

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

registerTree

private void registerTree(Path dir,
 PathWatcher.Config config,
 boolean notify)
                   throws IOException

Throws:

IOException

registerDir

private void registerDir(Path path,
 PathWatcher.Config config)
                  throws IOException

Throws:

IOException

register

protected void register(Path path,
 PathWatcher.Config config)
                 throws IOException

Throws:

IOException

register

private void register(Path path,
 PathWatcher.Config config,
 WatchEvent.Kind<?>[] kinds)
               throws IOException

Throws:

IOException

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()

handleKey

private void handleKey(WatchKey key)

handleWatchEvent

public void handleWatchEvent(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

processPending

private long processPending()

notifyEvents

private void notifyEvents()

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 AbstractLifeCycle