DEV Community: Márton Braun

The conflation problem of testing StateFlows

Márton Braun — Tue, 15 Aug 2023 15:10:58 +0000

StateFlow has a bit of a wave–particle duality. On one hand, it's a data holder which holds a current value. On the other hand, it's also a Flow, emitting the values it holds over time to its collectors. Importantly, as the type's documentation states:

Updates to the value are always conflated. So a slow collector skips fast updates, but always collects the most recently emitted value.

This conflation means that depending on how "fast" the code setting values in the StateFlow and the code collecting values from it are relative to each other, the collector may or may not receive intermediate values when the StateFlow's value is rapidly updated multiple times.

In production code, this generally shouldn't cause any issues. The collector should not be affected by conflation happening or not happening. The end result - for example, what's displayed on the UI - should remain the same. Testing, however, is a different story.

Testing StateFlows

There are two approaches for testing a StateFlow: you can either make assertions on its value property, or collect it as a Flow and assert on the values collected.

This article assumes that you're familiar with coroutine testing using the kotlinx-coroutines-test library.

Generally speaking, it's simpler to treat StateFlow as a state holder and make assertions on its value after performing actions in the test, as described in the Android documentation about testing StateFlows.

However, there might be cases where this is not feasible to do, and you need to collect from a StateFlow in a test. For example, a single action on a class under test may trigger multiple value writes on the StateFlow, and you may want to assert on all intermediate values written (instead of just asserting on value once, after the last write).

A typical case of this is testing a ViewModel function that first triggers a loading state and then replaces that with actual data (oversimplified pseudocode!):

class MyViewModel(private val repo: Repo) : ViewModel() {
    val state: MutableStateFlow<MyState> = MutableStateFlow(Initial)

    fun initialize() {
        state.value = Loading
        state.value = Content(repo.getData())
    }
}

In this specific example, you might be able to write a test which only reads the value property of the StateFlow, by injecting a fake repository implementation that lets us control when getData returns, giving us a chance to read state.value while it's still in the loading state. However, it's often not possible or too cumbersome to control the object under test this way.

Experiencing conflation

If you choose to test a StateFlow by collecting it, you'll need to take conflation into account. When writing a test asserting on values collected from a StateFlow, you have to decide whether you expect to see all values without conflation, or to experience conflation and only see the most recent value after rapid updates.

Let's see what happens if you start two coroutines in a test using runTest, one collecting from the StateFlow and another setting values in it. In this case, they'll be equally "fast", as they'll both inherit the StandardTestDispatcher from runTest.

We'll call the first coroutine the collecting coroutine, and the second coroutine the producing coroutine.

@Test
fun useStandardTestDispatcherForCollection() = runTest {
    val stateFlow = MutableStateFlow(0)

    // Collecting coroutine
    launch {
        val values = stateFlow.take(2).toList()
        assertEquals(listOf(0, 3), values) // Conflation happened
    }

    // Producing coroutine
    launch {
        stateFlow.value = 1
        stateFlow.value = 2
        stateFlow.value = 3
    }
}

As they are launched on a StandardTestDispatcher, both coroutines here will first be queued up on the test scheduler. When runTest reaches the end of the lambda passed to it, it will start executing the tasks queued up on the scheduler.

This starts the collecting coroutine first, which begins collecting the StateFlow. The StateFlow immediately emits its initial value, which is collected into the list. The collecting coroutine then suspends as toList waits for new values.

This lets the second coroutine start, which sets the value of the StateFlow several times. Setting the value property of StateFlow is a regular property assignment, which is not a suspending call, however its implementation does resume any collecting coroutines.

Though the collector is resumed, it's on a StandardTestDispatcher and still needs a chance to dispatch in order to run its code, which it doesn't get until the test thread is yielded. That only happens on the completion of the producing coroutine, after all three value writes are done.

With the completion of the producing coroutine, the collector gets to execute, and receives only the latest value, which it places in the list. Conflation happened.

Avoiding conflation

Let's see what you can do if you want to avoid conflation in our tests.

Note that conflation is not inherently bad. However, it's often undesirable in testing scenarios that want to verify all the behaviour of an object.

Yielding manually

For a simple approach, if you let go of the test thread after each value assignment - for example, using a simple yield() call - the collecting coroutine gets a chance to dispatch, and receives all four values, eliminating conflation:

@Test
fun yieldingExample() = runTest {
    val stateFlow = MutableStateFlow(0)

    launch {
        val values = stateFlow.take(4).toList()
        assertEquals(listOf(0, 1, 2, 3), values) // No conflation
    }

    launch {
        stateFlow.value = 1
        yield()
        stateFlow.value = 2
        yield()
        stateFlow.value = 3
    }
}

This doesn't scale very well, as it requires explicitly yielding the thread every time a new value is set in the StateFlow.

To make things worse, in a real test this likely happens somewhere in code that's called from the test, and not within the test itself. Modifying the scheduling behaviour of production code to make testing more convenient isn't great.

Collecting faster

Alternatively, you can change how "fast" the collecting coroutine is, so that it can better keep up with new values being produced. In the next example, the collecting coroutine is created using an eager UnconfinedTestDispatcher while the producing coroutine keeps using the lazier StandardTestDispatcher.

For an explanation of the scheduling of these two dispatchers, see the Android docs on TestDispatchers.

@Test
fun useUnconfinedTestDispatcherForCollection() = runTest {
    val stateFlow = MutableStateFlow(0)

    launch(UnconfinedTestDispatcher(testScheduler)) {
        val values = stateFlow.take(4).toList()
        assertEquals(listOf(0, 1, 2, 3), values) // No conflation
    }

    launch {
        stateFlow.value = 1
        stateFlow.value = 2
        stateFlow.value = 3
    }
}

In this test, collection happens immediately whenever the assignment of value resumes the collecting coroutine, thanks to UnconfinedTestDispatcher which doesn't require a dispatch before resuming execution. Conflation is gone!

Using UnconfinedTestDispatcher for the collecting coroutine also has the added benefit that the collecting coroutine is launched eagerly. This means that by the time the first launch call of the test returns the first coroutine has already started executing, collected the initial value of the StateFlow, and is suspended waiting for new values to be produced.

Using the Turbine library instead of collecting from the Flow yourself behaves the exact same way, as Turbine's test function also uses UnconfinedTestDispatcher under the hood if you're using it with runTest.

@Test
fun useTurbineForCollection() = runTest {
    val stateFlow = MutableStateFlow(0)

    launch {
        stateFlow.test { // No conflation
            assertEquals(0, awaitItem())
            assertEquals(1, awaitItem())
            assertEquals(2, awaitItem())
            assertEquals(3, awaitItem())
        }
    }

    launch {
        stateFlow.value = 1
        stateFlow.value = 2
        stateFlow.value = 3
    }
}

Note that your collecting coroutine can only go faster if the producing coroutine is on a "slow" StandardTestDispatcher. If the producing coroutine runs on an UnconfinedTestDispatcher and does not yield the thread at any point, conflation makes a comeback, and you have no chance of seeing those intermediate values.

Here's an example demonstrating just that:

@Test
fun useUnconfinedTestDispatcherForCollectionAndProduction() = runTest {
    val stateFlow = MutableStateFlow(0)

    launch(UnconfinedTestDispatcher(testScheduler)) {
        val values = stateFlow.take(2).toList()
        assertEquals(listOf(0, 3), values) // Conflation happened
    }

    launch(UnconfinedTestDispatcher(testScheduler)) {
        stateFlow.value = 1
        stateFlow.value = 2
        stateFlow.value = 3
    }
}

Conclusion

When testing a StateFlow, you have two options: reading its value at various points during the test or collecting it as a Flow. The former is the easier path if your circumstances allow it. Otherwise, you'll have to keep in mind that collectors of a StateFlow are affected by conflation.

It's up to you to decide whether you want values to be conflated or not during a test, and set up assertions accordingly. You can control whether conflation can happen by choosing the dispatchers your code executes on during tests. Using injected dispatchers that you can replace with appropriate TestDispatcher instances during tests is crucial for this.

Finally, the only way your collecting coroutine can be "faster" than the producing coroutine and avoid conflation is if the collector is on an UnconfinedTestDispatcher while the producer is on a StandardTestDispatcher. Other cases—where the coroutines are equally fast or the collector is slower—will result in conflation.

Adventures in Tracking Upload Progress With OkHttp and Retrofit

Márton Braun — Fri, 10 Dec 2021 19:19:09 +0000

This article tells the story of how Stream’s Android team refined our progress tracking process during file uploads in the Stream Chat Android SDK.

Our original implementation to track file upload progress worked, but it had some in-code usability and UX issues that we wanted to clean up.

The following account gives an up-close look into the process we had, the problems we encountered, and what we did to improve.

Warning: As this is a story of mistakes we made and then corrected over time, do not use any of the initial or intermediate forms of code here in your own projects, only the final fixed version. 😉

Uploading Files With Retrofit

First things first, let's see how you can upload a file to an API using Retrofit. Most APIs will expect a multipart form to contain the file data. You can declare a method inside a Retrofit interface like the one below to support that operation:

@Multipart
@POST("/channels/{type}/{id}/file")
fun sendFile(
    @Path("type") channelType: String,
    @Path("id") channelId: String,
    @Part file: MultipartBody.Part,
): RetrofitCall<UploadFileResponse>

To invoke this method, you can create a Part by using the createFormData function, like so:

fun sendFile(file: File) {
    val part = MultipartBody.Part.createFormData("file", file.name,
                   file.asRequestBody(file.getMediaType()))
    retrofitCdnApi
        .sendFile(channelType, channelId, part)
        .enqueue(...)
}

Then you just enqueue the Retrofit Call to run it, and done! That's a basic, working file upload.

Counting in the Request Body

Time to add progress tracking. For our initial implementation, we used this callback interface:

public interface ProgressCallback {
    public fun onProgress(progress: Long)
    public fun onSuccess(file: String)
    public fun onError(error: ChatError)
}

We then created a ProgressRequestBody class, most likely based on this StackOverflow answer.

This wraps a file and a callback, and implements the OkHttp RequestBody class.

internal class ProgressRequestBody(
    private val file: File,
    private val callback: ProgressCallback
) : RequestBody() {
    override fun contentType(): MediaType = file.getMediaType()

    override fun contentLength(): Long = file.length()

    override fun writeTo(sink: BufferedSink) {
        val total = file.length()
        val buffer = ByteArray(DEFAULT_BUFFER_SIZE)
        var uploaded = 0L
        FileInputStream(file).use { fis ->
            var read: Int
            val handler = Handler(Looper.getMainLooper())
            while (fis.read(buffer).also { read = it } != -1) {
                handler.post {
                    callback.onProgress((100 * uploaded / total))
                }
                uploaded += read.toLong()
                sink.write(buffer, 0, read)
            }
        }
    }

    companion object {
        private const val DEFAULT_BUFFER_SIZE = 2048
    }
}

Whenever writeTo is invoked to write this RequestBody to the network, we loop through the contents of the file manually, write the bytes, and invoke the callback, calculating the percentage of the upload completed so far.

This requires a modification to our API invocation, as we now have to create a ProgressRequestBody that we then embed in our Part, which will — remember this — contain the ProgressCallback instance that was passed in.

fun sendFile(file: File, callback: ProgressCallback) {
    val progressBody = ProgressRequestBody(file, callback)
    val part = MultipartBody.Part.createFormData("file", file.name, progressBody)

    retrofitCdnApi
        .sendFile(channelType, channelId, part)
        .enqueue(RetroProgressCallback(callback))
}

We also pass the callback to the enqueue call via a wrapper to adapt it to a Retrofit Callback, which will run the onFailure and onSuccess methods of our original callback as needed.

internal class RetroProgressCallback(
    private val callback: ProgressCallback
) : Callback<UploadFileResponse> {
    override fun onFailure(call: Call<UploadFileResponse>, t: Throwable) {
        callback.onError(ChatError(cause = t))
    }

    override fun onResponse(
        call: Call<UploadFileResponse>,
        response: retrofit2.Response<UploadFileResponse>
    ) {
        val body = response.body()
        if (body == null) {
            onFailure(call, RuntimeException("File response is null"))
        } else {
            callback.onSuccess(body.file)
        }
    }
}

If you want to explore this implementation, you can find the old version of our code here in the GitHub history.

Counting With a Custom Sink Implementation

This is okay, but we can make it a lot nicer. For this change, we essentially took the implementation from Paulina Sadowska's post about the topic.

The improvement is to (instead of handling a FileInputStream manually) create a custom OkHttp Sink implementation (based on the handy ForwardingSink), which will perform the counting and corresponding progress callbacks for us.

We'll also make ProgressRequestBody wrap a RequestBody and delegate to it whenever it needs to behave like a RequestBody.

internal class ProgressRequestBody(
    private val delegate: RequestBody,
    private val callback: ProgressCallback,
) : RequestBody() {
    override fun contentType(): MediaType? = delegate.contentType()
    override fun contentLength(): Long = delegate.contentLength()

    override fun writeTo(sink: BufferedSink) {
        val countingSink = CountingSink(sink).buffer()
        delegate.writeTo(countingSink)
        countingSink.flush()
    }

    private inner class CountingSink(delegate: Sink) : ForwardingSink(delegate) {
        private val handler = Handler(Looper.getMainLooper())
        private val total = contentLength()
        private var uploaded = 0L

        override fun write(source: Buffer, byteCount: Long) {
            super.write(source, byteCount)
            uploaded += byteCount

                        handler.post { callback.onProgress(uploaded, total) }
        }
    }
}

For this improvement, we've updated our ProgressCallback interface to take the more meaningful bytesUploaded and totalBytes values during progress updates instead of a percentage.

(We also added KDoc at this point to make the interface more obvious, which you can check out in the GitHub repo.)

