Como usar um ListenableFuture

Um ListenableFuture representa o resultado de um cálculo assíncrono: um cálculo que pode ou não ter terminado de produzir um resultado. É um tipo de Future que permite registrar callbacks para serem executados assim que o cálculo for concluído ou, se o cálculo já estiver concluído, imediatamente.

ListenableFuture não faz parte do framework do Android e é fornecido pelo Guava. Para mais informações sobre a implementação dessa classe, consulte Explicação sobre o ListenableFuture.

Muitas bibliotecas do Jetpack, como CameraX ou Recursos de saúde, têm métodos assíncronos em que o tipo de retorno é um ListenableFuture que representa o status da execução. Em alguns casos, pode ser necessário implementar um método que retorne um ListenableFuture, como para atender aos requisitos de TileService.

Bibliotecas necessárias

Groovy

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")
}

Como receber o resultado de um ListenableFuture

Como adicionar um callback

Use o método auxiliar Futures.addCallback(...) para anexar callbacks de sucesso e falha a um 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
)

Suspensão em Kotlin

Ao usar o Kotlin, a maneira mais fácil de aguardar o resultado de um ListenableFuture é usar await().

// import kotlinx.coroutines.guava.await

// ...

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

Interoperabilidade com RxJava

Um Single do RxJava pode ser criado com base em um ListenableFuture registrando callbacks em um 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)
}

Como criar um ListenableFuture

Criar uma reserva imediata

Se a API não for assíncrona, mas você precisar unir o resultado de uma operação concluída em um ListenableFuture, crie um ImmediateFuture. Isso pode ser feito usando o método de fábrica Futures.immediateFuture(...).

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

Como usar uma corrotina

No Kotlin, um future{ ... } pode ser usado para converter o resultado de uma função de suspensão em um ListenableFuture.

// import kotlinx.coroutines.guava.future

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

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

Como converter um callback

Para converter uma API baseada em callback em uma que use ListenableFuture, use CallbackToFutureAdapter. Essa API é fornecida pelo artefato androidx.concurrent:concurrent-futures.

Consulte androidx.concurrent para mais informações.

Como converter do RxJava Single

Ao usar o RxJava, um Single pode ser convertido em um SettableFuture, que implementa ListenableFuture.

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

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