DEV Community: Christophe Beyls

Strategies for automatically refreshing data on Android using Kotlin Flow

Christophe Beyls — Sat, 05 Aug 2023 22:00:00 +0000

This is the third part of a series of articles discussing the usage of Kotlin Flow to efficiently load data in Android applications. It’s a direct follow-up to part 2: “Smarter Shared Kotlin Flows”, as it reuses the same concepts to cover another use case: automatic periodic refresh of the user interface.

Simple periodic refresh

When it’s not possible to determine precisely when a data set displayed by the UI has changed, or when it changes too frequently, a common strategy is to reload the data periodically at a fixed interval while the screen is visible.

One of the simplest ways to achieve this is to create a Flow from an infinite loop calling delay() between emissions:

fun tickerFlow(period: Duration): Flow<Unit> = flow {
    while (true) {
        emit(Unit)    // Tick
        delay(period)
    }
}

This is equivalent to the Observable.interval() operator in RxJava with a fixed emitted value (Unit) and an initial delay of 0.

Then, transform this Flow using the map() or mapLatest() operator to perform the loading action on each “tick” of the timer and return the result:

tickerFlow(REFRESH_INTERVAL)
    .map {
        repository.loadSomeData()
    }

Note the subtle difference in behavior between the two operators:

With map() the entire Flow will be executed in sequence within a single coroutine, meaning delay() will only start running after the loading operation completes. As a result, each loading operation will be delayed by the amount of time it took to perform the previous loading operation, plus the fixed interval.
With mapLatest() the main coroutine will collect the upstream values of tickerFlow() while a child coroutine will be created to perform the loading operation concurrently and collect the result without suspending the main coroutine. This means that delay() will start running immediately after the previous tick and each loading operation will start precisely according to schedule. This also means that the interval must be longer than the typical loading time because it will act as a timeout: a previous loading operation that did not complete in time when tickerFlow() emits a new value will be canceled. A new child coroutine then replaces the previous one to execute the next loading operation.

This simple implementation will always trigger a new load immediately when the Flow collection starts or restarts, without taking the previous run into account. This is good enough for short intervals of a few seconds, when the loading action is considered cheap.

Making refresh smarter in order to leverage caching

However, for longer refresh intervals and when the loading action demands more resources (like performing an API call), the above algorithm is not very efficient: when a screen that was temporarily hidden becomes visible again and the Flow collection restarts, we would like to avoid the unnecessary work of reloading data that is still considered fresh for the minutes or hours to come.

In the first article, we saw that StateFlow is commonly used to cache the latest value of a Flow and share it between multiple subscribers. But StateFlow and SharedFlow have their limitations, as they are unable to simply pause and resume work following the Activity lifecycle: if the underlying Flow collection is stopped when the screen is hidden, it always has to restart from scratch when the screen becomes visible again, making the cache useless in that scenario.

In the second article, we studied the creation of a custom Flow operator designed to work around these limitations: flowWhileShared(). It allows to make only the upstream part of an underlying Flow lifecycle-aware, so that the heavy work in the downstream part of the Flow can be avoided when combined with some filtering logic. StateFlow’s cache can then be used to its full potential.

As it turns out, we can use that same operator to implement a smarter version of tickerFlow(), designed to be used in combination with StateFlow. synchronizedTickerFlow() is lifecycle-aware and will only emit values while the parent StateFlow has at least one subscriber. What makes it smarter is that it also remembers the time when to emit next, so after resuming from a pause with no subscribers, it will first wait until that time is reached before emitting the next value.

fun synchronizedTickerFlow(
    period: Duration,
    subscriptionCount: StateFlow<Int>,
    timeSource: TimeSource = ElapsedRealTimeSource
): Flow<Unit> {
    return flow {
        var nextEmissionTimeMark: TimeMark? = null
        flow {
            nextEmissionTimeMark?.let { delay(-it.elapsedNow()) }
            while (true) {
                emit(Unit)
                nextEmissionTimeMark = timeSource.markNow() + period
                delay(period)
            }
        }
            .flowWhileShared(subscriptionCount, SharingStarted.WhileSubscribed())
            .collect(this)
    }
}

Let’s analyze the code in detail.

One of the first things you’ll notice is that the time counting logic is based on the new kotlin.time API that became stable in version 1.9.0 of the Kotlin standard library. This includes the classes Duration, TimeSource and TimeMark.

The main Flow returned by the function collects the output of a secondary Flow used internally. The role of the main Flow is simply to encapsulate state (nextEmissionTimeMark) and make it local to each collection, as it is the case with all Flow operators. The secondary Flow is the one that starts and stops according to the parent lifecycle (stopping immediately when the provided subscriptionCount reaches zero) thanks to the flowWhileShared() operator.

Note: we don’t pass any timeout value to the sharing strategy SharingStarted.WhileSubscribed() because the cost of stopping and restarting the secondary Flow is cheap.

The main logic of that secondary flow is almost identical to tickerFlow(), the only difference being that the first “tick” will only be emitted when nextEmissionTimeMark is reached. A TimeMark represents a point in time and nextEmissionTimeMark is the earliest point in time when the next emission needs to occur.

When the main Flow collection starts, nextEmissionTimeMark is initially null and the first tick is emitted immediately with no delay. Then, after each emission, the future point in time of the next emission is computed by retrieving the current point in time from a TimeSource using markNow() and adding the period Duration to it.

When the secondary Flow restarts after a pause and nextEmissionTimeMark is not null, the amount of time (Duration) to wait to reach that point in time is computed by calling elapsedNow() on the TimeMark and negating the result, because elapsedNow() actually returns the elapsed time between the TimeMark and now, which is a negative value if the TimeMark is in the future. Note that calling delay() with a negative Duration has no effect and will return immediately, so we don’t need to separately handle the case where the next emission time has already been reached and is now in the past.

The importance of using the right `TimeSource`

For this code to work properly, it’s mandatory to use a TimeSource based on a monotonic clock instead of a wall clock. A monotonic clock is a clock that always moves forward and cannot be adjusted or reset. kotlin.time already provides TimeSource.Monotonic for this purpose, which is based on System.nanoTime() on the JVM and Android. While this clock is good enough for the JVM, it can cause issues for Android applications because it stops when the device’s CPU enters deep sleep, which can occur after the screen turns off. This means that if a user unlocks an Android device that just spent 10 minutes in deep sleep and goes back to the application, the data refresh will be triggered 10 minutes too late.

On Android, a more suitable clock for this usage is SystemClock.elapsedRealtimeNanos() which is a monotonic clock with nanosecond precision that includes the time that the device spent in deep sleep mode. Since the official Android Jetpack libraries for Kotlin don’t (yet?) provide a TimeSource based on this clock, we create our own:

object ElapsedRealTimeSource : AbstractLongTimeSource(DurationUnit.NANOSECONDS) {
    override fun read(): Long = SystemClock.elapsedRealtimeNanos()
    override fun toString(): String = "TimeSource(SystemClock.elapsedRealtimeNanos())"
}

Because the TimeSource is passed as argument to synchronizedTickerFlow(), the implementation can be swapped easily, for example by using TestTimeSource for tests.

Putting it all together

Following is an example of how synchronizedTickerFlow() can be used in combination with the stateFlow() factory function described in the previous article. As a reminder, this factory function allows a StateFlow to share its subscriptionCount with the underlying Flow that feeds it.

val results: StateFlow<Result> = stateFlow(viewModelScope, Result.Empty) { subscriptionCount ->
    synchronizedTickerFlow(REFRESH_PERIOD, subscriptionCount)
        .mapLatest {
            repository.loadSomeData()
        }
}

Here is how this code reacts to the changes of UI state, step by step:

When the UI first becomes visible and starts collecting the results StateFlow, synchronizedTickerFlow() will start emitting new values periodically, which will trigger loading the latest data. This data will be cached in the StateFlow and shared with all current and future subscribers;
When the UI becomes invisible and stops collecting the StateFlow, the underlying Flow stays active but the ticker will not emit any new value so no new data will be loaded. We are saving resources;
When the UI becomes visible again and starts collecting again, it will immediately receive the cached value of the StateFlow. In the underlying Flow, the ticker will resume. But first it will wait for the planned time of the next emission to be reached before emitting anything. This way, data will be preserved in the StateFlow cache as long as it’s valid instead of being replaced unconditionally. We are now saving more resources.

Advanced use case: sharing the time reference

Sometimes, a screen requires multiple data sources to be queried separately, and updated periodically. If the data is time-dependent, all the sources need to use the same point in time as a reference to ensure their results are consistent with each other.

Example: you want to periodically load both the schedule of the last 10 minutes and the schedule of the next 10 minutes and make sure the results don’t overlap.

That reference point in time can be updated periodically using synchronizedTickerFlow() and cached and shared using stateFlow(), exactly like in the previous example:

private val timeReferenceFlow: Flow<Instant> = stateFlow(viewModelScope, null) { subscriptionCount ->
    synchronizedTickerFlow(REFRESH_PERIOD, subscriptionCount)
        .map { Instant.now() }
}.filterNotNull()

What’s different is that each data source will connect to the same timeReferenceFlow instance and use a combination of flowWhileShared() and distinctUntilChanged() to ensure the data is only updated when the time reference changes. The result will also be cached in a StateFlow:

val results1: StateFlow<Result> = stateFlow(viewModelScope, Result.Empty) { subscriptionCount ->
    timeReferenceFlow
        .flowWhileShared(subscriptionCount, SharingStarted.WhileSubscribed())
        .distinctUntilChanged()
        .map { timeReference: Instant ->
            repository.loadDataForTime(timeReference)
        }
}

Having a StateFlow depend on another one using this pattern allows the UI lifecycle to be propagated and aggregated from one StateFlow to the next through the subscriptionCount. Here is how they will react to the changes of UI state:

When the UI starts collecting the first result StateFlow, its subscriptionCount will update from 0 to 1 and flowWhileShared() will start collecting the upstream timeReferenceFlow;
Being a StateFlow itself, the subscriptionCount of timeReferenceFlow will also update from 0 to 1 and synchronizedTickerFlow() will wake up and start emitting new values as soon as the previous one is expired;
As more result StateFlows start collecting the same timeReferenceFlow, they all increment its subscriptionCount and receive the cached time reference immediately. The timer stays active and each newly computed time reference is distributed to all subscribers;
When all the result StateFlows connected to timeReferenceFlow stop being collected by the UI, its subscriptionCount will finally reach zero and synchronizedTickerFlow() will stop emitting new values.

We have demonstrated that timeReferenceFlow is also lifecycle-aware, even if it’s never collected directly by the UI. Its value will only update if it has at least one active subscriber and the previous value has expired. This allows maximizing cache usage throughout the application while keeping all the results consistent with each other.

Summary

Using a ticker Flow is a simple and elegant way to periodically update data presented to the user in Kotlin applications. In order to implement efficient caching on Android, it’s possible to synchronize the timer with the UI lifecycle by stopping it when a StateFlow exposing the data has no more subscribers, and by memorizing the time of the next tick according to the proper monotonic clock.

That complexity can be hidden behind a few reusable Flow operators.

I’ve been using this technique successfully in production applications. Do you think it makes sense or is it too complex? Did you find a better way to achieve the same results? Please share your feedback in the comments section and help spread the word if you liked it.

Kotlin JSON Benchmark on Android (2022): Moshi vs Kotlin Serialization

Christophe Beyls — Thu, 13 Oct 2022 22:00:00 +0000

When it comes to automatic serialization and deserialization of Kotlin classes using the JSON format, the two main libraries compatible with Kotlin metadata are currently Moshi and Kotlin Serialization. This compatibility is especially important for non-null types and default values during deserialization, where lack of proper Kotlin support could result in unexpected values occurring at runtime, such as null values in non-null fields. If you’re still using legacy libraries like Gson to parse Kotlin classes, it’s time to reconsider.

Moshi has been supporting Kotlin classes since version 1.5.0, released in 2017. One year later, the next major release 1.6.0 added an annotation processor to generate adapters for Kotlin classes at compile time. I was quite interested in the performance gains allowed by this solution and wrote an article detailing what the generated code does.

JetBrains released version 1.0.0 of Kotlin Serialization in 2020 with built-in support for JSON. This library generates adapters at compile time similarly to Moshi’s annotation processor while being compatible with more platforms and formats. The lack of initial support for streaming was disappointing, so I didn’t even consider using it in production until streaming support was eventually added in version 1.3.0 in 2021. The JSON engine had also been rewritten in the meantime in order to improve performance. Recently, version 1.4.0 added integration with the Okio library, the same library used by Moshi under the hood.

Now that Kotlin Serialization looks full-featured and well-optimized, I thought it would be a good time to compare its performance against Moshi on Android devices with some benchmarks. Which one is the fastest? Take your bets.

The contenders

Moshi-Kotlin Reflection

The runtime Kotlin plugin of the Moshi library. The JSON adapters are generated at runtime using reflection. The main downside of this library is that it adds a runtime dependency to the big kotlin-reflect library (currently a 3 MiB jar file).

Moshi-Kotlin Codegen

The annotation processor Kotlin plugin of the Moshi library. The JSON adapters are generated at compile time by an annotation processor (compatible with both kapt and KSP). It increases build times, but adds no extra runtime dependency (besides the generated adapters).

Moshi-IR

An alternative Kotlin IR implementation of Moshi Codegen, created by Zac Sweers (the current main maintainer of Moshi). It does the exact same thing as Moshi-Kotlin Codegen, but is implemented as a Kotlin compiler plugin instead of an annotation processor for faster build times.

Note: Unlike Moshi-Kotlin Codegen, Moshi-IR doesn’t use very limited reflection at runtime to read default parameter values.
But since the Kotlin model classes used in the following benchmarks don’t have any default parameter values, this optimization will not be put to the test.

Kotlin Serialization

The official Kotlin multiplatform / multi-format serialization library created and maintained by JetBrains. The JSON adapters are generated at compile time by a compiler plugin. Contrary to Moshi which is only compatible with the JSON format, the adapters generated by Kotlin Serialization support other formats: Protocol Buffers, CBOR, HOCON and Properties. Support for more formats is also provided by third-party plugins. The benchmarks in this article will only test the JSON format.

Benchmark setup

This benchmark is based on Zac Sweers’ JSON Serialization Benchmarking github project, updated to add new tests and support the most recent versions of the libraries. You can also find it on Github.

Two different tests are run for each library, in both reading an writing modes:

Encoding and decoding Kotlin data classes to and from a JSON String;
Encoding and decoding Kotlin data classes to and from an in-memory byte buffer containing JSON data encoded in UTF-8. This recreates the conditions of reading or writing JSON files or JSON network responses, without the cost of I/O. Kotlin Serialization supports 2 different APIs to do this: java.io and okio. Both will be tested.

The benchmarks are run using the AndroidX Benchmark (Microbenchmark) library for more accuracy.

Test data

The test data consists of a 230 KiB JSON file encoded in UTF-8 containing a list of 60 users. Each user contains 23 fields of various types, including nested objects and nested lists. For reference, here is the Kotlin data class definition:

data class User(
    val id: String,
    val index: Int,
    val guid: String,
    val isActive: Boolean,
    val balance: String,
    val pictureUrl: String,
    val age: Int,
    val name: Name,
    val company: String,
    val email: String,
    val address: String,
    val about: String,
    val registered: String,
    val latitude: Double,
    val longitude: Double,
    val tags: List<String>,
    val range: List<Int>,
    val friends: List<Friend>,
    val images: List<Image>,
    val greeting: String,
    val favoriteFruit: String,
    val eyeColor: String,
    val phone: String
)

The same data is used for read and write tests.

Libraries versions

AndroidX Benchmark 1.1.0
Kotlin 1.7.10
Okio 3.2.0
Moshi 1.14.0
MoshiX (Moshi-IR) 0.18.3
Kotlin Serialization (KSerizalizer) 1.4.0

Test hardware and operating system

Google Pixel 4a (2020) running Android 13
Google Nexus 5 (2013) running Android 6

Write performance

Note: the scale on the Nexus 5 graph is about 10x the scale of the Pixel 4a graph, meaning the tests ran about 10 times slower on this older device.

The first thing we can notice is that the reflection-based adapters are much slower than the compile-time generated adapters, especially on the older Android version.

We can verify that performance of Moshi-Kotlin Codegen and Moshi-IR is virtually identical, since the generated code is supposed to be the same.

The Moshi tests producing a String run a bit slower than the tests writing to a byte buffer. This can be explained by the way this library works:

Moshi is built on top of the Okio library and works primarily with byte buffers, not characters or Strings. Obtaining a String requires an extra step: reading back and decoding the entire byte buffer into a String. That extra step is the overhead that can be seen in the Moshi String benchmarks. It’s less visible on the slower Nexus 5 because producing the bytes takes much more time.

In comparison, the Kotlin Serialization tests producing a String run faster than the tests writing to a byte buffer. This can again be explained by the way this library works:

The JSON module of Kotlin Serialization works primarily with sequences of characters and Strings. Writing to a byte buffer requires an extra step: converting the characters to bytes. This conversion is performed either by the java.io.Writer class (used by Json.encodeToStream() in the buffer test) or the okio.BufferedSink class (used by Json.encodeToBufferedSink() in the okiobuffer test). We can see that the performance of these two methods is very close so which one to use doesn’t really matter.

In both cases, writing to byte buffers on the lower-end Nexus 5 is more than two times slower using Kotlin Serialization JSON compared to using Moshi. On the newer Pixel 4a, the performance of the two libraries is very close. This could be partially explained by the fact that Kotlin Serialization JSON allocated two times more objects than Moshi during the test (1373 allocations vs 769 for Moshi), and the memory allocation and garbage collector performance improved significantly in newer Android versions.

Winner: Moshi-IR / Moshi-Kotlin Codegen, even if Kotlin Serialization is close on newer devices.

Loser: Moshi-Kotlin Reflection.

Read performance

Now let’s test the more common operation of converting JSON data to Kotlin objects.

On average, the reading tests are almost two times slower than the writing tests.

The reflection-based Moshi adapters are still slower than the compile-time generated adapters, but this time the overhead is lower than for writing tests.

The performance of Moshi-Kotlin Codegen and Moshi-IR is still virtually identical as expected.

Again, the Moshi tests taking a String as input run a bit slower than the tests reading directly from a byte buffer for a similar reason: Moshi needs to encode the String to a byte buffer first.

The most important outtake from this chart is that the buffering performance of Moshi-Kotlin Codegen/Moshi-IR is on par with Kotlin Serialization Json. The teams at JetBrains did an impressive job at improving performance since version 1.0.0 of the library, while also adding buffering support. It’s still a bit slower on the Nexus 5, probably because of the lower byte-to-char decoding performance of java.io.Reader compared to Okio on older Android versions.

Last but not least, we need to talk about the elephant in the room (the last bar on the right): there is something really wrong with the reading performance of the new Okio module of Kotlin Serialization JSON. While it’s supposed to reduce overhead, it’s actually two times slower than the “regular” streaming API based on java.io.InputStream and java.io.Reader.

