Forem: Hicham Boushaba

Consuming Activity Results using coroutines: Part 2

Hicham Boushaba — Tue, 07 Dec 2021 11:21:00 +0000

This is the second post of a 2 parts article on how we can convert and consume Activity Results using coroutines.
In the first part, we were able to create a component that allowed us to convert the Activity Result's contract RequestMultiplePermissions to a Coroutine, while still able to handle Activity Recreation and process-death scenarios.

Generalize our code for all Activity Results

When reviewing the code we had for our PermissionManager class, the only specific parts related to permissions were:

The instantiation of RequestMultiplePermissions.
The mapping of the result to our defined sealed class.
Saving the permissions' list to the saved state, and using it as the flag for deciding if there is any pending operation.

So for designing our component that can be used to consume all Activity Results, we just need to generalize or remove the above points.
The first two points are straight forward, as we are aiming for a generic component here, we'll just remove them, so we'll pass the instance of our ActivityResultContract to our function, and we'll make it return the same type as defined by the contract. which means having a signature for our main function as this:

suspend fun <I, O, C : ActivityResultContract<I, O>> requestResult(
        contract: C,
        input: I
    ): O?

For the third point, we have many ways for handling it:

Using a simple boolean to tell us if there is any pending operation. This would work for most cases, but it has one downside, if a process-death occurs, and in the ViewModel's side we don't handle it, our component will still think that there is a pending operation, which means if we request a different type of results, it'll get stuck.
By saving the contract's class name, and comparing against it, this is a simple way for doing it, and would work for the majority of cases, although it may still break on a very specific case: if the ViewModel doesn't handle process-death, and we request another result using the same type of Contract, but using a different input, we'll probably return the wrong result.
By saving both the contract's class name and the input, and while this the ultimate solution, the comparison of the input against a saved value won't be straight forward, since it's a generic type, and we don't know if it has a valid equals implementation or not.

I opted for the option two, since the failure scenario is a very far corner case, and when using the SavedStateHandle correctly to save state, it won't occur at all, let me know what you think about this choice in the comments.

With all of this, we can have our component now:

Meet the library SuspendActivityResult

After starting the article, I decided to publish this component as a library for anyone interested, it's available in the same repo.
The Activity Result can be requested either using the low level API:

val uri = ActivityResultManager.getInstance().requestResult(
    contract = GetContent(),
    input = "image/*"
)

or using the extensions for the built-in ActivityResultContracts

val uri = ActivityResultManager.getInstance().getContent("image/*")

The example app has samples for using it for permissions and other activity results, and it has a sample for using it for a custom ActivityResultContract.

Conclusion

If you have any remarks or questions regarding the code or the API, please drop them in the comments section, I hope the library can be useful to some people.

Consuming Activity Results using coroutines: Part 1

Hicham Boushaba — Tue, 16 Nov 2021 19:46:57 +0000

Handling results from other Activies was always a tedious task: you need to override callbacks in the Activity/Fragment, and you need to manage the different request codes, and when you get a result, you need to parse it and this was never easy*.

* will the returned Uri be in intent.data or passed in the extras (looking at you RingtoneManager.EXTRA_RINGTONE_PICKED_URI)? what's the key of the returned data inside the extras and what's its type?...

To solve the above issues, the Android team introduced the androidx's Activity Result API, it offers a nicer API, and it's easily extendable by writing custom Contracts, but it still requires doing most of the work on the UI layer, which means lots of going back and forth between the View and the ViewModel for simple tasks.

This post is the first of two posts where we'll explore how we can optimize the API, by converting it to suspendable functions, and allowing it to be consumed by the ViewModel instead of the UI layer.
On this first part, we'll use permissions as an example, for this We'll start by showing an example on how the Activity Result API can be used to handle them, and then we'll try to write the new suspendable API together, and see how it can improve the readability of our code.
The code of the example can be found in this repo.

Part 2 is available here.

Activity Result API in play

Using the Activity Result API is quite simple, you just need to register an ActivityResultContract with your Activity/Fragment, while offering a callback that will be called when the result is delivered:

The registration will return an ActivityResultLauncher which you will use whenever you need to request the result

But while it's simple now, it becomes a bit complicated when we try to hook everything with the ViewModel, as it would require multiple two-way communication steps for something simple as the permission:

This is all while omitting some necessary parts, especially dealing with configuration changes and process-death.
For a full example, check the following sample fragment.

