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:
FakeFileSystemis an in-memory file system suitable for testing. Note that this class is included in the
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
For improved capability and testability, consider structuring your classes to dependency inject a
FileSystem rather than using
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!
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.
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----------------------------
java.io.File class is Java's original file system API. The
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.
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.