0
# Kotlin Standard Library JDK 7 Extension
1

2
The Kotlin Standard Library JDK 7 extension provides comprehensive Path utilities using Java NIO APIs introduced in JDK 7 and higher. It offers a complete set of extension functions for `java.nio.file.Path` that enable idiomatic Kotlin file system operations, I/O, directory traversal, and more.
3

4
## Package Information
5

6
- **Package Name**: kotlin-stdlib-jdk7
7
- **Package Type**: maven
8
- **Group ID**: org.jetbrains.kotlin
9
- **Language**: Kotlin
10
- **Installation**: `implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.2.0'`
11

12
**Note**: The Java 9 module `kotlin.stdlib.jdk7` is deprecated and empty. For Java 9+ module systems, use `kotlin.stdlib` instead which transitively includes this functionality.
13

14
## Core Imports
15

16
```kotlin
17
import kotlin.io.path.*
18
import java.nio.file.Path
19
import java.nio.file.Paths
20
```
21

22
For specific functionality:
23

24
```kotlin
25
import kotlin.io.path.exists
26
import kotlin.io.path.createDirectories
27
import kotlin.io.path.readText
28
import kotlin.io.path.writeText
29
import kotlin.io.path.copyToRecursively
30
import kotlin.io.path.walk
31
```
32

33
## Basic Usage
34

35
```kotlin
36
import kotlin.io.path.*
37
import java.nio.file.Paths
38

39
// Create and manipulate paths
40
val path = Paths.get("/home/user/documents/file.txt")
41
val filename = path.name                    // "file.txt"
42
val extension = path.extension              // "txt"
43
val parent = path.parent                    // Path to "/home/user/documents"
44

45
// Check file existence and properties
46
if (path.exists()) {
47
    println("File size: ${path.fileSize()} bytes")
48
    println("Is readable: ${path.isReadable()}")
49
    println("Is directory: ${path.isDirectory()}")
50
}
51

52
// Create directories and files
53
val newDir = Paths.get("/tmp/myapp")
54
newDir.createDirectories()
55

56
val configFile = newDir / "config.txt"
57
configFile.writeText("Setting=Value")
58

59
// Read and write files
60
val content = configFile.readText()
61
println("Config content: $content")
62

63
// List directory contents
64
newDir.listDirectoryEntries("*.txt").forEach { file ->
65
    println("Found text file: ${file.name}")
66
}
67
```
68

69
## Architecture
70

71
The kotlin-stdlib-jdk7 extension is built around several key components:
72

73
- **Path Extensions**: Extension properties and functions for `java.nio.file.Path` providing idiomatic Kotlin operations
74
- **File I/O Operations**: Stream-based and convenience methods for reading/writing files with charset support
75
- **Directory Operations**: Creation, listing, and traversal of directory structures
76
- **Tree Walking**: Comprehensive directory tree traversal with multiple options (breadth/depth-first, link following)
77
- **Recursive Operations**: Experimental APIs for recursive copying and deletion with error handling
78
- **Platform Implementations**: JDK 7+ specific implementations including Android compatibility
79

80
## Capabilities
81

82
### Path Operations
83

84
Core path manipulation including resolution, relativization, and property access for robust file system navigation.
85

86
```kotlin { .api }
87
val Path.name: String
88
val Path.nameWithoutExtension: String
89
val Path.extension: String
90
val Path.pathString: String
91
val Path.invariantSeparatorsPathString: String
92

93
fun Path.absolute(): Path
94
fun Path.relativeTo(base: Path): Path
95
operator fun Path.div(other: Path): Path
96
operator fun Path.div(other: String): Path
97

98
fun Path(path: String): Path
99
fun Path(base: String, vararg subpaths: String): Path
100
fun URI.toPath(): Path
101
```
102

103
[Path Operations](./path-operations.md)
104

105
### File System Operations
106

107
File and directory operations including existence checks, creation, deletion, copying, and attribute management.
108

109
```kotlin { .api }
110
fun Path.exists(vararg options: LinkOption): Boolean
111
fun Path.isDirectory(vararg options: LinkOption): Boolean
112
fun Path.isRegularFile(vararg options: LinkOption): Boolean
113

114
fun Path.createFile(vararg attributes: FileAttribute<*>): Path
115
fun Path.createDirectory(vararg attributes: FileAttribute<*>): Path
116
fun Path.createDirectories(vararg attributes: FileAttribute<*>): Path
117

118
fun Path.copyTo(target: Path, overwrite: Boolean = false): Path
119
fun Path.moveTo(target: Path, overwrite: Boolean = false): Path
120
fun Path.deleteExisting()
121
fun Path.deleteIfExists(): Boolean
122

123
fun Path.listDirectoryEntries(glob: String = "*"): List<Path>
124
```
125