I feel like with this code, the View is doing so much, and we can't easily reuse this code if we need to request the same permission in multiple parts of the app.

Converting the Activity Result to suspendable functions: Permissions as an example

On this part, we'll try to move the logic of Activity Result API to another layer, to allow it to be consumed by the ViewModel.
Our goal is to have something similar to this by the end:

Let's get started, since the Activity Result API needs a reference to the Activity or the Fragment, the first thing we'll need, is a reference to the current Activity, we can use the function registerActivityLifecycleCallbacks to listen to Activity lifecycle changes, and keep a track of the latest one, a short example on how we can achieve this:

This class needs to be a singleton, and initiated in the Application's onCreate.
With this in hand, we can now "naively" write something like this easily:

Before testing our code, let's take a moment to check what it does:

We use a suspendCancellableCoroutine to convert the Activity result to a suspendable function.
We can't register our Contract directly using the function registerForActivityResult, as it requires to be called before onCreate, instead we use the activityResultRegistry directly, and here we just need to handle the unregistering ourself, so we use the finally block to make sure we are unregistering in either a cancellation or completion.

Now, let's test the code:

When testing this, we'll see that it works well, until you rotate your phone, or a process-death occurs, when we'll leak the activity, and also we won't be able to recover to continue handling the result.

Fix the issue for screen rotation

This happens because we are capturing the current Activity in a variable, this variable stays available for the whole function's lifetime, which is longer than the Activity's lifecycle. To solve this, we need a way to listen to the Activity changes, to be able to cancel the previous block and unregister the Contract, then re-register with the new Activity, so we need to change our ActivityProvider's implementation to offer a Flow instead of a single variable, which can bee easily done using MutableStateFlow, for full code check this.
With those changes, we can now use Flow's mapLatest operator to handle registering our Contract, and unregistering it when the block is cancelled, since it would occur everytime the Activity wach changed, which would give something like this:

Let's examine what the code does:

We capture the value of the key outside of the Flow, to make sure we keep using the same value for other Activities.
We have a variable isLaunched to let us know that the ActivityResultLauncher has been already launched, to avoid re-submitting the Intent or permission request.
the suspendable funtion passed to mapLatest will be cancelled each time the upstream Flow emits a new value, so it does exactly what we need, it suspends waiting for the Activity Result, but if the Activity was changed before, it cancels the current block, and starts a new one with the new Activity.

When testing the new code, it works pretty well on screen rotations, we can continue the Flow from where we left, great.
Except that it has an issue, if a process-death occurs, or the Activity was destroyed to release memory (or when "Don't keep activities" option is enabled), we can't recover even if our ViewModel uses SavedStateHandle to restore its state, since the viewModelScope will be cancelled, and our function will lose its state, which takes us to the last part of this article, how we can use the Activity's SavedStateRegistry to save our state, and make sure that even when we make a second call to requestPermissions it will continue from where it left.

Saving the state

ComponentActivity from androidx has a component called SavedStateRegistry that allows plugging in custom components to save additional data and retrieve it later, and this is exactly what we need here, since we can't use the Activity's callbacks, we'll use it to keep track of the last key we used to register our Contract, to be able to intercept the Activity Result even after process-death:

The code seems complicated, but it differs from the previous step in only the fact that it tries to restore the last used key from the SavedStateRegistry, and also it registers our SavedStateProvider to save the state when needed.
If we test the code now, using a ViewModel that uses SavedStateHandle for saving/restoring its state correctly, we'll see that we continue to receive the Activity Result correctly even after a process-death.

What we can do with this component now

Being able to use a suspendable function like this here, makes it way easier to extract our logic into a reusable components, for example if your app requests the permission from multiple areas, and uses the same logic for showing the rationale or handling a pemanent denial, you'll be able to create a component or a usecase that handles this for you, without having to repeat it on each Fragment/Activity.
For example a class like this:

This component is self contained, and allows to handle the whole permission request Flow, and can be reused on every screen easily.
A full example can be found here.

Conclusion

To sum up, the callback aspect of the new Result Activity API allows it to be converted to suspendable functions relatively easy, instead of needing an intermediate Fragment or Activity for handling the callbacks (as many libraries do), and this conversion made it easier to extract pieces of the logic to their own component. But the code is not tested against all scenarios, especially when the app has multiple activities, so we'll try to check this in the next part, and we'll try to generalize what we did with permissions so far for all the Activity Result Contracts.
Please let me know in the comments if you have any remarks about this solution, thanks for your time.