The reason for this huge performance gap becomes obvious when looking at the source code of the current implementation:

internal class OkioSerialReader(private val source: BufferedSource): SerialReader {
    override fun read(buffer: CharArray, bufferOffset: Int, count: Int): Int {
        var i = 0
        while (i < count && !source.exhausted()) {
            buffer[bufferOffset + i] = source.readUtf8CodePoint().toChar()
            i++
        }
        return if (i > 0) i else -1
    }
}

Sure enough, the character array buffer is filled by decoding one character at a time, and checking for buffer exhaustion after each character. This is definitely a performance bottleneck, but an understandable one since the Okio API doesn’t provide a way to decode UTF-8 characters in batch to a CharArray yet. The best it can do is return a new String to copy to the array, which would allocate memory but probably still be faster.

In its current state, I see no reason to use the new Okio APIs of Kotlin Serialization JSON when targeting Android or the JVM. Just create a regular java.io.InputStream from your okio.BufferedSource instead:

Json.decodeFromStream(serializer, bufferedSource.inputStream())

That being said, if you need to implement a multiplatform JSON streaming parser that works on other platforms, then the Okio API of Kotlin Serialization is the only option. If the payload is small, it's probably better to fully convert it to a String first and not use streaming.

Winner: Moshi-IR / Moshi-Kotlin Codegen and Kotlin Serialization using InputStream (tie).

Loser: Kotlin Serialization using BufferedSource.

Read performance — Selective

In this final test, we’ll measure the performance of partial decoding: sometimes we’re not interested in parsing the entire JSON file and fields can be skipped. To test this, we modify the User data class to keep only 5 fields on 23:

data class User(
    val id: String,
    val index: Int,
    val guid: String,
    val age: Int,
    val name: Name
)

The test JSON file remains unchanged. All fields not present in the User class will be skipped by the JSON adapters.

In the previous test, the buffered reading performance of Moshi and Kotlin Serialization was identical or very close. With partial decoding, we can see that the gap widens and Moshi is ahead of Kotlin Serialization JSON, especially on older devices where it’s almost twice as fast when decoding bytes in streaming.

This is probably due to the fact that Moshi is able to directly skip unwanted bytes in the stream without having to decode them to characters first or allocate any memory, thanks to the powerful API of the Okio library. Kotlin Serialization JSON, on the other hand, has to decode all bytes to characters and also performs memory allocations while skipping the unwanted fields.

Conclusions

As with any microbenchmark, one needs to be careful when it comes to drawing conclusions. That being said, it’s safe to claim that:

The performance of Moshi 1.14.0 and Kotlin Serialization JSON 1.4.0 is very close and they both perfom very well;
Moshi-Kotlin Reflection should be avoided because compile-time generated adapters are always faster and don’t require extra runtime dependencies;
The current Okio integration in Kotlin Serialization JSON is mediocre and I would advise not to use it on Android and the JVM. It provides no substantial performance gains for encoding and hurts performance for decoding. I suspect that either this integration will be phased out in a future release, or the core JSON engine will be rewritten to take real advantage of Okio (like Moshi) instead of the limited high-level integration we have now.

And the most important conclusion of all:

The time required to encode or decode the JSON data is so small compared to the latency of the network or storage access that it doesn’t really matter and won’t be noticed, unless it’s so bad it goes off the charts. This is not the case for these two libraries.

Which one should you pick? The one that fits your needs best.
Both have their qualities:

Moshi has more advanced features and provides a lower-level JSON API for maximum control;
Kotlin Serialization is multiplatform (Javascript, Kotlin native) and its adapters work with other formats than JSON without extra configuration in the model classes. It’s also compatible with unsigned integer types, value classes and sealed classes out-of-the-box which is something to consider.

Thank you for reading and please share your own benchmark results if you have some.

ViewLifecycleLazy and other ways to avoid View memory leaks in Android Fragments

Christophe Beyls — Tue, 27 Sep 2022 22:00:00 +0000

Are your Fragments leaking?

Handling the lifecycle of Android Fragments is difficult. I already covered this topic in an article I wrote in 2017, before Google added a View-specific Lifecycle to Fragments in an attempt to solve some issues.

Until now, the number one cause of memory leaks when using Fragments remains the same: not properly clearing all direct and indirect View references in onDestroyView(). Tools like LeakCanary can help detecting some of these cases.

And of course, Jetpack Compose represents a big paradigm change which completely removes the need to keep View references but hey, we still have our legacy codebases to maintain!

I recently came across a blog post from Gabor Varadi describing an issue he encountered with a custom Kotlin delegated property he created to simplify managing view bindings in Fragments.

His solution is based on a class named AutoClearedValue from the architecture components samples. The purpose of AutoClearedValue is to provide a delegate that will automatically clear a value tied to one or more Views when the Fragment View hierarchy gets destroyed, in order to avoid the aforementioned memory leaks. This is an elegant alternative to declaring a Fragment property as nullable and manually setting it to null in onDestroyView(), which can be easily forgotten.

It turns out I had already come up with my own solution to do the exact same thing. And since my version is simpler and generates more optimized bytecode compared to AutoClearedValue and what Mr Varadi published, I decided to share it with you.

I named this delegate ViewLifecycleLazy. Like the name implies, the delegated property value is computed lazily and the Fragment’s current view lifecycle is observed in order to automatically clear the value when it moves to the DESTROYED state.

This is how it’s used in Fragments, for example with View Binding:

class MyFragment : Fragment(R.layout.my_fragment) {
    private val binding by viewLifecycleLazy(MyFragmentBinding::bind)
}

Why it’s simpler

The original code adds some unnecessary complexity by observing viewLifecycleOwnerLiveData, then in turn registering a new lifecycle observer on the new viewLifecycleOwner when it becomes available. It turns out this is not needed because the viewLifecycleOwner lifecycle observer can just be registered lazily, at the same time the value is initialized.

Since the property is designed to be read only when a view hierarchy is available, attempting to read it too early or too late will automatically throw an IllegalStateException when calling Fragment.requireView() or Fragment.viewLifecycleOwner: we don’t need to do that check ourselves.

Why it generates more optimized bytecode

The original code is a classic property delegate, an object implementing the ReadOnlyProperty interface which includes this function:

abstract operator fun getValue(thisRef: T, property: KProperty<*>): V

As a result, the compiler needs to generate extra metadata in the form of one KProperty object for each delegated property, even if this parameter is not actually used in the code of the delegate. For more details, check my 2017 blog post “Exploring Kotlin’s hidden costs — Part 3” which covers delegated properties.

Kotlin 1.4 added an optimization allowing to skip the generation of this metadata for delegated property operators declared as inline and not using the KProperty parameter. This includes the built-in operator of the standard Lazy interface:

inline operator fun <T> Lazy<T>.getValue(thisRef: Any?, property: KProperty<*>): T = value

By implementing Lazy instead of ReadOnlyProperty, no unnecessary metadata code will be generated.

Note: some may argue that this implementation does not strictly comply with the Lazy contract which states that once initialized, a property must stay initialized. If you think this is problematic, it’s possible to alter the above code to not implement Lazy and still benefit from the compiler optimization by adding a specialized inline delegated property operator for the ViewLifecycleLazy class. The operator will have to be imported for ViewLifecycleLazy to be recognized as a delegate.

Final advice: only use it if you have to

You should always try to architect your code in such a way that you don’t have to create properties in your Fragments to store references to Views in the first place.

The best way to do this is to always pass View references as function arguments instead of retrieving them through the Fragment, and register lifecycle-aware callbacks in onViewCreated() to update the View.
For example:

class MyFragment : Fragment(R.layout.fragment_example) {
    private val myViewModel: MyViewModel by viewModels()

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        val viewHolder = ViewHolder(view)

        initNavigationView(viewHolder.navigationView)

        val adapter = MyAdapter()
        viewHolder.recyclerView.adapter = adapter
        myViewModel.result.observe(viewLifecycleOwner) { result ->
            viewHolder.titleTextView.text = result.title
            adapter.submitList(result.list)
        }
    }

    private fun initNavigationView(navigationView: NavigationView) {
        // TODO
    }
}

As you can see in the above code, all view references like viewHolder or adapter are declared and used within the scope of the onViewCreated() function so none have to be stored as properties in the Fragment.

In order to improve readability, the code that configures the navigation menu is isolated in its own function initNavigationView() and the view references are passed as arguments.

Finally, the code which updates the View after its initialization is located inside a lifecycle-aware callback declared in onViewCreated(), in this case in the form of a LiveData observer. It could also be a coroutine launched from a LifecycleScope.

There are rare cases where this technique can’t be used or would make the code too complex. For these cases, you can use ViewLifecycleLazy.

Let’s conclude with an example from one of my own projects:

interface RecycledViewPoolProvider {
    val recycledViewPool: RecyclerView.RecycledViewPool
}

class ParentFragment : Fragment(R.layout.fragment_parent), RecycledViewPoolProvider {
    override val recycledViewPool by viewLifecycleLazy {
        RecyclerView.RecycledViewPool()
    }
}

It illustrates how to share a single lazily-created RecycledViewPool instance provided by a parent Fragment with multiple child Fragments hosting similarly-configured RecyclerViews. When the parent Fragment’s View hierarchy gets destroyed, the RecycledViewPool instance will be cleared automatically. A ViewLifecycleLazy delegate is a good option to expose a View reference outside of the Fragment class, but be careful to only read it when the Fragment has a view hierarchy.

I hope you enjoyed the quick read (compared to my previous articles) and learned a thing or two about Fragments and Kotlin delegated properties. Let’s continue the conversation in the comments section and on social networks.

Smarter Shared Kotlin Flows

Christophe Beyls — Sun, 05 Jun 2022 22:00:00 +0000

This is the second part of a series of articles about using Kotlin Flow on Android.

In the first part, we described the main limitation of Kotlin Flow when used inside ViewModel classes:

When a SharedFlow or StateFlow using the SharingStarted.WhileSubscribed() strategy is collected again after the user navigates back to an Activity or Fragment, its source upstream Flow will always restart from scratch, sometimes resulting in unnecessary work being performed when the previously cached data was still valid.

val results: StateFlow<SearchResult> =
    queryFlow.mapLatest { query ->
        repository.search(query)
    }.stateIn(
        scope = viewModelScope,
        started = SharingStarted.WhileSubscribed(5000L),
        initialValue = SearchResult.EMPTY
    )

In the above example, repository.search() will be executed again even if the latest value of queryFlow didn’t change in the meantime. This means a potential unnecessary network request or database query.

LiveData doesn’t suffer from this issue because its observers don’t need to unsubscribe when they become inactive: LiveData is lifecycle-aware and will postpone the delivery of new results until it becomes active, while also ensuring that the same result will never be delivered to the same observer twice (even when it becomes active again). For more details I invite you to read the full article.

At the end of this first part, we concluded that there was no simple and correct way to avoid performing this unnecessary work when relying only on the standard shareIn() or stateIn() operators.

In this second part, we are going to solve that efficiency problem by designing a new Flow operator that will allow SharedFlows to integrate better with the lifecycle.

Synchronizing with the Lifecycle

LiveData

The core reason why LiveData deals with lifecycles better than Flow is because the lifecycle state is automatically propagated upstream through all the LiveData instances so they can all pause cooperatively while preserving their state. To be exact, the information that is propagated is a simplified and aggregated lifecycle state called the active state:

A LiveData instance becomes active when at least one of its observers enters the STARTED lifecycle state. This may happen when a subscribed observer enters the STARTED state or when a new started observer subscribes;
A LiveData instance becomes inactive when none of its observers remains in the STARTED lifecycle state. This may happen when a subscribed observer moves back from the STARTED state to the CREATED state or when a started observer unsubscribes.

When applying a LiveData transformation like map() or switchMap(), the upstream LiveData instance automatically inherits the active state of the downstream LiveData instance.

When inactive, LiveData instances will automatically postpone delivering new results to observers downstream. Additionnaly, LiveData implementations may be notified in order to stop doing active work. For example, the LiveData coroutine builder will cancel its coroutine block when it becomes inactive.

SharedFlow

SharedFlow (and its subclass StateFlow) is a special kind of Flow that is able to broadcast the values emitted by a single source to multiple observers (called collectors) and replay the latest value to new observers, just like LiveData. A SharedFlow instance is both a collector and an emitter of values, and the upstream values are collected by SharedFlow independently from the downstream collectors.

Flow and SharedFlow do not support the Android Lifecycle class directly, but AndroidX Lifecycle APIs like Lifecycle.repeatOnLifecycle() must be used in the UI layer to synchronize the Flow collection with the Android Lifecycle: Flows must be collected only when the UI is in the STARTED lifecycle state or higher and the collecting coroutine should be canceled as soon as the UI becomes invisible.

SharedFlow implementations like MutableSharedFlow are also able to expose the current number of subscribed collectors which, when used in combination with the Lifecycle synchronization APIs mentioned above, can be used to infer something equivalent to the active state of LiveData:

A SharedFlow instance becomes active when the first collector subscribes;
A SharedFlow instance becomes inactive when the last collector unsubscribes.

The shareIn() and stateIn() extension functions are the simplest ways of creating a SharedFlow instance from a source upstream Flow. They accept a SharingStarted argument which is the strategy used to start and stop collecting the upstream Flow (from a separate coroutine) in response to the changes of “active state”.

In conclusion, SharedFlow can be made lifecycle-aware, but when using these limited APIs the only thing that can be done in response to an active state change is to launch or cancel a coroutine collecting the entire upstream Flow. The upstream Flow cannot just pause and resume where it left off: canceling the coroutine means losing the entire internal state of the current collection and having to restart the upstream Flow from scratch during the next collection.

This makes it impractical to use operators like distinctUntilChanged() in the upstream Flow because the last emitted value will be forgotten as soon as the coroutine collecting the Flow gets canceled by the SharedFlow strategy. Flow operators are not designed to work across multiple collections.

An alternative approach

We need to find a trade-off. Instead of canceling the coroutine collecting the entire upstream Flow, we should keep it always active but split the upstream Flow into 2 parts:

The upper part of the upstream Flow should be synchronized with the lifecycle and should stop being collected when the lifecycle is inactive;
The lower part of the upstream Flow should never stop being collected but will temporarily not receive any new value from the upper part while the lifecycle is inactive. This way, operators like distinctUntilChanged() could be used in the lower part to successfully filter out values re-emitted by the upper part when it restarts and avoid unnecessary work further down the chain.

val results: StateFlow<Result> =
    someTriggerFlow()                           // upper part ↑
        .someOperator(someFormOfLifecycle)
        .distinctUntilChanged()                 // lower part ↓
        .map { someExpensiveLoadingOperation(it) }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.Eagerly,
            initialValue = Result.empty()
        )

This approach was proposed by Hicham Boushaba in his article “Making cold Flows lifecycle-aware” which served as a starting point for this one.

To make the upper part of the Flow lifecycle-aware, we need to use an operator taking some form of lifecycle as input, launching a child coroutine to collect it when the lifecycle is active and canceling the coroutine when inactive, while forwarding the values downstream to the lower part.

Injecting an Android `Lifecycle` in the ViewModel ?

Mr Boushaba suggested a new operator whenAtLeast() working in combination with a custom Android Lifecycle-aware ViewModel. A similar option is to use the flowWithLifecycle() operator provided by the AndroidX Lifecycle library in a standard ViewModel. Both these solutions require keeping a reference to an Android Lifecycle inside a ViewModel class. In my opinion this should be avoided for different reasons:

It makes the ViewModel more difficult to test because it adds an extra dependency to the Lifecycle class;
It requires additional complex code to clear the Lifecycle references from the ViewModel after the LifecycleOwner gets destroyed, in order to prevent memory leaks;
It doesn’t take into account the fact that a single ViewModel may be observed by multiple components with different Lifecycles at the same time. For example it’s common to use a ViewModel to allow a Fragment to communicate with an Activity or another Fragment. Supporting these use cases would require reinventing much of what LiveData already handles out-of-the box;
There is a simpler solution.

Introducing the `flowWhileShared()` operator

It turns out we don’t need to deal with Android’s Lifecycle at all in the ViewModel because MutableSharedFlow already provides something equivalent. In the previous section, we mentioned that it tracks and exposes the current number of subscribed collectors through the subscriptionCount property and this can be used to infer the active state which is all we need. It is used internally by shareIn() and stateIn() but can also be used as input value for a custom Flow operator that we are going to call flowWhileShared():

@OptIn(ExperimentalCoroutinesApi::class)
fun <T> Flow<T>.flowWhileShared(
    subscriptionCount: StateFlow<Int>,
    started: SharingStarted
): Flow<T> {
    return started.command(subscriptionCount)
        .distinctUntilChanged()
        .flatMapLatest {
            when (it) {
                SharingCommand.START -> this
                SharingCommand.STOP,
                SharingCommand.STOP_AND_RESET_REPLAY_CACHE -> emptyFlow()
            }
        }
        .buffer(0)
}

The implementation is straightforward and relies on two existing Flow building blocks:

SharingStarted is used to emit a Flow of START and STOP commands in reaction to the changes of subscriptionCount. In 99% of the cases, the implementation we’re going to use is SharingStarted.WhileSubscribed() so that the START command will be emitted when subscriptionCount > 0 and the STOP command will be emitted when subscriptionCount == 0 to match the behavior of LiveData;
The flatMapLatest() operator is used to switch between the upstream Flow (this) and an empty Flow. Internally, this operator creates a child coroutine to collect the values of these Flows and cancels it on each new command.

Note: for simplicity, the special “stop and reset replay cache” command which acts on the cache of the parent SharedFlow is ignored and treated like a regular “stop” command.

Usage with `SharedFlow` or `StateFlow`

Unfortunately this new operator can’t be used in combination with shareIn() or stateIn() because they don’t expose the subscriptionCount field of MutableSharedFlow publicly. Instead we need to create and manage our own instance of MutableSharedFlow or MutableStateFlow.

To reduce boilerplate code and avoid repetition, we can create a custom StateFlow factory function:

fun <T> stateFlow(
    scope: CoroutineScope,
    initialValue: T,
    producer: (subscriptionCount: StateFlow<Int>) -> Flow<T>
): StateFlow<T> {
    val state = MutableStateFlow(initialValue)
    scope.launch {
        producer(state.subscriptionCount).collect(state)
    }
    return state.asStateFlow()
}

This function immediately launches a coroutine from the provided scope and passes the subscriptionCount as argument to an upstream Flow producer lambda. The produced Flow is then collected by the MutableStateFlow (which implements FlowCollector<T>) and finally the MutableStateFlow is returned as a read-only StateFlow.

At the end of this article you will find the source code of an optimized version of this function (minimizing the number of classes generated by the compiler) and a variant for SharedFlow.

