FileWatcher (core 3.8.2 API)

java.lang.Object
- com.electronwill.nightconfig.core.file.FileWatcher

```
public final class FileWatcher
extends java.lang.Object
```
A FileWatcher can watch several files asynchronously.
New watches are added with the addWatch(Path, Runnable) method, which specifies the task to execute when the file is modified.
This class is thread-safe.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class FileWatcher.WatchingException

Nested Classes
Modifier and Type	Class and Description
`static class`	`FileWatcher.WatchingException`

Constructor Summary

Constructors
Constructor and Description
`FileWatcher()` Creates a new FileWatcher with a default exception handler and a default debounce time.
`FileWatcher(java.util.function.Consumer<java.lang.Exception> exceptionHandler)` Creates a new FileWatcher with the default debounce time and the given exception handler.
`FileWatcher(java.time.Duration debounceTime)` Creates a new FileWatcher with a default exception handler.
`FileWatcher(java.time.Duration debounceTime, java.util.function.Consumer<java.lang.Throwable> exceptionHandler)` Creates a new FileWatcher with the given exception handler.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addWatch(java.io.File file, java.lang.Runnable changeHandler)` Watches a file, if not already watched by this FileWatcher.
`void`	`addWatch(java.nio.file.Path file, java.lang.Runnable changeHandler)` Watches a file, if not already watched by this FileWatcher.
`java.util.concurrent.CompletableFuture<java.lang.Void>`	`addWatchFuture(java.nio.file.Path file, java.lang.Runnable changeHandler)` Watches a File, if not already watched by this FileWatcher.
`static FileWatcher`	`defaultInstance()` Gets the default, global instance of FileWatcher.
`void`	`removeWatch(java.io.File file)` Stops watching a file.
`void`	`removeWatch(java.nio.file.Path file)` Stops watching a file.
`java.util.concurrent.CompletableFuture<java.lang.Void>`	`removeWatchFuture(java.nio.file.Path file)`
`void`	`setWatch(java.io.File file, java.lang.Runnable changeHandler)` Watches a file.
`void`	`setWatch(java.nio.file.Path file, java.lang.Runnable changeHandler)` Watches a file.
`java.util.concurrent.CompletableFuture<java.lang.Void>`	`setWatchFuture(java.nio.file.Path file, java.lang.Runnable changeHandler)`
`void`	`stop()` Stops this FileWatcher.
`java.util.concurrent.CompletableFuture<java.lang.Void>`	`stopFuture()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - FileWatcher
```
public FileWatcher()
```
    Creates a new FileWatcher with a default exception handler and a default debounce time. The default exception handler is simply: (e) -> e.printStackTrace(); The default debounce time is unspecified and may change in the future, but is typically around 1 second or less.
  - FileWatcher
```
public FileWatcher(java.util.function.Consumer<java.lang.Exception> exceptionHandler)
```
    Creates a new FileWatcher with the default debounce time and the given exception handler.
    The default debounce time is unspecified and may change in the future, but is typically around 1 second or less.
  - FileWatcher
```
public FileWatcher(java.time.Duration debounceTime)
```
    Creates a new FileWatcher with a default exception handler. The default exception handler is simply: (e) -> e.printStackTrace();
    
    Parameters:
    
    debounceTime - hwo much time to wait after each modification of a file before triggering the change handler
  - FileWatcher
```
public FileWatcher(java.time.Duration debounceTime,
                   java.util.function.Consumer<java.lang.Throwable> exceptionHandler)
```
    Creates a new FileWatcher with the given exception handler.
    
    Parameters:
    
    debounceTime - delay between each call of the file's changeHandler.
    
    exceptionHandler - called when an exception occurs during the handling of file events
- Method Detail
  - defaultInstance
```
public static FileWatcher defaultInstance()
```
    Gets the default, global instance of FileWatcher. If the previous global instance has been stopped, create and start a new instance.
    
    Returns:
    
    the default FileWatcher
  - addWatch
```
public void addWatch(java.io.File file,
                     java.lang.Runnable changeHandler)
```
    Watches a file, if not already watched by this FileWatcher. The file's parent directory must exist.
    NOTE: This method may return before the handler is set up. Prefer to use addWatchFuture(Path, Runnable).
    
    Parameters:
    
    file - the file to watch
    
    changeHandler - the handler to call when the file is modified
  - addWatch