Making cold Flows lifecycle-aware

Hicham Boushaba — Sat, 30 Oct 2021 17:37:01 +0000

With the introduction of SharedFlow and StateFlow, many developers are migrating from LiveData in the UI layer, to take advantage of the goodies of the Flow API, and for a more consistent API accross all layers, but sadly, and as Christophe Beyls explains on his post, the migration is complicated when the view's lifecycle enters into equation.
The version 2.4 of lifecycle:lifecycle-runtime-ktx introduced APIs to help on this side: repeatOnLifecycle and flowWithLifecycle (to learn more about those, check the article: A safer way to collect flows from Android UIs), on this article, we'll try them, and we'll dicuss a minor issue that they introduce in some cases, and we'll see if we can come up with a more flexible solution.

The problem

To explain the problem, let's imagine we have a sample app that listens to location updates when it's active, and whenever a new location is available, it'll make an API call to retrieve some nearby locations.
So for listening to location updates, we'll write a LocationObserver class that offers a cold Flow returning them

class LocationObserver(private val context: Context) {
    fun observeLocationUpdates(): Flow<Location> {
        return callbackFlow {
            Log.d(TAG, "observing location updates")

            val client = LocationServices.getFusedLocationProviderClient(context)
            val locationRequest = LocationRequest
                .create()
                .setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY)
                .setInterval(0)
                .setFastestInterval(0)

            val locationCallback = object : LocationCallback() {
                override fun onLocationResult(locationResult: LocationResult?) {
                    if (locationResult != null) {
                        Log.d(TAG, "got location ${locationResult.lastLocation}")
                        trySend(locationResult.lastLocation)
                    }
                }
            }

            client.requestLocationUpdates(
                locationRequest,
                locationCallback,
                Looper.getMainLooper()
            )

            awaitClose {
               Log.d(TAG, "stop observing location updates")
               client.removeLocationUpdates(locationCallback)
            }
        }
    }
}

then we'll use this class in our ViewModel

class MainViewModel(application: Application) : AndroidViewModel(application) {
    private val locationObserver = LocationObserver(application)

    private val hasLocationPermission = MutableStateFlow(false)

private val locationUpdates: Flow<Location> = hasLocationPermission
        .filter { it }
        .flatMapLatest { locationObserver.observeLocationUpdates() }

val viewState: Flow<ViewState> = locationUpdates
        .mapLatest { location ->
            val nearbyLocations = api.fetchNearbyLocations(location.latitude, location.longitude)
            ViewState(
                isLoading = false,
                location = location,
                nearbyLocations = nearbyLocations
            )
        }

    fun onLocationPermissionGranted() {
        hasLocationPermission.value = true
    }
}

For the sake of simplicity, we are using an AndroidViewModel to have access to the Context directly, and we won't handle different edge cases about location permissions and settings.

Now, all we have to do in our Fragment, is to listen to the react to the viewState updates, and update the UI:

viewLifecycleOwner.lifecycleScope.launchWhenStarted {
   viewModel.viewState
       .onEach { viewState ->
            binding.render(viewState)
        }
       .launchIn(this)
}

where the FragmentMainBinding#render is an extension that can update the UI.

Now if we try to run the app, when we put it to the background, we'll see that the LocationObserver is still listening to location updates, then fetching the nearby places, even though the UI is ignoring them.

Our first attempt to solve this, is to use the new API flowWithLifecycle

viewLifecycleOwner.lifecycleScope.launchWhenStarted {
   viewModel.viewState
       .flowWithLifecycle(viewLifecycleOwner.lifecycle)
       .onEach { viewState ->
            binding.render(viewState)
        }
       .launchIn(this)
}

If we run the app, now, we'll notice that it prints the following line to Logcat each time it goes to background

D/LocationObserver: stop observing location updates

So the new APIs fix the issue, but there is an issue, whenever the app goes to background then we come back, we lose the data we had before, and we hit the API another time even if the location hasn't changed, this occurs because flowWithLifecycle will cancel the upstream each time the used lifecycle goes below the passed State (which is Started for us) and restart it again when the state is restaured.

Solution using the official APIs

The official solution while keeping using flowWithLifecycle is explained in Jose Alcérreca's article, and it's to use stateIn but with a special timeout set to 5 seconds to account for configuration changes, so we need to add the following statement to our viewState's Flow to this

stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(stopTimeoutMillis = 5000L),
            initialValue = ViewState(isLoading = true)
        )

This works well, except, the stopping/restarting of the Flow each time the app goes to background creates another issue, let's say for example that we don't need to fetch the nearby places unless the location has changed by a minimum distance, so let's change our code to the following

val viewState: Flow<ViewState> = locationUpdates
        .distinctUntilChanged { l1, l2 -> l1.distanceTo(l2) <= 300 }
        .mapLatest { location ->
            val nearbyLocations = api.fetchNearbyLocations(location.latitude, location.longitude)
            ViewState(
                isLoading = false,
                location = location,
                nearbyLocations = nearbyLocations
            )
        }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(stopTimeoutMillis = 5000L),
            initialValue = ViewState(isLoading = true)
        )

If we run the app now, then we put it to background for longer than 5 seconds, and re-open it, we will notice that the we re-fetch the nearby locations even if the location didn't change at all, and while this is not a big issue for most cases, it can be costly on some situations: slow network, or slow APIs, or heavy calculations...

An alternative solution: making the Flows lifecycle-aware

What if we could make our locationUpdates flow lifecycle-aware, to stop it without any explicit interaction from the Fragment? This way, we will be able to stop listening to location updates, without having to restart the whole Flow, and re-run all the intermediate operators if the location didn't change, and we could even collect our viewState Flow regularly using launchWhenStarted, since we will be sure it won't run as we are not emitting any locations.

If only we can have an internal hot flow inside our ViewModel that let's us observe the View's state:

private val lifeCycleState = MutableSharedFlow<Lifecycle.State>(replay = 1, onBufferOverflow = BufferOverflow.DROP_OLDEST)

Then we would be able to have an extension that stops then restarts our upstream Flow depending on the lifecycle:

fun <T> Flow<T>.whenAtLeast(requiredState: Lifecycle.State): Flow<T> {
    return lifeCycleState.map { state -> state.isAtLeast(requiredState) }
            .distinctUntilChanged()
            .flatMapLatest {
                // flatMapLatest will take care of cancelling the upstream Flow
                if (it) this else emptyFlow()
            }
}

Actually, we can implement this using LifecycleEventObserver API

private val lifecycleObserver = object : LifecycleEventObserver {
    override fun onStateChanged(source: LifecycleOwner, event: Lifecycle.Event) {
        lifeCycleState.tryEmit(event.targetState)
        if (event.targetState == Lifecycle.State.DESTROYED) {
            source.lifecycle.removeObserver(this)
        }
    }
}

Which we can use to hook up to the Fragment's lifecycle events:

fun startObservingLifecycle(lifecycle: Lifecycle) {
    lifecycle.addObserver(lifecycleObserver)
}

Having this, we can now update our locationUpdates Flow to the following

private val locationUpdates: Flow<Location> = hasLocationPermission
    .filter { it }
    .flatMapLatest { locationObserver.observeLocationUpdates() }
    .whenAtLeast(Lifecycle.State.STARTED)

And we get to observe our viewState Flow regularly in the Fragment, without worrying about keeping the GPS on when the app goes to the background

viewLifecycleOwner.lifecycleScope.launchWhenStarted {
    viewModel.viewState
        .onEach { viewState ->
            binding.render(viewState)
        }
        .launchIn(this)
}

The extension whenAtLeast is flexible in the sense that it can be applied to any Flow in the chain, and not only during the collection, and as we saw, applying it to the upstream triggering Flow (location updates in our case), resulted in less calculations:

The intermediate operators including the nearby places fetching doesn't run unless needed.
We won't re-emit the result to the UI on coming back from background since we won't cancel the collection.

If you want to check the full code on Github: https://github.com/hichamboushaba/FlowLifecycle, and the full code contains a sample on how we can unit test our ViewModels with those changes in place.

Conclusion

As you can see, using kotlin Flows on the UI layer is still not always straightforward, but still, I prefer it over LiveData, to have access to all its APIs, and for a consistent API across all layers, for the issue we discussed here, I personally just put the explained logic in a BaseFragment/BaseViewModel, and then I can use it in all the screens without any boilerplate, and it worked well for me on my personal app since 2018.
Let's hope that this feature request gets implemented to offer a way to pause the collection cooperatively without cancelling it, which would fix the issue completely.

What do you think about the solutions explained on this article? And did I miss a simpler solution for this issue? Let me know on the comments.