Of course this entire system only works as intended if all the SharedFlows and StateFlows in the ViewModel are collected from the UI layer using the AndroidX Lifecycle APIs mentioned above, for example:

viewLifecycleOwner.lifecycleScope.launch {
    viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.results.collect { data ->
            displayResult(data)
        }
    }
}

Use cases

Let’s look at some real-world examples of how to use these new functions together.

Loading data in response to location updates

Suppose we have a locationFlow() function similar to the one described in this article which allows receiving location updates in the form of a cold Flow<Location>, actively using the device’s GPS while collected. We want to load a list of shops around the current location from an API and update that list every time the device moves by at least 30 meters to avoid unnecessary API calls. At the same time, we want to make sure the GPS resource is freed while the screen is not visible.

The ViewModel will contain a StateFlow builder similar to this:

@OptIn(ExperimentalCoroutinesApi::class)
val location: StateFlow<List<Shop>> =
    stateFlow(viewModelScope, emptyList()) { subscriptionCount ->
        locationClient.locationFlow(
            interval = 20000L,
            smallestDisplacement = 30f
        )
            .flowWhileShared(
                subscriptionCount,
                SharingStarted.WhileSubscribed(1000L)
            )
            .distinctUntilChanged { old, new ->
                old.distanceTo(new) < 30f
            }
            .mapLatest { location ->
                shopsRepository.getShopsAtLocation(location)
            }
            .catch { emit(emptyList()) }
    }

(Error handling has been simplified for the demonstration)

The stateFlow() factory function takes a producer lambda returning the upstream Flow as last argument. That lambda allows subscriptionCount to be used in the upstream Flow.

The main part of the upstream Flow will be collected with no interruption as long as the ViewModel stays in memory. However the part before flowWhileShared(), in this case locationFlow(), will only be collected while the StateFlow is active (has at least one subscription) so the GPS will stop when it becomes inactive. Thanks to the SharingStarted.WhileSubscribed(1000L) strategy, the collection will be canceled one second after the UI is hidden and the number of subscriptions reaches 0. That extra delay allows to avoid the cost of restarting location updates from scratch during configuration changes (when a new UI instance will resume the Flow collection almost immediately).

When the user leaves the screen and comes back to it later, the collection of locationFlow() will restart and distinctUntilChanged() (which is still being collected with no interruption) will take care of filtering out new locations that are too close to the previously emitted one. This way, we avoid the unnecessary work of calling the API again if the device did not move more than 30 meters since the last time the UI was visible.

The latest result will still be cached by StateFlow and automatically replayed to the current UI when it starts collecting it.

We managed to create the most efficient implementation solving that problem without having to rely on LiveData.

Reloading data on invalidation

Whenever possible, an application should present the latest version of the data to the user without the need of a manual refresh. To achieve this, a repository can send an invalidation signal to the observer of the data after each completed write operation (create/update/delete), eventually triggering a refresh.

To achieve maximum efficiency, the data should only be reloaded from storage or network if:

The screen is currently visible (no early refresh in the background);
The data has actually changed since the last load.

A natural way to represent data that can be invalidated is to return a Flow of results from the repository, rather than a single result.

However since we want to avoid refreshing the data while the screen is not visible, we need to cancel the collection of that Flow during that time. And since each Flow collection is self-contained, it will always start by loading the data, no matter if it has changed or not since the previous collection from the same screen.

For example, this kind of Flow is created by the Room Jetpack library to provide support for observable data sets in your DAOs. The Room implementation performs a database query when the Flow collection starts, then every time a related table is updated. This means that an unnecessary database query is performed every time a screen becomes visible again and the data set hasn’t changed in the meantime.

By comparison, the LiveData implementation generated by the older versions of Room is more efficient because it will only perform a database query if a table has changed since the last time the LiveData was active.

To make the Kotlin Flow code more efficient we need to use versioning.

The version of the data set should be exposed as a StateFlow<Int> in the repository, along with functions to retrieve current snapshots of the data. For example:

interface CustomerRepository {
    val customersVersion: StateFlow<Int>

    suspend fun getAllCustomers(): List<Customer>

    suspend fun getActiveCustomers(): List<Customer>
}

The repository may be backed by a remote API or local storage like a database; it doesn’t matter.

Every time the data set is updated successfully, the version number must be incremented atomically:

private val _customersVersion = MutableStateFlow(0)

suspend fun updateCustomerName(customerId: Long, newName: String) {
    // Insert some code to update the data here
    _customersVersion.update { it + 1 }
}

Tip: if your repository is backed by a Room database, you don’t need to keep track of changes manually, you can use Room’s invalidationTrackerFlow() to monitor a list of tables:

fun RoomDatabase.createVersionFlow(
    scope: CoroutineScope,
    vararg tables: String
): Flow<Int> {
    return flow {
        var version = 0
        invalidationTrackerFlow(*tables).collect {
            emit(version++)
        }
    }
        .conflate()
        .shareIn(
            scope = scope,
            started = SharingStarted.Eagerly,
            replay = 1,
        )
}

All the pieces of the puzzle are finally put together in the ViewModel:

@OptIn(ExperimentalCoroutinesApi::class)
val activeCustomers: Flow<List<Customer>> =
    stateFlow(viewModelScope, emptyList()) { subscriptionCount ->
        customersRepository.customersVersion
            .flowWhileShared(
                subscriptionCount, SharingStarted.WhileSubscribed()
            )
            .distinctUntilChanged()
            .mapLatest {
                customersRepository.getActiveCustomers()
            }
    }

Thanks again to the distinctUntilChanged() operator, the current version is compared against the previous one (if any) as soon as the StateFlow becomes active, and the data is only loaded if the version number changed. Problem solved.

Illustration from flowmarbles.com

Final tips

For many cases, the standard shareIn() and stateIn() operators should still be preferred over the complexity of flowWhileShared(). In particular:

For one-shot data loading;
When the source of the upstream Flow is a UI element on the screen like a refresh button, thus new values will never be emitted when the screen is invisible and the upstream Flow collection doesn’t need to be canceled;
When the cost of reloading the same data from the repository is cheap, for example because the implementation is backed by a shared cache. It’s then acceptable to reload data every time the screen becomes visible.

Conclusion

Using the new flowWhileShared() operator, we managed to synchronize a portion of an upstream Flow with the lifecycle of the downstream SharedFlow or StateFlow, allowing to skip unnecessary work with the help of an operator like distinctUntilChanged(). All of this without having to include any LiveData or Android-specific Lifecycle code in the ViewModel of Android applications.

Full source code

If you liked this article and found it helpful, please share it on social networks and post your feedback in the comments section. I’m curious to learn what you think about this pattern and how it could be improved. Expect reading about more uses cases for Kotlin Flow on Android in a following part.

Special thanks to Hicham Boushaba who gave me the original idea for writing this blog post.

Kotlin’s Flow in ViewModels: it’s complicated (LiveData is still your friend)

Christophe Beyls — Fri, 27 Aug 2021 22:00:00 +0000

Loading UI data in Android applications can be challenging. The lifecycle of the various screens need to be taken into account, as well as configuration changes leading to the destruction and recreation of Activities.

The individual screens of an app constantly toggle between interactive and hidden as the user navigates further and back in an app, switches from one app to another, or the device screen gets locked or unlocked. Each component needs to play fair and only perform active work when given the ball.

Configuration changes happen on various occasions: when changing the device orientation, switching the app to multi-window mode or resizing its window size, switching to dark or light mode, changing the default locale or font sizes, and more.

Goals of efficiency

To achieve efficient data loading in Activities and Fragments leading to the best user experience, the following should be considered:

Caching: data that has been loaded successfully and is still valid should be delivered immediately and not loaded a second time. In particular, when an existing Activity or Fragment becomes visible again, or after an Activity gets recreated on configuration change;
Avoiding background work: when an Activity or Fragment becomes invisible (moves from the STARTED to the CREATED state), any ongoing loading work should be paused or canceled in order to save resources. This is especially important for endless streams of data like location updates or periodic refreshes of any kind;
No work interruption during configuration changes: this is an exception to the second goal. During configuration changes, an Activity gets replaced by a new instance of it while preserving its state, so canceling ongoing work when the old instance is destroyed to immediately restart it when the new instance is created would be counter-productive.

Today: ViewModel and LiveData

To help developers reach these goals with code of manageable complexity, Google released the first Architecture Components libraries in 2017 in the form of ViewModel and LiveData. This was before Kotlin was introduced as the recommended programming language to develop Android applications.

ViewModels are objects preserved across configuration changes. They are useful to reach goals #1 and #3: loading operations can run uninterrupted inside of them during configuration changes, while the resulting data can be cached in them and shared with one or more Fragments/Activity currently attached to it.

LiveData is a simple observable data holder class that is also lifecycle-aware. New values are only dispatched to observers when their lifecycle is at least in the STARTED (visible) state, and observers are unregistered automatically which is handy to avoid memory leaks. LiveData is useful to reach goals #1 and #2: it caches the latest value of the data it holds and that value is automatically dispatched to new observers. Plus, it is notified when there are no more registered observers in the STARTED state, which allows to avoid performing unnecessary background work.

If you are an experienced Android developer, you probably know all of this already. But it’s important to recap these features in order to compare them with those of Flow.

LiveData + Coroutines

LiveData itself is quite limited compared to reactive streams solutions like RxJava:

It only handles passing data to and from the main thread, leaving the burden of managing background threads to the developer.
Notably, the map() operator executes its transformation function on the main thread and cannot be used to perform I/O operations or heavy CPU work. For that case the switchMap() operator needs to be used, in combination with manually launching an asynchronous operation on a background thread, even if only a single value has to be posted back on the main thread.
Only 3 transformation operators are provided for LiveData: map(), switchMap() and distinctUntilChanged(). If more are needed, you must implement them yourself using MediatorLiveData.

To help overcome these limitations, the Jetpack libraries also provide bridges from LiveData to other technologies like RxJava or Kotlin’s coroutines.

The simplest and most elegant bridge in my opinion is the LiveData coroutine builder function. This function is similar to the flow {} builder function from the Kotlin Coroutines library and allows to smartly wrap a coroutine as a LiveData instance:

val result: LiveData<Result> = liveData {
    val data = someSuspendingFunction()
    emit(data)
}

