FileSystem

abstract class FileSystem

Read and write access to a hierarchical collection of files, addressed by paths. This is a natural interface to the current computer's local file system.

Other implementations are possible:

  • FakeFileSystem is an in-memory file system suitable for testing. Note that this class is included in the okio-fakefilesystem artifact.

  • ForwardingFileSystem is a file system decorator. Use it to apply monitoring, encryption, compression, or filtering to another file system.

  • A ZIP file system could provide access to the contents of a .zip file.

For improved capability and testability, consider structuring your classes to dependency inject a FileSystem rather than using FileSystem.SYSTEM directly.

Small API

---------

This interface is deliberately limited in which features it supports.

It is not suitable for high-latency or unreliable remote file systems. It lacks support for retries, timeouts, cancellation, and bulk operations.

It cannot create special file types like hard links, pipes, or mounts. Reading or writing these files works as if they were regular files.

It cannot read or write file access control features like the UNIX chmod and Windows access control lists. It does honor these controls and will fail with an IOException if privileges are insufficient!

It cannot lock files or check which files are locked.

It cannot watch the file system for changes.

Applications that need rich file system features should use another API!

Multiplatform

-------------

This class supports a matrix of Kotlin platforms (JVM, Kotlin/Native, Kotlin/JS) and operating systems (Linux, macOS, and Windows). It attempts to balance working similarly across platforms with being consistent with the local operating system.

This is a blocking API which limits its applicability on concurrent Node.js services. File operations will block the event loop (and all JavaScript execution!) until they complete.

It supports the path schemes of both Windows (like C:\Users) and UNIX (like /home). Note that path resolution rules differ by platform.

Differences vs. Java IO APIs

----------------------------

The java.io.File class is Java's original file system API. The delete and renameTo methods return false if the operation failed. The list method returns null if the file isn't a directory or could not be listed. This class always throws an IOException when an operation doesn't succeed.

The java.nio.Path and java.nio.Files classes are the entry points of Java's new file system API. Each Path instance is scoped to a particular file system, though that is often implicit because the Paths.get() function automatically uses the default (ie. system) file system. In Okio's API paths are just identifiers; you must use a specific FileSystem object to do I/O with.

abstract class FileSystem
abstract class FileSystem

Constructors

FileSystem
Link copied to clipboard
common
fun FileSystem()

Types

Companion
Link copied to clipboard
common
object Companion

Functions