```
public void addWatch(java.nio.file.Path file,
                     java.lang.Runnable changeHandler)
```
    Watches a file, if not already watched by this FileWatcher. The file's parent directory must exist.
    NOTE: This method may return before the handler is set up. Prefer to use addWatchFuture(Path, Runnable).
    
    Parameters:
    
    file - the file to watch
    
    changeHandler - the handler to call when the file is modified
  - addWatchFuture
```
public java.util.concurrent.CompletableFuture<java.lang.Void> addWatchFuture(java.nio.file.Path file,
                                                                             java.lang.Runnable changeHandler)
```
    Watches a File, if not already watched by this FileWatcher. The file's parent directory must exist.
    This method returns a CompletableFuture that is completed when the handler is registered and ready to be notified of file events.
    Examples
    Waiting for the FileWatcher to register one handler:
```
 
 FileWatcher watcher = FileWatcher.defaultInstance();
 CompletableFuture<Void> f = watcher.addWatchFuture(file, handler);
 f.join();
 
 
```
    Watching multiple files and waiting for the handlers to be ready, with a timeout of 1 second:
```
 
 FileWatcher watcher = FileWatcher.defaultInstance();
 List<CompletableFuture<Void>> futures = new ArrayList<>();
 for (Path path : filesToWatch) {
     futures.add(watcher.addWatchFuture(file, () -> {
         // react to file creation or modification
     }));
 }
 CompletableFuture.allOf(futures.toArray(new CompletableFuture[futures.size()])).get(1, TimeUnit.SECONDS);
 
 
```
    Parameters:
    
    file - the file to watch
    
    changeHandler - the handler to call when the file is modified
    
    Returns:
    
    a future that completes when the handler is ready
  - setWatch
```
public void setWatch(java.io.File file,
                     java.lang.Runnable changeHandler)
```
    Watches a file. If the file is already watched by this FileWatcher, its changeHandler is replaced. The file's parent directory must exist.
    NOTE: This method may return before the handler is set up. Prefer to use setWatchFuture(Path, Runnable).
    
    Parameters:
    
    file - the file to watch
    
    changeHandler - the handler to call when the file is modified
  - setWatch
```
public void setWatch(java.nio.file.Path file,
                     java.lang.Runnable changeHandler)
```
    Watches a file. If the file is already watched by this FileWatcher, its changeHandler is replaced. The file's parent directory must exist.
    NOTE: This method may return before the handler is set up. Prefer to use setWatchFuture(Path, Runnable).
    
    Parameters:
    
    file - the file to watch
    
    changeHandler - the handler to call when the file is modified
  - setWatchFuture
```
public java.util.concurrent.CompletableFuture<java.lang.Void> setWatchFuture(java.nio.file.Path file,
                                                                             java.lang.Runnable changeHandler)
```
  - removeWatch
```
public void removeWatch(java.io.File file)
```
    Stops watching a file.
    NOTE: This method may return before the handler is removed. Prefer to use setWatchFuture(Path, Runnable).
    
    Parameters:
    
    file - the file to stop watching
  - removeWatch
```
public void removeWatch(java.nio.file.Path file)
```
    Stops watching a file.
    NOTE: This method may return before the handler is removed. Prefer to use setWatchFuture(Path, Runnable).
    
    Parameters:
    
    file - the file to stop watching
  - removeWatchFuture
```
public java.util.concurrent.CompletableFuture<java.lang.Void> removeWatchFuture(java.nio.file.Path file)
```
  - stop
```
public void stop()
```
    Stops this FileWatcher. The underlying ressources (ie the WatchServices) are closed, and the file modification handlers won't be called anymore.
    NOTE: This method may return before the FileWatcher is completely stopped. Prefer to use stopFuture().
  - stopFuture
```
public java.util.concurrent.CompletableFuture<java.lang.Void> stopFuture()
```

Class FileWatcher

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

FileWatcher

FileWatcher

FileWatcher

FileWatcher

Method Detail

defaultInstance

addWatch

addWatch

addWatchFuture

Examples

setWatch

setWatch

setWatchFuture

removeWatch

removeWatch

removeWatchFuture

stop

stopFuture