public interface ProgressCallback {
    public fun onProgress(bytesUploaded: Long, totalBytes: Long)
    public fun onSuccess(url: String?)
    public fun onError(error: ChatError)
}

On the call site, we can now create a simple RequestBody first, and then wrap it with the ProgressRequestBody implementation:

val body = file.asRequestBody(file.getMediaType())
val progressBody = ProgressRequestBody(body, callback)
val part = MultipartBody.Part.createFormData("file", file.name, progressBody)

The Logging Problem

A major problem we encountered was that we had several interceptors added to the OkHttpClient that we used for these uploads. The configuration looked something like this:

baseClientBuilder()
    .connectTimeout(timeout, TimeUnit.MILLISECONDS)
    .writeTimeout(timeout, TimeUnit.MILLISECONDS)
    .readTimeout(timeout, TimeUnit.MILLISECONDS)
    .addInterceptor(ApiKeyInterceptor(...))
    .addInterceptor(HeadersInterceptor(...))
    .addInterceptor(TokenAuthInterceptor(...))
    .addInterceptor(HttpLoggingInterceptor())
    .addInterceptor(
         CurlInterceptor { message ->
             logger().logI("CURL", message)
         }
    )

This is natural, and lots of apps have setups like this. What's notable here is that HttpLoggingInterceptor and CurlInterceptor will both log the request and call requestBody.writeTo() internally to do that.

In the case of our file upload calls, this method is what contains our progress tracking implementation.

The end result is that whenever we make an upload call, we'll run the progress callback three times in a row: twice for the logging, and once when it's actually written to the network.

This results in an... interesting experience for the user looking at the UI, where progress goes something like this:

0 15 45 50 100 0 25 37 57 87 100 0 20 67 100

This only happened in debug builds, as we had the logging disabled in release builds, but it was still a problem.

Fixing this wasn't simple, as we wanted to keep these logging interceptors around. After some elaboration, we begrudgingly added an ugly, ugly workaround, like this:

internal class ProgressRequestBody(
    private val delegate: RequestBody, ...
) : RequestBody() {

    var writeCount = 0

    override fun writeTo(sink: BufferedSink) {
        if (writeCount >= progressUpdatesToSkip) {
            val countingSink = CountingSink(sink).buffer()
            delegate.writeTo(countingSink)
            countingSink.flush()
        } else {
            delegate.writeTo(sink)
        }

        writeCount++
    }

    companion object {
        private val progressUpdatesToSkip = 2
    }
}

As you can see, we simply hardcoded that the first two times when the ProgressRequestBody is written, it shouldn't invoke callbacks.

What made this worse is that this value wasn't actually 2 like I assumed, because as mentioned above, we only log with these interceptors in debug builds.

This meant that we had to make this a var and set it dynamically. In release builds it'd be 0, and in debug builds, we'd increment it to 2. Ouch.

That's bad enough, but then we also had the requirement to allow our users to set their own OkHttpClient instances for the SDK to use, where they could also add more interceptors of their own, which may or may not invoke writeTo in the request body (one or more times!).

We could've somehow provided an additional API where they can increment progressUpdatesToSkip to account for this, but then they could also have interceptors that will sometimes read the body but not at other times, based on some dynamic condition... There's clearly no winning with this approach, and it's an awful rabbit hole to go down.

So, to quote myself from the workaround PR linked above:

A real solution would be intercepting the call with an OkHttp network interceptor, but we can't pass in individual callbacks per different Retrofit upload calls with that approach (at least not easily).

So the problem was that we had no way to get the callback value from the call site that invokes the Retrofit method down to the interceptor attached to the underlying OkHttp client.

Turns out, thankfully, that I was wrong about that!

OkHttp Tags

Enter OkHttp's tags API (many thanks to Jesse Wilson for showing me this!). With this API, the library allows you to add arbitrary tags (objects) to your requests when building them.

As the docs say, you can:

Use this API to attach timing, debugging, or other application data to a request so that you may read it in interceptors, event listeners, or callbacks.

When building the Request, you can pass in a Class as a key and then an object of that type as the associated value:

val request = Request.Builder()
    .post(requestBody)
    .tag(ProgressCallback::class.java, callback)
    .build()

And then later you can read these values from the Request:

val cb: ProgressCallback? = request.tag(ProgressCallback::class.java)

One small problem is that in our file upload code we create a RequestBody manually, but not the actual Request object, as that's created under the hood by Retrofit.

Thankfully, the tagging API is also exposed through Retrofit, so you can add tags to methods using the @Tag annotation on parameters. We'll use this in the next section!

The last-interceptor-swaparoo

The strategy then is the following:

Add the ProgressCallback instance as a tag when making the Retrofit call.
Create an interceptor at the end of the interceptor chain that will check each outgoing request and wrap its RequestBody into a ProgressRequestBody if the callback is present on it.

First, we'll update the Retrofit interface to accept a progressCallback parameter that will be used as a tag:

@Multipart
@POST("/channels/{type}/{id}/file")
fun sendFile(
    @Path("type") channelType: String,
    @Path("id") channelId: String,
    @Part file: MultipartBody.Part,
    @Tag progressCallback: ProgressCallback?,
): RetrofitCall<UploadFileResponse>

Then, we'll implement the interceptor that reads this tag and performs the wrapping of the RequestBody if needed:

internal class ProgressInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()

        val progressCallback = request.tag(ProgressCallback::class.java)
        if (progressCallback != null) {
            return chain.proceed(wrapRequest(request, progressCallback))
        }

        return chain.proceed(request)
    }

    private fun wrapRequest(request: Request, progressCallback: ProgressCallback): Request {
        return request.newBuilder()
            // Assume that any request tagged with a ProgressCallback is a POST
            // request and has a non-null body            
            .post(ProgressRequestBody(request.body!!, progressCallback))
            .build()
    }
}

Finally, we'll add this interceptor to our OkHttpClient, making sure it's the last one added.

We'll add it as a network interceptor, as we want it to be as close to the actual upload as possible, and it doesn't need to be involved in requests that don't go out to the network.

return baseClientBuilder()
    .addInterceptor(...)
    .addInterceptor(...)
    .addNetworkInterceptor(ProgressInterceptor())

This way nothing that previous interceptors do with the request will interfere with the progress reporting, as they'll still have the original RequestBody to work with, and the special progress-tracking wrapper is only added at the very last moment before it actually goes out to the network.

If you want to see this last change in detail, check out the corresponding PR on GitHub.

Wrap-Up

So that's the implementation we ended up with for now! You can find all of this code in the Chat Android SDK's GitHub repository if you want to look at it in a real project.

There is one remaining issue with this progress tracking: Whenever the body gets written, it's only written into local buffers, and what we track is how fast we're writing to that buffer. This then still needs to make it over the network, which can take some time.

So the upload progress tends to get to 100% relatively quickly and then the request will remain pending for a while as the network call completes.

This is as close to the socket (so to say) as we can get with these APIs. For a bit more info and references, see this GitHub discussion.

If you want to learn more about how Okio (and OkHttp, Retrofit, and Moshi) work super efficiently with data, watch A Few Ok Libraries by Jake Wharton. For an introduction to Moshi, check out Say Hi to Moshi.

All About Opt-In Annotations

Márton Braun — Thu, 30 Sep 2021 16:32:34 +0000

The opt-in mechanism in Kotlin allows you to mark APIs that should be used carefully -- or perhaps not at all. If you mark a declaration (a class, a function, a property, anything really) as opt-in required, using it will produce a warning or error in the code, prompting the user to explicitly opt in to using it. This can guarantee that there has been a conscious decision made about using the API on the use site.

This is very similar to how you deprecate declarations to prevent people from using them. You can read more about deprecations in Maintaining Compatibility in Kotlin Libraries.

Opt-in APIs are really useful if you're building libraries, but it also applies if you want to control the visibility and usages of APIs within any multi-module project. You also have to know how to interact with opt-in APIs correctly as a user.

In this article, we'll look at everything you need to know about opt-in APIs:

How to create them
How to use them
Real life use cases and useful conventions

And we'll also touch on some auxiliary topics around opt-in:

Java interop
Android usage
API verification

We have a lot of ground to cover, so let's get started. Feel free to use the links above to jump around to different parts of this guide!

Creating Opt-In APIs

First, let's see how you can create APIs that will require their users to opt-in to using them. This is done in two steps:

Creating an opt-in marker annotation
Marking APIs as opt-in required

Creating an Opt-in Marker Annotation

To create an opt-in marker annotation, create a new annotation class and annotate it with RequiresOptIn:

package com.example.lib.core

@RequiresOptIn(
    level = RequiresOptIn.Level.WARNING,
    message = "This is an experimental API. It may be changed or removed in the future."
)
public annotation class ExperimentalLibraryApi

This annotation has very similar properties to the @Deprecated annotation. Let's review what they are.

First, you can set a severity level:

WARNING will show a yellow warning on the call site and a warning during compilation. This is a "soft" warning, as it can be ignored and the code will still compile.
ERROR will cause a "hard" compilation error on the call site. Anyone using an API that has this opt-in level must explicitly opt-in to using it, otherwise their code won't compile.

You can also set a message that describes what the given opt-in marker annotation indicates. For this example, we're creating an annotation to mark APIs that are still experimental in a library, but are expected to become stable in later versions.

Note that marking experimental APIs is just one use case for opt-in annotations. See the Use Cases and Conventions below for other examples.

You'll notice that the usage of the RequiresOptIn annotation itself also produces the warning. This is because the opt-in system of the Kotlin Standard Library itself is still experimental. You can track the development progress on this YouTrack issue -- it's currently expected to become stable in Kotlin 1.7.

While this system might not be officially stable, it's already being widely used across popular Kotlin libraries.

To make that warning go away, you'll have to opt in to using Kotlin's opt-in system. You can do so by adding the following code to your module's build configuration, which adds an argument to the Kotlin compiler doing exactly that: opting in to opt-in.

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {
    kotlinOptions {
        freeCompilerArgs += [
            '-Xopt-in=kotlin.RequiresOptIn',
        ]
    }
}

Marking APIs as Opt-in Required

With the marker annotation created, you can now mark pieces of API as experimental! For example, you can annotate a function like this:

@ExperimentalLibraryApi
public fun someExperimentalApi()

Calling this function will now produce a warning on the call site:

You can also place these markers on larger scopes. For example, you can mark an entire class:

@ExperimentalLibraryApi
class Stack {
    fun push(data: Int)
    fun pop(): Int
}

With this in place, any usage of the class' APIs (as well as the usage of the type itself) will produce warnings:

Let's see how you can handle these on the call site.

Using Opt-In APIs

There are several ways of making the warnings and errors produced by calling opt-in APIs go away. Let's see when you want to use each of them.

Propagating the Opt-in Requirement

One way to use an opt-in API is to mark the code that's calling it with the same opt-in annotation, propagating the requirement further:

@ExperimentalLibraryApi
public fun anotherExperimentalApi() {
    someExperimentalApi()
}

This allows you to use other APIs that are marked with the same annotation within the implementation of this function. However, anyone using this function will now have to deal with the opt-in requirement as well.

This is useful within your own code to make sure that you don't accidentally create stable APIs that rely on experimental APIs in their implementation. If something relies on an experimental declaration, it too should likely be experimental.

However, you shouldn't do this in client code, as that'd just be putting off the issue. Instead, you want to actually opt in there. We'll look at this next.

Opting in an Entire Module

If you want to enable all usages of a certain kind of opt-in API in a module, you can use the same -Xopt-in compiler option that you used to opt in to using opt-in earlier, but provide the specific annotation as the value.

This configuration allows all usages of our experimental APIs within its module:

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {
    kotlinOptions {
        freeCompilerArgs += [
            '-Xopt-in=com.example.lib.core.ExperimentalLibraryApi',
        ]
    }
}

You should use this with care, as enabling a certain opt-in API module-wide can lead to creating lots of usages of that API accidentally. Since there are no warnings in the code this way, you can easily miss these usages.

On the other hand, this fits certain use cases really well, such as opting in to using internal APIs that are shared between different modules of the same library.

Opting in Locally

A more precise approach is opting in locally. You can do this for each usage of opt-in APIs, using the OptIn annotation:

public fun clientCode() {
    @OptIn(InternalMyLibraryApi::class)
    someExperimentalApi()
}

You'll notice that the usage of the OptIn annotation itself also produces the warning. This, again, is due to the system itself being experimental. Interestingly, you have to opt in to kotlin.RequiresOptIn in this case as well:

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {
    kotlinOptions {
        freeCompilerArgs += [
            '-Xopt-in=kotlin.RequiresOptIn',
        ]
    }
}

With the configuration above, you can now freely use OptIn to suppress opt-in related warnings and errors. This comes with the benefit that each usage of opt-in APIs will be clearly visible in the code thanks to the OptIn annotation being present on the use site.

You can opt-in at the statement level, like seen above, but also in broader scopes, such as for an entire function:

@OptIn(InternalMyLibraryApi::class)
public fun clientCode() {
    someExperimentalApi()
    someExperimentalApi()
}

Or even an entire file, using an annotation use-site target, @file: :

@file:OptIn(InternalMyLibraryApi::class)

public fun firstFunction() {
    someExperimentalApi()
}

public fun secondFunction() {
    someExperimentalApi()
}

Next, let's expand beyond using these annotations to mark experimental APIs, and see what other scenarios they can be useful in.

Use Cases and Conventions

Some of the best examples of opt-in APIs are in first-party Kotlin libraries. A great example is the kotlinx.coroutines library, which uses four different opt-in marker annotations across its API.

The annotation naming conventions used in this library are also widely adopted in other libraries. You should consider aligning your own opt-in usages with this as well.

These opt-in annotations all follow the [Prefix][LibraryName]Api pattern, and each prefix carries different semantics. Let's see what each of them mean:

