Blog

Kotlin SharedFlow or: How I learned to stop using RxJava and love the Flow

Thu, 29 Apr 2021 07:39:31 Z

Coroutines are great. Period. When they were introduced along with Kotlin 1.3 we immediately knew that they were going to be a game changer. And they are indeed. Easy to learn. Easy to understand. And so easy to use. When coroutines 1.0.0 were released, many anticipated that it would be the end for RxJava on Android.

It turned out that despite coroutines being great, RxJava was still being picked for many new projects. Why? Probably one of the reasons was that it was well known, sure. But there was also a more important reason: coroutines still couldn’t be used in some use cases where RxJava could.

RxJava is not only `Single`

In the majority of the apps RxJava was used mostly for API requests handling. We all know that – make a REST API call with Retrofit, return RxJava Single, apply proper schedulers, and then map the response. In this scenario, coroutines are a great fit. We just need to change our endpoint methods to suspending ones, and we’re more or less ready to go. But of course, RxJava is much more than that, right? The real strength of reactive programming is processing of ongoing data streams.

Example 1: we have a few-step data upload process in the app (done in a background thread), and the update at each step should cause real-time update of the UI. Seems like a great case for good old Observable and its onNext(). This scenario could not be handled with plain coroutines, as suspend functions can return only a single value. So we lacked a proper tool. It all changed with the introduction of coroutines 1.2.0, when we were given Kotlin Flow. A mighty Kotlin Flow that handled (almost) all cases that previously could be handled only with RxJava, and what’s the most important – it was handling them using coroutines.

If you have any experience with both RxJava and coroutines, switching to Flows should be really seamless, as their syntax and logic is using both aforementioned concepts. Let’s see the example code for Example1.

Using RxJava:

fun uploadData(): Observable<UpdateStep> = Observable.create<UpdateStep> {
    it.onNext(UpdateStep.Step1)
    doUpdateStep1()
    it.onNext(UpdateStep.Step2)
    doUpdateStep2()
    it.onNext(UpdateStep.Step3)
    doUpdateStep3()
    it.onNext(UpdateStep.Success)
}.onErrorReturn {
    UpdateStep.Error(it)
}

And using Flow:

fun uploadData(): Flow<UpdateStep> = flow {
    emit(UpdateStep.Step1)
    doUpdateStep1()
    emit(UpdateStep.Step2)
    doUpdateStep2()
    emit(UpdateStep.Step3)
    doUpdateStep3()
    emit(UpdateStep.Success)
}.catch {
    emit(UpdateStep.Error(it))
}

Now we just need to subscribe() our Observable or collect() our Flow, and we’ve got all we need. Easy peasy. This way coroutines made another step to replace RxJava. However, that wasn’t the last step.

You’re hot then you’re cold

For anyone working with RxJava a bit more extensively, the concept of cold/hot streams is well known. Streams created by Observable.create() or Flowable.just() are cold, which means that they start executing the code and emitting values only when something subscribes to them. This is the case that can be also handled using flow{} or flowOf() - flows created with these methods are called cold flows (no surprise here).

The last big RxJava use case that coroutines were still missing was handling hot flows. In reactive programming hot streams are the ones that don’t have to be observed by anything to emit values. This makes them a perfect candidate eg. for handling BLE connection state - app knows about connection state changes at all times, and informs observers if there are any, or as soon as they arrive (Example 2). Hot streams in RxJava can be created using eg. PublishSubject and BehaviorSubject. Here is how we can use them to implement Example2:

class BleManager : BleConnectionObserver {
    private val _bleConnectionStateSubject = BehaviorSubject.createDefault(ConnectionState.Disconnected)
    val bleConnectionStateObservable: Observable<ConnectionState> = _bleConnectionStateSubject.hide()
    val currentConnectionState: ConnectionState
        get() = _bleConnectionStateSubject.value

    override fun onDeviceConnected(device: BluetoothDevice) {
        /* ... */
        _bleConnectionStateSubject.onNext(ConnectionState.Connected)
    }

    override fun onDeviceDisconnected() {
        /* ... */
        _bleConnectionStateSubject.onNext(ConnectionState.Disconnected)
    }
}

For a long time, this part of functionality was missing in stable coroutines API, and that changed with the release of coroutines 1.4.0 in October 2020. But let’s take a step back. Even before Kotlin Flow was released, we heard of a concept called channels. It was designed to solve the Producer-Consumer problem - of course using coroutines. Channel interface, which is offering suspendable send() and receive() methods, seemed to be quite straightforward but in reality is a bit more complex.

