Module xaos.core

Package eu.ess.xaos.core.util.io

Class DirectoryWatcher

java.lang.Object

eu.ess.xaos.core.util.io.DirectoryWatcher

All Implemented Interfaces:

AutoCloseable

public class DirectoryWatcher
extends Object
implements AutoCloseable

Watches for changes in files and directories, and allows for standard operations on both files and directories.

Usage:

   ExecutorService executor = Executors.newSingleThreadExecutor();
   DirectoryWatcher watcher = build(executor);

   watcher.events().subscribe(event -> {
     event.getEvents().stream().forEach(e -> {
       if ( StandardWatchEventKinds.ENTRY_CREATE.equals(e.kind()) ) {
         ...
       } else if ( StandardWatchEventKinds.ENTRY_DELETE.equals(e.kind()) ) {
         ...
       } else if ( StandardWatchEventKinds.ENTRY_MODIFY.equals(e.kind()) ) {
         ...
       }
     });
   });

   Path root = ...

   watcher.watch(root);

Author:

claudio.rosati@esss.se

See Also:

LiveDirsFX:org.fxmisc.livedirs.DirWatcher

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	DirectoryWatcher.DirectoryEvent	Contains the information about entry create, delete or modify occurred to a watched directory.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	DirectoryWatcher(Executor eventThreadExecutor)

Method Summary