ExperimentalCoroutinesApi: Perhaps the most frequently used convention, it marks APIs that are not stable yet. These might have known issues or ongoing design discussions that can change the API or its behaviour in the future.
InternalCoroutinesApi: Marks APIs that are only exposed for cross-module usage within a single library group, and should not be relied on by end users. They should be considered internal and can change or be removed at any time. See Mastering API Visibility in Kotlin for a detailed example of how to use these.
ObsoleteCoroutinesApi: A more niche marker than previous ones, this marks APIs that should not be used anymore. However, they are not deprecated yet, as they don't have replacements ready that users could migrate to.
DelicateCoroutinesApi: Another niche convention, delicate APIs should only be used in very specific situations, and users should make sure they understand the implications of using such APIs.

On Android, Google's own Jetpack libraries also make generous use of opt-in APIs. In the API guidelines document for Jetpack, using opt-in annotations is the recommended way of "annotating API surfaces as unstable".

As a result, you'll see lots of these annotations when interacting with Jetpack libraries. They are especially widespread in Jetpack Compose libraries, given that the framework is still very new. Some common examples of these:

InternalComposeApi and ExperimentalComposeApi
InternalFoundationApi andExperimentalFoundationApi
ExperimentalMaterialApi
InternalTextApi and ExperimentalTextApi
InternalComposeUiApi and ExperimentalComposeUiApi
InternalTestApi and ExperimentalTestApi
... and more!

As you can see, these usually come in pairs, and a separate pair is created for each of the different Compose packages.

They are generally not documented in Kdoc, but you can find out what their purpose is by reading the provided message. A good place to do this is on cs.android.com. For example, you can find the sources of InternalFoundationApi here, and the sources of ExperimentalFoundationApi here, in the same package.

They, of course, follow the conventions layed out by kotlinx.coroutines above.

Java Interop

Until now, we've discussed using Kotlin's own opt-in annotations: kotlin.RequiresOptIn and kotlin.OptIn. Usages of these are verified by the Kotlin compiler, which produces warnings and errors around them as needed.

In most cases, the API marked with opt-in annotations is public, but the annotation being present deters clients from using it. However, when Java source code uses these APIs, they'll only see it as regular public API. The Java compiler does not understand or respect these opt-in requirements.

You can either ignore this and accept that Java users (if they exist) will be able to access these APIs freely, and not be warned at all, or you can take extra steps to make sure that Java clients don't access opt-in APIs accidentally.

One solution is to mark your opt-in declarations with @JvmSynthetic as well. Synthetic declarations are inaccessible from Java source code, preventing all Java usages of these APIs (with no way to opt-in).

@JvmSynthetic
@ExperimentalLibraryApi
public fun someExperimentalApi()

If you're on Android, keep reading for another one.

Opt-In on Android

Android is now officially Kotlin-first, but Java is also still a fully-supported language on the platform. To work around the Java compatibility issue described above, Android has its own set of opt-in annotations (androidx.annotation.RequiresOptIn and androidx.annotation.OptIn), which can be used the exact same way as described earlier for the Kotlin annotations.

The difference is in how these are verified. Instead of the Kotlin compiler performing the checks, verifying these Android-specific annotations is up to the Android Lint tool. As Lint checks are performed on the UAST (Unified Abstract Syntax Tree), these annotations are verified not only in Kotlin, but also in Java code. This means that the opt-in marker annotation, its usage, and the code using the opt-in APIs can all be in either language.

To use these annotations in your project, you need to add a dependency on the annotation-experimental artifact:

dependencies {
    implementation("androidx.annotation:annotation-experimental:1.1.0")
}

Note that you can still use the Kotlin opt-in system on Android, you'll just miss out on Java support.

API Verification

If you mark some pieces of public API in your module as experimental or internal using Opt-In annotations, you will probably want to ignore them when checking for changes (especially breaking changes) in your public API.

A common tool you can use for Kotlin projects is the Binary compatibility validator
plugin. This plugin calls annotations that mark API that shouldn't be considered public "non-public markers".

These can be configured in the plugin's configuration block by adding the fully qualified names of the marker annotations to nonPublicMarkers:

apiValidation {
    /**
     * Set of annotations that exclude API from being public.
     * Typically, it is all kinds of `@InternalApi` annotations 
     * that mark effectively private API that cannot be actually 
     * private for technical reasons.
     */
    nonPublicMarkers += [
        "com.example.lib.core.ExperimentalLibraryApi",
        "com.example.lib.core.InternalLibraryApi",
    ]
}

APIs annotated with non-public markers will be excluded from the API dumps of the validator plugin (they won't show up in the generated .api files).

Conclusion

That's -- hopefully -- everything you'd ever want to know about opt-in annotations, and more. With this, you should now be ready to use these annotations in your own library or multi-module projects as well, whether you just need to interact with experimental APIs while building your apps or create your own opt-in APIs.

Thanks to István Juhos, Arnaud Giuliani, Thomas Künneth, and Annyce Davis for taking an early look and reviewing this post :)

Follow me @zsmb13 on Twitter to keep in touch and get notified of similar posts!

A Bit of Gradle Housekeeping

Márton Braun — Wed, 01 Sep 2021 20:38:52 +0000

While cleaning is traditionally a spring activity, let me invite you to do it at the end of summer this time around.

Note: Yes, I'm still using Groovy because I never found a compelling reason to upgrade to Kotlin DSL 🤷‍

Something I'm quite enthusiastic about is having the simplest and most default Gradle configuration for an Android project that you can possibly have.

Why? Because simple and boring configuration is great! The more configuration you have in these files, the more custom your setup, the harder it is to navigate.

When something weird is happening in your project, having simpler project setup avoids a lot of potential headache when you need to figure out what's going on.
When someone new joins the project or starts working with the project configuration files, a simpler setup will make their lives easier too.

In this article, we'll look at various bits of configuration that you might have in your build files that you don't actually need anymore, or can replace with something simpler.

Build tools version

I'll start with a classic that you should have removed four years ago when version 3.0.0 of the Android Gradle Plugin was released. Despite that, it still lingers around in many projects.

android {
    buildToolsVersion "30.0.3"
}

This version number is set by default - feel free to simply remove it from your build config!

Java version settings

Continuing with a more recent change, if you're on AGP 4.2 or later, you no longer have to specify that you want to target version 8 of the Java language (which gives you desugaring for various features like lambdas and method references).

This means you can remove this config, if you have it in your build files:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

Kotlin JVM target settings

On a very similar note, we used to have to specify the JVM version that the Kotlin compiler should target explicitly (as the default was 1.6). Since Kotlin 1.5 however, the default value for this is 1.8, which means you can remove this config as well:

android {
    kotlinOptions {
        jvmTarget = '1.8'
    }
}

*SdkVersion

Something not to completely remove but to slightly simplify is the various SDK versions you specify in a project. Traditionally, you have probably used the following properties to set these values:

android {
    compileSdkVersion 31

    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 31
    }
}

However, since AGP 4.1.0, these are deprecated and should be replaced with variants that no longer have the Version postfix. So, for example, minSdkVersion is now just minSdk:

android {
    compileSdk 31

    defaultConfig {
        minSdk 21
        targetSdk 31
    }
}

The `src/main/kotlin` source set

Back to things you can remove, let's talk a bit of Kotlin. If you prefer using the src/main/kotlin folder instead of the src/main/java folder to store your source files (because you're just that enthusiastic about using the language), you probably have configuration in your build files that resembles something like this:

sourceSets.all {
    it.java.srcDir "src/$it.name/kotlin"
}

This simply adds the folder in question as a source set where files will be used as compilation sources.

The good news is that since version 7.0.0 of the Android Gradle Plugin, you no longer need this. kotlin source folders are just supported by default!

Kotlin standard library dependency

Let's wrap it up with a final Kotlin tip. The classic Kotlin Android project setup includes this variable set in the top level build.gradle file:

buildscript {
    ext.kotlin_version = "1.5.30"
}

And then a reference to it in the module level build.gradle file, where the Standard Library is included:

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}

However, since Kotlin 1.4.0, including the Kotlin Gradle plugin automatically adds the Kotlin Standard Library as a runtime dependency to your modules (since you wouldn't want to use the language without its Standard Library anyway).

It will include the correct version based on the module's properties, matching the version of the plugin, the platform you're running on, and the JVM target you have configured.

This means that you can remove the explicit dependency on the stdlib from your build files, and as a consequence, you can likely remove the kotlin_version variable as well.

Conclusion

Thanks for participating in this quick late summer project cleaning initiative. I hope you got to create a quick and simple PR to make your project config a bit leaner. See you next time!

Keeping public API in check with the Kotlin binary validator plugin

Márton Braun — Wed, 14 Jul 2021 07:50:56 +0000

Within the Stream Chat Android SDK project, we use the Kotlin binary compatibility validator plugin to keep track of all the changes we make to our public API. This is a first-party plugin by JetBrains, though it's still experimental (it's an incubator project by JetBrains on GitHub).

In this article, you'll learn what the plugin does, how to set up and configure it, and how you can use it to make your library project better.

Core concept

Let's start with a TL;DR of what the plugin does:

It generates .api files that describe the public API for each module, and if you make changes to public API, you have to explicitly update the content of the .api files (otherwise, checks will fail, alerting you of the accidental API change).

By doing this, it guarantees that developers on the project are always aware of the exact changes they're making to public API. Since the plugin works on binary API, it will catch incompatible changes that might not be obvious when looking at source code. For example, when writing Kotlin code, using data classes, default implementations, or companion objects might create binary API that you're usually unaware of.

Setup and configuration

The binary validator is available as a simple Gradle plugin, which makes setup really quick. Just add this code to your top level build.gradle file:

buildscript {
    dependencies {
        classpath 'org.jetbrains.kotlinx:binary-compatibility-validator:0.6.0'
    }
}

apply plugin: 'binary-compatibility-validator'

With the plugin added, it's now time to configure it. You can do this inside the apiValidation block. Here's the configuration we use in our SDK as an example:

apiValidation {
    ignoredPackages += [ // 1
            'com/getstream/sdk/chat/databinding',
            'io/getstream/chat/android/ui/databinding',
    ]

    ignoredProjects += [ // 2
            'stream-chat-android-docs',
            'stream-chat-android-sample',
            'stream-chat-android-ui-components-sample',
            'stream-chat-android-test',
    ]

    nonPublicMarkers += [ // 3
            'io.getstream.chat.android.core.internal.InternalStreamChatApi',
    ]
}

Let's look at each of the options we're using:

ignoredPackages allows you to exclude some packages from validation. In our case, we don't want to keep track of the files generated by View Binding. You could also use ignoredClasses to exclude individual classes by name.
By default, the plugin will be enabled for all modules of a project. We use ignoredProjects to exclude non-published modules, like documentation and sample apps.
The nonPublicMarkers entry allows you to specify any Kotlin Opt-in annotations that you're using on API that's not considered publicly available. To learn more about these, watch Mastering API Visibility in Kotlin.

Usage

To (re)generate the .api files, you'll have to run the apiDump Gradle task. When you're doing this for the first time, you should review all the generated .api files to make sure that everything in there is really supposed to be public API, and then commit them to your repository.

Here's a small sample of what you'll see in these files:

public abstract interface class io/getstream/chat/android/ui/StyleTransformer {
    public abstract fun transform (Ljava/lang/Object;)Ljava/lang/Object;
}

public final class io/getstream/chat/android/ui/common/Debouncer {
    public fun <init> (J)V
    public final fun shutdown ()V
    public final fun submit (Lkotlin/jvm/functions/Function0;)V
    public final fun submitSuspendable (Lkotlin/jvm/functions/Function1;)V
}

public abstract interface class io/getstream/chat/android/ui/common/UrlSigner {
    public abstract fun signFileUrl (Ljava/lang/String;)Ljava/lang/String;
    public abstract fun signImageUrl (Ljava/lang/String;)Ljava/lang/String;
}

You can then use the apiCheck Gradle task to verify that your current source code still has the same API as your committed .api files. This task will create up-to-date .api dumps in temporary build folders, and compare them to the .api files you have in your repository. If they don't match, it will fail, and report the differences detected.

For example, see this error the task generates after moving a property from a data class' constructor to its body:

Execution failed for task ':stream-chat-android-client:apiCheck'.
> API check failed for project stream-chat-android-client.
   @@ -218,9 +218,8 @@

   public final class io/getstream/chat/android/client/api/models/AutocompleteFilterObject : io/getstream/chat/android/client/api/models/FilterObject {
    public final fun component1 ()Ljava/lang/String;
  - public final fun component2 ()Ljava/lang/String;
  - public final fun copy (Ljava/lang/String;Ljava/lang/String;)Lio/getstream/chat/android/client/api/models/AutocompleteFilterObject;
  + public final fun copy (Ljava/lang/String;)Lio/getstream/chat/android/client/api/models/AutocompleteFilterObject;
    public fun equals (Ljava/lang/Object;)Z
    public final fun getFieldName ()Ljava/lang/String;
    public final fun getValue ()Ljava/lang/String;

   You can run :stream-chat-android-client:apiDump task to overwrite API declarations

If those differences are intentional, you should run the apiDump task again, which updates the stored .api files, now including any changes in the API you've created by changing the source code. Running the apiCheck task at this point will complete successfully, as the sources and the .api files are in sync again.

This is the goal of the plugin: making developers explicitly run a task to update the API description files when they touch public API.

You should then commit the changes you've introduced to the .api files. These will show up in commits and on pull requests, allowing reviewers to easily tell when you've made changes to the binary API, and catch any unintentional changes.

Git hooks and CI checks

The power of the plugin really shows if you have automated checks in place to make sure that whenever you change your public API, you've actually updated the .api files to match.

At Stream, we run the checks in two ways:

Using a pre-commit git hook in our repository that will run the apiCheck task (and automatically run apiDump for you if it fails) when you try to create a new commit in the repository.
With a GitHub Action step in our PR checks workflow that makes sure that the api files are up-to-date before we merge changes.

Limitations

This plugin is a binary validator. This means that it doesn't track public API changes that don't affect binary compatibility. For example, reified functions are part of source-level API but are not present in the binary API. Thankfully, changes in these should be obvious from the source file changes anyway (and they're not very frequent).

There are also some known issues in the library, as you can see on GitHub. We've reported some of these ourselves, mostly for problems in respecting non-public markers, which we use extensively in our project (see #36 and #58).

Conclusion

Even with those limitations in mind, the binary compatibility validator plugin is a great tool for making sure that you don't make any accidental changes in your public binary API when building a library. Check it out on GitHub.

You'll also find our Android Chat SDK on GitHub, and you can try our In-App Messaging Tutorial to get started with it.

More library development topics you might be interested in:

Publishing Android libraries to MavenCentral in 2021

Márton Braun — Wed, 21 Apr 2021 14:29:27 +0000

Introduction

This is an updated version of an article published two years ago on blog.autsoft.hu. This new version supports non-Android libraries, uses command line GPG handling instead of a specific Windows GUI app, includes new best practices, and uses GitHub Actions for its CI integration.

Update, April 2021: addressed new Sonatype infra, moved to using AGP Maven Publish plugin integration for release components, and to using the new gradle-nexus/publish-plugin.

Update, July 2021: fixed keyserver being used (thanks Chetan Gupta), moved to using in-memory GPG keys for signing (thanks Arkadii Ivanov).

Update, July 2021: use JDK11 in GitHub Actions configuration to support new AGP versions.

Creating a great library is hard work. Coming up with the idea, implementing it, making sure you have a nice, stable public API that you control carefully and maintain… That’s already lots to do.

After all that, you need to make your library available to the public. Technically, you could distribute the .aar file any way you want, but the norm is publishing it to a publicly available Maven repository. It’s a good idea to use one of the well-established repositories that people are already likely to have in their projects, to make getting started with your library as easy as possible.

The simplest choice would be JitPack, which might not give you much in terms of customization or control, but is very easy to get started with. All you have to do is publish your project on GitHub, and JitPack should be able to build and distribute it immediately. If you’re new to libraries, this is a great choice for getting your code out there.

The next step up is Jcenter… Which no longer accepts new packages and will stop serving them in February 2022. Using it had its issues anyway.

Finally, the fanciest place you can be in is The Central Repository via Sonatype OSSRH (OSS Repository Hosting), which I’ll refer to as simply MavenCentral from here on. This is the place to be if you’re a Maven dependency. Artifacts on MavenCentral are well trusted, and their integrity can be verified, as they are all required to be signed by the author.

The publication process, however, and especially automating it, can be quite a headache. It’s easy to get stuck at many of the various steps no matter what tutorials you’re following, especially if they’re out of date, and this can get demotivating very quickly. It’s not uncommon to give up and just use Bintray/Jcenter instead – which is not an option anymore.

So, if you feel up for a bit of a challenge, and want to do things the right way, here’s how you can get a library into MavenCentral, in 2021.

Overview

Here's a quick overview of the steps we'll go through:

Registering a Jira account with Sonatype, and verifying your ownership of the group ID you want to publish your artifact with
Generating a GPG key pair for signing your artifacts, publishing your public key, and exporting your private key
Setting up Gradle tasks that can sign upload your artifacts to a staging repository
Manually going through the process of checking your artifacts in the staging repo and releasing them via the Sonatype web UI
Automating the close & release flow with a Gradle plugin
Configuring CI workflows with GitHub Actions to automate all of the above

A lot of ground to cover - let’s go!

Prerequisites

We’ll be using the following tools for this tutorial. You are free to use alternatives, but these are our favourites, and they work well for us.

The command line gpg tool
- GPG Suite for macOS or Gpg4win for Windows are great choices, which also come with helpful GUIs. Many alternatives for different platforms are available here.
GitHub as the public host of the library’s repository
GitHub Actions as the continuous integration solution

For this article, we’ll assume that you already have your library developed, and have uploaded it to a public GitHub repository.

We’ll use our very own Android Chat SDK in our examples. This SDK is made up of multiple artifacts, but for simplification, we’ll just talk about publishing the low-level networking client, which lives in the stream-chat-android-client module of the GitHub repository.

Shameless plug: if you need a chat solution in your Android app, check out our documentation and our Android Chat tutorial.

Registering a Sonatype account

First things first, you’ll need an account in the Sonatype Jira. Head over there and hit Sign up. Registration is straightforward, it just requires a username, an email, and a password.

After you’ve logged in, you’ll need to open an issue, asking for access to the group ID that you’ll want to publish your project under. For us, based on our domain name (getstream.io), our group ID is io.getstream. If you own a domain, it’s best to choose the reversed version of that as your group ID. Otherwise, you’ll have to stick with having a GitHub-based group ID (see Choosing your Coordinates for more details).

After choosing a language and an avatar, you’ll end up on this landing page - click on Create an issue:

Select Community Support - Open Source Project Repository Hosting and then New Project:

On the next page, fill out the following fields:

Summary: Create repository for your.group.id.here
Description: An optional, quick summary of what your project is.
Group Id: Your group ID, as described a few sections earlier.
Project URL: If your project has a webpage, the URL of that page. This can also be just the GitHub repository.
SCM url: Your source control URL, i.e. the GitHub repository link.
Username(s): If you want additional users (on top of the one you’re using for this process) to have deploy access for your group ID, you can list them here.
Already Synced to Central: If you’re just getting started, this should be No.

Soon after opening it, your issue will get a comment telling you to verify that you own the domain corresponding to your group ID:

![Comment requesting domain verification](https://stream-blog-v2.imgix.net/blog/wp-content/uploads/da8ea3aa9e7861342114d89a78f7e7ef/please_verify_2-0-00-00-00.png?auto=compress%2Cformat&ixlib=php-3.3.0](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hgsfecmkirg0f8bmf18g.PNG)

To comply with this, add the required TXT record to your domain - how to do this will depend on where your domain is registered, but it should be a fairly simple task.

@    TXT    1800    OSSRH-12345

Make sure to replace the ticket number above with your actual number.

When done, don’t forget to leave a comment on the issue so that Sonatype knows to check the record. You’ll eventually get a response telling you that you now have deploy rights - congrats!

![The Sonatype comment confirming domain verification]](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/niwgnp6n317gkapz14cb.PNG)

Generating a GPG key pair

As we eluded to earlier, artifacts published on MavenCentral have to be signed by their publishers. You’ll need a GPG key for this.

MavenCentral also has its own documentation for Working with PGP Signatures which you can reference if you get stuck along the way.

This part requires access to the gpg command. There are several ways to install this via package managers, and there are many distributions available for different platforms on gnupg.org.

GPG Suite is an easy-to-use distribution for macOS, and you can use Gpg4win if you’re on Windows. Both of these come with GUI tools that make managing keys easier.

We'll stick to the command line here, but note that the old article shows how to use the Kleopatra GUI (included in Gpg4win) on Windows for generating and managing keys.

To generate a new key, run the following command:

gpg --full-gen-key

You’ll be prompted to enter a few details:

Kind of key: Accept the default value, which is (1) RSA and RSA.
Key size: 4096.
Expiration: You can input 0 to generate a key that never expires. You can also create a key that has an expiry date and then renew it periodically, if you prefer to do so.
Real name, email: Should be obvious.
Comment: Freeform text, can be left empty.

After entering these details, you’ll be prompted to enter a passphrase to secure your key with.

Here’s the full flow you'll go through, with a bit of truncation:

Please select what kind of key you want:
   (1) RSA and RSA (default)
   ...
Your selection? 1

RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096
Requested keysize is 4096 bits

Please specify how long the key should be valid.
         0 = key does not expire
         ...
Key is valid for? (0) 0
Key does not expire at all
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: Marton Braun
Email address: marton@getstream.io
Comment: Example key for tutorial
You selected this USER-ID:
    "Marton Braun (Example key for tutorial) <marton@getstream.io>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O

gpg: key 36271B955BEF072A marked as ultimately trusted
gpg: revocation certificate stored as '.../gnupg/openpgp-revocs.d\7A5D73CFEDDDBC915986998A36271B955BEF072A.rev'
public and secret key created and signed.

pub   rsa4096 2021-02-03 [SC]
      7A5D73CFEDDDBC915986998A36271B955BEF072A
uid                      Marton Braun (Example key for tutorial) <marton@getstream.io>
sub   rsa4096 2021-02-03 [E]

You can always check the keys you have on your system by running gpg --list-keys:

gpg: checking the trustdb
.../gnupg/pubring.kbx
-----------------------------------------------
pub   rsa4096 2021-02-03 [SC]
      7A5D73CFEDDDBC915986998A36271B955BEF072A
uid           [ultimate] Marton Braun (Example key for tutorial) <marton@getstream.io>
sub   rsa4096 2021-02-03 [E]

Your key’s ID is the last eight digits of its fingerprint (the long hexadecimal string above). In this case, this is 5BEF072A - take note of this, as you’ll use this later.

You’ve generated a pair of keys - a private and a public key. You’ll keep the private one hidden and use it to sign your artifacts. The public key has to be uploaded to the server so that anyone can check that it belongs to you, which you can do by running the following (use your own key ID!):

gpg --keyserver keyserver.ubuntu.com --send-keys 5BEF072A

See Distributing Your Public Key for the list of supported keyservers.

Your private key will need to be referenced by your project when it signs the artifacts. You can get a base 64 export of it with the following:

gpg --export-secret-keys 5BEF072A | base64

Enter your passphrase that you’ve set earlier when prompted. You can either copy-paste this key from the terminal output later on, or save it to a file temporarily.

Setting up publication in your project

That’s a lot of work without touching your project, but the time has come to do that now. In the next few steps, you will:

Add Gradle scripts that set up the publication plugin required to push artifacts to a repository.
Configure the properties of the library you’re releasing.
Grab the necessary authentication details along with the private key you’ve just exported.

Root project Gradle configuration

To easily automate publishing later, you'll use the gradle-nexus/publish-plugin tool. This has to be added in your project level (root) build.gradle file as a dependency.

You can do this either with a plugins block:

plugins {
    id("io.github.gradle-nexus.publish-plugin") version "1.1.0"
}

Or with the classic buildscript dependency syntax, and then applying it in your project:

buildscript {
    dependencies {
        classpath 'io.github.gradle-nexus:publish-plugin:1.1.0'
    }
}

apply plugin: 'io.github.gradle-nexus.publish-plugin'

Check the releases page of the plugin to get the latest version.

Next, create a new file called publish-root.gradle in a new scripts folder inside your project. This will contain global configuration you need for publishing, grabbing input values for your scripts, and defining the MavenCentral repository.

Note that here we’ll go through the contents of these scripts part by part, with explanations. You can always find the complete, up-to-date files we use in production in the Stream Chat repository.

In this file, you'll grab some configuration parameters. Using the script below, you’ll first set all the variables to a dummy empty string. This will let the project sync and build without the publication values set up, which would otherwise be an issue for your contributors.

// Create variables with empty default values
ext["signing.keyId"] = ''
ext["signing.password"] = ''
ext["signing.key"] = ''
ext["ossrhUsername"] = ''
ext["ossrhPassword"] = ''
ext["sonatypeStagingProfileId"] = ''

The first three variables will be used to sign the artifacts after they’re built:

signing.keyId: the ID of the GPG key pair, the last eight characters of its fingerprint
signing.password: the passphrase of the key pair
signing.key: the base64 encoded private key you exported earlier

osshrUsername and ossrhPassword: are your account details for MavenCentral, which you’ve chosen at the Jira registration step. We’ll get back to where sonatypeStagingProfileId comes from later on.

Next, you’ll try to fetch the values of the variables from a local.properties file in the root of the project if it exists, otherwise you’ll look for them in the environment variables. The former lets you easily input these values locally on your machine, while the latter will help with setting up CI.

File secretPropsFile = project.rootProject.file('local.properties')
if (secretPropsFile.exists()) {
    // Read local.properties file first if it exists
    Properties p = new Properties()
    new FileInputStream(secretPropsFile).withCloseable { is -> p.load(is) }
    p.each { name, value -> ext[name] = value }
} else {
    // Use system environment variables
    ext["ossrhUsername"] = System.getenv('OSSRH_USERNAME')
    ext["ossrhPassword"] = System.getenv('OSSRH_PASSWORD')
    ext["sonatypeStagingProfileId"] = System.getenv('SONATYPE_STAGING_PROFILE_ID')
    ext["signing.keyId"] = System.getenv('SIGNING_KEY_ID')
    ext["signing.password"] = System.getenv('SIGNING_PASSWORD')
    ext["signing.key"] = System.getenv('SIGNING_KEY')
}

Make sure that you’ve set these variables either in the aforementioned local.properties file or in your environment variables. If you want to use the property file, the syntax for it should look something like this (replace all the data here with your own!):

signing.keyId=5BEF072A
signing.password=signingPass123
signing.key=bm90IGEgcmVhbCBrZXksIHdoYXQgd2VyZSB5b3UgZXhwZWN0aW5n
ossrhUsername=yourSonatypeUser
ossrhPassword=yourSonatypePassword

The last piece of code to add to this file will define the MavenCentral (Sonatype) repository where publishing should upload the artifacts. This relies on parameters fetched above to authenticate:

// Set up Sonatype repository
nexusPublishing {
    repositories {
        sonatype {
            stagingProfileId = sonatypeStagingProfileId
            username = ossrhUsername
            password = ossrhPassword
        }
    }
}

Important: If you're on the new Sonatype infrastructure (happens if you've registered after 2021-02-24 or requested it specifically), you have to add explicit URLs pointing to s01.oss.sonatype.org in this config block next to the existing parameters, like so:

nexusPublishing {
    repositories {
        sonatype {
            /* Existing params here... */
            nexusUrl.set(uri("https://s01.oss.sonatype.org/service/local/"))
            snapshotRepositoryUrl.set(uri("https://s01.oss.sonatype.org/content/repositories/snapshots/"))
        }
    }
}

As the last step, apply this script in your root build.gradle file like so:

apply from: "${rootDir}/scripts/publish-root.gradle"

This completes the configuration needed in the root project. This gist contains the code blocks detailed above in a single snippet. The final, up-to-date script we use for publishing our SDK can be found in the Stream Chat repository.

Per-module Gradle setup

With the repository defined and parameters fetched, it's time to create a script that will define the artifacts in each module you want to publish. Create a new file called publish-module.gradle in the scripts folder. As its name suggests, this will be applied to each module that you want to publish an artifact from.

In this file, first you’ll apply two plugins for publishing and signing.

apply plugin: 'maven-publish'
apply plugin: 'signing'

Our publishing file also applies the Dokka plugin in this block, which you have to configure separately, if you want to use it.

Then you declare the sources artifact for the library. This is really important - it will make sure that the source files are packaged along with the executable, compiled code, so that your users can easily jump to the definitions that they’re calling into within their IDE.

task androidSourcesJar(type: Jar) {
    archiveClassifier.set('sources')
    if (project.plugins.findPlugin("com.android.library")) {
        // For Android libraries
        from android.sourceSets.main.java.srcDirs
        from android.sourceSets.main.kotlin.srcDirs
    } else {
        // For pure Kotlin libraries, in case you have them
        from sourceSets.main.java.srcDirs
        from sourceSets.main.kotlin.srcDirs
    }
}

artifacts {
    archives androidSourcesJar
}

Once again, our real publishing file also adds an additional javadocJar task which ships Dokka-generated documentation - again, you can skip this if you want to.

You’ll set two properties on the Gradle project itself here, the group ID and the version of the artifact. You’ll see where these uppercase values come from later on, when you apply this publication script in the module level build.gradle files.

group = PUBLISH_GROUP_ID
version = PUBLISH_VERSION

Here comes the complicated part, providing all the metadata for the library you’re releasing. See the inline comments for the play-by-play explanation.

afterEvaluate {
    publishing {
        publications {
            release(MavenPublication) {
                // The coordinates of the library, being set from variables that
                // we'll set up later
                groupId PUBLISH_GROUP_ID
                artifactId PUBLISH_ARTIFACT_ID
                version PUBLISH_VERSION

                // Two artifacts, the `aar` (or `jar`) and the sources
                if (project.plugins.findPlugin("com.android.library")) {
                    from components.release
                } else {
                    from components.java
                }

                artifact androidSourcesJar
                artifact javadocJar

                // Mostly self-explanatory metadata
                pom {
                    name = PUBLISH_ARTIFACT_ID
                    description = 'Stream Chat official Android SDK'
                    url = 'https://github.com/getstream/stream-chat-android'
                    licenses {
                        license {
                            name = 'Stream License'
                            url = 'https://github.com/GetStream/stream-chat-android/blob/main/LICENSE'
                        }
                    }
                    developers {
                        developer {
                          id = 'zsmb13'
                          name = 'Márton Braun'
                          email = 'marton@getstream.io'
                        }
                        // Add all other devs here...
                    }

                    // Version control info - if you're using GitHub, follow the 
                    // format as seen here
                    scm {
                        connection = 'scm:git:github.com/getstream/stream-chat-android.git'
                        developerConnection = 'scm:git:ssh://github.com/getstream/stream-chat-android.git'
                        url = 'https://github.com/getstream/stream-chat-android/tree/main'
                    }
                }
            }
        }
    }
}

Finally, this piece of code grabs signing related values from the root project, and then tells the signing plugin to sign the artifacts you’ve defined above as a publication.

signing {
    useInMemoryPgpKeys(
            rootProject.ext["signing.keyId"],
            rootProject.ext["signing.key"],
            rootProject.ext["signing.password"],
    )
    sign publishing.publications
}

That’s the publish-module.gradle script all built up, ready to use. This gist contains the code blocks shown above in a single snippet. The final, up-to-date script we use for publishing our SDK can be found in the Stream Chat repository.

Time to include this script in a module! Head to the build.gradle file of your library module - in our case, this is the stream-chat-android-client module - and add the following code:

ext {
    PUBLISH_GROUP_ID = 'io.getstream'
    PUBLISH_VERSION = '4.5.2'
    PUBLISH_ARTIFACT_ID = 'stream-chat-android-client'
}

apply from: "${rootProject.projectDir}/scripts/publish-module.gradle"

Here you finally see the group ID, artifact ID, and version being set, so that the publication script can make use of them. Then, the script itself is applied. This is all the code you need to add per-module if you are publishing your library in multiple artifacts, everything else is done by the common script.

One last configuration step: you'll need to set the sonatypeStagingProfileId variable in your project. This value is an ID that Sonatype assigns to you, which the plugin uses to make sure all the artifacts end up in the right place during the upload.

Go to https://oss.sonatype.org/ and log in. In the menu on the left, select Staging profiles, select your profile, and then look for the ID in the URL.

Either set this value in your local.properties file, or set the corresponding environment variable.

Your first release

With all of that set up, you’re now ready to publish the first version of your library!

For each repository you have defined in the publishing script, a Gradle task will be created to publish to that repository. In our example, our first module to publish is stream-chat-android-client, and we’ve named the repository sonatype. Therefore, we need to execute the following command to start publication (replace the module name with your own here):

gradlew stream-chat-android-client:publishReleasePublicationToSonatypeRepository

This will create a so-called staging repository for your library, and upload your artifacts (aar and sources) to that repository. At this point, you can check that all the artifacts you wanted to upload have made it, before hitting the release button.

Now, go to the Sonatype site, and in the menu on the left, select Staging repositories.

Find your repository (might be the only one in the list, might have to scroll around a bit for it), which has your group ID in its name. If you select it and look at the Content tab, you’ll see the files that have been uploaded.

If everything looks good, and you’re done uploading files to the repository, you have to Close it. With the repository selected, hit the Close button in the toolbar on top. Confirm your action in the dialog (you don’t need to provide a description here).

This will take just a few moments, you can follow along with it happening in the Activity tab.

With the repository closed, you now have two final options available to you. Drop will throw away the repository, and cancel the publication process. Use this if something went wrong during the upload or you’ve changed your mind.

Release, on the other hand, will publish the contents of your staging repository to MavenCentral. Again, you get a confirmation dialog, and you can choose Automatically Drop so that the staging repository is cleaned up after the release completes.

The time this process takes can vary a bit. If you get lucky, your artifact will show up on MavenCentral in 10-15 minutes, but it could also take an hour or more in other cases. You can check whether your artifact is available by going to https://repo1.maven.org/maven2/ and browsing for it.

For example, for our client, we can keep refreshing the following page to see if the new version is there: https://repo1.maven.org/maven2/io/getstream/stream-chat-android-client/.

If you see the package via those links, Gradle will also be able to pull it if mavenCentral() is added as a repository and you add your library as a dependency.

Search indexing is a separate, even longer process, so it can take about two hours for your artifact to show up on search.maven.org.

If this was your first release, you should at this point go back and comment on your original Jira issue, to let them know that your repository setup and publication is working.

Automating Sonatype actions

That was quite the adventure! To make things smoother for subsequent releases, you can automate the entire release flow with the publishing plugin that you already have configured in the project.

This, in theory, would mean that you don’t have to revisit the Sonatype UI ever again. In practice, you’ll do that more often than you’d like when the plugin (really, the Sonatype API it calls) breaks or misbehaves, so it's worth being familiar with.

The plugin provides a Gradle task that you can use to close and then release your staging repository with one simple call:

gradlew closeAndReleaseSonatypeStagingRepository

At this point, you can upload and publish your library by just invoking these two Gradle tasks in sequence - pretty convenient! As a final step, let’s hook this into a CI pipeline.

Continuous integration

Since the library is hosted on GitHub anyway, we use GitHub Actions for running the publication Gradle tasks automatically. Whatever CI solution you’re using, setting up publication with it will consist of two main steps:

Getting your secret variables in place.
Invoking the two Gradle tasks.

Your secret variables - for the list of these, look at the publishing script again - can simply go into Repository secrets (Add each of these by going to Settings -> Secrets within your GitHub repository):

Now, let’s create the GitHub Actions workflow that will put all of this together. The configuration for this will go in the .github/workflows/publish.yml file of the repository. This publish workflow will run every time a new release is created in the repository (you can also change the triggers to run when a tag is created, for example). Again, see the inline comments for some explanation of what each step does.

If you’re new to GitHub Actions, check out their introductory documentation first.

name: Publish

on:
  release:
    # We'll run this workflow when a new GitHub release is created
    types: [released]

jobs:
  publish:
    name: Release build and publish
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v2
      - name: Set up JDK 11
        uses: actions/setup-java@v2
        with:
          distribution: adopt
          java-version: 11

        # Builds the release artifacts of the library
      - name: Release build
        run: ./gradlew :stream-chat-android-client:assembleRelease

        # Generates other artifacts (javadocJar is optional)
      - name: Source jar and dokka
        run: ./gradlew androidSourcesJar javadocJar

        # Runs upload, and then closes & releases the repository
      - name: Publish to MavenCentral
        run: ./gradlew publishReleasePublicationToSonatypeRepository --max-workers 1 closeAndReleaseSonatypeStagingRepository
        env:
          OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
          OSSRH_PASSWORD: ${{ secrets.OSSRH_PASSWORD }}
          SIGNING_KEY_ID: ${{ secrets.SIGNING_KEY_ID }}
          SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}
          SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
          SONATYPE_STAGING_PROFILE_ID: ${{ secrets.SONATYPE_STAGING_PROFILE_ID }}