It is using independent coroutines on both sides of the communication that introduces concurrency which has to be handled by us, and may lead to some issues with concurrent access to the same resources. It also wasn’t helpful that channels API was still not fully stable – there were (and still are) many experimental/preview methods there. Lucky for us, the Kotlin team came up with a concept of SharedFlow and StateFlow that doesn’t mess with multiple coroutines and makes our data flow much cleaner. If you want to read more about channels-flow relation, take a look at this great article by Roman Elizarov.

Now to the best part. SharedFlow is an equivalent of RxJava’s PublishSubject. It allows us to create hot flows and specify strategies for handling backpressure and replay. StateFlow is a special case of SharedFlow which is an equivalent of RxJava’s BehaviorSubject. It creates a hot flow that persists its latest value – which makes it a perfect candidate for handling BLE connection state from Example2.

class BleManager : BleConnectionObserver {
    private val _bleConnectionStateFlow = MutableStateFlow(ConnectionState.Disconnected)
    val bleConnectionStateFlow: StateFlow<ConnectionState> = _bleConnectionStateFlow

    override fun onDeviceConnected(device: BluetoothDevice) {
        /* ... */
        _bleConnectionStateFlow.value = ConnectionState.Connected
    }

    override fun onDeviceDisconnected() {
        /* ... */
        _bleConnectionStateFlow.value = ConnectionState.Disconnected
    }
}

It’s worth noticing that both Shared and State flows can be used in mutable form and be exposed as immutables – this concept is well known for anyone using LiveData. In RxJava we had to hide BehaviorSubject behind plain Observable and expose current state separately. With flows, the immutable form of StateFlow still allows us to get its latest value.

To use SharedFlow and StateFlow correctly we need to remember a few things:

▸ StateFlow is conflated, which means that if we update its value with a new value that is equal to the previous one, the update will not be propagated.

▸ SharedFlow needs to have a proper replay/buffer configuration. In most cases, we just need to make sure that our producer will not get suspended if there’s no consumer, eg. by setting replay or buffer capacity to a positive value or setting bufferOverflow to something else than SUSPEND.

▸ StateFlow and SharedFlow will never complete, so you cannot depend on their onCompletionCallback, and need to remember that collecting them will never finish normally (neither will the coroutine in which we called their collect).

Ok, cool, but do we even need that?

For me, SharedFlow and StateFlow were real game changers, and only when they were introduced I decided that I can fully quit using RxJava. What is more, recently StateFlow also received alpha support for working with data binding. And what is great is that using StateFlow in data binding is lifecycle aware – just like LiveData! No more updating UI when it’s not ready ❤️ However, you need to remember that collecting SharedFlow in the Fragment using lifecycleScope.launch{} is not lifecycle aware – you need to use launchWhenStarted or cancel the job when the app goes to background. This topic has been well discussed in this article.

Some of you may say: “Why do we even need SharedFlow? Most of the described use cases can be handled with LiveData!”. And then I’ll ask: “Have you ever heard of clean architecture?" 😉 Sure, when you need to observe changes from ViewModel in the Fragment, LiveData is absolutely enough, but sometimes you need to observe events in different modules, or in general – somewhere behind the abstraction layer. And LiveData unfortunately won’t work in this case because it is an Android class, and our domain module (or in general - base abstraction layer) should be pure Kotlin.

This is where SharedFlow purely shines, because it is a Kotlin class. We can expose it from our database or API without tight coupling our domain code to Android classes. Sounds like a really nice approach 😀 What is more, it seems that SharedFlow can be used as an alternative solution for the SingleLiveEvent problem that needs a special approach when using LiveData.

I’ve been using SharedFlow and StateFlow in my latest project for about 7 months now, and they’re really fun to use!

Have you already tried SharedFlow or StateFlow? What are your thoughts about them? I know that I finally can stop using RxJava and just love the Flow 😀

About the Author
Aleksandra Krzemień has profound experience in building all sorts of mobile apps, including those connected with external devices. She is a natural mentor and loves to share her knowledge. Throughout her career, she has been actively engaged in many mentoring programs and IT-related organizations, such as Women in Technology or Google Developers Group. She likes to spend her free time singing and playing board games.

MotionLayout + Android Studio 4.0 = ❤

Fri, 15 Nov 2019 14:21:28 Z

