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 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, symlinks, 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 IOExceptions when operations don'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.

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): 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
abstract 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
abstract 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
abstract fun createDirectory(dir: Path)
Creates a directory at the path identified by dir.
delete
Link copied to clipboard
common
abstract 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
abstract 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
abstract fun metadataOrNull(path: Path): FileMetadata?
Returns metadata of the file, directory, or object identified by path.
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
abstract fun sink(file: Path): Sink
Returns a sink that writes bytes to file from beginning to end.
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.
toString
Link copied to clipboard
common
open 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.

Inheritors

ForwardingFileSystem
Link copied to clipboard