MavenCentral uploads tend to be… Flaky, to put it nicely. Here are some recommendations to have fewer issues with them:

Perform all your Gradle upload tasks in a single job, on a single machine.
The --max-workers 1 option used above guarantees that the upload task runs on a single thread, even if parallel builds are otherwise configured.
It’s also a good idea to put the upload task (all of them, if you’re uploading multiple modules’ worth of artifacts) in a different Gradle invocation than the assemble & signing tasks, as you see it done above, so that they run closely together.

If a long time passes between your upload calls, or if they originate from different CI machines, you might see problems such as multiple staging repositories being created for you on Sonatype with your files scattered all over them.

Even if you do everything described above right, you might still get random upload errors, or timeouts either during the upload or while the plugin is trying to close and release the repository. At this point, being able to look at the staging repository on the Sonatype UI and manually closing/dropping/releasing repositories will come in handy to fix things up.

If your staging repository seems okay (has correct contents), and it just failed to close, you can close and release it yourself. If it looks messed up somehow, or you ended up with multiple staging repositories, it’s best to drop them all and then run the upload workflow again.

Reminder: our up-to-date publishing workflow is always available in our GitHub repository.

Conclusion

Well, that was quite a journey. We hope that this detailed guide helped you get up and running with MavenCentral publication. You can follow us on Twitter @getstream_io for more great technical content - please tweet at us if you've successfully set up publishing following these steps! You can also reach the author @zsmb13 if you have any questions.

If you're looking for a Kotlin-first, powerful Chat SDK to use in your Android app, check out our Android documentation and our Android Chat tutorial.

If you're interested in library development, you'll find these articles helpful as well:

Pi Practice App in Compose

Márton Braun — Mon, 19 Apr 2021 07:48:27 +0000

This article was originally planned for 🥧 Pi Day, and it clearly ran more than a month late. However, it's finally complete!

Concept

This project is once again one of my older projects revived with Jetpack Compose. A couple years ago, I wrote an app that lets you practice and learn the digits of pi - always a fun thing to spend your commute on.

I'm rather rusty now and down to knowing about ~60 digits. How high can you score in the app? Tweet at me @zsmb13!

The app is still available in its original form on the Google Play Store for your pi practicing pleasure. Its sources are also available on GitHub.

If you take a look at the repository, you'll find something rather interesting in its dependencies. It uses Anko Layouts to render some parts of its UI! This was an early, now deprecated and abandoned attempt by JetBrains to create declarative Android UI with Kotlin DSLs.

In this article, we'll build the app in Compose, and also take a look at what some of the old Anko code looked like when we reach the relevant parts.

The completed app's source code is available on GitHub, so you can browse it freely while reading the article.

Project setup, navigation

The app is rather simple, it consists of just two screens. The main screen contains the field displaying the current progress and the keypad to mash in the digits. The high scores screen displays the best runs you had at the digits of pi (a top 10 list of best attempts).

Navigation setup is simple in MainActivity:

setContent {
    PiPracticeComposeTheme {
        Surface(color = MaterialTheme.colors.background) {
            val navController = rememberNavController()
            NavHost(navController, startDestination = "home") {
                composable("home") {
                    Home(navController)
                }
                composable("highscores") {
                    HighScores(navController)
                }
            }
        }
    }
}

Main screen

The first building block of the main screen will be a composable that displays a button, which can notify us when it was clicked. We'll design this with a bottom-up approach.

@Composable
private fun NumberButton(
    number: Int,
    onClick: (Char) -> Unit,
    modifier: Modifier = Modifier,
) {
    OutlinedButton(
        onClick = {
            @OptIn(ExperimentalStdlibApi::class)
            onClick(number.digitToChar())
        },
        modifier = modifier
            .aspectRatio(1f)
            .padding(4.dp),
        border = ButtonDefaults.outlinedBorder.copy(
            brush = SolidColor(MaterialTheme.colors.primary)
        )
    ) {
        Text(
            text = number.toString(),
            fontSize = 30.sp,
            color = MaterialTheme.colors.primary,
        )
    }
}