You can use all the power of coroutines and coroutine contexts to write asynchronous code in a synchronous way without callbacks, switching between threads automatically as needed;
New values are dispatched to the LiveData observers on the main thread by calling the emit() or emitSource() suspending functions from the coroutine;
The coroutine uses a special scope and lifecycle tied to the LiveData instance. When the LiveData becomes inactive (has no more observer in the STARTED state), the coroutine will automatically be canceled, allowing to reach goal #2 without having to do any extra work;
The cancellation of the coroutine will actually be delayed by 5 seconds after the LiveData becomes inactive in order to handle configuration changes gracefully: if a new Activity immediately replaces the old one and the LiveData becomes active again before the timeout, cancellation will not happen and the cost of an unnecessary restart will be avoided (goal #3);
If the user comes back to the screen and the LiveData becomes active again, the coroutine will automatically restart, but only if it was previously canceled before completion. As soon as the coroutine completes it will not restart anymore, allowing to avoid loading the same data twice if the input did not change (goal #1).

Conclusion: by using the LiveData coroutines builder you get the best behavior by default with the simplest code.

Instead of suspending functions returning a single value, what if a repository provides functions returning a stream of values in the form of a Flow? It is also possible to convert it to a LiveData and take advantage of all the above features by using the asLiveData() extension function:

val result: LiveData<Result> = someFunctionReturningFlow().asLiveData()

Under the hood, asLiveData() also uses the LiveData coroutines builder to create a simple coroutine collecting the Flow while the LiveData is active:

fun <T> Flow<T>.asLiveData(): LiveData<T> = liveData {
    collect {
        emit(it)
    }
}

But let’s pause for a moment — what exactly is a Flow and is it possible to use it as a complete replacement for LiveData?

Introducing Kotlin’s Flow

Flow is newer and trendy so it must be better in every aspect, right?

Flow is a class from Kotlin’s Coroutines library introduced in 2019 which represents a stream of values computed asynchronously. It’s similar in concept to RxJava Observables but is based on coroutines and has a simpler API.

At first, only cold flows were available: stateless streams that are created on demand each time an observer starts collecting their values in the scope of a coroutine. Each observer gets its own sequence of values, they are not shared.

Later, new hot flows subtypes SharedFlow and StateFlow were added and graduated as stable APIs in release 1.4.0 of the Coroutines library.

SharedFlow allows to publish values that are broadcast to all observers. It can manage an optional replay cache and/or a buffer and basically replaces all variants of the deprecated BroadcastChannel API.

StateFlow is a specialized and optimized subclass of SharedFlow which stores and replays the latest value only. Sounds familiar?

StateFlow and LiveData have a lot in common:

They are observable classes
They store and broadcast the latest value to any number of observers
They force you to catch exceptions early: an uncaught Exception in a LiveData callback stops the application. An uncaught Exception in a hot Flow ends the stream with no possibility to restart it, even when using the .catch() operator.

But they also have important differences:

MutableStateFlow requires an initial value, MutableLiveData does not (note: MutableSharedFlow(replay = 1) can be used to emulate a MutableStateFlow with no initial value, but its implementation is a bit less efficient)
StateFlow always filters out repetitions of the same value using Any.equals() for comparison, LiveData does not unless combined with the distinctUntilChanged() operator (note: a SharedFlow can also be used to prevent this behavior)
StateFlow is not lifecycle-aware. However, a Flow can be collected from a lifecycle-aware coroutine which requires more code to setup without using LiveData (more details below)
LiveData uses versioning to keep track of which value has been dispatched to which observer. This allows to avoid dispatching the same value twice to the same observer when it moves back to the STARTED state. StateFlow has no versioning. Each time a coroutine collects a Flow, it is considered as a new observer and will always receive the latest value first. This can lead to performing duplicate work as we will see in the following case study.

Observing `LiveData` vs Collecting `Flow`

Observing a LiveData instance from an Activity of Fragment is straightforward:

viewModel.results.observe(viewLifecycleOwner) { data ->
    displayResult(data)
}

It’s a one-time operation and LiveData takes care of syncing the stream with the lifecycle of the observers.

The equivalent operation for a Flow is called collecting and collection needs to be done from a coroutine. Because a Flow itself is not lifecycle-aware, the responsibility of syncing with the lifecycle is moved up to the coroutine collecting the Flow.

To create a lifecycle-aware coroutine collecting a Flow while an Activity/Fragment is in the STARTED state and cancel the collection automatically when the Activity/Fragment is destroyed, the following code can be used:

viewLifecycleOwner.lifecycleScope.launchWhenStarted {
    viewModel.result.collect { data ->
        displayResult(data)
    }
}

But there is a major limitation with this code: it will only work properly with cold flows not backed by a channel or buffer. Such a flow is only driven by the coroutine collecting it: when the Activity/Fragment moves back to the CREATED state, the coroutine will suspend, the Flow producer will suspend along and nothing else will happen until the coroutine is resumed.

However, there are other kinds of flows:

hot flows which are always active and will dispatch results to all current observers (including the suspended ones);
callback-based or channel-based cold flows which subscribe to an active data source when collection starts and only stop the subscription when the collection is canceled (not suspended).

For these cases, the underlying flow producer will be kept active even when the coroutine collecting the Flow is suspended, buffering new results in the background. Resources are wasted and goal #2 is missed.

Update (2023): launchWhenStarted() has been fully deprecated for the reasons mentioned above and should not be used anymore.

A safer way to collect Flows of any kind needs to be implemented. The coroutine performing the collection must be canceled when the Activity/Fragment becomes invisible and restarted when it becomes visible again, exactly like what the LiveData coroutine builder does. For this purpose, new APIs were introduced in lifecycle:lifecycle-runtime-ktx:2.4.0:

viewLifecycleOwner.lifecycleScope.launch {
    viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
        viewModel.result.collect { data ->
            displayResult(data)
        }
    }
}

or alternatively:

viewLifecycleOwner.lifecycleScope.launch {
    viewModel.result
        .flowWithLifecycle(viewLifecycleOwner.lifecycle, Lifecycle.State.STARTED)
        .collect { data ->
            displayResult(data)
        }
}

As you can see, to achieve the same level of safety and efficiency, observing results from an Activity or Fragment is simpler with LiveData.

You can learn more about these new APIs in the article “A safer way to collect flows from Android UIs” from Manuel Vivo.

Replacing `LiveData` with `StateFlow` in ViewModels

Let’s go back to the ViewModel. We established that this is a simple and efficient way to fetch data asynchronously using LiveData:

val result: LiveData<Result> = liveData {
    val data = someSuspendingFunction()
    emit(data)
}

How can we achieve the same effect using StateFlow in place of LiveData? Jose Alcérreca wrote a long migration guide to help answer this question. Long story short, for the above use case the equivalent code is:

val result: Flow<Result> = flow {
    val data = someSuspendingFunction()
    emit(data)
}.stateIn(
    scope = viewModelScope,
    started = SharingStarted.WhileSubscribed(5000L),
    initialValue = Result.Loading
)

The stateIn() operator transforms our cold flow into a hot flow able to share a single result between multiple observers. Thanks to SharingStarted.WhileSubscribed(5000L), the hot flow is started lazily when the first observer subscribes and is canceled 5 seconds after the last observer unsubscribes, allowing to avoid doing unnecessary work in the background while also taking configuration changes into account.

Unfortunately, contrary to the LiveData coroutine builder, the upstream flow will always be restarted automatically by the sharing coroutine when a new observer subscribes after that inactivity period, even if it reached its end during the previous collection. For the above example, it means that someSuspendingFunction() will always run again if an Activity/Fragment becomes visible after being hidden for more than 5 seconds.

Goal #1 is missed: the data is indeed cached (StateFlow will store and replay the latest value), but this will not prevent it from being loaded a second time.

It looks like we managed to achieve 2 goals out of 3 and replicate most of the behavior of LiveData using code that is a bit more complex.

There remains another small key difference: each time a new flow collection starts, StateFlow will always immediately deliver the latest result to the observer. Even if that same result had already been delivered to the same Activity/Fragment instance during the previous collection. Because unlike LiveData, StateFlow doesn’t support versioning and each flow collection is considered as a brand new observer.

Is that problematic? For this simple use case, not really: an Activity or Fragment could just perform an extra check to avoid updating the View if the data hasn’t changed.

viewLifecycleOwner.lifecycleScope.launch {
    viewModel.result
        .flowWithLifecycle(viewLifecycleOwner.lifecycle, Lifecycle.State.STARTED)
        .distinctUntilChanged()
        .collect { data ->
            displayResult(data)
        }
}

But problems may arise in more complicated, real-life use cases, as we’ll see in the next section.

Using `StateFlow` as trigger in a ViewModel

A common scenario is to use a trigger-based approach to load data in a ViewModel: every time the trigger value is updated, the data gets refreshed.

Using MutableLiveData this works very well:

class MyViewModel(repository: MyRepository) : ViewModel() {
    private val trigger = MutableLiveData<String>()

    fun setQuery(query: String) {
        trigger.value = query
    }

    val results: LiveData<SearchResult>
            = trigger.switchMap { query ->
        liveData {
            emit(repository.search(query))
        }
    }
}

On refresh, the switchMap() operator will connect the observers to a new underlying LiveData source, replacing the old one. And because the above example uses the LiveData coroutine builder, the previous LiveData source will automatically cancel its associated coroutine 5 seconds after being disconnected from its observers. Work on obsolete values is avoided with a small delay.
Because LiveData has versioning, the MutableLiveData trigger will only dispatch the new value once to the switchMap() operator, as soon as there is at least one active observer. Later, when observers become inactive and active again, the work of the latest underlying LiveData source will just resume where it left off.

The code is simple enough and reaches all goals of efficiency.

Now let’s see if we can implement the same logic using MutableStateFlow in place of MutableLiveData.

The naive approach

class MyViewModel(repository: MyRepository) : ViewModel() {
    private val trigger = MutableStateFlow("")

    fun setQuery(query: String) {
        trigger.value = query
    }

    val results: Flow<SearchResult> = trigger.mapLatest { query ->
        repository.search(query)
    }.stateIn(
        scope = viewModelScope,
        started = SharingStarted.WhileSubscribed(5000L),
        initialValue = SearchResult.EMPTY
    )
}

The API of MutableLiveData and MutableStateFlow being very close, the trigger code looks almost identical. The biggest difference is the usage of the mapLatest() transformation function which is equivalent to LiveData’s switchMap() for a single return value (for multiple return values, flatMapLatest() should be used).

mapLatest() works like map() but instead of fully executing the transformation on all input values in sequence, the input values are consumed immediately and the transformation is executed asynchronously in a separate coroutine. When a new value is emitted in the upstream flow, the transformation coroutine for the previous value will be canceled immediately if it was still running and a new one will be launched to replace it. This way, work on obsolete values is avoided.

So far so good. However, here comes the major problem with this code: because StateFlow does not support versioning, the trigger will re-emit the latest value when the flow collection restarts. This happens every time the Activity/Fragment becomes visible again after being invisible for more than 5 seconds.

And when the trigger re-emits the same value, the mapLatest() transformation will run again, hitting the repository one more time with the same arguments, even though the result had already been delivered and cached!
Goal #1 is missed: data that is still valid should not be loaded a second time.

Preventing re-emission of the latest trigger value

The next questions that come to mind are: should we prevent this re-emission and how? StateFlow already takes care of deduplicating values from within a flow collection, and the distinctUntilChanged() operator does the same for other kinds of flows. But no standard operator exists to deduplicate values across multiple collections of the same flow, because flow collections are supposed to be self-contained. This is a major difference with LiveData.

In the specific case of a Flow shared between multiple observers using the stateIn() operator, emitted values will be cached and there will always be at most one coroutine collecting the source Flow at any given time. It looks tempting to hack around some operator function that would remember the latest value of a previous collection to be able to skip it when a new collection starts:

// Don't do this at home (or at work)
fun <T> Flow<T>.rememberLatest(): Flow<T> {
    var latest: Any? = NULL
    return flow {
        collectIndexed { index, value ->
            if (index != 0 || value !== latest) {
                emit(value)
                latest = value
            }
        }
    }
}

Remark: an attentive reader noted that the same behavior can be achieved by replacing the MutableStateFlow with a Channel(capacity = CONFLATED) then turning it into a Flow using receiveAsFlow(). Channels never re-emit values.

Unfortunately the above logic is flawed and will not work as intended when the downstream flow transformation is canceled before completion.

The code assumes that after emit(value) returns, the value has been processed and should not be emitted again if the flow collection restarts, but this is only true when using unbuffered Flow operators. Operators like mapLatest() are buffered and in this case emit(value) will return immediately while the transformation is executed asynchronously. This means that there is no way to know when a value has been fully processed by the downstream flow. If the flow collection is canceled in the middle of an asynchronous transformation, we still need to re-emit the latest value when the flow collection restarts in order to resume that transformation, otherwise that value will be lost!

TL; DR: Using StateFlow as a trigger in a ViewModel leads to repeating work every time the Activity/Fragment becomes visible again and there is no simple way to avoid it.

This is why LiveData is superior to StateFlow when used as a trigger in a ViewModel, even though these differences are not mentioned in Google’s “Advanced coroutines with Kotlin Flow” codelab which implies the Flow implementation behaves the exact same way as the LiveData one. It does not.

Conclusion

Here are my recommendations based on the above demonstration:

Keep using LiveData in your Android UI layer and ViewModels, especially for triggers. Use it whenever possible to expose data to be consumed in Activities and Fragments: it will make your code both simple and efficient;
The LiveData coroutine builder function is your friend and can replace Flows in ViewModels in many cases;
You can still use the power of Flow operators when you need them, then convert the resulting Flow to a LiveData;
Flow is a better fit than LiveData for all the other layers of an application like repositories or data sources, because it doesn’t depend on Android-specific lifecycles and is easier to test.

Now you know the tradeoffs you’re willing to make if you still want to fully “go with the Flow” and eradicate LiveData from your Android UI layer.

Update (June 2022): I wrote a follow-up article describing a pattern that can be used to improve Kotlin Flow synchronization with the Lifecycle and make SharedFlow as efficient as LiveData in ViewModels.

Are you concerned about performance and experienced similar issues? Did you find other ways to work around them? If so, feel free to post a message in the comments section and as always, please share or subscribe if you enjoyed reading this long article.

Fixing RecyclerView nested scrolling in opposite direction

Christophe Beyls — Wed, 25 Mar 2020 23:00:00 +0000

RecyclerView is one of the main building blocks of Android user interfaces today. It’s more capable and flexible than its ListView predecessor but this also leads to more complexity and new problems.

One core feature of RecyclerView is the externalization of its layout engine to components called LayoutManagers, which are no longer limited to vertical scrolling only. Most implementations allow to choose between horizontal and vertical scrolling and a LayoutManager could technically support both at the same time.

RecyclerView also supports nested scrolling by implementing the NestedScrollingChild3 interface, which means it can cooperate with a parent view implementing NestedScrollingParent3 when both are configured to scroll in the same direction. In a nutshell, the scrolling child intercepts a scroll event and initiates a nested scroll in cooperation with the scrolling parent. Depending on its internal logic, the parent optionally consumes the scroll before or after the child, until they both reach their available scroll distance. A single scroll event may be consumed by both the parent and child with a seamless transition. For example, this mechanism is used when a RecyclerView is placed inside a CoordinatorLayout next to an app bar which will automatically slide up or collapse when a scroll gesture is initiated.

Note that RecyclerView doesn’t implement NestedScrollingParent3, so using a scrollable child inside a RecyclerView which scrolls in the same direction is not supported. However, Google currently provides a workaround to implement nested scrolling in a ViewPager2.

The problem

What about nested scrolling in the opposite direction? This should be supported out-of-the-box, since a vertical scrolling view is not supposed to intercept horizontal gestures and vice versa. In practice this works well with the legacy ViewPager which only scrolls horizontally, ignoring vertical gestures.

But there is a problem with RecyclerView, and by extension ViewPager2.

Suppose we have a RecyclerView with a vertical LinearLayoutManager and each item of this vertical list consists of a RecyclerView with an horizontal LinearLayoutManager. This kind of layout with scrollable horizontal items inside a vertical list is commonly found in Netflix-like video streaming apps with scrollable movie posters inside sections, or the Google Play Store app.

Notice that attempting to scroll the nested horizontal RecyclerViews often ends up with unexpected results.

Horizontal scroll is expected, but vertical scroll kicks in instead.

Many times, even though an horizontal gesture is performed on a child RecyclerView, the parent RecyclerView kicks in and intercepts the touch event instead of the child RecyclerView, resulting in a small vertical scroll instead of an horizontal scroll. This actually happens when the scroll gesture is not perfectly horizontal. It’s actually diagonal, even if you can see that the vertical distance of the gesture is small compared to its horizontal distance and its intent was clearly horizontal.

Most of the time when using our phones, we are actually performing such imprecise diagonal gestures because we expect the system to understand our intent based on the current context. And it usually does it pretty well, but not in this particular case where only a perfectly horizontal gesture will be recognized. It harms the user experience. That’s why I consider it a bug.

Introducing ViewPager2

At this point you may think that nested RecyclerViews are rare so the severity of this issue is low.

But it turns out that the new ViewPager2 layout, which officially replaces the legacy ViewPager, uses a RecyclerView internally. Horizontal pagers are present in almost every app I’m aware of, and the pages often contain a vertical RecyclerView or some form of ScrollView.

Here’s what happens when you try to scroll a vertical RecyclerView inside a parent horizontal ViewPager2 (which internally uses a RecyclerView):

Vertical scroll is expected, but the horizontal ViewPager2 reacts instead.

This time the ViewPager2 takes over and intercepts the gesture, unless it’s perfectly vertical (which is difficult to achieve). The result is the same with any kind of ViewPager2 adapter, including FragmentStateAdapter. In my opinion this makes ViewPager2, in its current state, practically unusable compared to the legacy ViewPager.

The same annoying behavior occurs when the pages contain a ScrollView or a NestedScrollView, hinting at which component is causing these problems: the parent RecyclerView.

The cause

Rather than giving up and reverting to ViewPager, I decided to investigate by debugging and looking at the source code of RecyclerView. The culprit is the code responsible for initiating a scroll inside the onInterceptTouchEvent() method (taken from version 1.1.0 of the RecyclerView library):

boolean canScrollHorizontally = mLayout.canScrollHorizontally();
boolean canScrollVertically = mLayout.canScrollVertically();
switch (action) {
    // ...
    case MotionEvent.ACTION_MOVE: {
        // ...
        final int x = (int) (e.getX(index) + 0.5f);
        final int y = (int) (e.getY(index) + 0.5f);
        if (mScrollState != SCROLL_STATE_DRAGGING) {
            final int dx = x - mInitialTouchX;
            final int dy = y - mInitialTouchY;
            boolean startScroll = false;
            if (canScrollHorizontally && Math.abs(dx) > mTouchSlop) {
                mLastTouchX = x;
                startScroll = true;
            }
            if (canScrollVertically && Math.abs(dy) > mTouchSlop) {
                mLastTouchY = y;
                startScroll = true;
            }
            if (startScroll) {
                setScrollState(SCROLL_STATE_DRAGGING);
            }
        }
    } break;
    // ...
}
return mScrollState == SCROLL_STATE_DRAGGING;

dx and dy are respectively the horizontal and vertical distances the finger has travelled the on screen since it started touching it.

The RecyclerView will switch to SCROLL_STATE_DRAGGING mode and the method will return true to intercept the gesture (preventing the child views from detecting it) as soon as the touch slop is reached in its scrolling direction. The touch slop is the minimal distance a finger must move on the screen before a touch event is considered as an actual drag gesture and not a tap. When a gesture is perfectly horizontal, the vertical touch slop is not reached and a vertical RecyclerView will not interfere. But if it’s not perfect and rather diagonal, then a vertical RecyclerView will consider it as a vertical gesture nonetheless and start a vertical scroll.

In summary, the problem is that when the RecyclerView is configured to scroll in a single direction as it’s usually the case, it doesn’t test if the global shape of the gesture is more horizontal (abs(dx) > abs(dy)) or vertical (abs(dy) > abs(dx)) before deciding to intercept it, potentially conflicting with a child view scrolling in the opposite direction.

A better drag gesture detection code would be:

if (canScrollHorizontally && Math.abs(dx) > mTouchSlop && (canScrollVertically || Math.abs(dx) > Math.abs(dy))) {
    mLastTouchX = x;
    startScroll = true;
}
if (canScrollVertically && Math.abs(dy) > mTouchSlop && (canScrollHorizontally || Math.abs(dy) > Math.abs(dx))) {
    mLastTouchY = y;
    startScroll = true;
}

With this code, the behavior will be the same as before if the RecyclerView scrolls in both directions, but will check the gesture direction before intercepting it if the RecyclerView scrolls in a single direction.

The solution

Ideally the above code change would be integrated directly into the RecyclerView library. One of the motivations behind this article is to raise the attention of developers working at Google, in the hopes that they will eventually release a fixed version.

In the meantime, which options are available to work around this issue today?

A first attempt would be to extend the RecyclerView class and override the onInterceptTouchEvent() method. This is not easy because the original code of this method is accessing private fields which are not available to child classes, so it can’t just be copy-pasted and updated. Instead, you have to call the super.onInterceptTouchEvent() method, then duplicate some of the detection logic and tweak it in order to cancel the scroll and finally return false instead of true for the cases discussed earlier. Next, you would have to change all your layout files to use that new class. But then, what about ViewPager2? It will still use the original RecyclerView internally instead of the fixed one, which means you’d have to create and maintain a custom version of ViewPager2 as well! This turns out to be quite impractical.

There is a better way. As mentioned in the introduction, RecyclerView is flexible and features a modular architecture enabling the usage of extensions. It turns out that such an extension can be created to customize the behavior of the scroll gesture detection. In detail, the extension will have to use a combination of 2 RecyclerView APIs:

An OnItemTouchListener to be registered on the RecyclerView, where the updated gesture detection code (based on the original code of RecyclerView) will be implemented by overriding onInterceptTouchEvent().
An OnScrollListener to be registered on the RecyclerView as well, whose role is to detect transitions from SCROLL_STATE_IDLE to SCROLL_STATE_DRAGGING and revert back to SCROLL_STATE_IDLE if required (depending on the data provided by the updated gesture detection code). After reverting back, RecyclerView.onInterceptTouchEvent() will now return false and the gesture will not be captured.

Here is the full code, provided as a single Kotlin extension function:

For ViewPager2, an additional extension property has to be created in order to make its internal RecyclerView public:

import androidx.core.view.get
import androidx.viewpager2.widget.ViewPager2
val ViewPager2.recyclerView: RecyclerView
    get() {
        return this[0] as RecyclerView
    }

Then to enable the fix for a ViewPager2 instance, one would call:

val pager: ViewPager2 = findViewById(R.id.pager)
pager.recyclerView.enforceSingleScrollDirection()

Mission accomplished. Now the parent RecyclerView and ViewPager2 will react properly to diagonal gestures and the app users can enjoy easier nested scrolling.

Conclusion

As an early adopter of the first stable version of ViewPager2, I was surprised to hardly see anyone raising concerns about the usability of this new widget in nested lists scenarios, compared to its predecessor. Issues with nested scrolling have been present since the first release of RecyclerView but don’t seem to get much attention. At least we now have a simple pluggable fix which doesn’t involve subclassing, altough it should still be considered as a hack and may break in future versions of the library. I created an issue for this on the RecyclerView issue tracker so you can follow the progress of a fix in the library itself.

Thank you for reading this and please share and comment to help feeding the debate.

Special thanks to Manideep Polireddi who was the first person to document this issue.

A study of the Parcelize feature from Kotlin Android Extensions

Christophe Beyls — Mon, 18 Nov 2019 23:00:00 +0000

Two years ago, I wrote about how you can leverage features of the Kotlin programming language to manually write your Android Parcelable implementations in the most concise and readable way. Does it mean that I always prefer writing this code manually rather than letting a library or tool generate it for me? Of course not: like most developers, I believe that the best code is the code you don’t have to write. But I expect the tools I use to meet my quality standards.

That’s why I tend to be conservative about the dependencies I add to my projects and will always favor official libraries from Jetbrains or Google over third-party solutions. Things have changed for the better since I wrote the previous article: with the release of Kotlin 1.3.40, @Parcelize is now a stable feature provided by the Parcelize Gradle plugin (formerly known as Kotlin Android Extensions). And since version 1.3.60, the Android Studio plugin also properly recognizes the feature as non-experimental so it can finally be considered as production-ready.

I previously enumerated a list of some of the negative aspects of third-party Parcelable code generation libraries compared to manual implementation. Here’s why I believe @Parcelize stands out from the rest in regard to that list:

It’s an official plugin made by JetBrains with the collaboration of Google and is guaranteed to be well supported in the future
The generated code of @Parcelize is very efficient (as we’ll discover further in this article)
The CREATOR field doesn’t have to be declared at all, along with that easy-to-forget @JvmField annotation
Thanks to the Parceler interface, it is possible to write simple plugins to handle unsupported types or override the default implementation
No extra classes are created by the plugin. All the generated code is embedded in the annotated class so the app will behave exactly as if you wrote the code yourself
There is no runtime library overhead and zero extra methods are added to your app.

Project setup

First, you should upgrade your Kotlin Gradle plugins and Android Studio plugin to version 1.3.60 or more recent.

For Kotlin 1.3.60 to 1.4.10

To enable the “Parcelable implementation generator” feature, you have to enable the Kotlin Android Extensions Gradle plugin in your project by simply declaring it at the top of your module’s build.gradle file, just after the kotlin-android plugin:

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply plugin: 'kotlin-android-extensions'

By using the newer version of the plugin, it’s not necessary anymore to turn on experimental mode to be able to use the @Parcelize feature or for the IDE to detect it as available.

However, I’m not a big fan of the other features provided by this plugin like the View binding and caching. By default, this will scan your layouts and generate static properties for every View with an id, as well as adding a hidden View cache in your Activities and Fragments. I don’t want it. Fortunately, there is a way to enable Parcelize while disabling other features of the plugin. Add this extra section to the same build.gradle file, below the android section:

androidExtensions {
    features = ["parcelize"]
}

Since Kotlin 1.4.20

All other features of the Kotlin Android Extensions Gradle plugin have been deprecated since Kotlin 1.4.20 and Parcelize has moved to its own Gradle plugin. Enable it by declaring it at the top of your module’s build.gradle file, just after the kotlin-android plugin:

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply plugin: 'kotlin-parcelize'

We’re all set to use the @Parcelize annotation.

Usage

Just add the @Parcelize annotation to a class implementing the Parcelable interface and the Parcelable implementation will be generated automatically.

@Parcelize
class Person(val name: String, val age: Int) : Parcelable

This is the same example as in the previous article, in just 2 lines of code.

The class can be a data class but it’s optional. All properties to serialize have to be declared in the primary constructor, and like a data class all parameters of the primary constructor need to be properties. They can be val or var, private or public.

The main limitation of the feature is that it is not allowed to annotate abstract or sealed classes. To make them implement the Parcelable interface you can annotate each of their child classes instead. We’ll go further into details with concrete examples in a following chapter.

Analyzing the generated code

This looks fine so far, but what about the quality of the generated code? Is the implementation as efficient as it could be? Let’s find out.

We’re going to use the Kotlin Bytecode inspector on the annotated class and decompile it back to Java to reveal the code under the hood.

Basic types

@Parcelize
class Basic(val aByte: Byte, val aShort: Short,
            val anInt: Int, val aLong: Long,
            val aFloat: Float, val aDouble: Double,
            val aBoolean: Boolean, val aString: String) : Parcelable

The following code will be generated:

public void writeToParcel(@NotNull Parcel parcel, int flags) {
   parcel.writeByte(this.aByte);
   parcel.writeInt(this.aShort);
   parcel.writeInt(this.anInt);
   parcel.writeLong(this.aLong);
   parcel.writeFloat(this.aFloat);
   parcel.writeDouble(this.aDouble);
   parcel.writeInt(this.aBoolean);
   parcel.writeString(this.aString);
}

For basic types like primitives and String, we see that the proper dedicated methods from the Parcel class are used as expected. Notice that the Boolean value is written as an Int. This is because at the Java bytecode level, a boolean is represented as a primitive integer whose value is either 0 or 1. The programming language hides this abstraction. Also, the Short value is written as an Int as well, because the Parcel API doesn’t provide a way to serialize Short values so the next bigger integer type is used instead.

The code which reads back the values looks like this:

public static class Creator implements android.os.Parcelable.Creator {
   @NotNull
   public final Object[] newArray(int size) {
      return new Basic[size];
   }

   @NotNull
   public final Object createFromParcel(@NotNull Parcel in) {
      return new Basic(in.readByte(), (short)in.readInt(), in.readInt(), in.readLong(), in.readFloat(), in.readDouble(), in.readInt() != 0, in.readString());
   }
}

Besides the above code, no additional constructor or method is added to the base class and all of the Parcelable deserialization code fits inside the createFromParcel() method of the Creator class. This guarantees that the number of methods in the application’s APK file will be as low as possible, which is always important.

Nullable types

Here is another Kotlin sample with various types of nullable fields.

@Parcelize
class NullableFields(
    val aNullableInt: Int?,
    val aNullableFloat: Float?,
    val aNullableBoolean: Boolean?,
    val aNullableString: String?
) : Parcelable

The generated serialization code decompiles to this:

public void writeToParcel(@NotNull Parcel parcel, int flags) {
   Integer var10001 = this.aNullableInt;
   if (var10001 != null) {
      parcel.writeInt(1);
      parcel.writeInt(var10001);
   } else {
      parcel.writeInt(0);
   }

   Float var3 = this.aNullableFloat;
   if (var3 != null) {
      parcel.writeInt(1);
      parcel.writeFloat(var3);
   } else {
      parcel.writeInt(0);
   }

   Boolean var4 = this.aNullableBoolean;
   if (var4 != null) {
      parcel.writeInt(1);
      parcel.writeInt(var4);
   } else {
      parcel.writeInt(0);
   }

   parcel.writeString(this.aNullableString);
}

For nullable counterparts of primitive types, the plugin generates code which writes an extra integer before the value to indicate if it’s null or not, which is just as efficient as a manual implementation. As for the String? value, Parcel.writeString() already properly handles null values so no integer is added to serialize this type.

Nullable fields are handled properly and efficiently for every type.

Nested Parcelables

Let’s declare a Parcelable class embedding a Parcelable field.

@Parcelize
class Book(val title: "String, val author: Person) : Parcelable"

Person is the class we defined earlier, which is also Parcelable. Here is the representation of the serialization code:

public void writeToParcel(@NotNull Parcel parcel, int flags) {
   parcel.writeString(this.title);
   this.author.writeToParcel(parcel, 0);
}

Interesting: the plugin generated a direct nested call to writeToParcel(). This is equivalent to calling Parcel.writeTypedObject(). It’s very efficient because it allows skipping writing the class name of the nested type like Parcel.writeParcelable() does. This information is normally used during deserialization in order to perform a small reflection lookup to retrieve the CREATOR field corresponding to the correct subtype.

But in this case the CREATOR field to use is well-known and unique, because the Person class is final. That’s why the deserialization code looks like this:

@NotNull
public final Object createFromParcel(@NotNull Parcel in) {
   return new Book(in.readString(), (Person)Person.CREATOR.createFromParcel(in));
}

For non-final classes or interfaces, the Parcelize plugin will generate a call to Parcel.writeParcelable() instead.

Classes are final by default in Kotlin, allowing optimized nested serialization to be used in most cases. If you are including a Java Parcelable class as a field of a Kotlin class annotated with @Parcelize, declare the class as final whenever possible to be able to benefit from the same optimization.

Enum classes

enum classes are supported out-of-the-box by the plugin.

enum class State {
    ON, OFF
}

@Parcelize
class PowerSwitch(var state: State) : Parcelable

Serialization code:

public void writeToParcel(@NotNull Parcel parcel, int flags) {
   parcel.writeString(this.state.name());
}

The enum value name is written as a String and the deserialization code uses Enum.valueOf(Class enumType, String name) to transform the name back to an enum value. This is definitely more efficient than using writeSerializable() which must be avoided at all costs on Android for performance and efficiency reasons. Internally, the Enum implementation uses a name cache to quickly retrieve an enum value from its name.

Another way of efficiently serializing an enum value would be to store its ordinal() integer, ~~with the downside of having the values array cloned each time EnumType.values() is called during deserialization~~ and during deserialization reading the value back from the read-only cached EnumType.entries collection generated by the Kotlin compiler since Kotlin 1.9.2 to avoid extra memory allocations. In summary, the code generated by the plugin is fine in terms of performance.

Bonus feature: make enum classes implement `Parcelable`

You can actually annotate an enum class itself if you make it implement Parcelable.

@Parcelize
enum class State : Parcelable {
    ON, OFF
}

Unlike regular classes whose properties are serialized, the enum classes have their value name serialized so that the proper value instance is retrieved from memory on deserialization (since enum values are singletons).

This is particularly handy when you want to put an enum value in a Bundle (as an Intent extra or Fragment argument for example), without having to use Bundle.putSerializable() which is slower and less efficient and without having to write your own helper methods for custom serialization. Now you can just write:

val args = Bundle(1).apply {
    putParcelable("state", state)
}

Collections

@Parcelize supports a wide range of collections by default:

All array types (ShortArray is serialized as a series of Int values because Parcel doesn't support Short)
List, Set, Map interfaces (mapped to ArrayList, LinkedHashSet and LinkedHashMap respectively)
ArrayList, LinkedList, SortedSet, NavigableSet, HashSet, LinkedHashSet, TreeSet, SortedMap, NavigableMap, HashMap, LinkedHashMap, TreeMap, ConcurrentHashMap
Android-specific framework collections: SparseArray, SparseIntArray, SparseLongArray, SparseBooleanArray.

For the following types: ByteArray, IntArray, CharArray, LongArray, FloatArray, DoubleArray, BooleanArray, Array<String>, List<String>, Array<Binder>, the generated code will simply call the dedicated optimized methods from the Parcel API. For other array and collection types, things work differently.

Here is an example of a class including a collection of objects implementing Parcelable.

@Parcelize
class Library(val books: List<Book>) : Parcelable

The bytecode inspector reveals that the generated code doesn’t use Parcel.writeTypedList() from the Parcel API but instead inlines the logic to handle the list directly in the body of the writeToParcel() method:

public void writeToParcel(@NotNull Parcel parcel, int flags) {
   List var10002 = this.books;
   parcel.writeInt(var10002.size());
   Iterator var10000 = var10002.iterator();

   while(var10000.hasNext()) {
      ((Book)var10000.next()).writeToParcel(parcel, 0);
   }
}

Same goes for the deserialization code. This way of doing things actually has two benefits:

It allows Parcelize to support more collection types than the ones provided by the Parcel collections API, without adding extra methods to the code.
Serialization will be more efficient for many types compared to the Parcel collections API implementation because the compiler plugin will always use the best serialization method for each value type in the collection. For example, serializing a SparseArray<Book> (where Book is a final class) using Parcel.writeSparseArray() will result in Parcel.writeValue() to be used to serialize the Book type. This method is less efficient because for each value it will write an extra integer describing the value type (which is unnecessary because all values are of the same type in this case), then use Parcel.writeParcelable() which is also less efficient than a nested call to Book.writeToParcel() as we saw earlier. In comparison, the Parcelize plugin will just generate a call to Book.writeToParcel() for each value.

Note that ArrayMap, ArraySet, LongSparseArray from the Android framework are not supported by default, as well as all the unbundled collection classes provided by the Jetpack libraries: ArrayMap, ArraySet, LongSparseArray, SimpleArrayMap, SparseArrayCompat. Consider using SparseArray instead of SparseArrayCompat, and write your own custom serializer for the other types if you need them.

Finally, ArrayDeque, EnumMap and EnumSet may look like they are supported, but it’s only because they implement the Serializable interface and the generated code will just fall back to using Parcel.writeSerializable() which is slow and inefficient. Therefore it’s highly recommended to either use more generic collection types like Set<Enum> or write your own custom serializer, as we’ll see in the next chapter.

When including collections in your Parcelable objects, make sure their type is properly supported by the plugin or a custom serializer, especially when it implements the Serializable interface.

Custom types serializers

The Parcelize plugin also provides support for the remaining types that are part of the Parcel API: CharSequence, Exception (which only supports a few types of Exceptions), Size, SizeF, Bundle, IBinder, IInterface and FileDescriptor.

For all other types, it will default to using Parcel.writeSerializable() if the type implements Serializable (which — again — is bad for performance and produces a large amount of data, so must be avoided). If it doesn’t implement Serializable, a Lint warning will be shown and Parcel.writeValue() will be used instead, ultimately failing at runtime.

To avoid both of the above cases, you should provide your own custom type serializer implementation in the form of an object implementing the Parceler interface. Here’s a simple example for the Date type:

object DateParceler : Parceler<Date> {

    override fun create(parcel: Parcel) = Date(parcel.readLong())

    override fun Date.write(parcel: Parcel, flags: Int)
            = parcel.writeLong(time)
}

Then, in order to make the plugin use that Parceler implementation to serialize and deserialize properties using the Date type, you need to add an extra annotation to your Parcelable objects. You can either annotate the type of a property with @WriteWith<ParcelerType>, or annotate the property or the whole class with @TypeParceler<PropertyType, ParcelerType>.

Annotating the Parcelable class allows to group annotations together and avoid repetition, especially if you have many properties of the same type for which you want a custom serializer.

@Parcelize
@TypeParceler<Date, DateParceler>
class Session(val title: String,
              val startTime: Date,
              val endTime: Date): Parcelable

Annotating the property type avoids any ambiguity regarding which implementation is going to be used to serialize a property. If there is a mismatch between the annotation and the type, a Lint warning will be shown in the IDE (but it won’t prevent compilation).

@Parcelize
class Session(
    val title: String,
    val startTime: @WriteWith<DateParceler> Date,
    val endTime: @WriteWith<DateParceler> Date
) : Parcelable

Let’s have a look at the generated code to check that the custom Parceler implementation is being used in place of writeSerializable() for the dates:

public void writeToParcel(@NotNull Parcel parcel, int flags) {
   parcel.writeString(this.title);
   DateParceler.INSTANCE.write(this.startTime, parcel, flags);
   DateParceler.INSTANCE.write(this.endTime, parcel, flags);
}

Handling nullable custom types

Even though Parcelize provides support for serializing the nullable variant of all built-in types, it doesn’t add automatic support for the nullable variant of a custom type based on its non-null custom type Parceler. This means that if you provide a Parceler implementation for the Date type, it won’t support Date? properties automatically unless you add another annotation for the Date? type as well.

We can verify this by making the endTime property nullable in our class…

@Parcelize
@TypeParceler<Date, DateParceler>
class Session(val title: String,
              val startTime: Date,
              val endTime: Date?): Parcelable

… and then checking the generated code again:

public void writeToParcel(@NotNull Parcel parcel, int flags) {
   parcel.writeString(this.title);
   DateParceler.INSTANCE.write(this.startTime, parcel, flags);
   parcel.writeSerializable(this.endTime);
}

Indeed, DateParceler is not used for the endTime property. To fix this, another @TypeParceler (or @WriteWith) annotation needs to be added for the nullable Date? type and the Parceler implementation needs to properly handle nullable values as well.

Fortunately, it’s not needed to provide two separate Parceler implementations for nullable and non-null types: you can use a single one designed for nullable types to handle non-null types as well.

Here is a sample collection of Parceler implementations which are able to serialize and deserialize nullable and non-null variants of Date, BigInteger and BigDecimal types.

When creating a custom Parceler implementation, prefer declaring the nullable variant of the type to be able to use it for both nullable and non-null properties.

Going back to our example, we can now use the revised DateParceler implementation to handle nullable and non-null dates by adding annotations for both types:

@Parcelize
@TypeParceler<Date, DateParceler>
@TypeParceler<Date?, DateParceler>
class Session(val title: String,
              val startTime: Date,
              val endTime: Date?): Parcelable

and we can confirm that the generated code now uses the custom type serializer for both date properties:

public void writeToParcel(@NotNull Parcel parcel, int flags) {
   parcel.writeString(this.title);
   DateParceler.INSTANCE.write(this.startTime, parcel, flags);
   DateParceler.INSTANCE.write(this.endTime, parcel, flags);
}

Add annotations targeting the correct type variant (nullable or non-null) for each property type requiring a custom serializer in the primary constructor of the Parcelable class. An annotation targeting a non-null type will be ignored for a nullable type, and vice-versa.

Handling generic custom types

One limitation of custom Parceler implementations is that they are required to be object singletons. Which means they can’t be passed extra arguments through a constructor: a separate object needs to be declared for each variation of the serialization algorithm.

But you can work around that limitation and avoid duplicating code by creating reusable utility functions and/or parent classes to be used by these object instances.

Let’s illustrate this with an example by creating a Parceler implementation for EnumSet<E>. The concrete Enum class is actually needed to be able to instantiate an EnumSet and populate its values during deserialization. We would like to be able to pass that Class as argument to the Parceler at deserialization time but we can’t do it directly. Instead, it can be passed as constructor argument of a reusable Parceler implementation:

open class EnumSetParceler<E : Enum<E>>(private val elementType: Class<E>) : Parceler<EnumSet<E>> {

    private val values = elementType.enumConstants

    override fun create(parcel: Parcel): EnumSet<E> {
        val set = EnumSet.noneOf(elementType)
        repeat(parcel.readInt()) {
            set.add(values[parcel.readInt()])
        }
        return set
    }

    override fun EnumSet<E>.write(parcel: Parcel, flags: Int) {
        parcel.writeInt(size)
        for (value in this) {
            parcel.writeInt(value.ordinal)
        }
    }
}

That single open class can then be used as parent for multiple object instances, one for each concrete EnumSet<E> type that needs to be serialized using Parcelize:

object StateEnumSetParceler : EnumSetParceler<State>(State::class.java)
object CategoryEnumSetParceler : EnumSetParceler<Category>(Category::class.java)

We end up with a collection of objects that can be used to serialize variants of the same type, without the need to duplicate logic.

Accessing generated CREATOR fields from Kotlin code

When writing custom Parcel deserialization code, for example by implementing a Parceler object, sometimes you need to reference the static CREATOR field of Parcelable classes. It’s useful to create an object instance for a concrete type without relying on reflection, and is used among others by Parcel.createTypedArrayList() and Parcel.readTypedObject().

But sadly you’ll notice that the static CREATOR fields generated by Parcelize are not visible from Kotlin code located in the same module. This is because these fields are added to the classes annotated with @Parcelize at a later stage of the Kotlin compilation process, which means they don’t exist yet when the compiler attempts to resolve references amongst Kotlin files at the beginning of compilation. This issue is known since 2017 ~~and no fix seems to be planned so far, which is a bit surprising for a feature that took years to be called “production-ready”~~. Update: a solution is finally provided starting with Kotlin 1.6.20 (April 2022). You should use the specially optimized parcelableCreator() function to reference the generated CREATOR field of a Parcelable class. For example:

object ExampleAParceler : Parceler<ExampleA> {

    override fun create(parcel: Parcel): ExampleA {
        val b = parcelableCreator<ExampleB>().createFromParcel(parcel)
        return ExampleA(
            b = b
        )
    }

    override fun ExampleA.write(parcel: Parcel, flags: Int) {
        b.writeToParcel(parcel, flags)
    }
}

Calls to the parcelableCreator() function will be optimized during compilation and replaced with a direct access to the CREATOR field for concrete types so no reflection will be involved!

Sokoban puzzle by Borgar Þorsteinsson. Under Creative Commons license

Dealing with class inheritance

You can annotate open classes with @Parcelize. However, it’s not possible to also annotate child classes that inherit from these open classes without duplicating all the serializable properties of their parent class. Let’s look at an example to have a better understanding of the problem:

@Parcelize
open class Book(val title: String, val author: Person) : Parcelable

@Parcelize
class ElectronicBook(private val _title: String,
                     private val _author: Person,
                     val downloadSize: Long) : Book(_title, _author)

In order to comply with the Parcelize restriction of having all primary constructor arguments declared as either val or var, we end up redeclaring two unnecessary properties for title and author which are already handled by the parent class. This works but is far from elegant, not to mention duplicating fields in an object is wasting memory.

If you need to create a child class inheriting from an open Parcelable class, you should either write the Parcelable implementation of that child class manually, or refactor the parent class to make it abstract or sealed.

In the case of the above example, the Book class would be turned into an abstract or sealed class (or even an interface) with a new concrete child class PaperBook.

Parcelable abstract and sealed classes with common fields

It’s not allowed to annotate abstract or sealed classes with @Parcelize: all concrete child classes that inherit from them must be annotated instead.

This has a few implications to keep in mind:

It’s not possible to reuse serialization code from a parent class in a child class, meaning that the generated code needed to serialize a field declared in the parent class will effectively be repeated in every child class;
All properties that need to be serialized in the abstract or sealed class must be declared as abstract in order to avoid duplicating them in the child class.

Let’s look at an example of a Parcelable abstract class.

abstract class Vehicle(val wheels: Int) : Parcelable {
    abstract val model: String
    abstract var speed: Float
}

@Parcelize
class Car(override val model: String, override var speed: Float)
    : Vehicle(4)

@Parcelize
class Bicycle(override val model: String, override var speed: Float)
    : Vehicle(2)

The common wheels property should not be serialized and its value is initialized directly by the child classes constructor.
The common model and speed properties need to be serialized in each instance, so they are declared as abstract in the parent Vehicle class. Then, they are overridden in the primary constructor of all child classes and will be handled by Parcelize.
Extra properties to serialize could also be added in the primary constructor of the child classes.

Objects with a parent class

Another interesting feature of Parcelize that has not yet been mentioned is that it supports annotating object. At first it would seem useless to support the serialization of a singleton, but it actually makes sense when the object has a parent class and represents one of the possible values of its parent class.

This feature is particularly useful when it comes to implement a Parcelable sealed class where some of the values are objects. A typical example of such class would look like this:

sealed class Status : Parcelable

@Parcelize
object Success : Status()

@Parcelize
class Error(val message: String) : Status()

We can take one last look at the bytecode inspector in order to confirm that the generated deserializing code for the object is indeed returning the existing singleton instance and not a new instance:

@NotNull
public final Object createFromParcel(@NotNull Parcel in) {
   return in.readInt() != 0 ? Success.INSTANCE : null;
}

Excluding properties from serialization

Sometimes properties are used to store transient state that must be excluded from serialization. In a typical Java world, the containing class would implement the Serializable interface and the excluded fields would be annotated with @Transient.

But in our Android world we are using the preferred Parcelable interface and this annotation is not recognized by Parcelize. Instead, to be exempted from serialization a Kotlin property has to be declared in the body of the class instead of the primary constructor:

@Parcelize
class Book(val title: String, val totalPages: Int) : Parcelable {
    @IgnoredOnParcel
    var readPages: Int = 0
}

In this example, the readPages property will be skipped. The IDE will highlight it with a warning message by default, until you annotate it with @IgnoredOnParcel to make that behavior more explicit.

Now, is it still possible to pass the initial value of that property through a class constructor like for the other properties? The answer is yes: by using a secondary constructor which delegates to the primary constructor.

@Parcelize
class Book private constructor(val title: String,
                               val totalPages: Int) : Parcelable {
    @IgnoredOnParcel
    var readPages: Int = 0

    constructor(title: String, totalPages: Int, readPages: Int)
            : this(title, totalPages) {
        this.readPages = readPages
    }
}

In the above example, the primary constructor was made private so that it’s only callable by the secondary constructor and the generated Parcelable CREATOR, and external classes have to use the secondary constructor with 3 arguments to create an instance.

Similarly, it’s possible to use the same technique to achieve the opposite: make private properties serializable without having to pass their initial value through the public class constructor.

@Parcelize
class ClickCounter private constructor(private var count: Int)
    : Parcelable {

    constructor() : this(0)

    fun click() {
        count++
    }

    val currentValue
        get() = count
}

In this final example, count is an internal state variable that will be initialized to 0 when the class public constructor is called, and restored to its current value upon deserialization.

Use a public secondary constructor in combination with a private primary constructor to control which properties you want to be initializable through the public constructor and which properties you want to be serialized.

And that’s a wrap. This covers everything there is to know about the feature so that, except for rare cases, no Android developer should have to write manual Parcelable serialization code ever again. If you are aware of other caveats or tips and tricks regarding Parcelize, feel free to detail them in the comments section.

Thank you for reading this exceptionally long post. If you liked it, please share or subscribe and stay tuned for more in the coming months.

Advanced JSON parsing techniques using Moshi and Kotlin

Christophe Beyls — Mon, 30 Jul 2018 22:00:00 +0000

Moshi is a modern JSON library for Android and Java from Square. It can be considered as the successor to GSON, with a simpler and leaner API and an architecture enabling better performance through the use of the Okio library. It’s also the most Kotlin-friendly library you can use to parse JSON files, as it comes with Kotlin-aware extensions.

In this article I’m going to demonstrate how to take advantage of features from both the Moshi library and the Kotlin language itself in order to write efficient and robust JSON parsers.

The example model and JSON file

Consider the following model representing a person:

class Person(val id: Long, val name: String, val age: Int = -1)

id and name are mandatory properties, while the age is optional with a default value of -1.

Our objective is to load a list of Person objects in our application from a JSON file or stream with the following contents:

[
  {
    "id": 1,
    "name": "John",
    "age": 38
  },
  {
    "id": 8,
    "name": "Lisa",
    "age": 23
  },
  {
    "id": 23,
    "name": "Karen"
  }
]

In this simple example, the JSON object key names exactly match the Person property names and the "age" key is also optional.

1. Fully manual parsing

The most basic way of parsing JSON using Moshi is to use the streaming API, which is similar to the streaming API of GSON and the one provided by the Android Framework. This gives you the most control over the parsing process, which is especially useful when the JSON source is dirty.

Typical code would look like this:

class ManualParser {
    fun parse(reader: JsonReader): List<Person> {
        val result = mutableListOf<Person>()

        reader.beginArray()
        while (reader.hasNext()) {
            var id: Long = -1L
            var name: String = ""
            var age: Int = -1

            reader.beginObject()
            while (reader.hasNext()) {
                when (reader.nextName()) {
                    "id" -> id = reader.nextLong()
                    "name" -> name = reader.nextString()
                    "age" -> age = reader.nextInt()
                    else -> reader.skipValue()
                }
            }
            reader.endObject()

            if (id == -1L || name == "") {
                throw JsonDataException("Missing required field")
            }
            val person = Person(id, name, age)
            result.add(person)
        }
        reader.endArray()

        return result
    }
}

Introducing `selectName()` for performance

We can further optimize the parser by leveraging a feature introduced in Moshi 1.5: the ability to compare the next bytes of the stream to expected JSON object key names or values. This is done using the JsonReader.selectName() and JsonReader.selectString() methods, respectively.

How does that improve performance? By looking at the JSON file, you can see that some string values are being repeated multiple times: the key names for the JSON objects are known in advance and match the property names of the Person class ("id", "name", "age"). So instead of letting Moshi decode the UTF-8 string and allocate memory for it every time a key name is encountered in the stream, we can skip that step and simply compare the next bytes of the stream with a preloaded collection of known key names, already encoded in UTF-8. If the byte sequence is found in the collection, its index will be returned by selectName(). This is made possible using some neat features of the lower-level Okio library.

Note: Moshi is optimized for, and only works with, JSON files encoded in UTF-8. If you still use a different character encoding in 2018, shame on you.

After replacing nextName() with selectName() in the parser, the code now looks like this:

class ManualParser {
    companion object {
        val NAMES = JsonReader.Options.of("id", "name", "age")
    }

    fun parse(reader: JsonReader): List<Person> {
        val result = mutableListOf<Person>()

        reader.beginArray()
        while (reader.hasNext()) {
            var id: Long = -1L
            var name: String = ""
            var age: Int = -1

            reader.beginObject()
            while (reader.hasNext()) {
                when (reader.selectName(NAMES)) {
                    0 -> id = reader.nextLong()
                    1 -> name = reader.nextString()
                    2 -> age = reader.nextInt()
                    else -> {
                        reader.skipName()
                        reader.skipValue()
                    }
                }
            }
            reader.endObject()

            if (id == -1L || name == "") {
                throw JsonDataException("Missing required field")
            }
            val person = Person(id, name, age)
            result.add(person)
        }
        reader.endArray()

        return result
    }
}

It’s a bit less readable than before since the when expression now mentions array indices instead of the string values directly. That can be improved by declaring extra constants for these indices in the companion object, at the expense of adding more lines of code.

Reducing boilerplate code using extension functions

The code for reading a JSON array and a JSON object using a streaming API always follows the same patterns. These patterns can be extracted to extension functions to avoid the repetition. This especially improves readability and reduces the risk of errors for JSON files with multiple levels of nested arrays and objects.

fun JsonReader.skipNameAndValue() {
    skipName()
    skipValue()
}

inline fun JsonReader.readObject(body: () -> Unit) {
    beginObject()
    while (hasNext()) {
        body()
    }
    endObject()
}

inline fun JsonReader.readArray(body: () -> Unit) {
    beginArray()
    while (hasNext()) {
        body()
    }
    endArray()
}

It’s recommended to declare the higher-order functions as inline so that calling them introduces no additional cost compared to the original code (no extra objects allocations) and the bytecode will be identical.

We can also create another version of readArray() which goes one step further and builds and returns the list as well.

inline fun <T : Any> JsonReader.readArrayToList(body: () -> T?): List<T> {
    val result = mutableListOf<T>()
    beginArray()
    while (hasNext()) {
        body()?.let { result.add(it) }
    }
    endArray()
    return result
}

When using that function, the body of the lambda must return the item to be added to the list, or null to skip it.

With these new functions the parser code becomes much shorter:

class ManualParser {
    companion object {
        val NAMES = JsonReader.Options.of("id", "name", "age")
    }

    fun parse(reader: JsonReader): List<Person> {
        return reader.readArrayToList {
            var id: Long = -1L
            var name: String = ""
            var age: Int = -1

            reader.readObject {
                when (reader.selectName(NAMES)) {
                    0 -> id = reader.nextLong()
                    1 -> name = reader.nextString()
                    2 -> age = reader.nextInt()
                    else -> reader.skipNameAndValue()
                }
            }

            if (id == -1L || name == "") {
                throw JsonDataException("Missing required field")
            }
            Person(id, name, age)
        }
    }
}

Immutability, default values and mandatory fields

To be able to enforce the immutability of the Person object (all its fields are vals), we need to pass all the field values at once in its constructor, which means that we need to declare one extra variable for each field.

var id: Long = -1L
var name: String = ""
var age: Int = -1

Variables for optional fields (age) need to be assigned a default value matching the default value of the field.
Variables for mandatory fields (id, name) are assigned an arbitrary default value outside of the range of valid values. null can also be used as default value for non-null mandatory fields. Then before instantiating the model object, we need to check that these variables have been reassigned valid values, otherwise throw an Exception or skip the item:

if (id == -1L || name == "") {
    throw JsonDataException("Missing required field")
}

Manual fields validation makes the parser code both more verbose and error-prone because we need to remember updating the parser every time we change the mandatory fields or update the default values in the model.

Note: We can avoid declaring these variables entirely in the parser by making the model fully mutable (declaring all fields as vars) with an empty constructor.

class Person {
    var id: Long = 0L
    var name: String = ""
    var age: Int = -1
}

Benefits:

Less lines of code in the parser;
We can rely on the model default values instead of duplicating them in the parser code.

Downsides:

We lose all the benefits of immutability: coherent states, no side effects, thread safety;
All fields are now declared as optional. We need to document which ones are effectively mandatory and the parser still needs to manually check if they have been assigned a valid value.

Because the downsides outweigh the benefits, I recommend to always favor immutability in your model objects when you can, especially since Kotlin makes this easier than Java.

2. Moshi’s Kotlin Code Gen

A better way to validate mandatory Kotlin fields and respect default values while keeping the objects immutable is to let Moshi do this work for us by using the automatic JSON to Kotlin converters it provides.

Moshi has two ways to generate these converters which are called JsonAdapters:

Using reflection, via the moshi-kotlin artifact. Adapters will be generated at runtime when needed, then reused. The main downside of this solution is that in order to understand metadata like nullability and default values of Kotlin properties, this artifact depends on the kotlin-reflect library, a 2.5 MiB jar file which will make your application code size grow significantly.
Since Moshi 1.6, adapters can also be generated at compile time using the moshi-kotlin-codegen annotation processor. This is a much better solution because it provides better performance while adding no extra dependency to your application. The only limitation of that solution compared to kotlin-reflect is that it is unable to initialize private or protected fields without using the class constructor, but the same limitations apply when writing your parsers manually.

Setup moshi-kotlin-codegen

Make sure you enable the kapt plugin in your application’s build.gradle file.

apply plugin: 'kotlin-kapt'

Then add the annotation processor to your dependencies.

dependencies {
    kapt 'com.squareup.moshi:moshi-kotlin-codegen:1.6.0'
}

Update (2026): Today you should use the KSP annotation processor plugin in place of KAPT which is deprecated and unmaintained. Recent versions of moshi-kotlin-codegen are compatible with KSP.

Now for every Kotlin class for which you want to generate a JsonAdapter implementation at compile time, add the @JsonClass annotation on top of it with the generateAdapter element set to true. In this example, we’ll add it to the Person class.

@JsonClass(generateAdapter = true)
class Person(val id: Long, val name: String, val age: Int = -1)

By default, the generated parser will match the property names with the JSON object key names. To override that, add the @Json annotation on the property to specify its JSON key name.

Moshi also allows to fully customize the way each property is converted from or to JSON, by using custom annotations associated with your own custom type adapters. For more information, check out the official documentation.

A look at the generated code

When building the project, the annotation processor will create a new Kotlin class called PersonJsonAdapter. Let’s evaluate its code quality.

class PersonJsonAdapter(moshi: Moshi) : JsonAdapter<Person>() {
    private val options: JsonReader.Options = JsonReader.Options.of("id", "name", "age")

    private val longAdapter: JsonAdapter<Long> = moshi.adapter(Long::class.java).nonNull()

    private val stringAdapter: JsonAdapter<String> = moshi.adapter(String::class.java).nonNull()

    private val intAdapter: JsonAdapter<Int> = moshi.adapter(Int::class.java).nonNull()

    override fun toString(): String = "GeneratedJsonAdapter(Person)"

    override fun fromJson(reader: JsonReader): Person {
        var id: Long? = null
        var name: String? = null
        var age: Int? = null
        reader.beginObject()
        while (reader.hasNext()) {
            when (reader.selectName(options)) {
                0 -> id = longAdapter.fromJson(reader) ?: throw JsonDataException("Non-null value 'id' was null at ${reader.path}")
                1 -> name = stringAdapter.fromJson(reader) ?: throw JsonDataException("Non-null value 'name' was null at ${reader.path}")
                2 -> age = intAdapter.fromJson(reader) ?: throw JsonDataException("Non-null value 'age' was null at ${reader.path}")
                -1 -> {
                    // Unknown name, skip it.
                    reader.skipName()
                    reader.skipValue()
                }
            }
        }
        reader.endObject()
        var result = Person(
                id = id
                        ?: throw JsonDataException("Required property 'id' missing at ${reader.path}"),
                name = name
                        ?: throw JsonDataException("Required property 'name' missing at ${reader.path}"))
        result = Person(
                id = id ?: result.id,
                name = name ?: result.name,
                age = age ?: result.age)
        return result
    }

    override fun toJson(writer: JsonWriter, value: Person?) {
        // Removed for brevity
    }
}

We can notice that this code is quite similar to what we wrote in the manual parser.

It uses selectName() for better performance, which is good. The options are not stored inside a companion object but it doesn’t matter because a JsonAdapter is only instantiated once then reused, making it effectively a singleton. Non-null properties are enforced. Mandatory fields are properly checked and an exception is thrown when they are missing.

Only two things aren’t perfect compared to a smart manually-written parser:

Nullable variables are used to store values of non-null primitive types (Long, Int) and generic adapters are used to read them ( longAdapter, intAdapter), which means unnecessary boxing will occur when reading these values.
For each item, two instances of Person are created instead of one. The reason behind this is to allow reading back all the default values of optional fields from the first instance when creating the second, final instance. This should not cause any performance issue, unless your model class includes heavy initialization code that you want to avoid doing twice. This also means that when all fields are mandatory, only one instance will be created by the adapter.

These are minor performance issues, so I recommend that you use the automatically generated Kotlin JsonAdapters when both your code and the JSON data source allow it.

Update (2026): The code generator in Moshi 1.9.0 (released in 2019) is now able to call the Kotlin synthetic constructor that handles default values for optional fields. A single instance of each object is now created in every case and this limitation doesn't exist anymore.

Using the generated adapters

It’s preferred to use the Moshi API to retrieve adapter instances, because it will automatically locate the class, create a single instance of it and put it in a cache so it can be shared between parsers.

val adapter: JsonAdapter<Person> = moshi.adapter(Person::class.java)

The generated adapter converts JSON to a single Person object. But the JSON file contains an array of persons so we want to retrieve a List<Person> instead. There are two ways to achieve this.

First, we can ask Moshi to build a generic list adapter which will use the generated PersonJsonAdapter under the hood. This is done by using Moshi’s Types utility class to build a type representing List<Person>:

val listType = Types.newParameterizedType(List::class.java, Person::class.java)
val adapter: JsonAdapter<List<Person>> = moshi.adapter(listType)
val result = adapter.fromJson(reader)

Update (2026): Moshi 1.11.0 (released in 2020) provides a new experimental adapter() extension function using Kotlin's reified typeOf() function to resolve the type at compile time. So in Kotlin you don't need to use the Types class anymore and you can simply write this:
val adapter: JsonAdapter<List<Person>> = moshi.adapter()
val result = adapter.fromJson(reader)

But more interestingly, we can also use the generated adapters inside our own parsers, effectively mixing and matching manual and automatic parsing. This is especially useful when the JSON source is not very well structured or contains a lot of unnecessary layers that we want to skip, but at the same time we still want to leverage the automatic parsing in some parts of the file.

For our example, we can write a hybrid parser which builds a list of Person objects while filtering out children and people of unknown age:

class HybridParser(moshi: Moshi) {
    private val personAdapter: JsonAdapter<Person> = moshi.adapter(Person::class.java)

    fun parse(reader: JsonReader): List<Person> {
        return reader.readArrayToList {
            personAdapter.fromJson(reader)?.takeIf { it.age >= 18 }
        }
    }
}

We start by manually parsing the JSON array using the readArrayToList() extension function defined earlier. It was designed to not add the item to the list when the lambda returns null, so we can use takeIf() to filter out items.

Generated JsonAdapters are a great way to remove boilerplate code from manual JSON parsers.
Of course, you can also write your own custom JsonAdapters and reuse them in your code.

If you want to learn more about Moshi’s Kotlin Code Gen, you can read this excellent article from its main contributor, Zac Sweers.

3. Coroutines magic for big data sources

In the previous example we saw how to filter out items inside the parser. Now, what if we wanted to filter out items from outside the parser, or wanted to process parsed items one by one, without storing them all at once into memory?

We can achieve this by creating a lazy streaming parser which returns a Kotlin Sequence instead of a List. Sequences allow to keep memory usage under control when dealing with potentially huge JSON lists, as they only deal with one item at a time and all processing is delayed until their final collection. A Sequence can also be converted to an Iterable for Java compatibility.

While it is possible to manually write a custom Sequence with a custom Iterator which will resume parsing every time next() is called, it is not an easy task. It requires some mental gymnastics because the parsing code, instead of being structured hierarchically like the JSON file in one single block, has to be split into separate parts sharing the same state.

Fortunately, there is an easier way thanks to Kotlin’s coroutines which allow to build a lazy sequence using only a single block of synchronous code and the yield() suspending function.

class LazyParser(moshi: Moshi) {
    private val personAdapter: JsonAdapter<Person> = moshi.adapter(Person::class.java)

    fun parse(reader: JsonReader): Sequence<Person> {
        return sequence {
            reader.readArray {
                yield(personAdapter.fromJson(reader)!!)
            }
        }
    }
}

The code is very simple. It’s similar to building a list in one go, except that the calls to add an item to the list are replaced with yield(item). The parser will effectively stop at that point, preserving its state, then resume later when the next item of the Sequence is requested by the caller. That’s all the code needed to create a fully lazy JSON parser in Kotlin.

It’s then possible filter out items, iterate over them or do anything else lazily outside of the parser:

val sequence = LazyParser(moshi).parse(reader)
val filteredList = sequence.filter { it.age >= 18 }.toList()

I hope this article was able to inspire you to make your JSON parsers cleaner, faster and fun. Feel free to share it and also ask questions or provide more examples in the comments. Happy coding!

Architecture Components pitfalls: LiveData and the Fragment lifecycle

Christophe Beyls — Mon, 23 Oct 2017 22:00:00 +0000

The new Android Architecture Components are soon to be announced as stable after a few months of public testing.

A lot has already been written about the basics (starting with the very good documentation) so I won’t cover them here. Instead I would like to focus on important pitfalls that are mostly undocumented and rarely discussed and may cause issues in your applications if you miss them. In this article, I’ll talk about our beloved Fragments.

Edit (14 may 2018): Google has finally fixed the issue in support library 28.0.0 and AndroidX 1.0.0. See solution 4 below.

Edit (13 march 2020): onActivityCreated() has been officially deprecated and onViewCreated() should be used instead. The code samples in this article have been updated accordingly.

The Architecture Components provide default ViewModelProvider implementations for activities and fragments. They allow you to store LiveData instances inside a ViewModel to be reused across configuration changes. The usage with activities is quite straightforward because the activity lifecyle maps well to the Lifecycle interface of the Architecture Components, but the fragment lifecycle is more complex and may cause subtle side effects if you’re not being careful.

The Fragment lifecycle (simplified version)

Fragments can be detached and re-attached. When they are detached, their view hierarchy is destroyed and they become invisible and inactive, but their instance is not destroyed. When they are later re-attached, a new view hierarchy is created and onCreateView() and onViewCreated() are called again.

For this reason, the usually recommended place to initialize Loaders and other asynchronous loading operations that will eventually interact with the view hierarchy is in onViewCreated(). We can assume this is also the best place to initialize LiveData instances by subscribing a new Observer. Most of the official Architecture Components samples also do it there. You would expect typical code to look like this:

class Page1Fragment : Fragment() {

    private var textView: TextView? = null

    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? {
        val view = inflater.inflate(R.layout.fragment_page1, container, false)
        textView = view.findViewById(R.id.result)
        return view
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        val vm = ViewModelProviders.of(this)
                .get(Page1ViewModel::class.java)

        vm.myData.observe(this, Observer { textView?.text = it })
    }

    override fun onDestroyView() {
        super.onDestroyView()
        textView = null
    }
}

There is a hidden problem with this code. We subscribe an anonymous observer within the lifespan of the fragment (using the fragment as LifecycleOwner), which means it will automatically be unsubscribed when the fragment is destroyed. However, when the fragment is detached and re-attached, it is not destroyed and a new identical observer instance will be added in onViewCreated(), while the previous one has not been removed! The result is a growing number of identical observers being active at the same time and the same code being executed multiple times, which is both a memory leak and a performance problem (until the fragment is destroyed).

This problem concerns any fragment subscribing an observer for its own lifecycle in onCreateView() or later, without taking any other extra step to unsubscribe it.

Worse: it also impacts retained fragments, which are not destroyed during configuration changes but re-attached to a new Activity.

How do we solve this? There are a few solutions to explore, some better than others. Here are the ones I found so far.

1. Observing in `onCreate()`

Your first attempt may be to simply move the observer subscription to onCreate() instead of onViewCreated(). But it won’t work as expected without adding more boilerplate code: LiveData keeps track of which result has been delivered to which observer, and it won’t deliver the latest result again to a new view hierarchy because the observer hasn’t changed. This means you have to manually check for a latest result and bind it to the new view hierarchy in onViewCreated() which is not very elegant:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    vm = ViewModelProviders.of(this)
            .get(Page1ViewModel::class.java)

    vm.myData.observe(this, Observer(this::bindResult))
}

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)

    vm.myData.value?.apply(this::bindResult)
}

