Package engineering.swat.watch

Class Watch

  • public class Watch
extends Object

    Watch a path for changes.

    It will avoid common errors using the raw apis, and will try to use the most native api where possible.

    Note, there are differences per platform that cannot be avoided, please review the readme of the library.

    • Method Detail

      • build

        public static Watch build​(Path path,
                          WatchScope scope)
        Watch a path for updates, optionally also get events for its children/descendants
        Parameters:
        path - which absolute path to monitor, can be a file or a directory, but has to be absolute
        scope - for directories you can also choose to monitor it's direct children or all it's descendants
        Returns:
        watch builder that can be further configured and then started
        Throws:
        IllegalArgumentException - in case a path is not supported (in relation to the scope)

      • on

        public Watch on​(Consumer<WatchEvent> eventHandler)
        Callback that gets executed for every event. Can get called quite a bit, so be careful what happens here. Use the withExecutor(Executor) function to influence the sequencing of these events. By default they can arrive in parallel.
        Parameters:
        eventHandler - a callback that handles the watch event, will be called once per event.
        Returns:
        this (to support method chaining)

      • on

        public Watch on​(WatchEventListener listener)
        Convenience variant of on(Consumer), which allows you to only respond to certain events
        Parameters:
        listener - gets executed on every event the watch produced
        Returns:
        this (to support method chaining)

      • withExecutor

        public Watch withExecutor​(Executor callbackHandler)
        Optionally configure the executor in which the on(Consumer) callbacks are scheduled. Make sure to consider the termination of the threadpool, it should be after the close of the active watch.
        Parameters:
        callbackHandler - worker pool to use
        Returns:
        this for optional method chaining

      • onOverflow

        public Watch onOverflow​(Approximation whichFiles)
        Optionally configure which regular files/directories in the scope of the watch an approximation of synthetic events (of kinds WatchEvent.Kind.CREATED, WatchEvent.Kind.MODIFIED, and/or WatchEvent.Kind.DELETED) should be issued when an overflow event happens. If not defined before this watcher is started, the Approximation.ALL approach will be used.
        Parameters:
        whichFiles - Constant to indicate for which regular files/directories to approximate
        Returns:
        This watcher for optional method chaining

      • start

        public ActiveWatch start()
                  throws IOException
        Start watch the path for events.
        Returns:
        a subscription for the watch, when closed, new events will stop being registered to the worker pool.
        Throws:
        IOException - in case the starting of the watcher caused an underlying IO exception
        IllegalStateException - the watchers is not configured correctly (for example, missing on(Consumer), or a watcher is started twice)