MotionLayout is out there since the release of constraint-layout:2.0.0-alpha1 (June 2018), and it has already caused quite a stir. When we first saw the example animations that can be done pretty easily using it, we were pretty impressed. However, as it turned out, using MotionLayout was time- and work-consuming, because there was a lot of code to write, and in order to test it we had to run our app on the device each time.

These times are over!

As for constraint-layout:2.0.0-beta3 and Android Studio 4.0 Canary1 we can edit MotionLayout in the graphic design tool, and what’s even better, we can preview the effects of our work right in the Android Studio, with no need to run the app on the device ❤

That sounds really awesome. Now, let’s see how it works.

A simple MotionLayout with changing position, color, rotation, and size of the view.

MotionLayout

At the beginning, just a few words about the MotionLayout itself.

MotionLayout class extends ConstraintLayout. That means you can seamlessly convert the latter to the first, and without any changes, it should work pretty much the same. That is really nice, because it enables us to experiment with MotionLayout, starting with any existing ConstraintLayout.

<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <View
        android:id="@+id/sky"
        android:layout_width="0dp"
        android:layout_height="0dp"
        android:background="@color/sky_morning"
        app:layout_constraintBottom_toTopOf="@id/guideline"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

    <View
        android:id="@+id/ground"
        android:layout_width="0dp"
        android:layout_height="0dp"
        android:background="@color/ground"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@id/guideline" />

    <androidx.constraintlayout.widget.Guideline
        android:id="@+id/guideline"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:orientation="horizontal"
        app:layout_constraintGuide_percent="0.5" />

    <ImageView
        android:id="@+id/biker"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:contentDescription="@string/biker"
        android:src="@drawable/ic_bike"
        app:layout_constraintBottom_toBottomOf="@id/guideline"
        app:layout_constraintTop_toTopOf="@id/guideline" />

</androidx.constraintlayout.widget.ConstraintLayout>

Above: just a simple constraint layout that will be our starting point.

The real magic of MotionLayout lays in the MotionScene resource file, which contains all the constraints and attributes transitions that result in our layout animation.

<?xml version="1.0" encoding="utf-8"?>
<MotionScene 
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:motion="http://schemas.android.com/apk/res-auto">

    <Transition
        motion:constraintSetEnd="@+id/end"
        motion:constraintSetStart="@id/start"
        motion:duration="1000">
       <KeyFrameSet>
       </KeyFrameSet>
    </Transition>

    <ConstraintSet android:id="@+id/start">
    </ConstraintSet>

    <ConstraintSet android:id="@+id/end">
    </ConstraintSet>
</MotionScene>

Above: an empty MotionScene file.

Each Transition has to have a start and end ConstraintSet, and a number of KeyFrames that enables us to achieve various interesting effects. You should remember, that constraints set in the MotionScene always take precedence over these declared in the MotionLayout file.

If you want to know more about the MotionLayout itself, there is a great series of articles on the Google Developers Medium.

To use all the discussed below features you need to add a dependency to your build.gradle file.

dependencies {
    implementation 'androidx.constraintlayout:constraintlayout:2.0.0-beta3'
}

MotionEditor

Ok, so now that we know what MotionLayout is, let’s see what Android Studio 4.0 can do to make our work with it more enjoyable.

First of all, in the layout design panel there is a tool to automatically convert our selected ConstraintLayout to the MotionLayout.

What it really does is changing the root layout to MotionLayout, creating a new MotionScene xml file in the resources/xml package and setting the app:layoutDescription attribute of the new layout to the motion scene file. That’s it. But is also redirects us to the brand new MotionEditor view.

There you can see a preview of our MotionLayout on the left, a panel with all the transitions and constraint sets in the middle, and attributes panel on the right.

One thing to remember is that you can navigate between code, design, and split the screen using the three buttons on the top right corner of the view (not on the bottom left as it was before).

Now, by navigating between the start and end states in the middle panel, we are able to add/change views constraints and attributes. E.g. we want the color of the sky to change from light to dark. All we need to do is to choose start state, click on sky entry and add a new Custom Attribute (there is an autocomplete in the attributes popups ☺). Then repeat it for the end state.

MotionLayout will do the rest for us, and we get a nice simple sky animation.

In a similar way, but by changing the start and end constraints of the biker image, we are able to create a changing position animation.

By clicking on the grey arrow between the states, you open the Transition panel where you can play the current motion animation.

To make it work on the device we need to start the motion somehow. We can either start/set the progress in code, or add an OnSwipe/OnClick MotionObject. In this example, we choose the second option, and by clicking the third button on top of the motion panel we add a SwipeHandler with an anchor at the biker.