This NumberButton uses basic Compose concepts, and is based on a material OutlinedButton. It takes a modifier as an optional parameter, following the relevant section of the Jetpack Compose API Guidelines by Google (a must-read if you're writing Compose code).

Keypad

The next step up is assembling a grid of these on the screen, adding a progress indicator in the bottom row, and adding the current value of pi that's been entered in a field on the top of the keypad:

@Composable
private fun KeyPad(
    input: String,
    scrollState: ScrollState, // 1
    onClick: (digit: Char) -> Unit, // 2
) {
    val progress = input.length - 2
    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(8.dp)
    ) {
        Text(
            text = input,
            fontSize = 32.sp,
            modifier = Modifier
                .verticalScroll(scrollState) // 1
                .weight(1f)
                .padding(4.dp),
        )
        Row(Modifier.fillMaxWidth()) {
            NumberButton(number = 1, onClick, Modifier.weight(1f))
            NumberButton(number = 2, onClick, Modifier.weight(1f))
            NumberButton(number = 3, onClick, Modifier.weight(1f))
        }
        Row(Modifier.fillMaxWidth()) {
            NumberButton(number = 4, onClick, Modifier.weight(1f))
            NumberButton(number = 5, onClick, Modifier.weight(1f))
            NumberButton(number = 6, onClick, Modifier.weight(1f))
        }
        Row(Modifier.fillMaxWidth()) {
            NumberButton(number = 7, onClick, Modifier.weight(1f))
            NumberButton(number = 8, onClick, Modifier.weight(1f))
            NumberButton(number = 9, onClick, Modifier.weight(1f))
        }
        Row(Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
            NumberButton(number = 0, onClick, Modifier.weight(1f))
            Text( // 3
                text = stringResource(id = R.string.current_progress, progress),
                modifier = Modifier.weight(2f),
                textAlign = TextAlign.Center,
                fontSize = 18.sp,
            )
        }
    }
}

This code is a bit wordy, but it mostly just creates all the rows of buttons we'll need, and aligns them using weight modifiers. Let's review some of the other interesting bits:

We'll make the top Text that displays the current value of pi scrollable, as we'd eventually run out of space while practicing. This is easily done by using the verticalScroll modifier. Note how the scroll state is hoisted to the containing function, which will let it control it externally.
All number button clicks are passed to the same onClick event listener.
We use the stringResource function to access Android string resources to make the few UI strings we have translatable.

This is what we built so far:

Game logic

Now it's time to add the main game logic.

@Composable
private fun PiPad() {
    val pi = stringResource(R.string.pi) // 1

    val scope = rememberCoroutineScope()

    // 2
    var input by remember { mutableStateOf("3.") }
    val scrollState = rememberScrollState()

    // 3
    var showDialog by remember { mutableStateOf(false) }
    var lastInput by remember { mutableStateOf('-') }

    fun reset() {
        input = "3."
        lastInput = '-'
        showDialog = false
    }

    KeyPad(
        input = input,
        scrollState = scrollState,
        onClick = { digit -> // 4
            val indexToTest = input.length
            val correctDigit = pi[indexToTest]

            lastInput = digit

            if (digit == correctDigit) {
                // 5
                input += digit.toString()
                scope.launch {
                    delay(100)
                    scrollState.animateScrollTo(scrollState.maxValue)
                }
            } else {
                // 6
                val decimalReached = input.length - 2
                ScoreKeeper.logScore(decimalReached)

                showDialog = true
            }
        }
    )

    if (showDialog) {
        val length = input.length

        EndOfGameDialog(onDismiss = { reset() }) {
            // 7
            Column {
                Text(stringResource(R.string.dialog_decimal_reached, length - 2))
                Text(stringResource(R.string.dialog_digit_info, lastInput, pi[length]))
                Text(stringResource(R.string.dialog_next_digits, pi.substring(length, length + 10)))
            }
        }
    }
}

This is quite a bit of code, but most of it is simple, and it handles all of the game logic for us!

The true value of pi comes from string resources.
The current value that the player has progressed to is always in the input variable. We also create the scroll state of the view that will display this value on the top of the screen here.
When the game ends, we'll show a dialog. This requires us to remember the last input digit, and to keep track of whether we need to show the dialog or not.
We instantiate a KeyPad, and in its onClick listener, we implement all of the game logic.
If the player inputs the correct digit, we'll add it to the input, and make sure the view displaying it is scrolled to the bottom.
If the player makes an error, we log the score they reached, and then display the end-of-game dialog.
The dialog's content is passed in with the content lambda convention.

ScoreKeeper is a relatively boring Kotlin object that reads/writes a file to keep track of the high scores. You can check out its implementation in the GitHub repository.

Displaying a dialog

The EndOfGameDialog function used above is a wrapper around AlertDialog, implemented like so:

@Composable
private fun EndOfGameDialog(
    onDismiss: () -> Unit,
    content: @Composable () -> Unit,
) {
    AlertDialog(
        onDismissRequest = onDismiss,
        title = {
            Text(stringResource(R.string.dialog_game_over_title))
        },
        text = content,
        confirmButton = {
            Button(onClick = onDismiss) {
                Text(stringResource(R.string.dialog_ok))
            }
        },
    )
}

This dialog was one of the parts implemented with Anko in the original app, which looked like this - quite familiar and easy to read!

alert {
    customView {
        verticalLayout {
            padding = dip(24)

            textView {
                text = getString(R.string.decimal_reached, indexReached)
                textSize = 16f
            }
            textView {
                text = getString(R.string.digit_info, digit, correctDigit)
                textSize = 16f
            }
            textView {
                val nextDigit = indexReached + 1
                text = getString(R.string.next_digits, digitsToShow,
                        pi.substring(nextDigit, nextDigit + digitsToShow))
                textSize = 16f
            }
        }

        positiveButton(getString(R.string.OK)) { resetState() }
        onCancelled { resetState() }
    }
}.show()

As the final touch for the main screen, we'll add a toolbar on top to display the app name and provide navigation to the second screen.

@Composable
fun Home(navController: NavController) {
    Scaffold(topBar = {
        TopAppBar(
            title = { Text("Pi") },
            actions = {
                IconButton(onClick = { navController.navigate("highscores") }) {
                    Icon(
                        Icons.Default.Star,
                        stringResource(R.string.content_description_high_scores)
                    )
                }
            }
        )
    }) {
        PiPad()
    }
}

This now shows up on the top of our screen:

High scores

The high scores screen is extremely simple, it will display just a toolbar and a list of values. Before we see the Compose implementation, here's the original Anko code for this screen:

verticalLayout {
    padding = dip(16)
    verticalGravity = Gravity.CENTER

    tableLayout {
        tableRow {
            horizontalGravity = Gravity.CENTER
            cell("# ") // 2
            cell(getString(R.string.Score)) // 2
        }

        ScoreKeeper.scores.forEachIndexed { index, score -> // 1
            tableRow {
                horizontalGravity = Gravity.CENTER
                cell("${index + 1}.") // 2
                cell(score.toString()) // 2
            }
        }
    }
}

The rows of the table are created with a simple forEachIndexed loop - a huge advantage and convenience of writing declarative layouts in Kotlin, having all the language features and constructs like the collection APIs available.

Each row here was assembled by calls to the cell function, an extension I added on the receiver scope of the Anko tableRow function - the oddly named _TableRow type.

private fun _TableRow.cell(text: String) {
    textView(text) {
        padding = dip(4)
        textSize = 20f
    }
}

The Compose syntax for this screen will yet again be very similar to the Anko based approach. We'll set up a toolbar much like on the main screen, and then add a header and some items underneath in a loop.

@Composable
fun HighScores(navController: NavController) {
    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(stringResource(R.string.high_scores_title)) },
                navigationIcon = {
                    IconButton(onClick = { navController.popBackStack() }) {
                        Icon(Icons.Default.ArrowBack, null)
                    }
                },
            )
        }
    ) {
        Column(
            modifier = Modifier
                .fillMaxSize()
                .padding(32.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
        ) {
            Header(Modifier.width(120.dp))

            ScoreKeeper.scores.forEachIndexed { index, score ->
                ScoreItem(index + 1, score, Modifier.width(120.dp))
            }
        }
    }
}

The Header and the ScoreItem composables are extremely similar, they'll just use slightly different text styling. Here's just the latter of them:

@Composable
private fun ScoreItem(
    index: Int,
    score: Int,
    modifier: Modifier = Modifier,
) {
    Row(modifier) {
        Text(
            text = "${index}.",
            textAlign = TextAlign.Start,
            modifier = Modifier.weight(1f),
        )
        Text(
            text = score.toString(),
            textAlign = TextAlign.Center,
            modifier = Modifier.weight(2f),
        )
    }
}

Ta-da, now we can display the high scores in the app:

Wrap-up

That's it for now! Thanks for following along with another Compose article. You can find the completed project on GitHub to play around with it and see the rest of the code that I omitted from the article.

If you liked this project, you'll also like these other ones:

Prime Table Generator in Jetpack Compose

Márton Braun — Thu, 25 Mar 2021 17:11:09 +0000

It's been more than 6 years since I wrote an original version of this prime table generator. That was back at the very beginning of my coding career, after learning C and SDL in the first semester of university. An archived version of that original project is available here, including the sources, 120 lines of excellent C code.

Premise

Recapping from the article linked above briefly: the point of this project is to create a visually pleasing and concise representation of prime numbers. The original, on-paper version contained prime numbers up to 4000, and looked like this:

How does it work? Each square represents a block of ten numbers. Since primes (above 2) may only end on the digits 1, 3, 7, or 9, each corner of the square can indicate whether or not a given ending digit is a prime within the 10 number wide block.

As an example, the third block of the table corresponds to the numbers 21-30, and the two connected corners indicate that only 23 and 29 are primes within this range.

Now, let's get to coding this for Android!

You can find the code for the completed project on GitHub.

Creating a grid

In the previous Jetpack Compose article on this blog, we created an animated clock with a bottom-up approach. This time, we'll design things top-down, and start with rendering a grid in Compose. For this, we'll use the experimental LazyVerticalGrid APIs.

@OptIn(ExperimentalFoundationApi::class)
@Composable
fun Primes() {
    LazyVerticalGrid(
        modifier = Modifier // 1
            .fillMaxSize()
            .background(Color(0xFFE53935))
            .padding(8.dp),
        cells = GridCells.Fixed(10), // 2
    ) {
        items(count = 100) { // 3
            Box( 
                Modifier // 4
                    .aspectRatio(1f)
                    .padding(1.dp)
                    .background(Color.DarkGray)
            )
        }
    }
}

Breaking down the code above:

The LazyVerticalGrid composable fills the entire screen, has a red background, and a small bit of padding.
It displays a grid with a fixed number of columns.
The grid contains 100 items.
Each item is a simple Box for a start, which is constrained to be a square shape, has a bit of padding, and a dark background colour.

Note how we had to opt-in to using the experimental API with the @OptIn annotation, which also requires some additional project-level configuration to enable it. You can read more about this language feature in Mastering API Visibility in Kotlin.

Running the code above renders the (scrollable) grid of squares:

A single square

Let's refactor this a bit, and create a PrimeSquare composable for each item of the grid. This will receive the current offset that it should render prime numbers for.

@OptIn(ExperimentalFoundationApi::class)
@Composable
fun Primes() {
    LazyVerticalGrid(...) {
        items(count = 100) { index ->
            PrimeSquare(offset = index * 10)
        }
    }
}

@Composable
fun PrimeSquare(offset: Int) {
    Box(
        Modifier
            .aspectRatio(1f)
            .padding(1.dp)
            .background(Color.DarkGray)
    ) {
        CornerLine()
    }
}

For the content of a single PrimeSquare, we'll render just one line from the top left corner to the center, with our own CornerLine composable. We can do this in Compose using the Canvas API:

@Composable
fun CornerLine() {
    Canvas(Modifier.fillMaxSize()) {
        drawLine(
            color = Color.White,
            start = Offset.Zero,
            end = Offset(size.width / 2, size.height / 2),
            strokeWidth = 2.dp.toPx(),
        )
    }
}

This gives us the following look - a good start!

Rotating and stacking squares

To get this line into the correct corner, we can rotate the canvas while drawing on it. A simple rotate function call takes care of this for us. We'll take the rotation amount as a parameter to CornerLine.

@Composable
fun CornerLine(degrees: Float) {
    Canvas(Modifier.fillMaxSize()) {
        rotate(degrees) {
            drawLine(
                color = Color.White,
                start = Offset.Zero,
                end = Offset(size.width / 2, size.height / 2),
                strokeWidth = 2.dp.toPx(),
            )
        }
    }
}

To make things super easy, we'll create a named composable for each corner, with the appropriate rotation:

@Composable fun One() = CornerLine(degrees = 0f)
@Composable fun Three() = CornerLine(degrees = -90f)
@Composable fun Seven() = CornerLine(degrees = -180f)
@Composable fun Nine() = CornerLine(degrees = -270f)

We'll have to know which number is a prime, for this we'll go with a very basic implementation.

fun Int.isPrime(): Boolean {
    if (this < 2) return false
    return (2 until this).none { this % it == 0 }
}

Have a shorter implementation for this that's at least as correct for checking primes? Tweet it at me!

Now that we can check whether a number's a prime and can draw lines into each corner, we can implement PrimeSquare trivially:

@Composable
fun PrimeSquare(offset: Int) {
    Box(
        Modifier
            .aspectRatio(1f)
            .padding(1.dp)
            .background(Color.DarkGray)
    ) {
        if ((offset + 1).isPrime()) One()
        if ((offset + 3).isPrime()) Three()
        if ((offset + 7).isPrime()) Seven()
        if ((offset + 9).isPrime()) Nine()
    }
}