private fun bindResult(result: String?) {
    textView?.text = result
}

Note that the binding code needs to be called at two different places, so you can’t just write an inline anonymous observer. And finally, there is no way with the current LiveData API to differentiate a null result from no result for the current value, so it’s better not to return any null result (for instance in case of error) when using this solution, which overall is probably the worst one.

Edit (2023): version 2.3.0 of the Lifecycle library finally added a new method LiveData.isInitialized() to allow determining if a LiveData instance contains a (possibly null) result.

2. Manually unsubscribing the observer in `onDestroyView()`

This is a bit better than the first solution but you still can’t use an inline anonymous observer. You must declare it as a final field, subscribe it in onViewCreated() and also not forget to unsubscribe it in onDestroyView(), so there is still boilerplate code and room for errors.

private val observer = Observer<String?> { textView?.text = it }

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    vm = ViewModelProviders.of(this)
            .get(Page1ViewModel::class.java)
}

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)

    vm.myData.observe(this, observer)
}

override fun onDestroyView() {
    super.onDestroyView()
    textView = null

    vm.myData.removeObserver(observer)
}

One of the main benefits of using LiveData being that it takes care of unsubscribing the observer for you, it’s a pity that it has to be done manually in this case. Keep reading, we can still do better.

3. Resetting an existing observer

