com.swoval.files

Interface FileTreeRepository<T>

Type Parameters:

T - the type of data stored in the FileTreeDataViews.Entry instances for the cache

All Superinterfaces:

java.lang.AutoCloseable, FileTreeDataView<T>, FileTreeDataViews.ObservableCache<T>, FileTreeView, FileTreeViews.Observable<FileTreeDataViews.Entry<T>>, PathWatcher<FileTreeDataViews.Entry<T>>

public interface FileTreeRepository<T>
extends FileTreeDataView<T>, PathWatcher<FileTreeDataViews.Entry<T>>, FileTreeDataViews.ObservableCache<T>, java.lang.AutoCloseable

Provides an in memory cache of portions of the file system. Directories are added to the cache using the register(java.nio.file.Path, int) method. Once a Path is added the cache, its contents may be retrieved using the FileTreeDataView.list(java.nio.file.Path, int, com.swoval.functional.Filter<? super com.swoval.files.TypedPath>) method. The cache stores the path information in FileTreeDataViews.Entry instances.

A default implementation is provided by FileTreeRepositories.get(com.swoval.files.FileTreeDataViews.Converter<T>, boolean). The user may cache arbitrary information in the cache by customizing the FileTreeDataViews.Converter that is passed into the factory FileTreeRepositories.get(com.swoval.files.FileTreeDataViews.Converter<T>, boolean).

The cache allows the user to register a regular file, directory or symbolic link. After registration, the cache should monitor the path (and in the case of symbolic links, the target of the link) for updates. Whenever an update is detected, the cache updates its internal representation of the file system. When that is complete, it will notify all of the registered Observers of the change. In general, the update that is sent in the callback will be visible if the user lists the relevant path. It is however, possible that if the file is being updated rapidly that the internal state of the cache may change in between the callback being invoked and the user listing the path. Once the file system activity settles down, the cache should always end up in a consistent state where it mirrors the state of the file system.

The semantics of the list method are very similar to the linux `ls` tool. Listing a directory returns all of the subdirectories and files contained in the directory and the empty list if the directory is empty. Listing a file, however, will return the entry for the file if it exists and the empty list otherwise.

Method Summary

Modifier and Type	Method and Description
Either<java.io.IOException,java.lang.Boolean>	register(java.nio.file.Path path, int maxDepth) Register a path with the cache.
void	unregister(java.nio.file.Path path) Unregister a path from the cache.

Methods inherited from interface com.swoval.files.FileTreeDataView

list, listEntries

Methods inherited from interface java.lang.AutoCloseable

close

Methods inherited from interface com.swoval.files.PathWatcher

close

Methods inherited from interface com.swoval.files.FileTreeDataViews.ObservableCache

addCacheObserver

Methods inherited from interface com.swoval.files.FileTreeViews.Observable

addObserver, removeObserver

Method Detail

register

Either<java.io.IOException,java.lang.Boolean> register(java.nio.file.Path path,
                                                       int maxDepth)

Register a path with the cache. A successful call to this method will both start monitoring of the path add will fill the cache for this path.

Specified by:

register in interface PathWatcher<FileTreeDataViews.Entry<T>>

Parameters:

path - the directory to watch for file events and to add to the cache

maxDepth - the maximum maxDepth of subdirectories to watch

Returns:

an Either that will return a right value when no exception is thrown. The right value will be true if the path has not been previously registered. The Either will be a left if any IOException is thrown attempting to register the path.

unregister

void unregister(java.nio.file.Path path)

Unregister a path from the cache. This removes the path from monitoring and from the cache so long as the path isn't covered by another registered path. For example, if the path /foo was previously registered, after removal, no changes to /foo or files in /foo should be detected by the cache. Moreover, calling FileTreeDataView.list(java.nio.file.Path, int, com.swoval.functional.Filter<? super com.swoval.files.TypedPath>) for /foo should return an empty list. If, however, we register both /foo recursively and /foo/bar (recursively or not), after unregistering /foo/bar, changes to /foo/bar should continue to be detected and /foo/bar should be included in the list returned by FileTreeDataView.list(java.nio.file.Path, int, com.swoval.functional.Filter<? super com.swoval.files.TypedPath>).

Specified by:

unregister in interface PathWatcher<FileTreeDataViews.Entry<T>>

Parameters:

path - the path to unregister