Modifier and Type	Method	Description
static DirectoryWatcher	build(Executor eventThreadExecutor)	Creates a DirectoryWatcher instance.
void	close()	Shutdown this watcher.
void	createDirectories(Path dir, Consumer<Path> onSuccess, Consumer<Throwable> onError, FileAttribute<?>... attrs)	Create a new directory by creating all nonexistent parent directories first.
void	createDirectory(Path dir, Consumer<Path> onSuccess, Consumer<Throwable> onError, FileAttribute<?>... attrs)	Create a new directory using the given path.
void	createFile(Path file, Consumer<FileTime> onSuccess, Consumer<Throwable> onError, FileAttribute<?>... attrs)	Create a new file using the given path.
void	delete(Path path, Consumer<Boolean> onSuccess, Consumer<Throwable> onError)	Deletes a file or an empty directory.
void	deleteTree(Path root, Consumer<Void> onSuccess, Consumer<Throwable> onError)	Deletes a file tree rooted at the given path.
io.reactivex.Observable<Throwable>	errors()
io.reactivex.Observable<DirectoryWatcher.DirectoryEvent>	events()
boolean	isCloseComplete()	Returns true if this watcher was shutdown, and the shutdown process is completed (i.e.
boolean	isClosed()	Returns true if this watcher was shutdown, meaning that no elements will be posted to the errors and events streams.
boolean	isWatched(Path dir)	Return whether the given Path is watched or not.
void	readBinaryFile(Path file, Consumer<byte[]> onSuccess, Consumer<Throwable> onError)	Reads the contents of a binary file.
void	readTextFile(Path file, Charset charset, Consumer<String> onSuccess, Consumer<Throwable> onError)	Reads the contents of a text file.
void	unwatch(Path dir)	Unwatch the given directory Path.
void	unwatchUp(Path dir)	Unwatch the given directory and all its parents.
void	unwatchUp(Path dir, Path to)	Unwatch the given directory and all its parents up to the given ancestor.
void	watch(Path dir)	Watch the given directory for entry create, delete, and modify events.
void	watchOrStreamError(Path dir)	Watch the given directory for entry create, delete, and modify events.
void	watchUp(Path dir)	Watch the given directory and all its parents for entry create, delete, and modify events.
void	watchUp(Path dir, Path to)	Watch the given directory and all its parents up to the given ancestor, for entry create, delete, and modify events.
void	watchUpOrStreamError(Path dir)	Watch the given directory and all its parents for entry create, delete, and modify events.
void	watchUpOrStreamError(Path dir, Path to)	Watch the given directory and all its parents up to the given ancestor, for entry create, delete, and modify events.
void	writeBinaryFile(Path file, byte[] content, Consumer<FileTime> onSuccess, Consumer<Throwable> onError)	Writes a binary file filling it with the given content.
void	writeTextFile(Path file, String content, Charset charset, Consumer<FileTime> onSuccess, Consumer<Throwable> onError)	Writes a text file filling it with the given content.

Methods inherited from class java.lang.Object

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

Constructor Detail

DirectoryWatcher

protected DirectoryWatcher(Executor eventThreadExecutor)
                    throws IOException

Throws:

IOException

Method Detail

build

public static DirectoryWatcher build(Executor eventThreadExecutor)
                              throws IOException

Creates a DirectoryWatcher instance.

Parameters:

eventThreadExecutor - The Executor used to queue I/O events.

Returns:

A newly created DirectoryWatcher instance.

Throws:

IOException - If an I/O error occurs.

close

public void close()

Shutdown this watcher.

Note: this method will not shutdown the event thread Executor used to create this watcher.

Specified by:

close in interface AutoCloseable

createDirectories

public void createDirectories(Path dir,
                              Consumer<Path> onSuccess,
                              Consumer<Throwable> onError,
                              FileAttribute<?>... attrs)

Create a new directory by creating all nonexistent parent directories first. One of the two given Consumers will be called on success or on failure.

Parameters:

dir - The pathname of the file to be created.

onSuccess - The Consumer called on success, where the passed parameter is the new directory Path.

onError - The Consumer called on failure.

attrs - An optional list of file attributes to set atomically when creating the directory.

createDirectory

public void createDirectory(Path dir,
                            Consumer<Path> onSuccess,
                            Consumer<Throwable> onError,
                            FileAttribute<?>... attrs)

Create a new directory using the given path. One of the two given Consumers will be called on success or on failure.

The createDirectories method should be used where it is required to create all nonexistent parent directories first.

Parameters:

dir - The pathname of the file to be created.

onSuccess - The Consumer called on success, where the passed parameter is the new directory Path.

onError - The Consumer called on failure.

attrs - An optional list of file attributes to set atomically when creating the directory.

createFile

public void createFile(Path file,
                       Consumer<FileTime> onSuccess,
                       Consumer<Throwable> onError,
                       FileAttribute<?>... attrs)

Create a new file using the given path. One of the two given Consumers will be called on success or on failure.

Files.createFile(java.nio.file.Path, java.nio.file.attribute.FileAttribute...) will be called to actually create the file.

Note: the operation is executed by the Executor passed to the build(java.util.concurrent.Executor) method, i.e. in a different thread from the caller's one.

Parameters:

file - The pathname of the file to be created.

onSuccess - The Consumer called on success, where the passed parameter is the new file timestamp.

onError - The Consumer called on failure.

attrs - An optional list of file attributes to set atomically when creating the file.

delete

public void delete(Path path,
                   Consumer<Boolean> onSuccess,
                   Consumer<Throwable> onError)

Deletes a file or an empty directory. One of the two given Consumers will be called on success or on failure.

Files.delete(java.nio.file.Path) will be called to actually delete the file or empty directory.

Note: the operation is executed by the Executor passed to the build(java.util.concurrent.Executor) method, i.e. in a different thread from the caller's one.

Parameters:

path - Pathname of the file or directory to be deleted.

onSuccess - The Consumer called on success, where the passed parameter is Boolean.TRUE if the file was deleted by this method; Boolean.FALSE if the file could not be deleted because it did not exist.

onError - The Consumer called on failure.

deleteTree

public void deleteTree(Path root,
                       Consumer<Void> onSuccess,
                       Consumer<Throwable> onError)

Deletes a file tree rooted at the given path. One of the two given Consumers will be called on success or on failure.

Parameters:

root - The path to the file tree root to be deleted.

onSuccess - The Consumer called on success.

onError - The Consumer called on failure.

errors

public io.reactivex.Observable<Throwable> errors()

Returns:

The Subject of thrown errors.

events

public io.reactivex.Observable<DirectoryWatcher.DirectoryEvent> events()

Returns:

The Subject of signalled DirectoryWatcher.DirectoryEvents.

isCloseComplete

public final boolean isCloseComplete()

Returns true if this watcher was shutdown, and the shutdown process is completed (i.e. the I/O thread is terminated).

Returns:

true if this watcher's shutdown completed.

isClosed

public final boolean isClosed()

Returns true if this watcher was shutdown, meaning that no elements will be posted to the errors and events streams.

Returns:

true if this watcher was shutdown.

isWatched

public boolean isWatched(Path dir)

Return whether the given Path is watched or not. A path is watched if watch(Path) or watchOrStreamError(Path) was invoked on it.

Parameters:

dir - The Path to be checked.

Returns:

true if watch(Path) or watchOrStreamError(Path) was invoked on the given dir.

readBinaryFile

public void readBinaryFile(Path file,
                           Consumer<byte[]> onSuccess,
                           Consumer<Throwable> onError)

Reads the contents of a binary file. One of the two given Consumers will be called on success or on failure.

Files.readAllBytes(java.nio.file.Path) will be called to actually read the file.

Note: the operation is executed by the Executor passed to the build(java.util.concurrent.Executor) method, i.e. in a different thread from the caller's one.

Parameters:

file - The pathname of the file to be read.

onSuccess - The Consumer called on success, where the passed parameter are the read bytes from the file.

onError - The Consumer called on failure.

readTextFile

public void readTextFile(Path file,
                         Charset charset,
                         Consumer<String> onSuccess,
                         Consumer<Throwable> onError)

Reads the contents of a text file. One of the two given Consumers will be called on success or on failure.

Files.readAllBytes(java.nio.file.Path) will be called to actually read the file.

Note: the operation is executed by the Executor passed to the build(java.util.concurrent.Executor) method, i.e. in a different thread from the caller's one.

Parameters:

file - The pathname of the file to be read.

charset - The Charset to be used in reading the from the file.

onSuccess - The Consumer called on success, where the passed parameter is the read string from the file.

onError - The Consumer called on failure.

unwatch

public void unwatch(Path dir)

Unwatch the given directory Path.

Parameters:

dir - The directory to be unwatched.

unwatchUp

public void unwatchUp(Path dir)

Unwatch the given directory and all its parents.

Parameters:

dir - The directory to be watched.

unwatchUp

public void unwatchUp(Path dir,
                      Path to)

Unwatch the given directory and all its parents up to the given ancestor.

Parameters:

dir - The directory to be watched.

to - The dir's ancestor Path (exclusive) where unwatching will be stopped. Can be null.

watch

public void watch(Path dir)
           throws IOException

Watch the given directory for entry create, delete, and modify events.

Parameters:

dir - The directory to be watched.

Throws:

IOException - If an I/O error occurs.

watchOrStreamError

public void watchOrStreamError(Path dir)

Watch the given directory for entry create, delete, and modify events. If an I/O error occurs, the exception is logged (emitted).

Parameters:

dir - The directory to be watched.

watchUp

public void watchUp(Path dir)
             throws IOException

Watch the given directory and all its parents for entry create, delete, and modify events.

This method is equivalent to calling watchUp(Path, Path) passing null to its second parameter.

Parameters:

dir - The directory to be watched.

Throws:

IOException - If an I/O error occurs.

watchUp

public void watchUp(Path dir,
                    Path to)
             throws IOException,
                    IllegalArgumentException

Watch the given directory and all its parents up to the given ancestor, for entry create, delete, and modify events.

Parameters:

dir - The directory to be watched.

to - The dir's ancestor Path (exclusive) where watching will be stopped. Can be null.

Throws:

IOException - If an I/O error occurs.

IllegalArgumentException - If to is not an ancestor of dir.

watchUpOrStreamError

public void watchUpOrStreamError(Path dir)

Watch the given directory and all its parents for entry create, delete, and modify events. If an I/O error occurs, the exception is logged (emitted).

This method is equivalent to calling watchUpOrStreamError(Path, Path) passing null to its second parameter.

Parameters:

dir - The directory to be watched.

watchUpOrStreamError

public void watchUpOrStreamError(Path dir,
                                 Path to)

Watch the given directory and all its parents up to the given ancestor, for entry create, delete, and modify events. If an I/O error occurs, the exception is logged (emitted).

Parameters:

dir - The directory to be watched.

to - The dir's ancestor Path (exclusive) where watching will be stopped. Can be null.

writeBinaryFile

public void writeBinaryFile(Path file,
                            byte[] content,
                            Consumer<FileTime> onSuccess,
                            Consumer<Throwable> onError)

Writes a binary file filling it with the given content. One of the two given Consumers will be called on success or on failure.

Files.write(java.nio.file.Path, java.lang.Iterable, java.nio.file.OpenOption...) will be called to actually write the file.

Note: the operation is executed by the Executor passed to the build(java.util.concurrent.Executor) method, i.e. in a different thread from the caller's one.

Parameters:

file - The pathname of the file to be written.

content - The bytes to be written.

onSuccess - The Consumer called on success, where the passed parameter is the written file timestamp.

onError - The Consumer called on failure.

writeTextFile

public void writeTextFile(Path file,
                          String content,
                          Charset charset,
                          Consumer<FileTime> onSuccess,
                          Consumer<Throwable> onError)

Writes a text file filling it with the given content. One of the two given Consumers will be called on success or on failure.

Files.write(java.nio.file.Path, java.lang.Iterable, java.nio.file.OpenOption...) will be called to actually write the file.

Note: the operation is executed by the Executor passed to the build(java.util.concurrent.Executor) method, i.e. in a different thread from the caller's one.

Parameters:

file - The pathname of the file to be written.

content - The String content to be written.

charset - The Charset to be used in writing the content into the file.

onSuccess - The Consumer called on success, where the passed parameter is the written file timestamp.

onError - The Consumer called on failure.