Now let’s add some sunshine to our animation ☺

We add the sun image, and want it to move above the biker, but on the arc, so simply changing the constrains won’t be sufficient. We need to add also a KeyFrame. We can do it by choosing KeyPosition from the Transition panel, and setting the percentY position in a 50th frame (frames go from 0 to 100) to a negative value, and type do pathRelative.

Now our animation starts to gain some life.

In a similar way, but using KeyAttribute we can modify things like scale, rotation or alpha of our view.

Let’s get nuts and add all of the above attributes! Making the sun do a 360 degrees rotation during the animation, scaling to 1.5 in the middle, and vanishing after the 60th frame.

When we add a moon image with the same path as the sun image, and with alpha increasing after 60th, we’ll get a really nice transition.

Here, I added also a backgroundColor frame for sky at the 60th frame.

Now you can use your imagination and add other views to the animation. Will you be able to recreate the one from below? ☺

This kind of animation is a great example of how MotionLayout can be mixed with a ViewPager for creating a really nice custom experience.

You can find the complete code of the example HERE.

It is also worth to mention that if you have a MotionLayout written with an older constraint-layout version and older Android Studio, you can still use it with the Android Studio 4.0, and MotionEditor will work just fine, no changes need to be done ✔

Problems

The tools that Android Studio 4.0 gives us to work with the MotionLayout are great, however we must remember that neither of them is stable yet, and definitely not production-ready. There still can occur some random crashes and other errors.

Here are some problems I encountered while playing with the above example:
• modifying constraints can sometimes cause big lags
• there must be no errors or warnings (!) in your xml code for MotionEditor to work
• ‘showPaths’ option does not work when there are many views in the layout
• MotionEditor does not work for your custom classes extending MotionLayout

Conclusion

Now it’s time for your own experiments. MotionLayout gives us great abilities to create beautiful and meaningful animations. There are many other features that I haven’t discussed here, like multiple transitions in a single MotionScene, creating custom attributes, using MotionLayout progress, KeyCycles, or motion easing.

The best place to start your adventure is definitely the documentation page, where you can find many examples.

If you have any questions regarding the article, or want to share your MotionLayout animations, feel free to leave a comment!

Couchbase Lite Android migration from 1.4 to 2.x

Thu, 23 May 2019 07:12:52 Z

Couchbase Lite is out there for a while, but recently, with an update to version 2.0, it went through a big redesign. In this article, we’d like to point out some differences between versions 1.4 and 2.0, and help you with migrating your code.

[Note: this article does not cover migrating your data replication code.]

All examples you’ll see in this article are based on the official sample Android Couchbase Lite Todo app.

Internal database format

Couchbase Lite is a document database that stores data in JSON documents, however internally it uses an SQLite database. We will look into this database a few times in this article. The first two tables we’re interested in are docs and revs. The first one contains a list of all documents internal ids, and the ids you gave them:

The second table contains info about all documents current revisions:

Up to version 1.4 Couchbase Lite was using a map-reduce approach, which bases on creating views (which work more or less like SQL indexes). It requires you to create a map (and optional reduce) function, which given a JSON document input emits a number of key-value pairs to be indexed in the view. In code it would look like this:

val view = db.getView("list/listByName")
view.setMap({ document, emitter ->
               if (document["type"] == "task-list") {
                   emitter.emit(document["name"], null)
               }
           }, "1")

Executing this code will result in inserting a new row in the internal database in views table:

and creating a new table maps_1 which will include all emitted values. In this case:

A new table maps_x will be created for every view.

The first thing that changed in 2.0 version is the format of the internal SQLite database. Now the table we’re interested in is named kv_default.

It contains all the info about the documents, but JSON body is stored in a binary form, so we’re no longer able to read it! The only way to read the data is to use an official cblite tool. More info about the new db schema can be found here.

The important thing is that if in your app you have a database in version 1.4, when you update the library version in your code, your database will be automatically updated to the new format on the first open.

Database creation

After changing your gradle dependency from implementation "com.couchbase.lite:couchbase-lite-android:1.4.*" to implementation "com.couchbase.lite:couchbase-lite-android:2.0.0" and compiling the project, your code will light up with dozens of error messages. Let’s try to fix some of them step by step.

First things first. In 1.4 to create and open your database you probably used code like this:

