ForwardingFileSystem

abstract class ForwardingFileSystem(delegate: FileSystem) : FileSystem

A FileSystem that forwards calls to another, intended for subclassing.

Fault Injection

You can use this to deterministically trigger file system failures in tests. This is useful to confirm that your program behaves correctly even if its file system operations fail. For example, this subclass fails every access of files named unlucky.txt:

val faultyFileSystem = object : ForwardingFileSystem(FileSystem.SYSTEM) {
override fun onPathParameter(path: Path, functionName: String, parameterName: String): Path {
if (path.name == "unlucky.txt") throw IOException("synthetic failure!")
return path
}
}

You can fail specific operations by overriding them directly:

val faultyFileSystem = object : ForwardingFileSystem(FileSystem.SYSTEM) {
override fun delete(path: Path) {
throw IOException("synthetic failure!")
}
}

Observability

You can extend this to verify which files your program accesses. This is a testing file system that records accesses as they happen:

class LoggingFileSystem : ForwardingFileSystem(FileSystem.SYSTEM) {
val log = mutableListOf<String>()

override fun onPathParameter(path: Path, functionName: String, parameterName: String): Path {
log += "$functionName($parameterName=$path)"
return path
}
}

This makes it easy for tests to assert exactly which files were accessed.

@Test
fun testMergeJsonReports() {
createSampleJsonReports()
loggingFileSystem.log.clear()

mergeJsonReports()

assertThat(loggingFileSystem.log).containsExactly(
"list(dir=json_reports)",
"source(file=json_reports/2020-10.json)",
"source(file=json_reports/2020-12.json)",
"source(file=json_reports/2020-11.json)",
"sink(file=json_reports/2020-all.json)"
)
}

Transformations

Subclasses can transform file names and content.

For example, your program may be written to operate on a well-known directory like /etc/ or /System. You can rewrite paths to make such operations safer to test.

You may also transform file content to apply application-layer encryption or compression. This is particularly useful in situations where it's difficult or impossible to enable those features in the underlying file system.

Abstract Functions Only

Some file system functions like copy are implemented by using other features. These are the non-abstract functions in the FileSystem interface.

This class forwards only the abstract functions; non-abstract functions delegate to the other functions of this class. If desired, subclasses may override non-abstract functions to forward them.

Constructors

ForwardingFileSystem
Link copied to clipboard
common
fun ForwardingFileSystem(delegate: FileSystem)

Functions

appendingSink
Link copied to clipboard
common
open override fun appendingSink(file: Path): Sink
Returns a sink that appends bytes to the end of file, creating it if it doesn't already exist.
atomicMove
Link copied to clipboard
common
open override fun atomicMove(source: Path, target: Path)
Moves source to target in-place if the underlying file system supports it.
canonicalize
Link copied to clipboard
common
open override fun canonicalize(path: Path): Path
Resolves path against the current working directory and symlinks in this file system.
copy
Link copied to clipboard
common
open fun copy(source: Path, target: Path)
Copies all of the bytes from the file at source to the file at target.
createDirectories
Link copied to clipboard
common
fun createDirectories(dir: Path)
Creates a directory at the path identified by dir, and any enclosing parent path directories, recursively.
createDirectory
Link copied to clipboard
common
open override fun createDirectory(dir: Path)
Creates a directory at the path identified by dir.
delete
Link copied to clipboard
common
open override fun delete(path: Path)
Deletes the file or directory at path.
deleteRecursively
Link copied to clipboard
common
open fun deleteRecursively(fileOrDirectory: Path)
Recursively deletes all children of fileOrDirectory if it is a directory, then deletes fileOrDirectory itself.
equals
Link copied to clipboard
common
open operator fun equals(other: Any?): Boolean
exists
Link copied to clipboard
common
fun exists(path: Path): Boolean
Returns true if path identifies an object on this file system.
hashCode
Link copied to clipboard
common
open fun hashCode(): Int
list
Link copied to clipboard
common
open override fun list(dir: Path): List<Path>
Returns the children of the directory identified by dir.
metadata
Link copied to clipboard
common
fun metadata(path: Path): FileMetadata
Returns metadata of the file, directory, or object identified by path.
metadataOrNull
Link copied to clipboard
common
open override fun metadataOrNull(path: Path): FileMetadata?
Returns metadata of the file, directory, or object identified by path.
onPathParameter
Link copied to clipboard
common
open fun onPathParameter(path: Path, functionName: String, parameterName: String): Path
Invoked each time a path is passed as a parameter to this file system.
onPathResult
Link copied to clipboard
common
open fun onPathResult(path: Path, functionName: String): Path
Invoked each time a path is returned by delegate.
open
Link copied to clipboard
common
open override fun open(file: Path, read: Boolean, write: Boolean): FileHandle
Returns a handle to operate on file.
read
Link copied to clipboard
common
inline fun <T> read(file: Path, readerAction: BufferedSource.() -> T): T
Creates a source to read file, executes readerAction to read it, and then closes the source.
sink
Link copied to clipboard
common
open override fun sink(file: Path): Sink
Returns a sink that writes bytes to file from beginning to end.
source
Link copied to clipboard
common
open override fun source(file: Path): Source
Returns a source that reads the bytes of file from beginning to end.
toString
Link copied to clipboard
common
open override fun toString(): String
write
Link copied to clipboard
common
inline fun <T> write(file: Path, writerAction: BufferedSink.() -> T): T
Creates a sink to write file, executes writerAction to write it, and then closes the sink.

Properties

delegate
Link copied to clipboard
common
val delegate: FileSystem
FileSystem to which this instance is delegating.