שימוש ב-ListenableFuture

הערך ListenableFuture מייצג את התוצאה של חישוב אסינכרוני: חישוב שיכול להיות שהסתיים או לא הסתיים עדיין. זהו סוג של Future שמאפשר לרשום קריאות חוזרות (callbacks) שיופעלו אחרי שהחישוב יסתיים, או באופן מיידי אם החישוב כבר הסתיים.

ListenableFuture לא נכלל ב-framework של Android, אלא מסופק על ידי Guava. למידע נוסף על ההטמעה של המחלקה הזו, קראו את ההסבר על ListenableFuture.

בהרבה ספריות קיימות של Jetpack, כמו CameraX או Health Services, יש שיטות אסינכרוניות שבהן סוג ההחזרה הוא ListenableFuture שמייצג את סטטוס הביצוע. במקרים מסוימים, יכול להיות שתצטרכו להטמיע שיטה שמחזירה ListenableFuture, למשל כדי לעמוד בדרישות של TileService.

ספריות נדרשות

מגניב

dependencies {
    implementation "com.google.guava:guava:31.0.1-android"

    // To use CallbackToFutureAdapter
    implementation "androidx.concurrent:concurrent-futures:1.3.0"

    // Kotlin
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.6.0"
}

Kotlin

dependencies {
    implementation("com.google.guava:guava:31.0.1-android")

    // To use CallbackToFutureAdapter
    implementation("androidx.concurrent:concurrent-futures:1.3.0")

    // Kotlin
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.6.0")
}

קבלת התוצאה של ListenableFuture

הוספת קריאה חוזרת (callback)

משתמשים ב-method העזר Futures.addCallback(...) כדי לצרף קריאות חוזרות (callbacks) של הצלחה וכישלון ל-ListenableFuture.

val future: ListenableFuture<QueryResult> = ...
Futures.addCallback(
    future,
    object : FutureCallback<QueryResult> {
        override fun onSuccess(result: QueryResult) {
            // handle success.
        }

        override fun onFailure(t: Throwable) {
            // handle failure.
        }
    },
    // causes the callbacks to be executed on the main (UI) thread.
    context.mainExecutor
)

השעיה ב-Kotlin

כשמשתמשים ב-Kotlin, הדרך הכי קלה להמתין לתוצאה של ListenableFuture היא להשתמש ב-await().

// import kotlinx.coroutines.guava.await

// ...

val future: ListenableFuture<QueryResult> = ...
val queryResult = future.await() // suspends awaiting success.

יכולת פעולה הדדית עם RxJava

אפשר ליצור Single של RxJava מ-ListenableFuture על ידי רישום של קריאות חוזרות (callbacks) בתוך SingleEmitter.

val future: ListenableFuture<QueryResult> = ...
val single = Single.create<QueryResult> {
    Futures.addCallback(future, object : FutureCallback<QueryResult> {
        override fun onSuccess(result: QueryResult) {
            it.onSuccess(result)
        }

        override fun onFailure(t: Throwable) {
            it.onError(t)
        }
    }, executor)
}

יצירת ListenableFuture

יצירת עתיד מיידי

אם ה-API לא אסינכרוני, אבל אתם צריכים לעטוף את התוצאה של פעולה שהושלמה ב-ListenableFuture, אתם יכולים ליצור ImmediateFuture. אפשר לעשות את זה באמצעות השיטה Futures.immediateFuture(...).

fun getResult(): ListenableFuture<QueryResult> {
    try {
        val queryResult = getQueryResult()
        return Futures.immediateFuture(queryResult)
    } catch (e: Exception) {
        return Futures.immediateFailedFuture(e)
    }
}

שימוש בשגרת משנה (coroutine)

ב-Kotlin, אפשר להשתמש ב-future{ ... } כדי להמיר את התוצאה של פונקציית השעיה ל-ListenableFuture.

// import kotlinx.coroutines.guava.future

suspend fun getResultAsync(): QueryResult = /* ... */

fun getResultFuture(): ListenableFuture<QueryResult> {
    return coroutineScope.future {
        getResultAsync()
    }
}

המרת קריאה חוזרת (callback)

כדי להמיר API שמבוסס על קריאה חוזרת (callback) ל-API שמשתמש ב-ListenableFuture, משתמשים ב-CallbackToFutureAdapter. ה-API הזה מסופק על ידי פריט המידע שנוצר בתהליך פיתוח (Artifact) androidx.concurrent:concurrent-futures.

מידע נוסף זמין ב-androidx.concurrent.

המרה מ-RxJava Single

כשמשתמשים ב-RxJava, אפשר להמיר Single ל-SettableFuture, שמטמיע את ListenableFuture.

fun getResult(): ListenableFuture<QueryResult> {
    val single: Single<QueryResult> = ...

    val future = SettableFuture.create<QueryResult>()
    single.subscribe(future::set, future::setException)
    return future
}