It’s not actually required to unsubscribe the current observer precisely in onDestroyView(), because it will eventually be unsubscribed automatically in onDestroy(). What’s important is that it’s unsubscribed before an identical one is subscribed in onViewCreated(), in order to avoid duplicates. Therefore, another valid solution is to unsubscribe right before subscribing, using for example this Kotlin extension function:

fun <T> LiveData<T>.reObserve(owner: LifecycleOwner, observer: Observer<T>) {
    removeObserver(observer)
    observe(owner, observer)
}

Removing and adding back the same observer will effectively reset its state so that LiveData will deliver the latest result again automatically during onStart(), if any. The above function can be used like this:

private val observer = Observer<String?> { textView?.text = it }

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    val vm = ViewModelProviders.of(this)
            .get(Page1ViewModel::class.java)

    vm.myData.reObserve(this, observer)
}

The fragment code is now less error-prone because there is one less callback to add, but we still need to declare the observer instance as a final field and reuse it, or else unsubscription will silently fail. Despite this, it’s probably my personal favorite solution for a quick workaround.

4. Creating a custom Lifecyle for view hierarchies

Ideally, we would want observers subscribed in onViewCreated() to be automatically unsubscribed in onDestroyView(). This means we actually want to follow the current view hierarchy lifecycle, which is different from the fragment lifecycle. One way to achieve this is to create a custom Fragment which provides an additional custom LifecycleOwner for the current view hierarchy. Here is an implementation in Java.

