File System
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 theokio-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.file.Path
and java.nio.file.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.
Inheritors
Constructors
Types
Functions
Creates a directory at the path identified by dir, and any enclosing parent path directories, recursively.
Deletes the file or directory at path.
Recursively deletes all children of fileOrDirectory if it is a directory, then deletes fileOrDirectory itself.
Returns a handle to read and write file. This will create the file if it doesn't already exist.
Creates a source to read file, executes readerAction to read it, and then closes the source. This is a compact way to read the contents of a file.
Creates a sink to write file, executes writerAction to write it, and then closes the sink. This is a compact way to write a file.