126
[File System Operations](./file-system.md)
127

128
### File I/O Operations
129

130
Comprehensive file input/output operations including streams, readers/writers, and convenience methods for text and binary data.
131

132
```kotlin { .api }
133
fun Path.inputStream(vararg options: OpenOption): InputStream
134
fun Path.outputStream(vararg options: OpenOption): OutputStream
135
fun Path.reader(charset: Charset = Charsets.UTF_8, vararg options: OpenOption): InputStreamReader
136
fun Path.bufferedReader(charset: Charset = Charsets.UTF_8, bufferSize: Int = DEFAULT_BUFFER_SIZE, vararg options: OpenOption): BufferedReader
137

138
fun Path.readText(charset: Charset = Charsets.UTF_8): String
139
fun Path.writeText(text: CharSequence, charset: Charset = Charsets.UTF_8, vararg options: OpenOption)
140
fun Path.readBytes(): ByteArray
141
fun Path.writeBytes(array: ByteArray, vararg options: OpenOption)
142

143
fun Path.readLines(charset: Charset = Charsets.UTF_8): List<String>
144
fun Path.writeLines(lines: Iterable<CharSequence>, charset: Charset = Charsets.UTF_8, vararg options: OpenOption): Path
145
```
146

147
[File I/O Operations](./file-io.md)
148

149
### Tree Traversal Operations
150

151
Advanced directory tree traversal with walking sequences and customizable file visitor patterns for complex file operations.
152

153
```kotlin { .api }
154
fun Path.walk(vararg options: PathWalkOption): Sequence<Path>
155
fun Path.visitFileTree(visitor: FileVisitor<Path>, maxDepth: Int = Int.MAX_VALUE, followLinks: Boolean = false)
156
fun Path.visitFileTree(maxDepth: Int = Int.MAX_VALUE, followLinks: Boolean = false, builderAction: FileVisitorBuilder.() -> Unit)
157

158
fun fileVisitor(builderAction: FileVisitorBuilder.() -> Unit): FileVisitor<Path>
159

160
enum class PathWalkOption {
161
    INCLUDE_DIRECTORIES,
162
    BREADTH_FIRST, 
163
    FOLLOW_LINKS
164
}
165
```
166

167
[Tree Traversal Operations](./tree-traversal.md)
168

169
### Recursive Operations
170

171
Experimental APIs for recursive file operations with comprehensive error handling and customizable behaviors.
172

173
```kotlin { .api }
174
@ExperimentalPathApi
175
fun Path.copyToRecursively(
176
    target: Path,
177
    onError: (source: Path, target: Path, exception: Exception) -> OnErrorResult = { _, _, exception -> throw exception },
178
    followLinks: Boolean,
179
    overwrite: Boolean
180
): Path
181

182
@ExperimentalPathApi
183
fun Path.deleteRecursively()
184
```
185

186
[Recursive Operations](./recursive-operations.md)
187

188
## Types
189

190
```kotlin { .api }
191
@ExperimentalPathApi
192
annotation class ExperimentalPathApi
193

194
@SinceKotlin("2.1")
195
enum class PathWalkOption {
196
    INCLUDE_DIRECTORIES,
197
    BREADTH_FIRST,
198
    FOLLOW_LINKS
199
}
200

201
@ExperimentalPathApi
202
enum class OnErrorResult {
203
    SKIP_SUBTREE,
204
    TERMINATE
205
}
206

207
@ExperimentalPathApi
208
enum class CopyActionResult {
209
    CONTINUE,
210
    SKIP_SUBTREE,
211
    TERMINATE
212
}
213

214
@ExperimentalPathApi
215
interface CopyActionContext {
216
    fun Path.copyToIgnoringExistingDirectory(target: Path, followLinks: Boolean): CopyActionResult
217
}
218

219
@SinceKotlin("2.1")
220
interface FileVisitorBuilder {
221
    fun onPreVisitDirectory(function: (directory: Path, attributes: BasicFileAttributes) -> FileVisitResult)
222
    fun onVisitFile(function: (file: Path, attributes: BasicFileAttributes) -> FileVisitResult)
223
    fun onVisitFileFailed(function: (file: Path, exception: IOException) -> FileVisitResult)  
224
    fun onPostVisitDirectory(function: (directory: Path, exception: IOException?) -> FileVisitResult)
225
}
226
```