Thanks to the custom LifecycleOwner returned by getViewLifecycleOwner(), the LiveData observers will be automatically unsubscribed when the view hierarchy is destroyed and nothing else has to be done.

Note: onViewCreated() won’t be called if onCreateView() returns null, so the custom LifecycleOwner won’t be created for headless fragments and getViewLifecycleOwner() will also return null in that case.

With this solution the code is now nearly identical to the initial code sample, but this time it does the right thing.

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    val vm = ViewModelProviders.of(this)
            .get(Page1ViewModel::class.java)

    vm.myData.observe(viewLifecycleOwner,
            Observer { textView?.text = it })
}

The downside is that it requires inheriting from a custom Fragment implementation. It is also possible to implement the same functionality without inheritance but then it requires declaring a delegate helper class inside each fragment where that custom LifecycleOwner is needed.

Edit (14 may 2018): Google implemented this solution directly in support library 28.0.0 and AndroidX 1.0.0. All fragments now provide an additional getViewLifecycleOwner() method just like in the above sample, so you don’t need to implement it yourself.

5. Using Data Binding

This section has been rewritten following the release of Android Studio 3.1 and the described solution is considered production-ready.

This last solution provides the cleanest architecture, at the expense of depending on an additional library. It consists of using the Android Data Binding Library to automatically bind your model to the current view hierarchy, and to simplify things the model will be the ViewModel instance already used to contain the various LiveData.

With that architecture, the LiveData instances exposed by the ViewModel will be automatically observed by the generated Binding class instead of the fragment itself.

<layout xmlns:android="http://schemas.android.com/apk/res/android">
    <data>
        <variable
            name="viewModel"
            type="my.app.viewmodel.Page1ViewModel"
            />
    </data>
    <TextView
        android:id="@+id/result"
        style="@style/TextAppearance.AppCompat.Large"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@{viewModel.myData}"/>
</layout>

The layout declares a variable of type Page1ViewModel and binds the TextView’s android:text property directly to the LiveData field. When the LiveData is updated, the TextView will immediately reflect its new value.

Note: The ability to bind LiveData fields directly to views and make the Binding classes lifecycle-aware has been added in Android Studio 3.1.

The ViewModel will always reflect the latest visual state of the fragment, even when no view hierarchy is currently attached to it. Each time a view hierarchy is created through a Binding class, it will register itself as a new observer on the LiveData instances, so we don’t have to manage any observer manually anymore and we got rid of the problem.

class Page1Fragment : Fragment() {

    lateinit var vm: Page1ViewModel

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        vm = ViewModelProviders.of(this)
                .get(Page1ViewModel::class.java)
    }

    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? {
        val binding = FragmentPage1Binding
                .inflate(inflater, container, false)
        binding.viewModel = vm
        binding.setLifecycleOwner(this)
        return binding.root
    }
}

Since the LifecycleOwner is passed to the Binding instance, the LiveData loading logic will still comply with the lifecycle of the current fragment: the views will only be updated while the fragment is started and the internal observers will be properly unsubscribed in onDestroy().

Furthermore, the special LiveData observers used by the Binding classes use weak references internally so they will eventually be unregistered automatically after their associated view hierarchy has been destroyed and garbage collected, even if the fragment itself has not been destroyed yet.

Overall, this simplifies the fragment by removing the tricky observers logic along with all the View boilerplate code.

Final warning

This issue should be taken seriously because detaching a fragment is a very common operation. For instance, it happens when:

Switching between sections in the main activity of an app;
Navigating between pages in a ViewPager using a FragmentPagerAdapter;
A fragment is replaced with another one and the transaction is added to the back stack.

Also, when a fragment is detached, all its child fragments are detached as well. When in doubt, it’s better to assume that any fragment will eventually be detached at some point and properly handle this case from day 1.

Now you are aware of this behavior and have at least a few options to work around it.

Edit (14 may 2018): Google decided to implement solution 4 directly in support library 28.0.0 and AndroidX 1.0.0. I now recommend that you register your observers using the special lifecycle returned by getViewLifecycleOwner() in onCreateView().
I like to think that this article played a part in Google fixing this issue and picking up the proposed solution.

Don’t hesitate to discuss this in the comments section and please share if you like.

Kotlin singletons with argument

Christophe Beyls — Fri, 25 Aug 2017 22:00:00 +0000

In Kotlin, the singleton pattern is used as a replacement for static members and fields that don’t exist in that programming language. A singleton is created by simply declaring an object.

object SomeSingleton

Contrary to a class, an object can’t have any constructor, but init blocks are allowed if some initialization code is needed.

object SomeSingleton {
    init {
        println("init complete")
    }
}

The object will be instantiated and its init blocks will be executed lazily upon first access, in a thread-safe way. To achieve this, a Kotlin object actually relies on a Java static initialization block. The above Kotlin object will be compiled to the following equivalent Java code:

public final class SomeSingleton {
   public static final SomeSingleton INSTANCE;

   private SomeSingleton() {
      INSTANCE = (SomeSingleton)this;
      System.out.println("init complete");
   }

   static {
      new SomeSingleton();
   }
}

This is the preferred way to implement singletons on a JVM because it enables thread-safe lazy initialization without having to rely on a locking algorithm like the complex double-checked locking. By simply using an object declaration in Kotlin, you are guaranteed to get a safe and efficient singleton implementation.

Singletons: forever alone

Passing an argument

But what if the initialization code requires some extra argument? Because a Kotlin object can’t have any constructor, you can’t pass any argument to it.

There are valid cases for which passing an argument to a singleton initialization block is the recommended pattern. The alternative requires the singleton class to be aware of some external component to be able to retrieve that argument, violating the principle of separation of concerns and making the code less reusable. To mitigate the issue, that external component could be a dependency injection system. It’s a valid solution but you don’t always want to use that kind of library and there are some cases where it can’t be used, like we’ll see in the following Android example.

Another scenario where you have to rely on a different way to manage a singleton in Kotlin is when the concrete implementation of the singleton is generated by an external tool or library (Retrofit, Room, …) and its instance is retrieved using a custom builder or factory method. In that case, you usually declare the singleton as an interface or abstract class and it can’t be an object.

An Android use case

On the Android platform, you often need to pass a Context instance to initialization blocks of singleton components so they can retrieve file paths, read settings or access services, but you also want to avoid keeping a static reference to it (even if a static reference to the application Context is technically safe). There are two ways to achieve that:

Early initialization: All components are initialized by calling their public init functions at startup time in Application.onCreate() where the application Context is available, before (almost) any other code runs. This simple solution has the main downside of slowing down the application startup by blocking the main thread, initializing all components including those that are not going to be used immediately. Another less known issue is that content providers may be created before this method is called (as stated in the documentation), so if a content provider makes use of a global application component, that component must be able to be initialized before Application.onCreate() or your application may crash.
Lazy initialization: This is the recommended way. The component is a singleton and a function returning its instance takes a Context argument. The singleton instance will be created and initialized using this argument the first time it’s invoked. This requires some synchronization mechanism in order to be thread-safe. An example of standard Android component using this pattern is LocalBroadcastManager:

LocalBroadcastManager.getInstance(context).sendBroadcast(intent)

A reusable Kotlin implementation

We can encapsulate the logic to lazily create and initialize a singleton with argument inside a SingletonHolder class. In order to make that logic thread-safe, we need to implement a synchronized algorithm and the most efficient one — which is also the hardest to get right — is the double-checked locking algorithm.

open class SingletonHolder<out T: Any, in A>(creator: (A) -> T) {
    private var creator: ((A) -> T)? = creator
    @Volatile private var instance: T? = null

    fun getInstance(arg: A): T {
        val i = instance
        if (i != null) {
            return i
        }

        return synchronized(this) {
            val i2 = instance
            if (i2 != null) {
                i2
            } else {
                val created = creator!!(arg)
                instance = created
                creator = null
                created
            }
        }
    }
}

Note that adding the @Volatile annotation to the instance field is required for the algorithm to work properly.

This may not be the most compact or elegant Kotlin code, but it’s the one producing the most efficient bytecode for the double-checked locking algorithm. Trust the Kotlin authors on this: this code is actually borrowed directly from the implementation of the lazy() function in the Kotlin standard library, which is synchronized by default. It has been modified to allow passing an argument to the creator function.

Given its relative complexity, it’s not the kind of code you want to write (or read) more than once, so the goal is to reuse that SingletonHolder class every time you have to implement a singleton with argument.

The logical place to declare the getInstance() function is inside the companion object of the singleton class, which allows it to be called by using simply the singleton class name as qualifier, similarly to a static method in Java. One powerful feature that Kotlin companion objects offer is their ability to inherit from a base class like any other object, which enables something comparable to static-only inheritance. In this case, we want to use SingletonHolder as a base class for the companion object of the singleton, in order to reuse and automatically expose its getInstance() function on the singleton class.

As for the creator function passed as argument to the SingletonHolder constructor, a custom lambda could be declared inline but the common solution is to pass a reference to the private constructor of the singleton class. The final code for a singleton with argument would look like this:

class Manager private constructor(context: Context) {
    init {
        // Init using context argument
    }

    companion object : SingletonHolder<Manager, Context>(::Manager)
}

Not as short as the object notation, but probably the next best thing.

The singleton may now be invoked using the following syntax and its initialization will be lazy and thread-safe:

Manager.getInstance(context).doStuff()

You can also use this idiom when a singleton implementation is generated by an external library and the builder requires an argument. Here’s an example using the Room Persistence Library for Android:

@Database(entities = arrayOf(User::class), version = 1)
abstract class UsersDatabase : RoomDatabase() {

    abstract fun userDao(): UserDao

    companion object : SingletonHolder<UsersDatabase, Context>({
        Room.databaseBuilder(
            it.applicationContext,
            UsersDatabase::class.java,
            "Sample.db"
        ).build()
    })
}

Note: When the builder doesn’t require an argument, you can simply use a lazy delegated property instead:

interface GitHubService {

    companion object {
        val instance: GitHubService by lazy {
            val retrofit = Retrofit.Builder()
                .baseUrl("https://api.github.com/")
                .build()
            retrofit.create(GitHubService::class.java)
        }
    }
}

I hope you found these code snippets useful. If you want to suggest other ways to solve this problem or have questions, don’t hesitate to start a discussion in the comments section. Thank you for reading!

Reducing Parcelable boilerplate code using Kotlin

Christophe Beyls — Fri, 14 Jul 2017 22:00:00 +0000

Update (november 2019): I published a detailed new article about how to use Parcelize to have your Parcelable boilerplate code generated automatically by a Kotlin plugin. This is the preferred method to implement Parcelable in Kotlin today, even if there are still exceptional cases for which you want to write this code manually in Kotlin. The following article will help you for those cases.

Implementing the Parcelable interface and maintaining this code remains a painful day-to-day task for Android developers. Surely, Android Studio can now automatically generate most of the boilerplate code, but this doesn’t work for all member types and most importantly, the result is quite verbose and clutters classes, decreasing their readability.

About Parcelable libraries

Annotation processor libraries like PaperParcel are able to automatically generate Parcelable implementations and get rid of some of the boilerplate code. This is fine, but I don’t use these solutions because I like to have full control over the serialization process. These libraries come with their limitations. For example:

Many of these libraries serialize types like Enum<T> or BigDecimal using Parcel.writeSerializable() which is not the fastest implementation nor most compact representation. Some provide support for non-Parcelable types through custom adapters, but you still need to specify the adapter class in every place where you want to use it.
These libraries usually serialize Parcelable members inside Parcelable classes using Parcel.writeParcelable() which is less efficient to deserialize than using Parcel.writeTypedObject() when the concrete type is known. This is because Parcel.readParcelable() first reads the full class name in order to retrieve the corresponding Parcelable.Creator via reflection, while Parcelable.readTypedObject() uses the provided Parcelable.Creator directly.
In some cases, I want the Parcelable.Creator to act like a factory method determining which concrete sub-type will be created. Again, this is more efficient than using Parcel.readParcelable(). I can’t do this if the Parcelable.Creator is generated automatically.
I like child classes to reuse Parcelable code from their parent to avoid redundancy. This is not what most libraries do.
Finally, almost all libraries slightly increase the methods count of your APK file, because they bundle their own small runtime into your app and generate a few extra methods for each Parcelable class.

If you want to learn more about Parcelable libraries and their differences, I recommend this excellent article from Brad Campbell.

Kotlin for Parcelables

Simply converting classes to the Kotlin programming language without any additional trick already makes them more readable than their Java equivalent.

Consider the following example class written in Kotlin.

class Person(val name: String, val age: Int)

By using the built-in Android Studio contextual action to generate a Parcelable implementation automatically, we get the following code:

class Person(val name: String, val age: Int) : Parcelable {

    constructor(parcel: Parcel) : this(
        parcel.readString(),
        parcel.readInt()
    )