val manager = Manager(AndroidContext(context.applicationContext), Manager.DEFAULT_OPTIONS)
database = manager.getExistingDatabase("dbName")
if (database == null) {
   ZipUtils.unzip(context.assets.open("dbName.zip"), context.filesDir)
   database = manager.getDatabase("dbName")
}

If you needed to have a preloaded database, you stored it in a zip file in assets and then unzipped it using ZipUtils, which was a utility class from the couchbase-lite library. Now you need to change it to

val config = DatabaseConfiguration(context.applicationContext)
if (!Database.exists("dbName", context.filesDir)) {
   ZipUtils.unzip(context.assets.open("dbName.zip"), context.filesDir)
}
database = Database("dbName", config)

and remember that ZipUtils class is no longer included in the library, so you need to write your own (or copy the old implementation from here).

CRUD operations

As in the 2.0 version Couchbase Lite changed data manipulation approach from map-reduce to N1QL-based Query API, the CRUD operations changed a lot. Say goodbye to getView() methods, and say hello to QueryBuilder.

Creating a single document didn’t change that much. From

val docId = username + "." + UUID.randomUUID()
val data = mapOf("type" to "task-list", "name" to title, "owner" to username)
val document = Document(db, docId)
document.putProperties(data)

we get to

val docId = username + "." + UUID.randomUUID()
val data = mapOf("type" to "task-list", "name" to title, "owner" to username)
val mDoc = MutableDocument(docId, data)
db.save(mDoc)

Updating existing document looks pretty much the same. You just need to set an existing document id. To create a MutableDocument from Document just call document.toMutable().

Reading a single document also looks the same

val document = db.getDocument(mDoc.id)

but to get the properties from the document instead of calling document.properties you need to call document.toMap().

Deleting a single document goes from

document.delete() or document.purge()

db.delete(document) or db.purge()

The real fun begins when we need to create a query to the database. Instead of calling db.getView(viewName).createQuery(), we build our query step by step using QueryBuilder.

Before:

val query = db.getView("list/listByName").createQuery() 
query.isDescending = false
query.limit = limit

query.run().forEach { result ->
   val doc = result.document /* we can get document or properties */
   /* mapping and other stuff */
}

After:

val query = QueryBuilder.select(SelectResult.expression(Meta.id),
                               SelectResult.all())
       .from(DataSource.database(db))
       .where(Expression.property("type").equalTo(Expression.string("task-list")))
       .orderBy(Ordering.property("name").ascending())
       .limit(Expression.intValue(limit))


query.execute().forEach { result ->
   val properties = result.toMap() /* we cannot access the document itself */
   /* mapping and other stuff */
}

This may seem longer at first sight, but remember that in the first example we omitted creating the view.

The semantics of the query builder is really easy to understand, as it reminds good old SQL SELECT * FROM table_name WHERE id=id_number ORDER BY name ASC LIMIT limit.

However, there are a few things that need to be pointed out.

In select() method you’d probably use mostly these three expressions:

• SelectResult.expression(Meta.id) - which will result in returning document id (key from the database, not the id inside your JSON, if you have one) under the name id.

• SelectResult.all() - which will result in returning entire JSON document in a form of a Dictionary under the name of your database.

• SelectResult.property("name") - which will result in returning a property name from your JSON document.

Of course you can build more complex expressions using comparators like Expression.greaterThan() or functions like Function.count() etc.

Where expressions can be chained using operators like Expression.and() or Expression.or(). You can also chain QueryBuilder with join() or groupBy() components.

For example, the above query will result in a structure like this:

[
  {
         "id": "todo.123",
         "todo": {
               "name": "Groceries",
               "owner": "todo",
               "type": "task-list"
         }
  }
]

One more confusing thing is how Couchbase Lite handles numbers now. If you want to maintain a Double field, it can be serialized (and as a result deserialized) to different data types. If the decimal part is zero, it will be deserialized as Long. If a number fits in the Float type, it will be deserialized asFloat. Therefore, if you need a Double, it would be best to read it from the document map as Number and then call toDouble().

You also should note that there are no more options to run multiple operations in the transaction. Instead, you can use db.inBatch() - although it works a bit differently.

The last thing you need to take into account is that for today (May 2019) Couchbase Lite versions 2.x do not support devices with architecture x86_64. That means they won’t work on these devices, but it also means that you will not be able to write a unit test using eg. Robolectric to test your db code. Instrumentation test, however, will work fine.

Now, hopefully, you will be able to migrate your database and CRUD operations from Couchbase Lite 1.4 to 2.0. For other examples and features you can look in the official documentation and dive into some official tutorials.