Of course, the way we're stacking Canvases here is not exactly optimal, but it's a good demonstration of how a Box works as a container. If we moved the prime calculations a level lower, we could draw all our lines on a single Canvas for better performance - try doing this as a practice exercise.

Still, our non-optimal implementation works well:

Final touches

There are two issues left here in our rendering, which you can spot if you look closely at the image above.

The ends of the lines drawn extend beyond the grey boxes.
The lines meeting in the middle don't meet as expected.

For the first issue, we can make the Box in the PrimeSquare composable clip to its bounds:

Box(
    Modifier
        .aspectRatio(1f)
        .padding(1.dp)
        .background(Color.DarkGray)
        .clipToBounds()
) { ... }

To make the lines overlap more in the middle, we can draw them just ever so slightly longer - 2f seems to do the trick:

end = Offset(size.width / 2 + 2f, size.height / 2 + 2f),

Running the app again gives us our final result.

Conclusion

Again, the completed source for this project is available on GitHub.

If you're looking for more similar Compose content, check out these articles:

Build an Android Chat app with Jetpack Compose

Márton Braun — Fri, 19 Mar 2021 13:42:18 +0000

Intro and context

In our previous article about Jetpack Compose, we shared our initial impressions and recommended some learning resources. This time, we'll take Compose out for a spin by building a basic chat UI implementation with it!

Stream now provides a Jetpack Compose Chat SDK. Check out the Compose Chat Messaging Tutorial and give it a try today!

Of course, you might be wondering why we're building a Compose Chat app when there's an official Google sample, Jetchat, which is also a chat app using Compose. That sample is a basic UI demo with a small bit of hardcoded data. Here, we're building a real, functional chat app instead that's hooked up to a real-time backend service.

We already ship a UI Components library in our Chat SDK which contains ready-to-go, fully-featured Android Views to drop into your app, along with ViewModels that let you connect them to business logic in just a single line of code. You can check out how that works in our Android Chat Tutorial.

This time, we're going to reuse the ViewModels (and a View) from that implementation, and build our Compose-based UI on top of that. This won't be an ideal scenario, as those ViewModels are designed to work with the Views that they ship with.

Having dedicated support for Compose in the SDK would make this much nicer and simpler, and that's something we'll be working on in the future. However, as you'll see, it's already quite easy to integrate Stream Chat with Jetpack Compose, without any specific support for it!

The project we're building in this article is available on GitHub, feel free to clone the project and play around with it on your own! We recommend getting your own Stream API key for this, which you can do by signing up for a free trial. Stream is free for hobby projects and small companies even beyond the trial - just apply for a free Maker account.

Project setup

To use Jetpack Compose, we'll create our project in the latest Canary version of Android Studio. This contains a project template for Compose apps.

After creating the project, our first step will be to add the Stream UI Components SDK as a dependency, as well as some Jetpack Compose dependencies we need. Some of our dependencies come from Jitpack, so make sure to add that repository in the settings.gradle file:

dependencyResolutionManagement {
    repositories {
        ...
        maven {url "https://jitpack.io" } // Add Jitpack
    }
}

Then, in the module's build.gradle file, replace the dependencies block with the following:

dependencies {
    // Stream Chat UI Components
    implementation "io.getstream:stream-chat-android-ui-components:4.8.1"

    // Google / Jetpack dependencies
    implementation "androidx.compose.runtime:runtime:$compose_version"
    implementation "androidx.compose.runtime:runtime-livedata:$compose_version"
    implementation 'androidx.core:core-ktx:1.3.2'
    implementation 'androidx.appcompat:appcompat:1.2.0'
    implementation 'com.google.android.material:material:1.3.0'
    implementation "androidx.compose.ui:ui:$compose_version"
    implementation "androidx.compose.material:material:$compose_version"
    implementation "androidx.compose.ui:ui-tooling:$compose_version"
    implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.3.0'
    implementation "androidx.navigation:navigation-compose:1.0.0-alpha10"
    implementation 'androidx.activity:activity-compose:1.3.0-alpha06'
    implementation 'androidx.lifecycle:lifecycle-viewmodel-compose:1.0.0-alpha04'
}

Check out the GitHub project if you get tangled up in the dependencies.

Next, we'll set up the Stream Chat SDK, providing an API key and user details to it. This is normally done in your custom Application class. To make things simple, we'll use the same environment and user as our tutorial.

class ChatApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        val client = ChatClient.Builder(appContext = this, apiKey = "b67pax5b2wdq").build()

        val user = User().apply {
            id = "tutorial-droid"
            image = "https://bit.ly/2TIt8NR"
            name = "Tutorial Droid"
        }

        ChatDomain.Builder(client, this)
            .offlineEnabled()
            .build()

        client.connectUser(
            user,
            "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidHV0b3JpYWwtZHJvaWQifQ.NhEr0hP9W9nwqV7ZkdShxvi02C5PR7SJE7Cs4y7kyqg"
        ).enqueue()
    }
}

We're initializing all three layers of our SDK here: the low-level client, the domain providing offline support, and the UI components. For more info about these, take a look at the documentation. Finally, we're connecting our user, using a hardcoded, non-expiring example token from the tutorial.

Since we created a custom Application class, we have to update our Manifest to use this ChatApplication when the app is launched. We'll also set windowSoftInputMode on the MainActivity so that we'll have better keyboard behaviour later on.

<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
    <application
        android:name=".ChatApplication"
        ...>
        <activity
            android:name=".MainActivity"
            ...
            android:windowSoftInputMode="adjustResize">
            ...
        </activity>
    </application>
</manifest>

Channel List Screen

First, we'll create a screen that lists the channels available to our user. The UI Components library contains a ChannelListView component for this purpose, and we can reuse its ViewModel here.

@Composable
fun ChannelListScreen(
    channelListViewModel: ChannelListViewModel = viewModel( // 1
        factory = ChannelListViewModelFactory()
    ),
) {
    val state by channelListViewModel.state.observeAsState()
    val channelState = state ?: return // 2

    Box( // 3
        modifier = Modifier.fillMaxSize(),
        contentAlignment = Alignment.Center,
    ) {
        if (channelState.isLoading) {
            CircularProgressIndicator() // 4
        } else {
            LazyColumn(Modifier.fillMaxSize()) { // 5
                items(channelState.channels) { channel ->
                    ChannelListItem(channel)
                    Divider()
                }
            }
        }
    }
}

Let's see what this code does step-by-step:

We use the viewModel() method provided by Compose to get a ViewModel for our current context. This allows us to specify a factory that creates a ViewModel, which we need in the case of ChannelListViewModel to pass in some parameters to it. We'll stick to the default parameters of the SDK's ChannelListViewModelFactory for now, which will filter for channels that our current user is a member of.
We observe the LiveData state in the ViewModel as a composable State, and we copy it to a local variable so that smart casts will work on it correctly. We also skip rendering anything if this State happens to be null.
We'll have the ChannelListScreen fill the entire screen, and center any content inside it.
If the state is loading, we'll display a basic progress indicator.
Otherwise, we'll display the list of channels in a LazyColumn. Each item will be a ChannelListItem responsible for showing info for a single channel. We're also adding a simple Divider after each item.

Now, let's see how we can render a single ChannelListItem in the list:

@Composable
fun ChannelListItem(channel: Channel) {
    Row( // 1
        modifier = Modifier
            .padding(horizontal = 8.dp, vertical = 8.dp)
            .fillMaxWidth(),
        verticalAlignment = Alignment.CenterVertically
    ) {
        Avatar(channel) // 2
        Column(modifier = Modifier.padding(start = 8.dp)) { // 3
            Text(
                text = channel.getDisplayName(LocalContext.current),
                style = TextStyle(fontWeight = FontWeight.Bold),
                fontSize = 18.sp,
            )

            val lastMessageText = channel.messages.lastOrNull()?.text ?: "..."
            Text(
                text = lastMessageText,
                maxLines = 1,
                overflow = TextOverflow.Ellipsis,
            )
        }
    }
}

We're rendering each item as a Row.
Inside that, we're adding an Avatar representing the Channel at the start.
Then we add a Column, laying out two pieces of Text vertically. These will contain the channel's title and a preview of the latest message. Note the LocalContext.current API being used to grab a Context in Compose, as well as the TextOverflow.Ellipsis option that will make long messages behave nicely in the preview.

We have one last Composable to implement, the Avatar used above. Our UI components SDK ships an AvatarView with complex rendering logic inside it, which we don't want to reimplement for now. We can use Jetpack Compose's interop features to include our regular Android View inside Compose UI.

This will be really simple, just a few lines of code to create a wrapper:

@Composable
fun Avatar(channel: Channel) {
    AndroidView(
        factory = { context -> AvatarView(context) },
        update = { view -> view.setChannelData(channel) },
        modifier = Modifier.size(48.dp)
    )
}

The AndroidView function allows us to create... Well, an Android View, which we get a Context for. It also gives us a way to hook into Compose's state updates using its update parameter, which will be executed whenever composable state (in our case, the Channel object) changes. When that happens, we set the new Channel on our AvatarView.

Finally, we can add the ChannelListScreen to MainActivity:

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            ComposeChatTheme {
                Surface(color = MaterialTheme.colors.background) {
                    ChannelListScreen()
                }
            }
        }
    }
}

Building and running this code gives us a working list of channels loaded from Stream's backend, with performant scrolling thanks to LazyColumn. Not bad for a hundred lines of code for the entire thing!

Setting up navigation

Continuing with our chat app, let's create a new screen, where we'll display the list of messages in a channel. For this, we'll need to set up click listeners and navigation. We'll use the Navigation Component for Jetpack Compose here.

Step one, we'll make our ChannelListItem clickable, and add an onClick parameter that it will call when it was clicked:

@Composable
fun ChannelListItem(
    channel: Channel,
    onClick: (channel: Channel) -> Unit, // New callback parameter
) {
    Row(
        modifier = Modifier
            .clickable { onClick(channel) } // Add clickablity
            .padding(horizontal = 8.dp, vertical = 8.dp)
            .fillMaxWidth(),
        ...
    ) { ... }
}

ChannelListScreen will take a NavController as its parameter, and use it to navigate to a new destination when an item was clicked, based on the cid of the channel.

@Composable
fun ChannelListScreen(
    navController: NavController, // New parameter
    channelListViewModel: ChannelListViewModel = viewModel(
        factory = ChannelListViewModelFactory()
    ),
) {
    ...
        items(channelState.channels) { channel ->
            ChannelListItem(
                channel = channel,
                onClick = { navController.navigate("messagelist/${channel.cid}") },
            )
            Divider()
        }
    ...
}

We'll update MainActivity by moving our top-level Composable code to a ChatApp composable, and setting up navigation in there.

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            ComposeChatTheme {
                Surface(color = MaterialTheme.colors.background) {
                    ChatApp()
                }
            }
        }
    }
}

@Composable
fun ChatApp() {
    val navController = rememberNavController() // 1
    NavHost(navController, startDestination = "channellist") {
        composable("channellist") { // 2
            ChannelListScreen(navController = navController)
        }
        composable("messagelist/{cid}") { backStackEntry -> // 3
            MessageListScreen(
                navController = navController,
                cid = backStackEntry.arguments?.getString("cid")!!
            )
        }
    }
}

We're creating a NavController and a NavHost for our application.
Our first and initial destination is a composable: ChannelListScreen. We pass the nav controller to it.
Our second destination will be a new composable called MessageListScreen. Here, we pass in both the nav controller and the argument that was used to navigate to it. We can grab this from the NavBackStackEntry parameter.

Message List Screen

Our message list will be a LazyColumn similar to the channel list we created before. For displaying messages, the UI Components library gives us a MessageListViewModelFactory which can create a few different ViewModel instances. This takes the cid of the channel we want to display.

@Composable
fun MessageListScreen(
    navController: NavController,
    cid: String,
) {
    val factory = MessageListViewModelFactory(cid)
    MessageList(
        navController = navController,
        factory = factory,
    )
}

We'll implement the MessageList like this:

@Composable
fun MessageList(
    navController: NavController,
    factory: MessageListViewModelFactory,
    modifier: Modifier = Modifier,
    messageListViewModel: MessageListViewModel = viewModel(factory = factory), // 1
) {
    val state by messageListViewModel.state.observeAsState() // 2
    val messageState = state ?: return

    Box(
        modifier = modifier,
        contentAlignment = Alignment.Center
    ) {
        when (messageState) { // 3
            is MessageListViewModel.State.Loading -> {
                CircularProgressIndicator()
            }
            is MessageListViewModel.State.NavigateUp -> {
                navController.popBackStack()
            }
            is MessageListViewModel.State.Result -> {
                val messageItems = messageState.messageListItem.items // 4
                    .filterIsInstance<MessageListItem.MessageItem>()
                    .filter { it.message.text.isNotBlank() }
                    .asReversed()

                LazyColumn(
                    modifier = Modifier.fillMaxSize(),
                    reverseLayout = true, // 5
                ) {
                    items(messageItems) { message ->
                        MessageCard(message) // 6
                    }
                }
            }
        }
    }
}

Let's review:

We get a MessageListViewModel from the factory, which will fetch messages for us, and expose it as LiveData.
As before, we convert the LiveData state from the ViewModel into composable State.
We have three states to handle, defined by a sealed class inside MessageListViewModel. The first state is a loading state, the second is a state that pushes us to the previous screen (using the nav controller), and the third is the result state, where we have a list of messages.
In the result state, we'll grab the list of messages received, filter for only MessageItems (excluding things such as date separators that we don't want to render for now). We also filter for messages that have non-blank text - for example, some messages might have only images attached to them, so we'll skip those for simplicity. Finally, we reverse the list, to match what we're doing in the next step.
We use reverseLayout on LazyColumn to stack its items from the bottom. This is similar to using stackFromEnd on a RecyclerView.
Each item will be rendered by a MessageCard composable.