appendingSink
Link copied to clipboard
common
abstract fun appendingSink(file: Path, mustExist: Boolean = false): Sink
Returns a sink that appends bytes to the end of file, creating it if it doesn't already exist.
abstract fun appendingSink(file: Path, mustExist: Boolean = false): Sink
abstract fun appendingSink(file: Path, mustExist: Boolean = false): Sink
atomicMove
Link copied to clipboard
common
abstract fun atomicMove(source: Path, target: Path)
Moves source to target in-place if the underlying file system supports it.
abstract fun atomicMove(source: Path, target: Path)
abstract fun atomicMove(source: Path, target: Path)
canonicalize
Link copied to clipboard
common
abstract fun canonicalize(path: Path): Path
Resolves path against the current working directory and symlinks in this file system.
abstract fun canonicalize(path: Path): Path
abstract fun canonicalize(path: Path): Path
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.
open fun copy(source: Path, target: Path)
open fun copy(source: Path, target: Path)
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.
fun createDirectories(dir: Path)
fun createDirectories(dir: Path)
createDirectory
Link copied to clipboard
common
abstract fun createDirectory(dir: Path)
Creates a directory at the path identified by dir.
abstract fun createDirectory(dir: Path)
abstract fun createDirectory(dir: Path)
createSymlink
Link copied to clipboard
common
abstract fun createSymlink(source: Path, target: Path)
Creates a symbolic link at source that resolves to target.
abstract fun createSymlink(source: Path, target: Path)
abstract fun createSymlink(source: Path, target: Path)
delete
Link copied to clipboard
common
abstract fun delete(path: Path)
Deletes the file or directory at path.
abstract fun delete(path: Path)
abstract fun delete(path: 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.
open fun deleteRecursively(fileOrDirectory: Path)
open fun deleteRecursively(fileOrDirectory: Path)
exists
Link copied to clipboard
common
fun exists(path: Path): Boolean
Returns true if path identifies an object on this file system.
fun exists(path: Path): Boolean
fun exists(path: Path): Boolean
list
Link copied to clipboard
common
abstract fun list(dir: Path): List<Path>
Returns the children of the directory identified by dir.
abstract fun list(dir: Path): List<Path>
abstract fun list(dir: Path): List<Path>
listOrNull
Link copied to clipboard
common
abstract fun listOrNull(dir: Path): List<Path>?
Returns the children of the directory identified by dir.
abstract fun listOrNull(dir: Path): List<Path>?
abstract fun listOrNull(dir: Path): List<Path>?
listRecursively
Link copied to clipboard
common
open fun listRecursively(dir: Path, followSymlinks: Boolean = false): Sequence<Path>
Returns a sequence that lazily traverses the children of dir using repeated calls to list.
open fun listRecursively(dir: Path, followSymlinks: Boolean = false): Sequence<Path>
open fun listRecursively(dir: Path, followSymlinks: Boolean = false): Sequence<Path>
metadata
Link copied to clipboard
common
fun metadata(path: Path): FileMetadata
Returns metadata of the file, directory, or object identified by path.
fun metadata(path: Path): FileMetadata
fun metadata(path: Path): FileMetadata
metadataOrNull
Link copied to clipboard
common
abstract fun metadataOrNull(path: Path): FileMetadata?
Returns metadata of the file, directory, or object identified by path.
abstract fun metadataOrNull(path: Path): FileMetadata?
abstract fun metadataOrNull(path: Path): FileMetadata?
openReadOnly
Link copied to clipboard
common
abstract fun openReadOnly(file: Path): FileHandle
Returns a handle to read file.
abstract fun openReadOnly(file: Path): FileHandle
abstract fun openReadOnly(file: Path): FileHandle
openReadWrite
Link copied to clipboard
common
abstract fun openReadWrite(file: Path, mustCreate: Boolean = false, mustExist: Boolean = false): FileHandle
Returns a handle to read and write file.
abstract fun openReadWrite(file: Path, mustCreate: Boolean = false, mustExist: Boolean = false): FileHandle
abstract fun openReadWrite(file: Path, mustCreate: Boolean = false, mustExist: Boolean = false): FileHandle
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.
inline fun <T> read(file: Path, readerAction: BufferedSource.() -> T): T
inline fun <T> read(file: Path, readerAction: BufferedSource.() -> T): T
sink
Link copied to clipboard
common
abstract fun sink(file: Path, mustCreate: Boolean = false): Sink
Returns a sink that writes bytes to file from beginning to end.
abstract fun sink(file: Path, mustCreate: Boolean = false): Sink
abstract fun sink(file: Path, mustCreate: Boolean = false): Sink
source
Link copied to clipboard
common
abstract fun source(file: Path): Source
Returns a source that reads the bytes of file from beginning to end.
abstract fun source(file: Path): Source
abstract fun source(file: Path): Source
write
Link copied to clipboard
common
inline fun <T> write(file: Path, mustCreate: Boolean = false, writerAction: BufferedSink.() -> T): T
Creates a sink to write file, executes writerAction to write it, and then closes the sink.
inline fun <T> write(file: Path, mustCreate: Boolean = false, writerAction: BufferedSink.() -> T): T
inline fun <T> write(file: Path, mustCreate: Boolean = false, writerAction: BufferedSink.() -> T): T

Inheritors

ForwardingFileSystem
Link copied to clipboard
ZipFileSystem
Link copied to clipboard

Extensions

openZip
Link copied to clipboard
fun FileSystem.openZip(zipPath: Path): FileSystem