FlowLiveDataConversions

public final class FlowLiveDataConversions


Summary

Public methods

static final @NonNull Flow<@NonNull T>
<T extends Object> FlowLiveDataConversions.asFlow(
    @NonNull LiveData<@NonNull T> receiver
)

Creates a Flow containing values dispatched by originating LiveData: at the start a flow collector receives the latest value held by LiveData and then observes LiveData updates.

static final @NonNull LiveData<@NonNull T>
<T extends Object> FlowLiveDataConversions.asLiveData(
    @NonNull Flow<@NonNull T> receiver,
    @NonNull CoroutineContext context,
    long timeoutInMs
)

Creates a LiveData that has values collected from the origin Flow.

static final @RequiresApi(value = "26") @NonNull LiveData<@NonNull T>
<T extends Object> FlowLiveDataConversions.asLiveData(
    @NonNull Flow<@NonNull T> receiver,
    @NonNull CoroutineContext context,
    @NonNull Duration timeout
)

Creates a LiveData that has values collected from the origin Flow.

Public methods

FlowLiveDataConversions.asFlow

@NonNull
public static final Flow<@NonNull T> <T extends Object> FlowLiveDataConversions.asFlow(
    @NonNull LiveData<@NonNull T> receiver
)

Creates a Flow containing values dispatched by originating LiveData: at the start a flow collector receives the latest value held by LiveData and then observes LiveData updates.

When a collection of the returned flow starts the originating LiveData becomes active. Similarly, when a collection completes LiveData becomes inactive.

BackPressure: the returned flow is conflated. There is no mechanism to suspend an emission by LiveData due to a slow collector, so collector always gets the most recent value emitted.

FlowLiveDataConversions.asLiveData

@NonNull
public static final LiveData<@NonNull T> <T extends Object> FlowLiveDataConversions.asLiveData(
    @NonNull Flow<@NonNull T> receiver,
    @NonNull CoroutineContext context,
    long timeoutInMs
)

Creates a LiveData that has values collected from the origin Flow.

The upstream flow collection starts when the returned LiveData becomes active (LiveData.onActive). If the LiveData becomes inactive (LiveData.onInactive) while the flow has not completed, the flow collection will be cancelled after timeoutInMs milliseconds unless the LiveData becomes active again before that timeout (to gracefully handle cases like Activity rotation).

After a cancellation, if the LiveData becomes active again, the upstream flow collection will be re-executed.

If the upstream flow completes successfully or is cancelled due to reasons other than LiveData becoming inactive, it will not be re-collected even after LiveData goes through active inactive cycle.

If flow completes with an exception, then exception will be delivered to the CoroutineExceptionHandler of provided context. By default EmptyCoroutineContext is used to so an exception will be delivered to main's thread UncaughtExceptionHandler. If your flow upstream is expected to throw, you can use catch operator on upstream flow to emit a helpful error object.

The timeoutInMs can be changed to fit different use cases better, for example increasing it will give more time to flow to complete before being canceled and is good for finite flows that are costly to restart. Otherwise if a flow is cheap to restart decreasing the timeoutInMs value will allow to produce less values that aren't consumed by anything.

Parameters
@NonNull CoroutineContext context

The CoroutineContext to collect the upstream flow in. Defaults to EmptyCoroutineContext combined with Dispatchers.Main.immediate

long timeoutInMs

The timeout in ms before cancelling the block if there are no active observers (LiveData.hasActiveObservers. Defaults to DEFAULT_TIMEOUT.

FlowLiveDataConversions.asLiveData

@RequiresApi(value = "26")
@NonNull
public static final @RequiresApi(value = "26") LiveData<@NonNull T> <T extends Object> FlowLiveDataConversions.asLiveData(
    @NonNull Flow<@NonNull T> receiver,
    @NonNull CoroutineContext context,
    @NonNull Duration timeout
)

Creates a LiveData that has values collected from the origin Flow.

The upstream flow collection starts when the returned LiveData becomes active (LiveData.onActive). If the LiveData becomes inactive (LiveData.onInactive) while the flow has not completed, the flow collection will be cancelled after timeout unless the LiveData becomes active again before that timeout (to gracefully handle cases like Activity rotation).

After a cancellation, if the LiveData becomes active again, the upstream flow collection will be re-executed.

If the upstream flow completes successfully or is cancelled due to reasons other than LiveData becoming inactive, it will not be re-collected even after LiveData goes through active inactive cycle.

If flow completes with an exception, then exception will be delivered to the CoroutineExceptionHandler of provided context. By default EmptyCoroutineContext is used to so an exception will be delivered to main's thread UncaughtExceptionHandler. If your flow upstream is expected to throw, you can use catch operator on upstream flow to emit a helpful error object.

The timeout can be changed to fit different use cases better, for example increasing it will give more time to flow to complete before being canceled and is good for finite flows that are costly to restart. Otherwise if a flow is cheap to restart decreasing the timeout value will allow to produce less values that aren't consumed by anything.

Parameters
@NonNull CoroutineContext context

The CoroutineContext to collect the upstream flow in. Defaults to EmptyCoroutineContext combined with Dispatchers.Main.immediate

@NonNull Duration timeout

The timeout in ms before cancelling the block if there are no active observers (LiveData.hasActiveObservers. Defaults to DEFAULT_TIMEOUT.