com.swoval.files.PathWatcher Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of file-tree-views Show documentation

File system apis.

There is a newer version: 2.1.12

package com.swoval.files;

import com.swoval.files.FileTreeViews.Observable;
import com.swoval.files.PathWatchers.Event;
import com.swoval.functional.Either;
import java.io.IOException;
import java.nio.file.Path;

/**
 * Watches directories for file changes. The api permits recursive watching of directories unlike
 * the  java.nio.file.WatchService. Some of the behavior may vary by platform due to
 * fundamental differences in the underlying file event apis. For example, Linux doesn't support
 * recursive directory monitoring via inotify, so it's possible in rare cases to miss file events
 * for newly created files in newly created directories. On OSX, it is difficult to disambiguate
 * file creation and modify events, so the {@link Event.Kind} is best effort, but should not be
 * relied upon to accurately reflect the state of the file.
 */
public interface PathWatcher extends Observable, AutoCloseable {

  /**
   * Register a path to monitor for file events. The watcher will only watch child subdirectories up
   * to maxDepth. For example, with a directory structure like /foo/bar/baz, if we register the path
   * /foo/ with maxDepth 0, we will be notified for any files that are created, updated or deleted
   * in foo, but not bar. If we increase maxDepth to 1, then the files in /foo/bar are monitored,
   * but not the files in /foo/bar/baz.
   *
   * @param path the directory to watch for file events
   * @param maxDepth the maximum maxDepth of subdirectories to watch
   * @return an {@link com.swoval.functional.Either} containing the result of the registration or an
   *     IOException if registration fails. This method should be idempotent and return true the
   *     first time the directory is registered or when the depth is changed. Otherwise it should
   *     return false.
   */
  Either register(Path path, int maxDepth);

  /**
   * Stop watching a path.
   *
   * @param path the path to remove from monitoring
   */
  void unregister(Path path);

  /** Catch any exceptions in subclasses. */
  @Override
  void close();
}