    override fun writeToParcel(parcel: Parcel, flags: Int) {
        parcel.writeString(name)
        parcel.writeInt(age)
    }

    override fun describeContents(): Int {
        return 0
    }

    companion object CREATOR : Parcelable.Creator<Person> {
        override fun createFromParcel(parcel: Parcel): Person {
            return Person(parcel)
        }

        override fun newArray(size: Int): Array<Person?> {
            return arrayOfNulls(size)
        }
    }
}

The result is 26 lines long.

Cleaning up the generated code

While the code quality is decent, you’ll notice that the CREATOR static field has been implemented as the companion object of that class. This is technically working, but since a class is only allowed to have a single companion object, it means you’ll have to add your class custom fields (like constants) directly into that CREATOR object:

companion object CREATOR : Parcelable.Creator<Person> {
    val DEFAULT = Person("James", 40)

    override fun createFromParcel(parcel: Parcel): Person {
        return Person(parcel)
    }

    override fun newArray(size: Int): Array<Person?> {
        return arrayOfNulls(size)
    }
}

In addition, the Creator methods will be exposed as members of the Person class, polluting its API. This definitely doesn’t feel right and harms readability, so you’ll probably want to change the code to the recommended pattern which is to move the CREATOR field inside the companion object, and annotate it with @JvmField so it will be compiled to a static Java field:

companion object {
    @JvmField val CREATOR = object : Parcelable.Creator<Person> {
        override fun createFromParcel(parcel: Parcel): Person {
            return Person(parcel)
        }

        override fun newArray(size: Int): Array<Person?> {
            return arrayOfNulls(size)
        }
    }
}

We can also make the code a bit shorter by using single-expression functions.

Finally, I like to use named arguments for more clarity when calling the primary constructor from the Parcel secondary constructor and make this constructor private or protected since only the CREATOR and child classes will invoke it.

We end up with the class looking like this:

class Person(val name: String, val age: Int) : Parcelable {

    private constructor(p: Parcel) : this(
        name = p.readString(),
        age = p.readInt()
    )

    override fun writeToParcel(dest: Parcel, flags: Int) {
        dest.writeString(name)
        dest.writeInt(age)
    }

    override fun describeContents() = 0

    companion object {
        @JvmField val CREATOR = object : Parcelable.Creator<Person> {
            override fun createFromParcel(parcel: Parcel) = Person(parcel)

            override fun newArray(size: Int) = arrayOfNulls<Person>(size)
        }
    }
}

It’s now 22 lines long.

1. A better interface

Like Java 8, Kotlin allows to add default implementations to interfaces. We can create an interface using this feature to provide the default implementation of the describeContents() method, which in 99.99% of cases should simply return 0 (and the cases where it should return another value are badly documented anyway). Now we won’t have to write that useless method ever again.

We’ll also override the signature of the writeToParcel() method to force its Parcel argument to be non-null, because it’s actually never null and you shouldn’t bother using the safe call operator on it.

interface KParcelable : Parcelable {
    override fun describeContents() = 0
    override fun writeToParcel(dest: Parcel, flags: Int)
}

From now on, we’ll simply make our objects implement KParcelable instead of Parcelable.

2. A creator for `Creator`s

It’s time to leverage one of the most powerful features of the Kotlin language: higher order inline functions, which can be used like macros for code generation. In this case, we will write a function that generates implementations of these Parcelable.Creator objects that always look the same.

inline fun <reified T> parcelableCreator(
    crossinline create: (Parcel) -> T
) = object : Parcelable.Creator<T> {
    override fun createFromParcel(source: Parcel) = create(source)
    override fun newArray(size: Int) = arrayOfNulls<T>(size)
}

This is a modified version of the function provided by Juan Ignacio Saravia in his instructive article about Parcelables in Kotlin.

Thanks to reified generic type parameters, the arrayOfNulls() function is able to create an array of the proper concrete type at compile time. This would not have been possible to achieve in Java without using reflection at runtime.

parcelableCreator() takes a single argument: a function returning a new instance of the target class from a non-null Parcel. This argument can be a lambda, but it can also simply be a reference to a function like the class secondary constructor which takes a Parcelable as argument:

companion object {
    @JvmField val CREATOR = parcelableCreator(::Person)
}

In addition, we can write a similar function to generate instances of Parcelable.ClassLoaderCreator for cases where we need access to the ClassLoader.

inline fun <reified T> parcelableClassLoaderCreator(
    crossinline create: (Parcel, ClassLoader) -> T
) = object : Parcelable.ClassLoaderCreator<T> {
    override fun createFromParcel(source: Parcel, loader: ClassLoader) = create(source, loader)

    override fun createFromParcel(source: Parcel) = createFromParcel(source, T::class.java.classLoader)

    override fun newArray(size: Int) = arrayOfNulls<T>(size)
}

Our final class has now been reduced to just 16 lines of code and is way more readable:

class Person(val name: String, val age: Int) : KParcelable {

    private constructor(p: Parcel) : this(
        name = p.readString(),
        age = p.readInt()
    )

    override fun writeToParcel(dest: Parcel, flags: Int) {
        dest.writeString(name)
        dest.writeInt(age)
    }

    companion object {
        @JvmField val CREATOR = parcelableCreator(::Person)
    }
}

3. Extending Parcel

Parcel only supports a handful of types to serialize. What if we could extend it to support more types, so that writing an Enum to a Parcel would be as simple and as efficient as writing a String? That’s exactly what Kotlin extension functions are made for.

inline fun <reified T : Enum<T>> Parcel.readEnum() =
    readString()?.let { enumValueOf<T>(it) }

inline fun <T : Enum<T>> Parcel.writeEnum(value: T?) =
    writeString(value?.name)

We can now write an Enum to a Parcel using this syntax:

dest.writeEnum(gender)

Note how these extension functions use nullable types, so they can be used with both nullable and non-null class members. The only compromise of this solution is that it forces you to use the !! operator when reading back a non-null value to a non-null member:

gender = p.readEnum<Gender>()!!

This is safe since you know that the value written to the Parcel was non-null in the first place. If somehow you get a null value here, it means that you made a huge mistake in your serializing code and the NullPointerException is deserved.

Another pair of useful Parcel methods I mentioned earlier is Parcel.readTypedObject() and Parcel.writeTypedObject() that should be preferred for reading or writing Parcelable members when their concrete type is known. These methods are only available since API 23 and not yet part of the support library, but their implementation is straightforward. We can create compatibility versions working on any Android release using simple Kotlin extension functions:

fun <T : Parcelable> Parcel.readTypedObjectCompat(c: Parcelable.Creator<T>) =
    readNullable { c.createFromParcel(this) }

fun <T : Parcelable> Parcel.writeTypedObjectCompat(value: T?, flags: Int) =
    writeNullable(value) { it.writeToParcel(this, flags) }

Note that I extracted the null handling parts of the code to external inline functions readNullable() and writeNullable() so they can be reused by other utility functions.

inline fun <T> Parcel.readNullable(reader: () -> T) =
    if (readInt() != 0) reader() else null

inline fun <T> Parcel.writeNullable(value: T?, writer: (T) -> Unit) {
    if (value != null) {
        writeInt(1)
        writer(value)
    } else {
        writeInt(0)
    }
}

You can find a complete set of useful extension functions for Parcel in the full source code listing at the end of this article.

As a last example, these function calls can be grouped with apply(), run() or with() to reduce the verbosity to a minimum:

override fun writeToParcel(dest: Parcel, flags: Int) = with(dest) {
    writeString(name)
    writeInt(age)
    writeEnum(gender)
    writeDate(birthDate)
    writeTypedObjectCompat(address, flags)
}

Full source code of the Parcelable utilities

The Kotlin language itself is a powerful tool to reduce boilerplate code in Parcelable classes. For those who want full control over the serialization process with minimum overhead while keeping the code as readable as possible, this set of Kotlin utilities and best practices is a good alternative to Parcelable libraries.

As always, please share if you like. Thank you for reading!

Fixing ugly Java APIs: read-only generic varargs and how Kotlin generic types are superior to Java’s

Christophe Beyls — Thu, 29 Jun 2017 22:00:00 +0000

There is an Android API I hate using because of a specific confusing method call. I’m certain there are many other examples of similar methods in the Java world. What’s interesting about it is that it illustrates how the limitations of a programming language (Java in this case) can lead to forcing developers to write unnecessarily cryptic code just to call a single method.

It’s also a good opportunity to explore the obscure world of generic types and variance that even experienced developers often struggle to fully understand.

While I’ll be using the Android platform as an example, the problems described hereafter apply to any Java code.

The problematic method

The Java method I want to discuss is part of the Android API designed to launch Activity transitions with shared elements.

public static ActivityOptions makeSceneTransitionAnimation(
    Activity activity,
    Pair<View, String>... sharedElements
) {
    // ...
}

A similar method is also available in the Android support library. A typical call forces me to write code looking like this:

@SuppressWarnings("unchecked")
final Bundle options = ActivityOptions.makeSceneTransitionAnimation(
    this,
    Pair.<View, String>create(textView, "elem1"),
    Pair.<View, String>create(imageView, "elem2")
).toBundle();

Not so pretty. There are 2 reasons why this method call is made difficult.

1. Arrays of generic types are unsafe

The first problem you’ll notice is that, no matter which arguments you pass to this method, the compiler will always show a warning message.

// Compiles with warning:
// "unchecked generics array creation for varargs parameter"
ActivityOptions.makeSceneTransitionAnimation(this, elem1, elem2);

The reason behind that warning is that Java does not allow creating arrays of parameterized types.

// Does NOT compile
Pair<View, String>[] array = new Pair<View, String>[2];

// Compiles with warning: "Unchecked assignment"
Pair<View, String>[] array = new Pair[2];

This is forbidden because Java arrays are covariant and they check the type of values written to them at runtime. But at runtime, generic types have been erased and the array can not differentiate a Pair<View, String> from a Pair<Integer, Integer>, leading to potential heap pollution and breaking the array contract.

When you call a method with a variable number of arguments, an array is created to pass all the arguments and since the type of that array can not be parameterized, an unchecked assignment has to be made.

To sum it up, as soon as you want to put generic types in a Java array, you’re on your own to guarantee the safety of your code and to prevent a ClassCastException from occurring at runtime. This is why collections should be preferred to arrays when dealing with generic types in Java. Changing the method signature to use a List<T> instead of T... would avoid compiler warnings and guarantee type safety at compile time:

final List<Pair<View, String>> args = new ArrayList<>(2);
args.add(elem1);
args.add(elem2);
ActivityOptions.makeSceneTransitionAnimation(this, args);

However, it would also make the method call even more verbose and we don’t want that either.

The fix: `@SafeVarargs`

The recommended way to fix the variable arguments declaration is to add the @SafeVarargs annotation (available since Java 7) to the method signature.

@SafeVarargs
public static ActivityOptions makeSceneTransitionAnimation(
    Activity activity,
    Pair<View, String>... sharedElements
) {
    // ...
}

This prevents the compiler from issuing a warning when calling the method with the multiple arguments syntax (not passing a single array reference). Adding this annotation tells the compiler that we guarantee that the body of this method only expects each argument in the varargs array to be of the exact declared type and will not perform potentially unsafe operations on it.

On the caller side, when the method is called with this syntax, we rely on the compiler to generate an array populated with objects of the exact same type as well.

Overall this solution feels like a hack, but that’s the best we can get with varargs using the Java language. It’s preferable to add this annotation once on your public API methods, rather than forcing developers to add @SuppressWarnings("unchecked") annotations above each method call.

2. Read-only arguments of generic types should not be invariant

The second problem with this method is the overly restrictive type of the Pair arguments. The Pair class is actually read-only by nature because its two fields are final, so it would be perfectly reasonable to provide for example a Pair<TextView, String> as argument and not only strict instances of Pair<View, String> (TextView inherits from View).

Suppose I previously declared a variable of type TextView and I want to pass it in the Pair arguments. In order to write shorter code, I tend to always use the Pair.create() generic factory method which allows creating a parameterized Pair<A, B> instance without having to specify the types:

// Creates a Pair<TextView, String>
Pair.create(textView, "elem1");
// Creates a Pair<View, String>
Pair.<View, String>create(textView, "elem1");
// Creates a Pair<View, String>
new Pair<View, String>(textView, "elem1");

The first syntax is the shortest but can’t be used here because unlike arrays, Java generic types are always invariant by default.

// Does NOT compile: incompatible types
Pair<View, String> elem1 = Pair.create(textView, "elem1");

The fix: wildcards declaration

Fortunately, there is a way to make a generic type covariant in Java: using wildcards in the type declaration. This is called use-site variance because it has to be specified in the type of each variable where you want to use covariance (read-only generic parameters) or contravariance (write-only generic parameters).

// Compiles (View type can only be consumed)
Pair<? extends View, String> elem1 = Pair.create(textView, "elem1");

Declaring wildcards for read-only or write-only generic arguments in methods of public APIs should be systematic. But they are easy to forget, especially for those who are not too familiar with variance and generic types.

Here is the final fixed signature of our Java method:

@SafeVarargs
public static ActivityOptions makeSceneTransitionAnimation(
    Activity activity,
    Pair<? extends View, ? extends String>... sharedElements
) {
    // ...
}

And now our caller code gets simpler with less room for errors:

final Bundle options = ActivityOptions.makeSceneTransitionAnimation(
    this,
    Pair.create(textView, "elem1"),
    Pair.create(imageView, "elem2")
).toBundle();

Cleaner APIs using Kotlin

If that method had been written in Kotlin, those 2 limitations would have been avoided entirely.

A programming language with 60% less calories.

Kotlin arrays are safer

Kotlin arrays are different from Java arrays: they behave just like standard classes and are invariant by default. This means that:

The compiler guarantees compile-time type safety for arrays as well;
Arrays of parameterized types are allowed;
No compiler warning will be shown when calling a method with a variable number of parameterized arguments.

Furthermore, variable arguments arrays are declared as covariant automatically, which makes them read-only inside the varargs function.

fun someFunction(vararg words: String) {
    if (words.isNotEmpty()) {
        // Does NOT compile: read-only
        words[0] = "Test"
    }
}

Use-site variance is supported in Kotlin as well, but instead of complicated wildcards, type projections are used. This is done using the out (read-only types) and in (write-only types) keywords.

// Type-safe universal array copy function
fun <T> copy (from: Array<out T?>, to: Array<in T?>) {
    assert(from.size == to.size)
    for (i in from.indices) {
        to[i] = from[i]
    }
}

Declaration-site variance is easier

But the real killer feature of Kotlin regarding generic types is the added ability to declare variance of generic types directly in a parameterized class or interface. This is called declaration-site variance.

Kotlin provides its own Pair class which uses this feature.

data class Pair<out A, out B>(
    val first: A,
    val second: B
) : Serializable

Because both values passed in the constructor are read-only, their type can be declared as covariant using the out keyword. Then the parameters of the Pair<A, B> class will always be covariant, no matter where it’s used. Variance only has to be declared once inside the class, eliminating the risk of forgetting to declare it in every public method signature using that class.

// Creates a Pair<TextView, String>
val pair = Pair(textView, "elem1")
// OK: it's covariant by default
val elem1: Pair<View, String> = pair

Our method in a Kotlin world

Due to the language features described above, our API method could have been written like the following extension function:

fun Activity.makeSceneTransitionAnimation(
    vararg sharedElements: Pair<View, String>
): ActivityOptions {
    // ...
}

There is no need to add annotations or specify variance for the Pair parameters because the language does the right thing by default. We also get null safety for free.

Finally, calling this function from Kotlin code would be even more readable than the fixed Java version, partly thanks to the sweeter syntax to create Pair objects:

val options = makeSceneTransitionAnimation(
    textView to "elem1",
    imageView to "elem2",
).toBundle()

This concludes this small demonstration of the benefits of the Kotlin approach to generic types and how the language helps you write cleaner and safer code by default. I hope you learned a few things and as always, please share if you like.

DEV Community: Christophe Beyls

Strategies for automatically refreshing data on Android using Kotlin Flow

Simple periodic refresh

Making refresh smarter in order to leverage caching

The importance of using the right TimeSource

Putting it all together

Advanced use case: sharing the time reference

Summary

Kotlin JSON Benchmark on Android (2022): Moshi vs Kotlin Serialization

The contenders

Moshi-Kotlin Reflection

Moshi-Kotlin Codegen

Moshi-IR

Kotlin Serialization

Benchmark setup

Test data

Libraries versions

Test hardware and operating system

Write performance

Read performance

Read performance — Selective

Conclusions

ViewLifecycleLazy and other ways to avoid View memory leaks in Android Fragments

Why it’s simpler

Why it generates more optimized bytecode

Final advice: only use it if you have to

Smarter Shared Kotlin Flows

Synchronizing with the Lifecycle

LiveData

SharedFlow

An alternative approach

Injecting an Android Lifecycle in the ViewModel ?

Introducing the flowWhileShared() operator

Usage with SharedFlow or StateFlow

Use cases

Loading data in response to location updates

Reloading data on invalidation

Final tips

Conclusion

Full source code

Kotlin’s Flow in ViewModels: it’s complicated (LiveData is still your friend)

Goals of efficiency

Today: ViewModel and LiveData

LiveData + Coroutines

Introducing Kotlin’s Flow

StateFlow and LiveData have a lot in common:

But they also have important differences:

Observing LiveData vs Collecting Flow

Replacing LiveData with StateFlow in ViewModels

Using StateFlow as trigger in a ViewModel

The naive approach

Preventing re-emission of the latest trigger value

Conclusion

Fixing RecyclerView nested scrolling in opposite direction

The problem

Introducing ViewPager2

The cause

The solution

Conclusion

A study of the Parcelize feature from Kotlin Android Extensions

Project setup

For Kotlin 1.3.60 to 1.4.10

Since Kotlin 1.4.20

Usage

Analyzing the generated code

Basic types

Nullable types

Nested Parcelables

Enum classes

Bonus feature: make enum classes implement Parcelable

Collections

Custom types serializers

Handling nullable custom types

Handling generic custom types

Accessing generated CREATOR fields from Kotlin code

Dealing with class inheritance

Parcelable abstract and sealed classes with common fields

Objects with a parent class

Excluding properties from serialization

Advanced JSON parsing techniques using Moshi and Kotlin

The importance of using the right `TimeSource`

Injecting an Android `Lifecycle` in the ViewModel ?

Introducing the `flowWhileShared()` operator

Usage with `SharedFlow` or `StateFlow`

Observing `LiveData` vs Collecting `Flow`

Replacing `LiveData` with `StateFlow` in ViewModels

Using `StateFlow` as trigger in a ViewModel

Bonus feature: make enum classes implement `Parcelable`

Introducing `selectName()` for performance

1. Observing in `onCreate()`

2. Manually unsubscribing the observer in `onDestroyView()`

2. A creator for `Creator`s

The fix: `@SafeVarargs`