For a single message, we'll use the following layout:

@Composable
fun MessageCard(messageItem: MessageListItem.MessageItem) { // 1
    Column(
        modifier = Modifier
            .fillMaxWidth()
            .padding(horizontal = 8.dp, vertical = 4.dp),
        horizontalAlignment = when { // 2
            messageItem.isMine -> Alignment.End
            else -> Alignment.Start
        },
    ) {
        Card(
            modifier = Modifier.widthIn(max = 340.dp),
            shape = cardShapeFor(messageItem), // 3
            backgroundColor = when {
                messageItem.isMine -> MaterialTheme.colors.primary
                else -> MaterialTheme.colors.secondary
            },
        ) {
            Text(
                modifier = Modifier.padding(8.dp),
                text = messageItem.message.text,
                color = when {
                    messageItem.isMine -> MaterialTheme.colors.onPrimary
                    else -> MaterialTheme.colors.onSecondary
                },
            )
        }
        Text( // 4
            text = messageItem.message.user.name,
            fontSize = 12.sp,
        )
    }
}

@Composable
fun cardShapeFor(message: MessageListItem.MessageItem): Shape {
    val roundedCorners = RoundedCornerShape(16.dp)
    return when {
        message.isMine -> roundedCorners.copy(bottomEnd = CornerSize(0))
        else -> roundedCorners.copy(bottomStart = CornerSize(0))
    }
}

This code is mostly straightforward, but let's review some of its important bits:

We take a MessageItem as a parameter.
Depending on whether this is our current user's message, or someone else's, we align it to one of the sides of the screen. We also set colours based on this in a few places.
We use a cardShapeFor helper method to create the shape of the Card that holds the message. This will create a shape with rounded corners, except for one of the bottom corners, giving us a chat bubble look.
We display the username under each message, so that we can distinguish between messages sent by others.

At this point, we can build and run again, and clicking a channel will navigate to the new screen, displaying the list of messages in it.

Message Input

For our final piece of Jetpack Compose chat implementation, we'll add an input view on the message list screen so that we can send new messages.

First, we'll modify MessageListScreen and place a new composable under MessageList:

@Composable
fun MessageListScreen(
    navController: NavController,
    cid: String,
) {
    Column(Modifier.fillMaxSize()) {
        val factory = MessageListViewModelFactory(cid)

        MessageList(
            navController = navController,
            factory = factory,
            modifier = Modifier.weight(1f),
        )
        MessageInput(factory = factory)
    }
}

The weight modifier on MessageList will make it take up the maximum available space above the new MessageInput. We pass in the factory to MessageInput as well, so that it's able to access the currently open channel's data via ViewModels.

@Composable
fun MessageInput(
    factory: MessageListViewModelFactory,
    messageInputViewModel: MessageInputViewModel = viewModel(factory = factory), // 1
) {
    var inputValue by remember { mutableStateOf("") } // 2

    fun sendMessage() { // 3
        messageInputViewModel.sendMessage(inputValue)
        inputValue = ""
    }

    Row {
        TextField( // 4
            modifier = Modifier.weight(1f),
            value = inputValue,
            onValueChange = { inputValue = it },
            keyboardOptions = KeyboardOptions(imeAction = ImeAction.Send),
            keyboardActions = KeyboardActions { sendMessage() },
        )
        Button( // 5
            modifier = Modifier.height(56.dp),
            onClick = { sendMessage() },
            enabled = inputValue.isNotBlank(),
        ) {
            Icon( // 6
                imageVector = Icons.Default.Send,
                contentDescription = stringResource(R.string.cd_button_send)
            )
        }
    }
}

This time, we'll use a MessageInputViewModel, which normally belongs to the MessageInputView shipped in the UI components library, and handles input actions.
We create a piece of composable state to hold the current input value.
This local helper function calls into the ViewModel and sends the message to the server. Then, it clears the input field by resetting the state.
We use a TextField to capture user input. This displays the current inputValue, and modifies it based on keyboard input. We also set up IME options so that our software keyboard displays a Send button, and we handle that being tapped by calling sendMessage.
We're also adding a Button that the user can tap to send a message. This is enabled/disabled dynamically based on the current input value.
The button will show an icon from the default Material icon set. Not to skimp on accessibility, we also add a content description string for the send icon. We grab this from regular Android resources using stringResource, which allows us to localize it as usual. Make sure to create this resource in your project.

Let's build and run for the last time, and we have a working chat app now! We can browse channels, open them, read messages, and send new messages.

Conclusion

This complete implementation, including UI, logic, and a connection to a real server is roughly 250 lines of code in total. Almost all of this is UI code with Jetpack Compose, the integration with Stream Chat's ViewModels and Views is just a small fraction of it.

Follow us on Twitter @getstream_io, and the author @zsmb13 for more content like this. If you liked this tutorial, tweet at us and let us know!

As a reminder, you can check out the full project and play with it on GitHub. We recommend expanding this project to learn more about Compose - a good first goal could be to add a login screen, so that you can have different users on different devices.

To jump into that, sign up for a free trial of Stream Chat. If you're doing this for a side project or you're a small business, you can use our SDK for with a free Maker account, even beyond the trial period!

Here are some more useful links to continue exploring:

The Stream Chat Android SDK on GitHub, including the UI Components Sample app that showcases many features, and includes a login implementation you can take ideas from
Our regular, non-Compose Android Tutorial
The Stream Chat Android documentation
For more about Compose, some first impressions and recommended learning resources

Originally published on getstream.io/blog.

Jetpack Compose: First Impressions and Learning Resources

Márton Braun — Fri, 05 Mar 2021 18:28:56 +0000

As you most certainly already know, Jetpack Compose is the hot new thing for Android UI development. Its promise is to save us by making all the pain points of the old View system and XML layouts go away.

Stream now provides a Jetpack Compose Chat SDK. Check out the Compose Chat Messaging Tutorial and give it a try today!

After many many preview versions, it got to beta status about a week ago. Here's what it's like to use Compose at the moment, and some of the best places to learn more about it.

The good

First of all, Compose is exciting. It makes a lot of basic UI work really simple, and you get to write it all in Kotlin, making use of all the language's powerful features! The APIs have great discoverability in Android Studio, since all of it is just Kotlin code that you can access via code completion. This makes it truly easy to get started.

Kotlin's type safety also works wonders in Compose. No passing in dp values instead of pixels, or mixing up vertical and horizontal alignment options. Everything is strongly typed, and the compiler safeguards you from making many, many mistakes.

The declarative style and state management of Compose are great as well. Writing down what you want to appear based on state is not only clear and explicit, but also a blessing after the problematic state management of the View system.

Given how much effort is going into developing and marketing Compose, it's almost certainly the future of Android UI development. That being said, the XML system will probably never fully go away. Just like the Java to Kotlin shift, it will take a couple years until the new standard really kicks in, and we'll occasionally still find ourselves interacting with code from the before times.

So... Get on board soon, just don't expect all of the old system to disappear overnight. I'd certainly still suggest learning the old XML-based system to anyone starting Android Development today - unless they're somehow very certain that they'll never work on an existing project.

Jetpack Compose comes with some cool Android Studio tooling as well. Flutter users will probably already be familiar with the handy Surround with shortcuts that let you wrap pieces of code in a new widget, and the same makes an appearance in Studio now.

Select some code, invoke Surround with (Ctrl+Alt+J on Windows, ⌥⌘J on macOS), and then hit R for a Row, C for a Column, or W for an arbitrary widget.

Another quick tip: creating a new Composable will immediately add a parameter list and a body to it, and then place your cursor inside its parameter list, to let you immediately add modifiers and other parameters.

If you don't want to add any parameters, you can hit Tab to quickly skip to defining its content.

The bad

Now, let's see the bad part, continuing with the tooling theme. To run Compose, you'll have to run the latest Canary version of Android Studio. This version has... Some issues.

From my personal experience of a few days:

IDE Previews (which would be a really nice feature for Compose) sometimes don't load at all, or don't update as changes are made (even after rebuilding). Re-running either the full app or just deploying a @Preview to a device was faster than using the IDE preview feature 100% of the time.
The debugger never connected to either an emulator or a physical device when running Compose apps. Still didn't manage to solve this, though I heard others had more success.
Logcat doesn't show app names when running apps, making it difficult to filter the logs for the current app.
When running the emulator in a tool window inside the IDE, the emulator tab occasionally doesn't appear in the preview version of Studio. I had times when I used the emulator tab inside another project in a stable Android Studio instead... I eventually gave in and reverted to using an emulator in a separate window.
Sometimes Studio just froze up entirely, and its process had to be killed and restarted. This happened about once a day or so.

I heard some similar anecdotal stories from others, including excessive resource usage when using Compose compared to other projects. These were occasionally fixable by restarting, invalidating caches, restarting adb, and similar "usual" debugging practices.

Another pain point of using Jetpack Compose can be that looking up how to do things is a bit hit-and-miss for the time being. For example, when you land on StackOverflow questions about it, you'll often find answers that say "this is how to do it in dev11", or "here's the new API for this in alpha3", but then none of those APIs will be present in the current beta version.

Of course, on one hand it's nice that Compose went through a lot of iteration and they weren't afraid to change and evolve APIs - that's what the preview versions are for.

On the other, it makes for a somewhat unpleasant experience for developers trying to build things on the latest Compose version. Thankfully this situation will naturally improve over time, but we'll have to wait a bit to get enough new, up-to-date answers in.

The resources

Since StackOverflow won't be your best friend for learning Compose yet, where else can you go?

First, there's Google's official resources, which are a decent start:

Their best resource by far is the written documentation pages - get started with them here. These include a lot of helpful explanation and snippets for designing things in Compose, and also touch on more advanced topics like navigation, architecture, and interop with existing code.
There's a lot of video content about Compose as well, under the #AndroidShow branding. I'll recommend skipping most of this, especially the livestream and Q&A parts - they're not really developer-focused, and contain a lot of hype and marketing. What contains a lot of value, however, are their screencasts about Compose features (which are also included in sections of the written docs). You can find these in this YouTube playlist.
If you're new to Compose, the Beta overview video is also worth watching. For more longer-form introductory content, these videos from last year are all really helpful: Jetpack Compose, Thinking in Compose, Compose by example, and Compose for existing apps.
For hands-on practice, take a look at Google's Compose Pathway that includes videos, articles, and code labs. This goes into significant detail in some parts - feel free to skip the things you're not interested in learning deeply immediately, otherwise it'll take a long time to get through it.
- I also found that some of the codelabs here were outdated (not using beta1 APIs yet), so be prepared to fiddle a bit with the code snippets provided, or to debug dependencies. Again, this is something that will be improved soon.

If you prefer reading, RayWenderlich team's Jetpack Compose book has really solid, professional content in it, providing a complete tour for you to get started with: A nice exploration of the basic UI building blocks of Compose, as well as multiple example apps. (This, again, is slightly outdated, as its samples use alpha10. Fingers crossed that it gets a revision soon.)

For even more long-form video explanations, guidance, and demos, Exploring Jetpack Compose and Advanced Jetpack Compose by Filip Babić are both excellent.

To find quick snippets for how to perform basic things, the Compose Academy site can come in handy.

Finally, exploring Compose on your own is also a great way to learn about it. All of the APIs you use are just Kotlin code, so exploring through code completion, and jumping into the underlying implementation in Android Studio to read the source are super easy. The in-code documentation for most Compose APIs also tends to be excellent.

Conclusion

Are you excited and ready for Compose? We know that we are, and you can look forward to more Compose content from us soon, including in our Android Chat SDK.

Tweet at us @getstream_io and tell us what you think about Compose, and what you found to be the most useful way to learn about it!

Originally published on getstream.io/blog.

DEV Community: Márton Braun

The conflation problem of testing StateFlows

Testing StateFlows

Experiencing conflation

Avoiding conflation

Yielding manually

Collecting faster

Conclusion

Adventures in Tracking Upload Progress With OkHttp and Retrofit

Uploading Files With Retrofit

Counting in the Request Body

Counting With a Custom Sink Implementation

The Logging Problem

OkHttp Tags

The last-interceptor-swaparoo

Wrap-Up

All About Opt-In Annotations

Creating Opt-In APIs

Creating an Opt-in Marker Annotation

Marking APIs as Opt-in Required

Using Opt-In APIs

Propagating the Opt-in Requirement

Opting in an Entire Module

Opting in Locally

Use Cases and Conventions

Java Interop

Opt-In on Android

API Verification

Conclusion

A Bit of Gradle Housekeeping

Build tools version

Java version settings

Kotlin JVM target settings

*SdkVersion

The src/main/kotlin source set

Kotlin standard library dependency

Conclusion

Keeping public API in check with the Kotlin binary validator plugin

Core concept

Setup and configuration

Usage

Git hooks and CI checks

Limitations

Conclusion

Publishing Android libraries to MavenCentral in 2021

Introduction

Overview

Prerequisites

Registering a Sonatype account

Generating a GPG key pair

Setting up publication in your project

Root project Gradle configuration

Per-module Gradle setup

Your first release

Automating Sonatype actions

Continuous integration

Conclusion

Pi Practice App in Compose

Concept

Project setup, navigation

Main screen

Keypad

Game logic

Displaying a dialog

High scores

Wrap-up

Prime Table Generator in Jetpack Compose

Premise

Creating a grid

A single square

Rotating and stacking squares

Final touches

Conclusion

Build an Android Chat app with Jetpack Compose

Intro and context

Project setup

Channel List Screen

Setting up navigation

Message List Screen

Message Input

The `src/main/kotlin` source set