0
# kotlinx-coroutines-jdk8
1

2
kotlinx-coroutines-jdk8 is a backwards compatibility stub module for Kotlin coroutines JDK8 integration functionality. Since version 1.7.0, the JDK8-specific functionality has been merged directly into the core kotlinx-coroutines library, making this package a transition module that maintains compatibility for existing projects by providing dependency access to the core JDK8 integration APIs.
3

4
## Package Information
5

6
- **Package Name**: kotlinx-coroutines-jdk8
7
- **Package Type**: maven
8
- **Group ID**: org.jetbrains.kotlinx
9
- **Language**: Kotlin
10
- **Installation**: `implementation("org.jetbrains.kotlinx:kotlinx-coroutines-jdk8:1.10.2")`
11

12
## Core Imports
13

14
Since this is a stub module, all JDK8 integration functionality is accessed through imports from the core kotlinx-coroutines library:
15

16
```kotlin
17
// CompletableFuture integration
18
import kotlinx.coroutines.future.*
19

20
// java.time integration  
21
import kotlinx.coroutines.time.*
22

23
// Stream integration
24
import kotlinx.coroutines.stream.*
25

26
// Core coroutines functionality
27
import kotlinx.coroutines.*
28
```
29

30
## Basic Usage
31

32
The most common use case is converting between coroutines and CompletableFuture:
33

34
```kotlin
35
import kotlinx.coroutines.*
36
import kotlinx.coroutines.future.*
37
import java.util.concurrent.CompletableFuture
38

39
// Start a coroutine and get CompletableFuture
40
val scope = CoroutineScope(Dispatchers.Default)
41
val future: CompletableFuture<String> = scope.future {
42
    delay(1000)
43
    "Hello from coroutine!"
44
}
45

46
// Convert CompletableFuture to Deferred
47
val deferred: Deferred<String> = future.asDeferred()
48

49
// Await CompletableFuture in suspending context
50
suspend fun example() {
51
    val result = future.await()
52
    println(result)
53
}
54
```
55

56
## Architecture
57

58
This stub module provides access to three main integration areas:
59

60
- **Future Integration**: Bidirectional conversion between coroutines and CompletableFuture/CompletionStage
61
- **Time Integration**: java.time.Duration adapters for coroutine timing functions
62
- **Stream Integration**: Convert Java 8 Streams to Kotlin Flows
63

64
All functionality is implemented in the core kotlinx-coroutines library and accessed transitively through this dependency.
65

66
## Capabilities
67

68
### CompletableFuture Integration
69

70
Bidirectional conversion between coroutines and Java's CompletableFuture/CompletionStage.
71

72
```kotlin { .api }
73
/**
74
 * Starts a coroutine and returns its result as CompletableFuture
75
 */
76
fun <T> CoroutineScope.future(
77
    context: CoroutineContext = EmptyCoroutineContext,
78
    start: CoroutineStart = CoroutineStart.DEFAULT,
79
    block: suspend CoroutineScope.() -> T
80
): CompletableFuture<T>
81

82
/**
83
 * Converts Deferred to CompletableFuture
84
 */
85
fun <T> Deferred<T>.asCompletableFuture(): CompletableFuture<T>
86

87
/**
88
 * Converts Job to CompletableFuture<Unit>
89
 */
90
fun Job.asCompletableFuture(): CompletableFuture<Unit>
91

92
/**
93
 * Converts CompletionStage to Deferred
94
 */
95
@Suppress("DeferredIsResult")
96
fun <T> CompletionStage<T>.asDeferred(): Deferred<T>
97

98
/**
99
 * Suspending await for CompletionStage
100
 */
101
suspend fun <T> CompletionStage<T>.await(): T
102
```
103

104
### java.time Integration
105

106
Adapter methods that accept java.time.Duration parameters for coroutine timing functions.
107

108
```kotlin { .api }
109
/**
110
 * java.time adapter for delay function
111
 */
112
suspend fun delay(duration: Duration): Unit
113

114
/**
115
 * java.time adapter for withTimeout
116
 */
117
suspend fun <T> withTimeout(
118
    duration: Duration, 
119
    block: suspend CoroutineScope.() -> T
120
): T
121

122
/**
123
 * java.time adapter for withTimeoutOrNull
124
 */
125
suspend fun <T> withTimeoutOrNull(
126
    duration: Duration,
127
    block: suspend CoroutineScope.() -> T
128
): T?
129

130
/**
131
 * java.time adapter for Flow.debounce
132
 */
133
@FlowPreview
134
fun <T> Flow<T>.debounce(timeout: Duration): Flow<T>
135

136
/**
137
 * java.time adapter for Flow.sample
138
 */
139
@FlowPreview
140
fun <T> Flow<T>.sample(period: Duration): Flow<T>
141

142
/**
143
 * java.time adapter for SelectBuilder.onTimeout
144
 */
145
fun <R> SelectBuilder<R>.onTimeout(
146
    duration: Duration,
147
    block: suspend () -> R
148
): Unit
149
```
150

151
### Stream Integration
152

153
Convert Java 8 Streams to Kotlin Flows for seamless integration.
154

155
```kotlin { .api }
156
/**
157
 * Converts Stream to Flow and closes the stream afterwards
158
 */
159
fun <T> Stream<T>.consumeAsFlow(): Flow<T>
160
```
161

162
## Types
163

164
All types are defined in the core kotlinx-coroutines library:
165

166
```kotlin { .api }
167
// From kotlinx.coroutines
168
interface Job : CoroutineContext.Element
169
interface Deferred<out T> : Job
170
class CoroutineScope(context: CoroutineContext)
171
enum class CoroutineStart
172
interface CoroutineContext
173

174
// From kotlinx.coroutines.flow  
175
interface Flow<out T>
176
interface FlowCollector<in T>
177

178
// From kotlinx.coroutines.selects
179
interface SelectBuilder<in R>
180

181
// Java types (from JDK)
182
class CompletableFuture<T>
183
interface CompletionStage<T>
184
interface Stream<T>
185
class Duration
186
```
187

188
## Notes
189

190
- This is a backwards compatibility stub module - no direct API exists in the package itself
191
- All functionality is provided through transitive dependency on kotlinx-coroutines-core
192
- For new projects, consider depending directly on kotlinx-coroutines-core
193
- The module contains only a Java module descriptor (`module kotlinx.coroutines.jdk8 {}`)
194
- Recommended migration path: replace dependency with kotlinx-coroutines-core and update imports accordingly