Lord Codes » Android & Kotlin Feed

Embed a SearchBar into a TopAppBar in Jetpack Compose

Andrew Lord — Mon, 29 Jan 2024 00:00:00 GMT

For many apps, search is a key part of creating a seamless and intuitive user experience. When it comes to building Android UIs with Compose, this can be achieved using the Material 3 SearchBar. The search bar component allows us to build a bar that, when focused, expands into a search view to display suggestions or search results.

When used as it comes, the SearchBar works nicely by itself and for large screens there is also a DockedSearchBar. Most Android screens, however, include a TopAppBar that has a background colour that changes when content scrolls behind it.

In this article, we will explore how to build a search experience and then how to embed it seamlessly into a TopAppBar. This allows us to create a polished UI that's perfect for including search into any screen.

The problem

As a starting point, we have a screen within our navigation hierarchy showing a list of projects. The projects list includes a TopAppBar containing a navigation icon and title. We would like to be able to search across these projects, using a persistent search bar within the top bar, below the title.

When we add the search bar below our TopAppBar, it is positioned correctly, however it is visually separate from the top bar.

There are various changes we need to make so that it appears within the bar:

Add a surface behind the SearchBar that matches the TopAppBar.
Match the elevation behaviour, when content scrolls behind the TopAppBar.
Apply styling when the SearchBar expands into a search view.

Building a search bar

Let's start by building our SearchBar.

@Composable
@OptIn(ExperimentalMaterial3Api::class)
fun EmbeddedSearchBar(
    onQueryChange: (String) -> Unit,
    isSearchActive: Boolean,
    onActiveChanged: (Boolean) -> Unit,
    modifier: Modifier = Modifier,
    onSearch: ((String) -> Unit)? = null,
) {
    var searchQuery by rememberSaveable { mutableStateOf("") }
    // 1
    val activeChanged: (Boolean) -> Unit = { active ->
        searchQuery = ""
        onQueryChange("")
        onActiveChanged(active)
    }
    SearchBar(
        query = searchQuery,
        // 2
        onQueryChange = { query ->
            searchQuery = query
            onQueryChange(query)
        },
        // 3
        onSearch = onSearch,
        active = isSearchActive,
        onActiveChange = activeChanged,
        // 4
        modifier = modifier
            .padding(start = 12.dp, top = 2.dp, end = 12.dp, bottom = 12.dp)
            .fillMaxWidth(),
        placeholder = { Text("Search") },
        leadingIcon = {
            Icon(
                imageVector = Icons.Rounded.Search,
                contentDescription = null,
                tint = MaterialTheme.colorScheme.onSurfaceVariant,
            )
        },
        // 5
        colors = SearchBarDefaults.colors(
            containerColor = MaterialTheme.colorScheme.surfaceContainerLow,
        ),
        tonalElevation = 0.dp,
    ) {
        // Search suggestions or results
    }
}

When the search bar receives focus it becomes active and expands. At this point we clear the search term and report the active state change via the onActiveChanged function. Note: if we wanted to keep the search term we wouldn't clear it here.
When the query changes we update the search term state and report the change via the onQueryChange function.
The IME search triggers onSearch. For now we are updating results whenever the query changes so are simply deactivating the search mode. If we were using a search API request we would perform the search here instead.
Add our search bar padding, sizing and other modifiers.
Style the search bar appearance, such as background colour.

Position the search bar

The top of the screen is a TopAppBar we have extracted out to ProjectsTopAppBar, which is configured with a back button and title.

Show code for ProjectTopAppBar

@Composable
@OptIn(ExperimentalMaterial3Api::class)
private fun ProjectsTopAppBar(
    onBackClick: () -> Unit,
    modifier: Modifier = Modifier,
    scrollBehavior: TopAppBarScrollBehavior? = null,
) {
    TopAppBar(
        title = { Text("Projects") },
        modifier = modifier,
        navigationIcon = {
            IconButton(onClick = onBackClick) {
                Icon(
                    imageVector = Icons.AutoMirrored.Rounded.ArrowBack,
                    contentDescription = "Back",
                )
            }
        },
        colors = TopAppBarDefaults.topAppBarColors(
            navigationIconContentColor = MaterialTheme.colorScheme.primary,
        ),
        scrollBehavior = scrollBehavior,
    )
}

When using the Material 3 Scaffold we can use a Column to position the SearchBar below the bar.

var isSearchActive by rememberSaveable { mutableStateOf(false) }
val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior()
Scaffold(
    modifier = modifier,
    topBar = {
        Column {
            ProjectsTopAppBar(
                onBackClick = onBackClick,
                scrollBehaviour = scrollBehavior,
            )
            EmbeddedSearchBar(
                onQueryChange = onQueryChange,
                isSearchActive = isSearchActive,
                onActiveChanged = { isSearchActive = it },
            )
        }
    },
) { contentPadding ->
    // Search suggestions or results
}

We now have a SearchBar showing below our TopAppBar, we next need to add a surface behind it so that it appears visually within the TopAppBar.

Surface behind the search bar

The TopAppBar is built with a surface that adapts its container colour based on the scroll behaviour applied to it. We can create a surface to display behind the SearchBar that uses the same styling.

@OptIn(ExperimentalMaterial3Api::class)
@Composable
private fun TopAppBarSurface(
    modifier: Modifier = Modifier,
    // 1
    colors: TopAppBarColors = TopAppBarDefaults.topAppBarColors(),
    // 2
    scrollBehavior: TopAppBarScrollBehavior? = null,
    content: @Composable () -> Unit,
) {
    // 3
    val colorTransitionFraction = scrollBehavior?.state?.overlappedFraction ?: 0f
    val fraction = if (colorTransitionFraction > 0.01f) 1f else 0f
    val appBarContainerColor by animateColorAsState(
        targetValue = lerp(
            colors.containerColor,
            colors.scrolledContainerColor,
            FastOutLinearInEasing.transform(fraction),
        ),
        animationSpec = spring(stiffness = Spring.StiffnessMediumLow),
        label = "TopBarSurfaceContainerColorAnimation",
    )
    Surface(
        modifier = modifier.fillMaxWidth(),
        color = appBarContainerColor,
        content = content,
    )
}

The same TopAppBarColors we used in the ProjectsTopAppBar above should be applied to this surface.
The same TopAppBarScrollBehavior we pass into the TopAppBar should be provided to the surface.
We can animate the container colour based on the scroll behaviour using the same approach as TopAppBar uses internally.

We can now wrap our search bar in the new TopAppBarSurface, passing in the same scroll behaviour.

topBar = {
    Column(verticalArrangement = Arrangement.spacedBy((-1).dp)) {
        ProjectsTopAppBar(
            onBackClick = onBackClick,
            scrollBehavior = scrollBehavior,
        )
        TopAppBarSurface(scrollBehavior = scrollBehavior) {
            EmbeddedSearchBar(
                onQueryChange = onQueryChange,
                isSearchActive = isSearchActive,
                onActiveChanged = { isSearchActive = it },
            )
        }
    }
}

It seems to render with a tiny 1dp gap between the two bars, so spacedBy((-1).dp) is included for vertical arrangement. If anyone can work out the cause of the 1dp gap please reach out.

Active search view styling

When the SearchBar becomes active it expands to form a search view. We need to hide the TopAppBar whilst search is active and also alter its appearance. We will make a few changes to the call to SearchBar(...).

When search is active we need to remove the padding we applied earlier.
We can also animate the content size change to give a clean transition.

modifier = if (isSearchActive) {
    modifier
        .animateContentSize(spring(stiffness = Spring.StiffnessHigh))
} else {
    modifier
        .padding(start = 12.dp, top = 2.dp, end = 12.dp, bottom = 12.dp)
        .fillMaxWidth()
        .animateContentSize(spring(stiffness = Spring.StiffnessHigh))
}

When active, we can replace the leading search icon with a back button to dismiss the search view.

leadingIcon = {
    if (isSearchActive) {
        IconButton(
            onClick = { activeChanged(false) },
        ) {
            Icon(
                imageVector = Icons.AutoMirrored.Rounded.ArrowBack,
                contentDescription = stringResource(R.string.navigation_action_back_cd),
                tint = MaterialTheme.colorScheme.primary,
            )
        }
    } else {
        Icon(
            imageVector = Icons.Rounded.Search,
            contentDescription = null,
            tint = MaterialTheme.colorScheme.onSurfaceVariant,
        )
    }
}

After a query has been entered into the search view, we can show a clear button.

trailingIcon = if (isSearchActive && searchQuery.isNotEmpty()) {
    {
        IconButton(
            onClick = {
                searchQuery = ""
                onQueryChange("")
            },
        ) {
            Icon(
                imageVector = Icons.Rounded.Close,
                contentDescription = stringResource(R.string.search_text_field_clear),
                tint = MaterialTheme.colorScheme.primary,
            )
        }
    }
} else {
    null
}

We can tweak the background colour of the search view when it's active.

colors = SearchBarDefaults.colors(
    containerColor = if (isSearchActive) {
        MaterialTheme.colorScheme.background
    } else {
        MaterialTheme.colorScheme.surfaceContainerLow
    },
)

As the search view is shown instead of the TopAppBar, we need to apply its window insets.

windowInsets = if (isSearchActive) {
    SearchBarDefaults.windowInsets
} else {
    WindowInsets(0.dp)
}

This completes our customisation of the active search view.

Show full EmbeddedSearchBar code

@Composable
@OptIn(ExperimentalMaterial3Api::class)
fun EmbeddedSearchBar(
    onQueryChange: (String) -> Unit,
    isSearchActive: Boolean,
    onActiveChanged: (Boolean) -> Unit,
    modifier: Modifier = Modifier,
    onSearch: ((String) -> Unit)? = null,
) {
    var searchQuery by rememberSaveable { mutableStateOf("") }
    val activeChanged: (Boolean) -> Unit = { active ->
        searchQuery = ""
        onQueryChange("")
        onActiveChanged(active)
    }
    SearchBar(
        query = searchQuery,
        onQueryChange = { query ->
            searchQuery = query
            onQueryChange(query)
        },
        onSearch = onSearch ?: { activeChanged(false) },
        active = isSearchActive,
        onActiveChange = activeChanged,
        modifier = if (isSearchActive) {
            modifier
                .animateContentSize(spring(stiffness = Spring.StiffnessHigh))
        } else {
            modifier
                .padding(start = 12.dp, top = 2.dp, end = 12.dp, bottom = 12.dp)
                .fillMaxWidth()
                .animateContentSize(spring(stiffness = Spring.StiffnessHigh))
        },
        placeholder = { Text("Search") },
        leadingIcon = {
            if (isSearchActive) {
                IconButton(
                    onClick = { activeChanged(false) },
                ) {
                    Icon(
                        imageVector = Icons.AutoMirrored.Rounded.ArrowBack,
                        contentDescription = stringResource(R.string.navigation_action_back_cd),
                        tint = MaterialTheme.colorScheme.primary,
                    )
                }
            } else {
                Icon(
                    imageVector = Icons.Rounded.Search,
                    contentDescription = null,
                    tint = MaterialTheme.colorScheme.onSurfaceVariant,
                )
            }
        },
        trailingIcon = if (isSearchActive && searchQuery.isNotEmpty()) {
            {
                IconButton(
                    onClick = {
                        searchQuery = ""
                        onQueryChange("")
                    },
                ) {
                    Icon(
                        imageVector = Icons.Rounded.Close,
                        contentDescription = stringResource(R.string.search_text_field_clear),
                        tint = MaterialTheme.colorScheme.primary,
                    )
                }
            }
        } else {
            null
        },
        colors = SearchBarDefaults.colors(
            containerColor = if (isSearchActive) {
                MaterialTheme.colorScheme.background
            } else {
                MaterialTheme.colorScheme.surfaceContainerLow
            },
        ),
        tonalElevation = 0.dp,
        windowInsets = if (isSearchActive) {
            SearchBarDefaults.windowInsets
        } else {
            WindowInsets(0.dp)
        }
    ) {
        // Search suggestions or results
    }
}

Wrap up

We have built a SearchBar that appears embedded within a TopAppBar that expands into a full-screen search view when focused. The SearchBar is a very customisible component and Jetpack Compose makes it easy to achieve the design we want. This search bar component can now be used throughout our apps to add search to any screen we want.

Authorization and retrying of web requests for OkHttp and Retrofit

Andrew Lord — Tue, 17 Mar 2020 00:00:00 GMT

Are you trying to set up authorization for your OkHttp or Retrofit web requests but aren't sure of the best way to do it? Have you explored Interceptor and Authenticator but aren't sure which to use or how best to use them? We will explore these concepts within OkHttp, how to sign web requests and also how to retry them if they fail due to a failed authorization attempt.

When setting up networking in our apps, authorization is almost always required, as not many remote APIs are completely un-authenticated. OAuth is a common system to use, relying on access tokens to protect our endpoints and refresh tokens to obtain new access tokens once they have expired. The idea is that the access token is added as an Authorization HTTP header on requests to let the API know we have access to a particular resource.

OkHttp provides Interceptors which can alter web requests before they are sent out and Authenticators that allow us to re-sign and retry requests that have failed due to authorization. It is very common, particularly on Android, to use Retrofit for networking, which uses OkHttp internally and so the same techniques apply to Retrofit as well.

Let's have a look at how we set this up and how it all works!

Signing requests

We will start by setting up our AuthorizationInterceptor that adds the Authorization header to all web requests that are sent off to our remote API.

Our access tokens are provided by AuthorizationRepository, which either provides a stored access token or obtains a new one if the stored one has already expired. How this process works depends on the authorization each particular API uses, the important part here is that AuthorizationInterceptor has a function it can call to get an access token to sign the web request with.

Our Interceptor implementation needs to provide an intercept function that can extract the current Request, transform it and then pass this new request back into the chain. The transformation we need to apply involves adding an Authorization header that signs the request with our access token. It is worth noting that the exact format of the header may change depending on what type of tokens each API uses, in our example Bearer tokens are used which are pretty common.

class AuthorizationInterceptor(
    private val authorizationRepository: AuthorizationRepository
) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val newRequest = chain.request().signedRequest()
        return chain.proceed(newRequest)
    }

    private fun Request.signedRequest(): Request {
        val accessToken = authorizationRepository.fetchFreshAccessToken()
        return newBuilder()
            .header("Authorization", "Bearer ${accessToken.rawToken}")
            .build()
    }
}

Registering our interceptor just involves adding it to the builder we are using to create our OkHttpClient for either use directly or with Retrofit.

fun okHttpClient(authorizationInterceptor: AuthorizationInterceptor) =
    OkHttpClient.Builder()
        .addInterceptor(authorizationInterceptor)
        .build()

All outgoing web requests will now be signed with our access token.

Retrying failed requests

It is possible that our requests may fail with 401 Unauthorized due to an issue with the access token we provided. This will usually be due to the access token having expired or being revoked on the server-side. To handle this situation we can build an OkHttp Authenticator, that allows us to catch this case, add a new token and then retry the request.

We will start by extracting an extension function to set the Authorization header on a request.

fun Request.signWithToken(accessToken: AccessToken) =
    newBuilder()
        .header("Authorization", "Bearer ${accessToken.rawToken}")
        .build()

We will build in a limit on the number of retries to avoid an infinite loop if authorization for a particular endpoint fails entirely. We can determine how many times a request has been retried from the response.

private val Response.retryCount: Int
    get() {
        var currentResponse = priorResponse
        var result = 0
        while (currentResponse != null) {
            result++
            currentResponse = currentResponse.priorResponse
        }
        return result
    }

The implementation of Authenticator receives the response that failed with 401 Unauthorized and has to optionally provide a new request to be triggered. If our request has already been retried twice we will simply allow it to fail to avoid an infinite loop. Signing the request is done in the same way as in our AuthorizationInterceptor above.

class TokenRefreshAuthenticator(
    private val authorizationRepository: AuthorizationRepository
) : Authenticator {
    override fun authenticate(
        route: Route?,
        response: Response
    ): Request? = when {
        response.retryCount > 2 -> null
        else -> response.createSignedRequest()
    }

    private fun Response.createSignedRequest(): Request? = try {
        val accessToken = authenticationRepository.fetchFreshAccessToken()
        request.signWithToken(accessToken)
    } catch (error: Throwable) {
        Logger.error(error, "Failed to re-sign request")
        null
    }
}

Registering our authenticator involves adding it to the builder alongside our interceptor.

OkHttpClient.Builder()
    .addInterceptor(authorizationInterceptor)
    .authenticator(tokenRefreshAuthenticator)
    .build()

Web requests that fail with authorization issues will now be re-signed and retried!

Refreshing expired tokens

In the above AuthorizationInterceptor and TokenRefreshAuthenticator we obtain an access token using fetchFreshAccessToken. This function has been built to return the stored access token if it hasn't expired yet or to obtain a new one if it has.

An important note is that the function signatures of both Interceptor and Authenticator require the request to be created or transformed synchronously. The process of refreshing an access token is likely asynchronous due to requiring its own web request to an OAuth API. We therefore need to call this asynchronous token refresh process synchronously, exactly how will depend on how on it is implemented.

Kotlin Coroutines can use the runBlocking function
Retrofit Call has a synchronous execute function
RxJava Single has a synchronous blockingGet operator

Multiple authorization types

In our implementation so far we have assumed that all requests need to be signed in the same way, however, in reality this likely won't be the case. For example, there will likely be requests that need to be performed before a user has signed in such as the account creation request or maybe fetching some form of configuration.

To incorporate this, we can use the OkHttp Tag API, which can also be used in our Retrofit calls. We will tag our web requests with an AuthType enum that specifies which type of authorization to be used.

enum class AuthType {
    ACCESS_TOKEN,
    CLIENT_CREDENTIALS,
    NONE;

    companion object {
        fun fromRequest(request: Request): AuthType =
            request.tag(AuthType::class.java) ?: ACCESS_TOKEN
    }
}

With OkHttp the tag can be specified in the request builder and with Retrofit it can be added using an annotation for a particular call.

interface CreateAccountRemoteApi {
    @POST("user/identity")
    suspend fun createAccount(
        @Body request: CreateAccountRemoteDto,
        @Tag authorization: AuthType = AuthType.CLIENT_CREDENTIALS
    ): AccountCreatedRemoteDto
}

The AuthType can now be extracted and used within our AuthorizationInterceptor and TokenRefreshAuthenticator, to decide how to sign the request.

class AuthorizationInterceptor(
    private val authorizationRepository: AuthorizationRepository
) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val newRequest = chain.request().signedRequest()
        return chain.proceed(newRequest)
    }

    private fun Request.signedRequest() = when (AuthType.fromRequest(this)) {
        AuthType.ACCESS_TOKEN -> signWithFreshAccessToken()
        AuthType.CLIENT_CREDENTIALS -> signWithClientCredentialsToken()
        AuthType.NONE -> this
    }
}

Using this approach we can easily control the exact type of authorization each individual endpoint requires, giving us a great level of flexibility.

Wrap up

Adding authorization to web requests for OkHttp and Retrofit can be done without too much complexity, however, without knowing which parts of the API to use it may not be immediately obvious. By using an Interceptor we can avoid requests failing due to being unauthorized and then we can combine this with an Authenticator to also handle the cases where it does unfortunately fail.

The power of lazy properties in Kotlin

Andrew Lord — Sun, 01 Mar 2020 00:00:00 GMT

Do you have properties in your Kotlin types that you want to create later after initialization? You may want to avoid making them nullable, avoid using lateinit or delay an expensive set up process to a later point. In Kotlin this is where delegated properties and lazy properties in particular can be used, allowing properties to be initialized when they are needed and even keep our main type's initialization simpler and cleaner.

The idea of making a property lazy is not new to Kotlin and many developers having been doing it in other languages or doing it themselves for ages. There were common approaches to a form of lazy creation in Java, it was hard to live in the Java world without coming across a getInstance() function at some point!

When it comes to defining lazy properties in Kotlin, they have been brought into being part of the language. There is some new syntax, some different options for initializing them and various situations in which they can be really useful. Let's take a look!

Creating them

Creating a lazy property in Kotlin is pretty simple, we define it using by lazy and provide a function initializer. At a later point, when the property is first accessed it will be initialized using the function we provided and then on future accesses the cached value will be returned instead. Nifty!

private val bindingController by lazy {
    FilesBindingController(viewModel::onFileOpened)
}

Our bindingController property needs to access the viewModel property in order to be created and so by making it lazy, this can be deferred until it is first used. After bindingController has been initialized, the value will simply be returned every time from then on.

Factory method

Creating our property may not always be as simple as just calling an initializer and more code may be needed to set it up. In these situations we may wish to move the contents of the lazy function initializer to a factory method on the outer class.

class TeamRepository(appSchedulers: AppSchedulers) {
  private val viewState by lazy(::createViewStateLiveData)

  private fun createViewStateLiveData(): LiveData<ViewState> =
      teamRepository.teamMembersStream()
          .map(::mapPresentingState)
          .onErrorReturn(::mapErrorState)
          .startWith(ViewState.Loading)
          .subscribeOn(appSchedulers.io)
          .observeOn(appSchedulers.main)
          .toLiveData()
}

Moving the initialization code to a factory method can keep the top of our class cleaner and we may find we prefer to keep this set up code out of the way. In some situations we may even be able to use a separate factory object to move the initialization logic to another type or file if we wanted to.

Extension

Across our codebase there will be common situations for using lazy properties and so to simplify the call sites we may decide to use an extension function. For example, when using Android ViewModel, each of our Activities will need to retrieve their View Model, which can be done using an extension function on a common base class.

inline fun <reified ViewModelT : ViewModel> ComponentActivity.bindViewModel() =
    bindViewModel(ViewModelT::class, viewModelFactoryProvider)

@PublishedApi
internal fun <ViewModelT : ViewModel> ComponentActivity.bindViewModel(
    viewModelType: KClass<ViewModelT>
): Lazy<ViewModelT> = lazy {
    ViewModelProvider(this).get(viewModelType.java)
}

Using our new lazy extension function cleans up the initialization call site.

class TeamActivity : FragmentActivity() {
  private val viewModel: TeamViewModel by bindViewModel()
}

This particular example is now provided by the AndroidX Activity library.

How does it work?

Delegated properties work as their name suggests, delegating the property's getter and maybe setter to another type. There are a selection of different delegated property types provided and then on top of this we can write our own. The expression we place after the by keyword is what specifies the delegate that will be used.

In the case of by lazy, a Lazy delegate type will control access to our property, initializing it on first access and then returning the cached value on subsequent accesses. Users of the property don't need to change how they call it, meaning the read-write behaviour of our property can be changed at the property definition without affecting code that uses it.

Multithreading

The lazy function has an argument with a default value that controls its synchronization behaviour. If a lazy property is accessed from multiple threads concurrently, synchronization will need to be handled by choosing an appropriate LazyThreadSafetyMode.

private val messageId by lazy(LazyThreadSafetyMode.NONE) { createMessageId() }

The default value SYNCHRONIZED will ensure only a single thread can initialize the property using locks. If we are sure the property will only be accessed by a single thread we can switch to NONE to avoid the overhead of performing the synchronization. There is also the option of using PUBLICATION which allows multiple threads to call the initializer, but only the first returned value being used.

Most UI code, such as in an Activity or Fragment, will run on the UI thread and so properties that are only used here can use the LazyThreadSafetyMode.NONE. We could even add an extension to avoid specifying this each time.

Other use cases

Lazy is useful wherever we want to delay initialization to a later point, rather than doing it straight away. Without it other options may include a lateinit property which simply "promises" to be initialized before it is used or a nullable property which can have a value or not.

When we just want to delay initialization, lazy can be a nicer approach to the alternatives. It can be especially helpful for obtaining dependencies whose initialization is out of our control, such as Android View Models from an Activity or Fragment.

There are times when we need to read a value from somewhere, but don't want it to be retrieved again each time it is needed. An example is reading Bundle extras from an Intent, where using a lazy property would mean on first access the value is read from the Intent and then cached for quicker access in the future.

class OrderDetailActivity : FragmentActivity() {
  val orderId by lazy {
      intent.getParcelableExtra<OrderId>(EXTRA_ORDER_ID)
  }
}

Wrap up

Delegated properties and lazy properties in particular are a great feature to have at our disposal. The give us flexibility over how our properties are initialized and accessed. It is really nice to be able to make a property lazy without having to alter how it is used in calling code.

Uploading a file with progress in Kotlin

Andrew Lord — Tue, 25 Feb 2020 00:00:00 GMT

Do you want to upload a file using the clean Retrofit syntax, but aren't sure how to receive the result as well as the upload progress? We will be using Retrofit to perform the file upload, building an implementation that is able to receive the completion progress at intervals and then complete with the remote API response.

Whilst long-running operations are happening, it is nice for the user to see that activity is occurring, such as a progress view being displayed. For the case of a file upload we can show the real progress, which can be represented by the number of bytes transmitted out of the total file size.

We will use the APIs available to us in Retrofit, OkHttp and Okio to build a class that can be used whenever we want a request to publish its progress to whoever wishes to observe it!

Endpoint

We are developing a messaging application that is able to attach a file to a message thread. It is worth noting that we are using Kotlin Coroutines, however, it can be altered to use regular callbacks or a reactive framework such as RxJava.

Our endpoint is a POST request that contains a multipart body, consisting of the filename, file MIME type, file size and the file itself. We can define it using Retrofit, specifying the required parts.

@Multipart
@POST("file")
suspend fun uploadFile(
    @Part("name") filename: RequestBody,
    @Part("type") mimeType: RequestBody,
    @Part("size") fileSize: RequestBody,
    @Part filePart: MultipartBody.Part,
): FileUploadedRemoteDto

Counting progress

If we just wanted to upload the file without any progress, we would simply convert the file to a request body and send it in the request.

fun createUploadRequestBody(file: File, mimeType: String) =
    file.asRequestBody(mimeType.toMediaType())

Monitoring upload progress can be achieved by using our own CountingRequestBody which wraps around the file RequestBody that would have been used before. The data that is transmitted is the same as before, allowing the raw file RequestBody to be delegated to for the content type and content length.

class CountingRequestBody(
    private val requestBody: RequestBody,
    private val onProgressUpdate: CountingRequestListener,
) : RequestBody() {
    override fun contentType() = requestBody.contentType()

    @Throws(IOException::class)
    override fun contentLength() = requestBody.contentLength()

    ...
}

Transmitting the request body is performed by writing it to a Sink, we will wrap the default sink with our own one that counts the bytes that are transmitted and reports them back via a progress callback.

typealias CountingRequestListener = (
    bytesWritten: Long,
    contentLength: Long,
) -> Unit

class CountingSink(
    sink: Sink,
    private val requestBody: RequestBody,
    private val onProgressUpdate: CountingRequestListener,
) : ForwardingSink(sink) {
    private var bytesWritten = 0L

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

        bytesWritten += byteCount
        onProgressUpdate(
            bytesWritten,
            requestBody.contentLength(),
        )
    }
}

Within CountingRequestBody we can wrap the default sink into our new CountingSink and write to a buffered version of that, in order to both transmit the file and observe its progress.

class CountingRequestBody(
    private val requestBody: RequestBody,
    private val onProgressUpdate: CountingRequestListener,
) : RequestBody() {
    override fun contentType() = requestBody.contentType()

    @Throws(IOException::class)
    override fun contentLength() = requestBody.contentLength()

    @Throws(IOException::class)
    override fun writeTo(sink: BufferedSink) {
        val countingSink = CountingSink(sink, this, onProgressUpdate)
        val bufferedSink = countingSink.buffer()

        requestBody.writeTo(bufferedSink)

        bufferedSink.flush()
    }
}

The result

Whilst observing the upload progress, there will either be progress or a completed response, the perfect candidate for a sealed class. This will allow CountingRequestResult to be the return type and callers can handle both progress updates and the completed result.

sealed class CountingRequestResult<ResultT> {
    data class Progress<ResultT>(
        val progressFraction: Double
    ) : CountingRequestResult<ResultT>()

    data class Completed<ResultT>(
        val result: ResultT
    ) : CountingRequestResult<ResultT>()
}

Perform the upload

Now that we have a way of uploading a file and receiving the upload progress, we can write our FileUploader. Creating the request body for our upload request involves using a CountingRequestBody that reports progress and completion to a MutableStateFlow (or another reactive type).

private fun createUploadRequestBody(
    file: File,
    mimeType: String,
    progressEmitter: MutableStateFlow<Double>,
): RequestBody {
    val fileRequestBody = file.asRequestBody(mimeType.toMediaType())
    return CountingRequestBody(fileRequestBody) { bytesWritten, contentLength ->
        val progress = 1.0 * bytesWritten / contentLength
        progressEmitter.update { progress }
    }
}

The upload request consists of using the Retrofit function we implemented at the beginning, providing the file details and the created request body that will count progress. The Retrofit definition and the format of the request parts will depend on how each particular API is put together. Here we are using a request that contains various plaintext parts for the file details and then one for the file to be uploaded.

private suspend fun performFileUpload(
    filename: String,
    file: File,
    mimeType: String,
    progressEmitter: MutableStateFlow<Double>,
): FileUploadedRemoteDto {
    val requestBody = createUploadRequestBody(file, mimeType, progressEmitter)
    return remoteApi.uploadFile(
        filename = filename.toRequestBody("text/plain".toMediaType()),
        mimeType = mimeType.toRequestBody("text/plain".toMediaType()),
        fileSize = file
            .length()
            .toString()
            .toRequestBody("text/plain".toMediaType()),
        filePart = MultipartBody.Part.createFormData(
            name = "files[]",
            filename = filename,
            body = requestBody,
        )
    )
}

Our main upload function can put together all of these parts to create a single result flow. We will be able to collect this to get progress updates as well as the final result.

fun uploadFile(
    filename: String,
    file: File,
    mimeType: String
): Flow<FileUploadRemoteResult> {
    val progressEmitter = MutableStateFlow(0.0)
    val progressStream = progressEmitter
        .transformWhile<Double, FileUploadRemoteResult> { progress ->
            emit(CountingRequestResult.Progress(progress))
            progress < 1.0
        }
    val resultStream = flow {
        val uploadResult = performFileUpload(
            filename,
            file,
            mimeType,
            progressEmitter,
        )
        emit(CountingRequestResult.Completed(uploadResult.result))
    }
    return merge(progressStream, resultStream)
}

typealias FileUploadRemoteResult = CountingRequestResult<FileUploadedRemoteDto>

We can now upload a file to our API and update a view as the request progresses, which is nice for noticeably long operations like uploading larger files.

uploader.uploadFile(request.filename, request.file, request.mimeType)
    .distinctUntilChanged()
    .collect { uploadResult ->
        // Update progress in UI
        fileUploadingState.update { inProgressState(uploadResult) }

        // Get uploaded file
        if (uploadResult.status is CountingRequestResult.Completed) {
            uploadedFileState.update { uploadResult.status.result }
        }
    }

Wrap up

Monitoring the progress of a web request may not be immediately obvious when reading through the Retrofit API, however, the powerful APIs of OkHttp and Okio can get the job done nicely. The solution we have developed can be used for any web request, as the counting process can be wrapped around any RequestBody that needs to be sent in a request.

Simplified launching of Android Activities

Andrew Lord — Tue, 25 Feb 2020 00:00:00 GMT

Extension functions are really great for making life easier, allowing us to add functionality to types that aren't our own. One area we can use an extension is for launching Android Activities more easily.

We can build an extension that allows all Activities to be launched via a generic type argument. An optional request code can be passed to the function, which controls whether startActivity or startActivityForResult is used to launch the Activity. By providing an intent builder function, the Intent that is fired can be customised.

inline fun <reified ActivityT : Activity> Activity.startActivity(
    requestCode: Int? = null,
    intentBuilder: Intent.() -> Unit = {}
) {
    val intent = Intent(this, ActivityT::class.java)
        .apply { intentBuilder() }
    if (requestCode == null) {
        startActivity(intent)
    } else {
        startActivityForResult(intent, requestCode)
    }
}

fun startContactCreation(fromActivity: Activity, requestCode: Int) {
    fromActivity.startActivity<ConnectionCreationActivity>(requestCode) {
        putExtra("source", ConnectionCreationSource.CONNECTIONS)
    }
}

Protecting secrets in an Android project

Andrew Lord — Sun, 16 Feb 2020 00:00:00 GMT

Would you like to include secrets such as API keys into your Android project, but also want to protect them and keep them safe? We can use features of Gradle, environment variables, obfuscation and encryption, to keep them out of Git and to keep them secure.

When developing apps we will often need to use secret values that we don't want anyone to get access to, such as tokens, IDs and API keys. There are many reasons they may be needed in our source code and in Gradle scripts, the most common being when we are asked to provide one to authenticate with a third-party API.

We will examine a selection of techniques that we can apply, providing protection for our secrets and preventing them from sitting in plaintext, in plain sight!

Why

When following the set up instructions to integrate a new library, we are usually told to put the API key in the AndroidManifest.xml, in the source code or in a Gradle file. These suggestions will result in the secrets being added to source control and to be easily obtainable in plaintext by decompiling our app.

There are more secure ways of managing our secrets and through these tips we can make them significantly harder to obtain. It is worth remembering that our app is published and installed, meaning people will be able to take it apart and try and find secret values within it. All we can do as developers is to apply an appropriate level of security and do our best to keep these secrets safe. When it comes to API keys and tokens, there are also techniques that can be applied on the backend-side to detect fraudulent use and block access using those credentials.

Where to store them

Gradle allows values to be passed in via Gradle properties, these can be passed on the command line or stored in a project-level or user-level properties file. A great way to handle our secrets is to use the user-level file on our filesystem, keeping them out of the project and out of source control. If we were to remove the project from our system and then re-clone it the secrets would still be there and we also have the possibility to include the same secrets into multiple projects without requiring extra set up.

By storing them at a user-level and keeping them out of Git, it means everyone with read-access to the source code doesn't automatically receive the secrets and if our source control system was compromised the attackers wouldn't obtain all of our secrets alongside the source code.

The file is stored within our user directory:

On Mac or Linux: /Users/<you>/.gradle/gradle.properties
On Windows: C:\Users\<you>\.gradle\gradle.properties

We add a property for each secret to the file, keeping in mind it is user-level and so we will want something to signify which app or project the secret corresponds to.

GameCatalogueApp_UploadKeystore_KeyPassword=aaaabbbbcccc
GameCatalogueApp_AuthClientSecret=123456789
GameCatalogueApp_Pusher_APIKey=ksldjalksdjskald

Using values

Accessing the values within our Android project is as simple as reading them as a Gradle property and using them how we wish. If the value is needed within a Gradle script, such as to pass in a keystore password, it can just be read and used as it is. We are using a handy extension to get the property and return an empty string if it isn't present, to avoid the null value. If our secrets are set up correctly, they won't be missing.

signingConfigs {
  create("upload") {
    storePassword = propertyOrEmpty(
      "GameCatalogueApp_UploadKeystore_KeyPassword"
    )
  }
}

fun Project.propertyOrEmpty(name: String): String {
    val property = findProperty(name) as String?
    return property ?: ""
}

Using the values from our source code requires them to be passed through using either resValue or buildConfigField, depending on whether we want them as an Android resource or as a property on the BuildConfig object. One quirk with buildConfigField is the String containing the property value needs to have quotes within it, in order for BuildConfig to be correctly generated.

defaultConfig {
  buildConfigField(
    "String",
    "AUTH_CLIENT_SECRET",
    buildConfigProperty("GameCatalogueApp_AuthClientSecret")
  )

  resValue(
    "string",
    "pusher_key",
    propertyOrEmpty("GameCatalogueApp_Pusher_APIKey")
  )
}

fun Project.buildConfigProperty(name: String) = "\"${propertyOrEmpty(name)}\""

What about CI

It would be very common for our project to be built on a continuous integration (CI) system or service, such as Bitrise or Jenkins. If this is the case we will need our secrets to be available on CI and passed through to the build environment. A handy trick here is that we can set the secrets as environment variables that use the same names as the Gradle properties. The functions we use to read their values within Gradle can then check for both a Gradle property or an environment variable and use whichever is found.

fun Project.propertyOrEmpty(name: String): String {
    val property = findProperty(name) as String?
    return property ?: environmentVariable(name)
}

fun environmentVariable(name: String) = System.getenv(name) ?: ""

Of course, this means environment variables can also be used locally if we would prefer, however, using Gradle properties is a very simple process.

Encrypt them

Even though our secrets are now usable and kept separate to the source code, it would still be fairly simple to decompile the app and extract our secrets in plain text. We can take our solution further by encrypting the values before they are stored and then decrypting them at runtime.

There are various options for encryption, including built-in options or third-party libraries. One possibility is Themis, which is easy to use and provides strong cryptographic techniques, along with a unified API between Android and iOS. Unless there is a skilled cryptographer working on the project, it may be a good idea to use a higher-level encryption API to avoid mistakes being made which weaken applied security measures.

In order to encrypt our data we will need an encryption key.

GameCatalogueApp_EncryptionKey=super_secret_key

buildConfigField(
  "String",
  "ENCRYPTION_KEY",
  buildConfigProperty("GameCatalogueApp_EncryptionKey")
)

We can provide some obfuscation and protection to our key by applying runtime transformations to it, resulting in the "real" key we will actually use. By doing this an attacker would need to decompile the source code and work out from the obfuscated code which operations were applied to the key.

fun generateKey(): ByteArray {
  val rawKey = buildString(5) {
      append(byteArrayOf(0x12, 0x27, 0x42).base64EncodedString())
      append(500 + 6 / 7 * 89)
      append(BuildConfig.ENCRYPTION_KEY)
      append("pghy^%£aft")
  }
  return rawKey.toByteArray()
}

fun ByteArray.base64EncodedString() = Base64.encodeToString(this, Base64.NO_WRAP)

Here we have only applied some fairly simple operations onto the key to demonstrate the idea, the concept could be taken much further and make the key harder to crack.

Now that we have our encryption key ready to go, we can use a Themis SecureCell to turn our raw String data into an encrypted byte string.

fun encrypt(message: String): ByteArray {
    val encryptionKey = generateKey()
    val cell = SecureCell(encryptionKey, SecureCell.MODE_SEAL)
    val protectedData = cell.protect(
        encryptionContext, message.toByteArray()
    )
    return protectedData.protectedData
}

private val encryptionContext: ByteArray? = null

To store our encrypted secret we can encode the produced ByteArray into a base 64 encoded string. The same key generation code could be added to a script or we could just run the app, encrypt the secret and print out the value for us to copy.

val encypted = EncryptionEngine().encrypt("raw_secret_value")
Log.d("ENCRYPTED", encypted.base64EncodedString())

The Gradle properties or our CI environment variables can now be replaced with encrypted versions.

Decrypt them

At runtime we will first need to convert the base 64 encoded version into an encrypted ByteArray.

val encryptedDaya = Base64.decode(secretAsBase64, Base64.NO_WRAP)

The encrypted ByteArray now needs to be turned into the raw string versions, using the same encryption key as was used for the encryption process earlier. We will need to handle a failed decryption in some way, which would mean something had been set up incorrectly or an invalid value was passed in.

fun decrypt(encryptedData: ByteArray): String? {
    val encryptionKey = generateKey()
    val cell = SecureCell(encryptionKey, SecureCell.MODE_SEAL)
    return try {
        val cellData = SecureCellData(encryptedData, null)
        val decodedData = cell.unprotect(encryptionContext, cellData)
        String(decodedData)
    } catch (error: SecureCellException) {
        Log.e("EncryptionEngine", "Failed to decrypt message, error)
        null
    }
}

Our unencrypted secrets can now be used as they were before. It can be a good practice to decrypt them when they need to be used rather than storing them in an unencrypted state during an app session.

Wrap up

Protecting our API keys and other secrets is a good practice to avoid someone accessing them and causing us harm. This is particularly true if the keys are used for authentication or for accessing our own API that serves up user data. Using various techniques, we have removed the secrets from source control, kept them out of the project, encrypted them and applied protection to our encryption key.

On top of what has been discussed there are further practices that can be applied, some requiring more significant changes. It is best to evaluate the security needs of a particular application, based on what type of data it uses and the level of security a user would expect. Clearly a banking app will need to be much more security concious than a timer app, however, a good-level of security should be applied regardless to protect access to a user's data.

Enforcing type safety of IDs in Kotlin

Andrew Lord — Sun, 09 Feb 2020 00:00:00 GMT

For codebases with many different entities, most of us will at some point have hit a bug due to the wrong ID being assigned to a property or passed to a function. Why don't we use the type system to give all of our IDs their own type and ensure this never happens again.

It is very common for objects to need a form of identifier or ID, frequently the reason being to refer to entities when communicating with a remote API or a database. We can easily implement this by giving our classes an ID property with an appropriate type, such as String, UUID or Long. An issue here is that imagine User and Team both have a String ID, it would be perfectly possible to pass a User ID to a function when we were meant to provide a Team ID instead.

Let's explore the idea of enforcing type safety by giving our IDs their own types.

General types

One option for our IDs is to use the String type, especially if they are in an unexpected format. Another common type of ID is a UUID, an implementation of which is provided by the Java standard library. UUID is designed for storing IDs and is a 128-bit value, which can be easily converted to and from a String.

data class Team(val id: UUID, val size: Int)

data class TeamMember(val id: String, val name: String)

Tiny type

Rather than relying on the general types, we can easily create a dedicated one.

data class Identifier(val rawValue: UUID)

If we require different raw types, we can either create extra ID types that contain different raw types or use a single one with a generic type parameter. Using a generic version allows us to have properties or function arguments that require a particular type of ID.

data class Identifier<RawT>(val rawValue: RawT)

We can add helpful extensions to Identifier for use with common raw types, such as pulling out the raw String value:

val Identifier<UUID>.uuidString: String
    get() = rawValue.toString()

Ensuring the correct type

There are some issues that can appear when using these general types internally. Say Team has a UUID ID and Member has a String ID:

Every Team ID is a UUID, but not every UUID refers to a valid Team.
A Member ID could have the same value as the raw String backing a Team ID, even though they refer to different entities.

Mixing and matching two different IDs that use the same raw type is perfectly valid and not prevented by the compiler. We can do better than this!

By adding a second generic type parameter to our Identifier we can limit its use for a particular entity.

data class Identifier<EntityT, RawT>(
    val rawValue: RawT
)

data class Room(val id: Identifier<Room, UUID>)
data class Meeting(val id: Identifier<Meeting, UUID>)

fun bookMeeting(id: Identifier<Meeting, UUID>) {}

// ❌ Compile error: Type mismatch.
bookMeeting(room.id)

Due to EntityT not actually being used within Identifier we will likely get a warning about it being unused, which can be ignored using @Suppress("unused").

Type aliases

When our codebase has a variety of entities, the number of IDs will grow and we are likely to get fed up with typing out the Identifier signature. We can rely on type aliases to simplify this task. A nice organisation tip is to store these alongside the entity they identify, making them easy to find.

// Team.kt

typealias TeamId = Identifier<Team, UUID>

data class Team(val id: TeamId)

Specifying IDs in properties and functions is now so much simpler.

fun Team.inviteMember(id: MemberId) {}

// ❌ Compile error: Type mismatch.
team.inviteMember(team.id)

// ✅ Compiles.
team.inviteMember(member.id)

Alternatives

If we wanted to avoid the generic type arguments, we could rely on the brevity of Kotlin data classes and simply have a separate tiny type for each ID.

data class MessageId(val raw: UUID)
data class ChatId(val raw: String)
data class PersonId(val raw: Long)

The advantage is they are significantly simpler due to being just basic data classes, they could even be inline classes. A possible downside is that with Identifier we can write code that automatically converts Identifier to other types for tasks such as storing in a Bundle to pass to an Activity or to a format Room can store in a SQLite database. We will have to weigh up the pros and cons of each approach and decide what is best for our particular situation.

Wrap up

By using a type that enforces type safety of our entity IDs, we can make our model code safer to work on and avoid bugs due to an incorrect ID being used. Our code will also be more readable as when we see an ID we will know which entity it refers to. There may even be ways to extend this solution to make it even more powerful!

The power of sealed classes in Kotlin

Andrew Lord — Sun, 02 Feb 2020 00:00:00 GMT

Wouldn't it be great if you could represent a single type that can come in different forms, each able to be constant or carry their own data? If programming in Kotlin, we are in luck as that is exactly what a sealed class is perfect for!

Enums or enumerated types have existed in many different programming languages for years and allows us to represent a type whose value is taken from a limited set of values. Kotlin takes this concept and evolves into something much more powerful, known as sealed classes. They are a really useful addition to the language, enabling powerful use cases and can help us build some really nice APIs. Let's have a look at how sealed classes can be used, their benefits and some example situations in which they can be the perfect tool for the job.

How

Both enums and sealed classes allow us to represent a type that can be one value from a set of possibilities. An enum consists of a set of constant values and the instance is assigned one of these constants. Sealed classes instead rely on a set of sub-classes, allowing us to have multiple instances of each sub-class and for them to have their own state.

Sealed class sub-classes can carry their own state

Let's say we have an AuthenticationState that keeps track of which state a user's account is in within our app. The user can be: signed in with a user identifier, signed out with some credentials stored or fully signed out.

sealed class AuthState {
    data class SignedIn(val userGuid: UUID) : AuthState()
    data class StoredCredentials(val credentials: Credentials) : AuthState()
    object SignedOut : AuthState()
}

By using a sealed class, a property of type AuthenticationState has to have one of the sub-classes assigned to it. We can use a data class to give the sub-class its own properties or an object and make it constant.

Unlike with an enum, the sub-classes do not need to be kept in the body of the sealed class, only within the same file.

// AuthState.kt

sealed class AuthState
data class SignedIn(val userGuid: UUID) : AuthState()
data class StoredCredentials(val credentials: Credentials) : AuthState()
object SignedOut : AuthState()

The way we choose to structure our sealed classes affects how they are referenced, the above examples resulting in AuthState.SignedOut or SignedOut. We can therefore place the sub-classes within the sealed class to create a namespace for our type.

When

One of the situations sealed classes really stand out is within a when expression. Using when as an expression, assigning or returning the result, allows the compiler to determine if all possible cases have been handled, without needing an else branch.

fun onAuthStateChanged(newState: AuthState) = when (newState) {
    is AuthState.SignedIn -> showSignedIn(newState.userGuid)
    is AuthState.StoredCredentials -> showSignedIn(newState.credentials)
    AuthState.SignedOut -> showSignedOut()
}

The compiler can determine if all cases have been handled

By using sealed classes within our APIs we can make it really easy for consumers to handle all of the possible states. When used within our own code, if we add an extra sub-class then any when statements used as an expression have to handle it.

View state

In Android apps (or other GUI applications), we need a way to connect the logic that controls our UI to the views themselves. One part of this process may involve modelling the state of the view, such as if it is loading, showing an error or showing data.

sealed class ViewState
object LoadingState : ViewState()
data class PresentingState(val viewData: ContactsViewData) : ViewState()
data class ErrorState(val message: String) : ViewState()

Imagine we are developing a screen that displays a list of contacts loaded from a local database. Our view layer will receive the ViewState and can then render the correct views based on which sub-class of the sealed class is received.

fun renderViewState(viewState: ViewState) = when (viewState) {
  LoadingState -> showLoadingViews()
  is PresentingState -> showPresentingViews(viewState.viewData)
  is ErrorState -> showErrorViews(viewState.message)
}

Using a sealed class allows us to update our views for all the possible view states, along with each state carrying a different set of data:

LoadingState can just be an object with no data
PresentingState brings with it ContactsViewData to render the contacts
ErrorState contains an error message to be shown

Without a sealed class, we would need a class that contains all of the data as nullable properties and an enum to represent which state it was in.

Analytics events

We will often need to work out how people are using our apps or verify the effectiveness of certain actions through the use of analytics. This usually boils down to firing off events after specific actions have been taken within the app. These analytics events will be reported in the same way, but may have different properties attached to them, this is a perfect candidate for a sealed class. Code that needs to handle the event can do this easily using a when expression, for example, mapping each event to its map of properties.

sealed class AnalyticsEvent {
    object AccountCreated : AnalyticsEvent()
    data class MessageSent(val conversation: Conversation) : AnalyticsEvent()
    data class ProfileOpened(val participant: Participant) : AnalyticsEvent()

    fun parameters(): Map<Parameter, String> = when (this) {
        AccountCreated -> mapOf()
        is MessageSent -> mapOf(
            Parameter.PARTICIPANT_COUNT to
                conversation.participants.size.toString(),
            Parameter.IS_ARCHIVED to
                conversation.isArchived.toString()
        )
        is ProfileOpened -> mapOf(
            Parameter.HAS_ACCOUNT to
                participant.hasCreatedAccount.toString()
        )
    }

    enum class Parameter {
        HAS_ACCOUNT,
        IS_ARCHIVED,
        PARTICIPANT_COUNT,
    }
}

We could instead model an analytics event as a simple data class with a name and map of properties. An issue with this approach is it can spread the event names, property names and creation of events all over the codebase. The advantage of the sealed class approach is that we can keep the definition of all our events in one place, ensuring they are correct and that they report the correct properties. It is really great that sealed classes allow us the flexibility to have an AnalyticsEvent type that can be passed around, even though it can come in many different forms.

Wrap up

Sealed classes are a really powerful feature of Kotlin, allowing the flexibility to model a single type that can come in a finite set of different forms. We have only explored a few of the use cases for them, I am sure you will find many more in your codebase!

Using Kotlin to bind Android views

Andrew Lord — Wed, 30 Jan 2019 00:00:00 GMT

When working in the UI layer of an Android app, it won't be long before we need to perform an operation upon one of our views. In order to do this, we first need to retrieve it via findViewById. Although using the API can seem simple, it does introduce a block of boilerplate to our Activities. On top of this the code to bind all the views usually ends up in onCreate, completely separate from the view properties themselves.

Now that Kotlin has entered the scene with new features we didn't previously have access to it seems like the perfect time to look for a new way of doing things. We will explore how some different approaches, including lazy initialisation and Kotlin Android Extensions, can be used to solve this problem.

The situation in Java

To set the scene and to demonstrate how Kotlin can help we first need to look at how these tasks are achieved in Java. To bind views to a field, we would use findViewById, historically casting the resulting view to the correct subclass. For an activity, the views would commonly be bound within onCreate, however, this may be elsewhere if views are retrieved at another time.

public class PlanningActivity extends AppCompatActivity {
    private TextView planningText;
    private ImageView appIcon;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setContentView(R.layout.activity_planning);
        // Before: Needed to cast
        planningText = (TextView) findViewById(R.id.planningText);
        // Now: No longer need to
        appIcon = findViewById(R.id.appIcon);

        planningText.setText("Hello!");
    }
}

The example here is very simple, containing only two views, whereas in reality many different views may need to be accessed. To avoid this repetitive boilerplate ButterKnife was created, which uses annotation processing to aid the binding of views.

public class PlanningActivity extends AppCompatActivity {
    @BindView(R.id.planningText) TextView planningText;
    @BindView(R.id.appIcon) ImageView appIcon;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setContentView(R.layout.activity_planning);
        ButterKnife.bind(this);
        planningText.setText("Hello!");
    }
}

Lazy in Kotlin

The Kotlin programming language has many new features and so it feels natural that it may offer a better solution to what we were using before. A new concept in the language is that of delegated properties, specifically the lazy delegated property. The way it works is that when the property is first accessed it will be initialized via the provided function and on future accesses the value will just be returned. This sounds perfect for binding views as the first access can call findViewById and then subsequent calls can just provide the stored view.

private val planningText by lazy {
    findViewById<TextView>(R.id.planningText)
}

A lazy delegated property is initialised on first access

To avoid typing all of this each time we want to bind a view, an extension function on Activity can be created. We can also optimise performance slightly by disabling thread safety, due to the fact that the views will only be accessed from the main UI thread.

fun <ViewT : View> Activity.bindView(@IdRes idRes: Int): Lazy<ViewT> {
    return lazy(LazyThreadSafetyMode.NONE) {
        findViewById<ViewT>(idRes)
    }
}

class PlanningActivity : AppCompatActivity() {
    private val planningText by bindView<TextView>(R.id.planningText)
    // or
    private val planningText: TextView by bindView(R.id.planningText)
}

We now have a succinct and clear call site, with full control over the view binding and no generated code required. As bindView is essentially a wrapper around findViewById it can be applied elsewhere in the codebase, beyond just in Activity.

Lazy elsewhere

Applying to views, such as in a RecyclerView.ViewHolder is as simple as creating a similar extension function to give us access to the same API we had within Activities.

Where our technique encounters some issues is when used within a Fragment due to differences in their lifecycle. Without alterations the lazy property can refer to an old view instance after the Fragment view has been recreated. We can either avoid lazy view binding in Fragments or put together a solution using the Lifecycle Architecture Component. By creating our own version of Lazy we can reset the stored value in onDestroyView, causing the next access to call findViewById again. An example implementation demonstrating this idea can be found within the sample code for the article.

Synthetic properties

As an alternative to implementing our own solution, especially if the situation with Fragments makes the lazy binding approach undesirable, we can use the Kotlin Android Extensions. The plugin automatically generates properties that match the IDs of the views in our layout file. Views no longer need to be stored manually as properties, as they are instead accessed via synthetic properties generated by the plugin.

Automatically generated properties that bind to our views

We first need to apply the plugin within our Gradle configuration.

build.gradle

apply plugin: 'kotlin-android-extensions'

build.gradle.kts

apply(plugin = "kotlin-android-extensions")

Once applied the plugin will generate synthetic properties for us to access views that are specified within our layout XML files, with names matching the IDs. To access the properties we need to add an import statement for each layout file. It is recommended to use the star syntax for the import, with Android Studio already having this specified within the default code style settings. The IDE should also add the import automatically when you try to reference one of the properties.

import kotlinx.android.synthetic.main.activity_planning.*

class PlanningActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContentView(R.layout.activity_planning)
        planningText.text = "Hello"
    }
}

The plugin comes with other features such as applying to other custom containers and customising the view caching. Any features that are still considered experimental can be enabled within our Gradle configuration. Please find all the details of the other features on the plugin website.

androidExtensions {
  experimental = true
}

Using Kotlin Android Extensions is a very clean approach, requiring practically no extra code. To previous users of ButterKnife it feels like an evolution to that approach. As with any potential solution it is best to try it out, see how it works and whether it fits with all the use cases a particular project has.

Wrap up

When this article was originally written I recommended the lazy property approach due to us being able to strike a great balance between brevity, avoidance of boilerplate and reducing reliance on generated code. Since this time I have found that my preferred solution has shifted towards the Kotlin Android Extensions plugin due to its simplicity and not having to worry if there will be issues with lazy binding in situations such as that of Fragments.

Android signing keystore details from Gradle properties

Andrew Lord — Sun, 27 Jan 2019 00:00:00 GMT

We may want to keep our Android project keystore details out of our source code and Git by passing them in. Aided by a handy function, these can be referenced from Gradle in Groovy or Kotlin.

import org.gradle.api.Project

fun Project.propertyOrEmpty(name: String): String {
    return findProperty(name) as String? ?: ""
}

android {
  signingConfigs {
    create("upload") {
      storeFile = file("upload.keystore")
      storePassword = propertyOrEmpty("UPLOAD_STORE_PASSWORD")
      keyAlias = "keyname"
      keyPassword = propertyOrEmpty("UPLOAD_KEY_PASSWORD")
    }
  }
}

Adding Continuous Integration to your Android project

Andrew Lord — Thu, 24 Jan 2019 00:00:00 GMT

When working on a software project, particularly in a team, a common workflow involves branching from the main branch, often master or develop. The created branch is where changes for a particular feature or issue are applied. One way of managing this branch would involve committing all work for a large feature to this branch and then merging it back once it has been completed. This means the branch lives for a relatively long time and we will likely find the integration process to be a painful process.

Continuous Integration, commonly referred to as CI, is a popular development practice that instead involves integrating changes back into the main branch regularly. By integrating regularly the aim is that the cost of doing so will go down and errors will be detected more quickly. An important part of this process is that before changes are merged, the code is automatically built and tested. By testing before the merge instead of afterwards, integration issues are visible earlier and issues can hopefully be fixed more easily.

Many people will agree that CI provides many benefits in a team environment, including in-house teams and open source projects with many different contributors. What is spoken about less often are the benefits of using CI in a solo environment. By having CI building and testing our code before it is merged, we can integrate code more safely and monitor it over time.

Available solutions

In order to build and test code automatically, it is a good idea to have the process running on a CI server of some kind. This server monitors the codebase for changes, such as via a Pull Request using web-hooks, and then triggers the test suite to be executed. By ensuring the CI server is separate to the development machines verifies that it builds correctly in a clean and consistent environment.

A pull request can automatically trigger a test run

When it comes to setting up and running a CI server, there are a huge number of services to choose from. We will have a look at a few that work differently to give an idea of what is available.

Circle CI is a cloud-based service that uses either Linux or MacOS virtual machines as the build environment. For Android, Linux is the best option due to the pricing being much more favourable with a free tier. Configuring the build jobs involves a YAML file within the project, resulting in a process that is very customisable.

Bitrise is similar to Circle CI in that it is a cloud-based service, however, it is tailored to the individual needs of mobile development. This means it has many mobile specific integrations, including deploying to Google Play alongside services such as TestFairy and Firebase Test Lab. As with Circle CI there is a free tier, although it is fairly limited in terms of build minutes allowed. Configuring the build jobs can be done either via a YAML file in the project or using the workflow editor directly within the web UI, giving an increased level of flexibility.

Jenkins is the leading self-hosted automation server that we install, configure and maintain ourselves on our own hardware or cloud infrastructure. Jenkins is perfect for people who want to maintain the full CI set up themselves. It is incredibly customisable, where we can essentially make it do whatever we want, boasting a huge number of plugins and integrations from the community. It does come at the cost of doing all this, where the other cloud-based solutions are managed for you.

There are many other CI solutions that haven't been mentioned here including: Travis CI, CodeMagic, GitLab CI, TeamCity and Bitbucket Pipelines.

The best solution isn't the same for everyone. The best solution depends on individual requirements, the features we want and also personal preference. To explore the process of setting up CI, we will look at getting a simple workflow running in both Circle CI and Bitrise via the web UI, for comparison.

Circle CI

Once our Circle CI account has been created and integrated with our source control, such as GitHub or Bitbucket, we can start creating our CI config. For Circle CI, this needs to be a YAML file at .circleci/config.yml.

version: 2.0

jobs:
  build:
    working_directory: ~/workspace
    docker:
      - image: circleci/android:api-28

    steps:
      - checkout

      - run:
          name: Run tests
          command: ./gradlew lintDebug testDebugUnitTest

      - store_artifacts:
          path: app/build/reports
          destination: reports
      - store_test_results:
          path: app/build/test-results

We start off by requesting Circle CI 2.0.
We can next set up our jobs, which in this simple example consist of a single job that runs Android Lint and our unit tests.
The first thing our job needs to do is configure the working directory and the image to use for our build environment. The working directory will be needed to do more advanced customisations such as sharing a workspace between steps in a workflow.
Within the build job definition, we can list the steps to take, starting with checking out the code, running our tests and archiving the test results.

This example only covers the very basics and there is much more we can do with our configuration. An example showing a more advanced workflow including caching and sharing the workspace between workflow steps can be found as a gist.

Bitrise

After creating our Bitrise account, we can add our app to Bitrise by following through the full set up wizard. Bitrise is specifically designed for mobile, the detailed wizard helping with pretty much all of the heavy lifting. Once complete and on the dashboard page for our project, the navigation banner should be visible, giving us access to all of the customisation we need.

Entering into the 'workflow' area, we will be able to fine tune the default generated workflow as well as add any extra workflows we will need. Each workflow can be triggered at different times, so we could have one that runs for pull requests and another for tagged commits as an example.

For our build we will need:

Activate SSH key to set up SSH access to our source code.
Git clone repository to retrieve our source code.
Install missing Android SDK components to ensure the Android SDK is available and updated.
Gradle Runner to run a Gradle task of our choice, where we should set the 'Gradle task to run' to lintDebug.
Gradle Unit Test to run unit tests with Gradle, where we should set the 'Test task' to testDebugUnitTest.
Deploy to Bitrise.io to deploy files and attach them to the Bitrise build page.

This covers a basic workflow that matches the one we created for Circle CI above. More advanced workflows can easily be put together using the many steps available, which are open source and viewable on GitHub.

Wrap up

Both Circle CI and Bitrise are very powerful and capable CI tools that apply well to Android development. Both solutions also work well for iOS development, allowing teams that develop for both platforms to use the same tool and subscription.

Circle CI has a more generous free tier in terms of usage, is highly customisable and will be very familiar with those used to configuring CI with a YAML file. Bitrise has more mobile specific plugins available out-of-the-box, allows configuration via the web UI and has a much more user-friendly interface.

It is important to find the right CI tool for the job by trying out the different options. When it comes to CI everyone will have a personal preference and this plays an important role in the decision of which one to use. It is even worth thinking about using CI for solo projects, although there is a set up and maintenance cost, it is still very valuable knowing that the project builds and that all tests are passing.

Set up Kotlin source directory from Gradle Kotlin DSL

Andrew Lord — Sun, 20 Jan 2019 00:00:00 GMT

When converting Android Gradle files from Groovy to Kotlin, one thing that may not be clear is how to keep Kotlin sources within src/main/kotlin. We simply need to get the source sets by name and call java.srcDirs() as a function call. Works like a dream!

sourceSets {
    getByName("main").java.srcDirs("src/main/kotlin")
    getByName("test").java.srcDirs("src/test/kotlin")
    getByName("androidTest").java.srcDirs("src/androidTest/kotlin")
}

Testing on Android using JUnit 5

Andrew Lord — Fri, 30 Nov 2018 00:00:00 GMT

JUnit 4 has always been the standard unit testing framework for Android development, however, a production version of JUnit 5 has been available for quite a while. JUnit 5 is the next generation of JUnit testing and has quite a new structure. From a user-perspective it offers a number of useful new features and various other benefits. Often Android developers are used to waiting a while for new things from the Java-world to be an option on Android. In the case of JUnit 5, with some changes to your Gradle dependencies, you can use it right now from your Java and Kotlin unit tests.

The architecture of JUnit 5 is quite a significant change from before, with the framework being split into three major components.

JUnit Platform is the underlying layer on which testing frameworks can run on the JVM and offers up the API for different test engines.
JUnit Jupiter defines how we write JUnit 5 tests and then contains an engine for running these tests on the platform.
JUnit Vintage gives us an engine for running our previous JUnit 4 tests. We don't need to worry about having to update all of our tests in one go, as we can use the vintage engine to run these and have both JUnit 4 and 5 tests within our project.

As users of the testing framework, it's likely that the most interesting part is the new features we get access to. Nested tests allow us to put our tests into groups, increasing readability and allowing us to reduce repetition within test names. Parameterised tests are really powerful and can also reduce duplicating tests to give different inputs, the parameters can even be provided through a variety of mechanisms. Dynamic tests offer an API to generate tests on the fly using a test factory, rather than hard-coding each of the tests.

Parameterised tests run tests with different inputs

The JUnit 5 extension model allows us to extend the test framework and is the evolution of concepts from JUnit 4 such as @Rule and custom runners. The extension model will allow JUnit 5 to evolve with all developers and tool makers having the same public extension API. There are many more features beyond those listed here, all of which can be found in the user guide.

Now, let's get JUnit 5 running in our Android project.

Configuring Gradle

Thanks to Marcel Schnelle (mannodermaus) there is an easy-to-use Gradle plugin that will configure all the testing tasks to use JUnit 5. The plugin has a few minimum requirements that our project needs to meet, at the time of writing this is the Android Gradle plugin 3.2.0+, Gradle 4.7+ and Java 8+.

We will start by adding the plugin to our root build.gradle file using the latest version, which at time of writing is 1.3.2.0.

→ /build.gradle

buildscript {
  dependencies {
    classpath "de.mannodermaus.gradle.plugins:android-junit5:1.3.2.0"
  }
}

After a successful Gradle sync, we will be ready to apply the plugin to any Android modules we wish to use JUnit 5 in.

→ /app/build.gradle

apply plugin: 'de.mannodermaus.android-junit5'

dependencies {
  testImplementation "org.junit.jupiter:junit-jupiter-api:5.3.2"
  testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:5.3.2"
  testImplementation "org.junit.jupiter:junit-jupiter-params:5.3.2"
}

If there are JUnit 4 tests in the project we are configuring, then we will also need to keep the JUnit 4 dependency and enable the JUnit vintage test engine mentioned above.

testImplementation "junit:junit:4.12"
testRuntimeOnly "org.junit.vintage:junit-vintage-engine:5.3.2"

Once the plugin and the Gradle dependencies have been configured, we can run tests in the same way as we were previously using the same Gradle tasks and run configurations in Android Studio.

If we need them, there are some options for configuring the test environment within Gradle. Our settings go in a junitPlatform block within the existing testOptions, where we may already be doing some configuration. The most common use-case would be for filtering which tests are executed. We could use the filters to divide our tests into unit and integration and then have them run for different variants, as an example.

android {
  testOptions {
    junitPlatform {
      filters {
        includePattern "^(tests_to_include_regex)$"
        excludePattern "^(tests_to_exclude_regex)$"

        includeTags "slow"
        excludeTags "integration"
      }
      debugFilters {
        includeTags "integration"
      }
    }
  }
}

For any more information on the plugin, all the setup and usage instructions can be found on GitHub.

JVM tests only

If our unit tests are only going to be ran on the JVM, no Robolectric or Android required, then we can get away without the Gradle plugin. To do this we can remove the plugin classpath entry from the root build.gradle and the line where the plugin is applied within the app module build.gradle. Instead we need to add some configuration to testOptions to enable running with JUnit 5.

→ /app/build.gradle

android {
  testOptions {
    unitTests.all {
      useJUnitPlatform()
    }
  }
}

We lose the per-variant filters that were demonstrated above if we go down this route. However, for most Android projects that aren't using Robolectric this should definitely be sufficient.

Writing the tests

Let's write some tests to explore the new features of JUnit 5 and how we should go about using it in our apps. We will be using AssertJ for our assertions, mainly for readability within the samples. We will be testing a very simple repository that allows us to look up contacts using their IDs, starting with the JUnit 4 version.

import org.assertj.core.api.Assertions.assertThat
import org.junit.Test

class ContactsRepositoryTest {
  private val repository = ContactsRepository()

  @Test
  fun findContact_givenExistingId() {
    val id = 2
    val expectedContact = Contact(id, "Melanie")

    val actualContact = repository.findContact(id)

    assertThat(actualContact)
        .isEqualTo(expectedContact)
  }
}

Converting this test to JUnit 5 is as simple as changing the import for @Test. Projects with many more tests, using more features of JUnit 4, may have more changes that are required. As mentioned above, we can start new tests in JUnit 5 and then either leave the JUnit 4 ones as is, or convert them gradually.

// Before
import org.junit.Test

// After
import org.junit.jupiter.api.Test

Descriptive test names

A common structure for tests is breaking them into given, when and then.

The given clause involves setting up the conditions for the test, such as mocking or configuring the component we are about to test.
Within the when clause, we execute the behaviour we are looking to verify.
It is in the then clause that we check the behaviour is working correctly with any assertions.

This structure is fairly clear within the body of the test function, however, in the naming of the function some issues may start to arise.

@Test
fun givenContactsLoadedAndIdMatches_whenFindContact_thenContactReturned()

@Test
fun givenContactsNotLoadedAndIdMatches_whenFindContact_thenNoContactReturned()

Some approaches could be taken to reduce the length, such as using shorter wording in the given clauses and potentially removing the then clause from the name. This does result in losing some detail, which can be really useful in test names to quickly see in the test report what is going on and to demonstrate what a test is supposed to do. It is also much easier to read a descriptive sentence than the camel-case seen in function names.

JUnit 5 introduces the @DisplayName annotation, which can be used to provide a descriptive name for the test report. The same result can be achieved in Kotlin through the use of back-ticks around the function name. The advantage of the @DisplayName approach is that we keep the searchable and familiar function name, whereas the back-tick approach avoids the need to maintain both the function name and annotation.

@Test
@DisplayName(
  "Given contacts are loaded but the ID is invalid, When we find a contact, Then no contact is returned."
)
fun findContact_givenExistingId()

@Test
fun `Given contacts are loaded but ID invalid, When we find a contact, Then no contact returned`()

Structuring tests

A common reason for test names growing in length is having multiple tests with the same starting condition. Beyond naming, a similar starting condition can cause test bodies to grow in length as well! To solve the issue, JUnit 5 introduces @Nested, allowing you to group a set of tests into an inner class. The group can have a shared starting state and can also have a display name specified, reducing the length of individual test function names. The nested structure is shown within the test report, making it very readable.

@Nested
@DisplayName("Given valid contact ID")
inner class ValidContactId  {
  private val id = 2

  @Test
  @DisplayName("When find contact, then correct contact returned")
  fun findContact_givenExistingId() {
    val expectedContact = Contact(id, "Melanie")

    val actualContact = repository.findContact(id)

    assertThat(actualContact)
        .isEqualTo(expectedContact)
  }

  ...
}

After fleshing out the tests for this repository more, with a few tests in each group, we can peek at the test report to see how it all looks. 👀

The code we have written is available on GitHub.

Instrumentation tests

We have been discussing unit tests only and as we all know instrumentation tests, usually using Espresso, are also very important. Currently, our Espresso tests will be using JUnit 4, which can be left as it was previously. This means using the JUnit 4 test runner, as opposed to adding the JUnit 5 vintage engine and using the new infrastructure.

Instrumentation tests using the JUnit 5 Gradle plugin are still considered experimental

The Gradle plugin we used to introduce JUnit 5 on Android has support for instrumentation tests, which at the time of writing is considered experimental. From checking the GitHub issues page for the plugin, many people have had problems using JUnit 5 for their instrumentation test suite. When the situation changes this article will be updated with the current details of using it.

Since JUnit 5 is built upon Java 8, to use it we need a minSdkVersion of 26 or above. Before we start freaking out, this can be achieved by running the tests with a product flavour that has the minimum SDK increased to this level.

To write and run our instrumentation tests using the JUnit 5 framework, we will need some Gradle configuration. A little bit more is required than for unit tests, due to needing to tell the system to to use the plugin's runner builder and ensuring tests running on the device work correctly.

→ /app/build.gradle

android {
  defaultConfig {
    testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
    testInstrumentationRunnerArgument "runnerBuilder", "de.mannodermaus.junit5.AndroidJUnit5Builder"
  }
}

dependencies {
  androidTestImplementation "org.junit.jupiter:junit-jupiter-api:5.3.2"
  androidTestImplementation "de.mannodermaus.junit5:android-instrumentation-test:0.2.2"

  androidTestRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:5.3.2"
  androidTestRuntimeOnly "org.junit.platform:junit-platform-runner:1.3.2"
  androidTestRuntimeOnly "de.mannodermaus.junit5:android-instrumentation-test-runner:0.2.2"
}

It is noteworthy that instrumentation tests tend to have less need for JUnit 5, due to there being less tests and fewer variants of similar tests, in general. This will of course depend heavily from project to project though! To find out more, please check out the plugin's GitHub page.

Wrap up

We have only considered a few small aspects of writing JUnit 5 tests, as there is simply so much to look at. To find out more, there is a detailed user guide covering all parts of the framework and how to go about writing tests and customising the test process.

By using JUnit 5 in our Android app testing we are using the latest evolution of the JUnit framework. It gives us access to more features, helps us make tests as readable as possible, reduce duplication within our tests and extending the test framework has never been easier. Hopefully it will catch on more in the Android community and become the "standard" for Android development sooner rather than later.

Enable Java 8 compatibility for Kotlin sources

Andrew Lord — Tue, 27 Nov 2018 00:00:00 GMT

Enabling Java 8 compatibility via the compileOptions block only works for Java sources. To do the same for Kotlin you need to use kotlinOptions on any KotlinCompile Gradle tasks. Interesting…

For Kotlin

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {
    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_1_8
    }
}

For Java

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

Manage Gradle dependencies using Kotlin code in buildSrc

Andrew Lord — Tue, 27 Nov 2018 00:00:00 GMT

Using Kotlin to maintain our Gradle dependencies within the buildSrc directory can be really great.

Allows us to use a familiar syntax
Provides auto-complete within Groovy or Kotlin Gradle scripts
Can click through to a particular dependencies definition

Sweet!

→ /buildSrc/src/main/java/com/myapp/Versions.kt

package com.myapp

object Versions {
  object AndroidX {
    const val appCompat = "1.0.2"
  }
  const val kotlin = "1.3.10"
  ...
}

→ /buildSrc/src/main/java/com/myapp/Libs.kt

package com.myapp

object Libs {
  object AndroidX {
    const val appCompat = "androidx.appcompat:appcompat:${Versions.AndroidX.appCompat}"
  }
  const val kotlinStdlib = "org.jetbrains.kotlin:kotlin-stdlib:${Versions.kotlin}"
}

→ /src/app/build.gradle

import com.myapp.Libs

dependencies {
  implementation Libs.kotlinStdlib
  implementation Libs.AndroidX.appCompat
}

Manage your Gradle dependencies in Kotlin, even from Groovy scripts

Andrew Lord — Fri, 23 Nov 2018 00:00:00 GMT

When defining the dependencies for a Gradle project, such as an Android app, there are situations that call for duplicated information. A common case is that libraries or plugins can often come with multiple dependencies, which are usually released together with matching versions. Maintaining these dependencies requires the version to be duplicated and then kept up-to-date as new versions are released.

Another case is that it is common to have a multi-module project, where we may want a dependency to be added to multiple modules. Similarly to the case with versions, the dependency definition would be duplicated for each module and then kept in-sync moving forward.

It is clear that in both cases we may want to define the dependencies in one place and then access this location from wherever the dependency definition is needed.

The Groovy way

There is a mechanism for sharing your dependency configuration using Groovy, by adding some extra properties in our root build.gradle file, similar to below.

→ /build.gradle

buildscript {
  ext.versions [
    'kotlin': '1.3.10',
    'dagger': '2.19'
  ]

  ext.deps [
    'kotlin': [
      'stdlib': "org.jetbrains.kotlin:kotlin-stdlib:${versions.kotlin}",
      'test': "org.jetbrains.kotlin:kotlin-test-common:${versions.kotlin}"
    ],
    'dagger': [
      'runtime': "com.google.dagger:dagger:${versions.dagger}",
      'compiler': "com.google.dagger:dagger-compiler:${versions.dagger}",
      'androidRuntime': "com.google.dagger:dagger-android:${versions.dagger}",
      'androidCompiler': "com.google.dagger:dagger-android-processor:${versions.dagger}",
    ]
  ]
}

→ /app/build.gradle

dependencies {
  implementation deps.kotlin.stdlib

  implementation deps.dagger.runtime
  implementation deps.dagger.androidRuntime
  kapt deps.dagger.compiler
  kapt deps.dagger.androidCompiler

  testImplementation deps.kotlin.test
}

Sharing the configuration via the root build.gradle achieves the goal of having a single location to maintain. Only needing to update dependency versions in a single file is a great time-saver as well. Unfortunately from practice, when using the Groovy Gradle DSL auto-complete is often missing or incomplete in this situation, making it awkward to use.

On top of this, Gradle 5.0 is now available which includes the production-ready Kotlin Gradle DSL. When we convert the above solution to Kotlin it isn't as nice to use in Kotlin as it is in Groovy. The map syntax can be achieved using mapOf, but reading the data to pass to implementation requires some casting to fit with the statically typed language.

Kotlin to the rescue

As many developers have found with their main app source code, Kotlin can help with defining our dependency configurations as well, from both Groovy and Kotlin Gradle scripts.

When ran, Gradle will check for a buildSrc directory in the root of the project, placing any code that is found into the classpath of our build. This is really handy and allows us to put Kotlin code into buildSrc and then reference it from our Gradle scripts. To get started we just need a little bit of structure.

→ /buildSrc/build.gradle.kts

plugins {
  `kotlin-dsl`
}

The Kotlin DSL plugin needs to be specified for buildSrc.

→ /buildSrc/src/main/kotlin/Versions.kt

Our source files need to be placed within the standard sources directory structure. To use inner objects, for now we need to include the sources within a package, e.g. 'com.ourapp'.

object Versions {
  const val dagger = "2.21"
  const val ktlint = "0.29.0"
  const val kotlin = "1.3.11"
}

→ /buildSrc/src/main/kotlin/Dependencies.kt

object Plugins {
    const val kotlin = "org.jetbrains.kotlin:kotlin-gradle-plugin:${Versions.kotlin}"
    const val ktlint = "com.github.shyiko:ktlint:${Versions.ktlint}"
}

object Libs {
    const val kotlinStdlib = "org.jetbrains.kotlin:kotlin-stdlib:${Versions.kotlin}"

    const val daggerRuntime = "com.google.dagger:dagger:${Versions.dagger}"
    const val daggerCompiler = "com.google.dagger:dagger-compiler:${Versions.dagger}"
    const val daggerAndroidRuntime = "com.google.dagger:dagger-android:${Versions.dagger}"
    const val daggerAndroidCompiler = "com.google.dagger:dagger-android-processor:${Versions.dagger}"
}

Once Gradle has been synced, we can now reference our dependencies within our Gradle scripts. This is pretty much the same as we used with the Groovy extra properties solution above.

→ /app/build.gradle

dependencies {
  implementation Libs.kotlinStdlib

  implementation Libs.daggerRuntime
  implementation Libs.daggerAndroidRuntime
  kapt Libs.daggerCompiler
  kapt Libs.daggerAndroidCompiler

  ktlint Plugins.ktlint
}

Using buildSrc and Kotlin sources achieves the goal of having a single location to maintain and we can even reduce it to a single Kotlin source file if it makes sense to. The solution can be used in the same way from both Groovy and Kotlin Gradle DSL without being altered, which frees us up to change our Gradle scripts to Kotlin if we want to.

The best thing about defining dependencies in this way is that we get access to effective auto-complete and being able to click through to where a dependency is defined from our Gradle scripts, super useful.

A good tool to look into is Ben Manes' Gradle Versions Plugin, which will inform us of any dependencies with new versions. Once we have the latest versions, we can simply update them in Versions.kt.

Wrap up

Naturally, for the reasons given I prefer to use the buildSrc and Kotlin source approach in my Android projects. It is really nice to use with both Groovy Gradle scripts and those written using the Gradle Kotlin DSL.

Welcome to Android Studio 3.0

Andrew Lord — Sat, 04 Nov 2017 00:00:00 GMT

After a long wait, Android Studio 3.0 has finally been released to the stable channel. This means everyone should be updating their IDE to the latest and greatest version. There are so many new features and improvements it is just a no brainer! I will go over the new features later on, but for now I will discuss the process of updating and cover the breaking changes in the new Gradle plugin.

How to update

Updating the IDE and plugin

Android Studio should have prompted you to update to 3.0, if not then go to Check for updates in the menu to do so.

Once you launch your project in 3.0 for the first time, you will be told there is a new version of the plugin to update to. You can continue to use your project as it is, but you will miss out on many of the new features and improvements until you update. Simply, follow the prompts to have your project updated to version 3 of the Gradle plugin and to use the latest version of Gradle 4.

If for some reason you need to do this manually:

Open gradle-wrapper.properties
Enter the latest version of Gradle (above 4.1)
Open build.gradle in the root of the project
Ensure it contains the Google Maven repository and version 3 of the plugin. Note: there might be a version higher than 3.0.0 available, so use the latest one.

Dependency configurations

Previously, when defining dependencies you would use compile.

compile 'com.android.support:support-compat:27.0.0'

This has now been deprecated in favour of implementation and api. In general, you can simply update all dependencies to use implementation. However, if your project is a library and it leaks one its module’s interfaces you may need to use api for that instead.

To understand the difference, please read this detailed guide.

Flavour dimensions

Variants are now automatically matched, which means an app’s debug variant will automatically use a library module debug variant. The same happens for product flavours as well, such as demo and trial.

To ensure this mechanism works correctly, it is now required that all product flavours are assigned to a particular flavour dimension. If you don’t need to use different dimensions, you can simply create one and assign all the flavours to it.

flavorDimensions "default"

productFlavors {
  prod {
    dimension "default"
    ...
  }

  dev {
    dimension "default"
    ...
  }
}

If you use a build type or flavour that doesn’t exist in one of your library modules, a fallback will need to be specified. This isn’t required for debug or release as they are present in all modules automatically. The plugin will select the first fallback from the list which is found.

debug { ... }
release { ... }
staging {
  matchingFallbacks = ['debug', 'release']
  ...
}

3rd party plugins you no longer need

If you are still using the android-apt plugin for annotation processing support, you should remove that and use the built-in annotationProcessor. The third party plugin is no longer supported.

Similarly, many people have been using retrolambda for Java 8 features support. This is no longer required and will simply be provided automatically, so you should remove the retrolambda dependency. ✂️

Variant API changes

You may find that there are Gradle API changes that remove certain functionality. One area that has some differences is the variant API, which mean you will no longer be able to manipulate variant outputs. This is due to variant-specific tasks no longer being created at configuration time.

If you are using the following Gradle syntax, you should check it is still functioning correctly.

android.applicationVariants.all { variant ->
  ...
}

Firebase plugin Guava issue

There is a known issue with the Firebase plugin causing a Guava dependency mismatch. It can be easily fixed by excluding Guava from the Firebase plugin. Only add this if it is needed within your project.

dependencies {
  classpath ('com.google.firebase:firebase-plugins:1.1.0') {
    exclude group: 'com.google.guava', module: 'guava-jdk5'
  }
  ...
}

Robolectric resources issue

This won’t affect everyone, however, if you are using Robolectric you may find there is a problem with missing resources. To fix this simply add the following to the build.gradle for your module.

testOptions {
  unitTests {
    includeAndroidResources = true
  }
}

Why should I update?

There is an endless list of new features and improvements in Android Studio 3.0 and in the new Gradle plugin.

Kotlin programming language support
Android profiler: memory, CPU, network
Java 8 language features built-in
Faster build times
Device file explorer
Instant apps support
Adaptive icon wizard
XML and downloadable fonts
Android Things support
Layout editor improvements
APK profiling and debugging
Layout inspector improvements
Improved Gradle sync speed
AAPT2 is now enabled by default
Firebase app indexing assistant
App links assistants

Hiring Android Developers

Andrew Lord — Mon, 03 Jul 2017 00:00:00 GMT

Since starting my career as a software developer, I have been to interviews at various companies. I have, however, more often been on the other side of the process: reviewing CVs, analysing code submissions and conducting interviews. On a few different occasions, I have been asked how I think the recruitment process should be structured and what is best to look for in Android developers. These questions don't have a simple answer that applies to all situations.

Hiring (and unfortunately not hiring) many developers across my working life has helped me to shape the way I approach it. I am by no means an expert and still have plenty to learn from others on the topic, but I believe (and hope) I have some valuable insights that may help other people hiring developers. Therefore, I will attempt to write down some different steps you could include in your hiring process.

Reviewing CVs

This stage shouldn’t come as a surprise to anyone, as obviously you will need some way for candidates to apply for the position. This is the first opportunity for the candidate to tell you why they think they are right for the job.

For some people a CV might be self explanatory, but it is pretty amazing how varied CVs can be. Over time I must have reviewed hundreds of CVs and almost every single CV is different in length, style, format and content. I have seen a few killer CVs and unfortunately some that weren’t as good.

When reviewing CVs, it is crucial that you be as fair and objective as possible, avoiding any biases you may have. A good way to achieve this is to compare each CV to the same set of requirements that you have decided are needed to do the job. For an Android developer these may include things like:

Live apps on Google Play
X years Android development experience
Performing app releases to Google Play
Network communication such as consuming REST APIs
Automation via Continuous Integration services like Bitrise
Automated unit and UI testing

If possible try to look for a skill rather than its specific application. For example, knowledge of how to consume a REST API, rather than just whether they mention Retrofit and OkHttp. Obviously if a candidate already knows the libraries you use, this can be a great bonus. The focus should, however, be on spotting their level of experience and their ability to learn new skills quickly.

I’m not keen on online tests

The next stage in the process for many companies can involve some form of online test or screening process such as Codility. These tools might make sense for some positions, for example a job that requires intense problem solving or coding quickly under pressure. However, from my experience:

They are very impersonal.
They can be time consuming and stressful for the candidate.
The problems are rarely similar to the type of work the job entails.
People often do better or worse than they would do in a real-world scenario.
They only check the solution rather than the journey to get there.

I'm not saying these online tests are wrong and should never be used. My preference is just to use other ways to find the right person for the role.

Remote / phone / video interview

Once you find a candidate that looks promising it is important to meet them as soon as possible. If the number of applications you are receiving is fairly low you could consider going straight to the on-site interview at this stage. In most situations though you will want a remote interview to take place first.

Remote interviews are usually much shorter than their on-site counterpart, preferably something in the region of 30 minutes or less. The shorter length and the fact they are remote can make them much quicker and easier to schedule with the person applying. They can be a good way to quickly gauge the candidate’s experience, their interest in the position and how well they would fit into the team. By having a conversation, it allows them to form a connection with you and the company. Without this having taken place, if another offer comes from elsewhere they would have a lot less driving them to continue the process with you.

Importantly, this shouldn’t feel like an interview and should be as informal as you can manage, allowing the candidate to relax. Some potential talking points:

Their current role
Working on a particular task
Code reviews
Testing
Continuous Integration

You may also be recruiting for a completely remote position or prefer to do your interviews entirely remotely for ease.

App programming

You are looking to hire an Android developer and so the best way to check their technical proficiency is by looking at how they program an Android application. This might seem obvious, but you will find many recruitment processes that rely on object-oriented or functional programming challenges and whiteboard exercises. I gave my stance on online testing earlier, however, there is a key difference here in that the candidate will be programming in Android, using the tools they are familiar with and often in their own time.

The candidate applying may already have examples of their Android development skills via open source app(s) on GitHub, you could consider looking at these instead to make the hiring process quicker for the candidate.

If you do decide to ask the candidate to work on an app project of yours, the app should either be very simple so that they can complete it in a reasonable amount of time or it should already be partially developed. You should also make it clear that they can use whatever approach they want and use whichever libraries they wish. This will allow you to see how they think an Android app should be developed.

There are many advantages to seeing applicant’s Android code before they come in to interview. You can gain insights into their development processes and how they would work as an Android developer. An important consideration though is that completing an app test does increase the amount of effort they have to put in. Therefore, you will have to decide if you think it makes sense for your company to include this in the recruitment process.

On-site interviews

This will make up the meat of your hiring process and will likely consist of various stages. The main areas you should consider covering are behavioural (team fit) and technical (skill and experience). Before getting started it is a good idea to describe the general format and timings to the candidate. This helps them to understand how much time they have got and what to expect.

Have a conversation

One way of running an interview is that the candidate sits in front of you and is asked a set of different questions, delivering an answer after each one. This approach would only give you answers to your specific questions and would be unnecessarily stressful for the person you are interviewing.

Alternatively, I try to make my interviews as conversational as possible. This means leading things in a certain direction using questions, but allowing the candidate to discuss what they want on the topic. This really shows you how the developer would communicate with other team members and allows them to demonstrate their experience and knowledge to you. By making the questions as open as possible, it will expel the notion that there is a single correct answer you are looking for. Instead the candidate should relax and open up, telling you their opinion freely on a particular topic. You will even find you learn about new things during these conversations.

Behavioural

These types of interviews can often be labelled soft skills or team fit interviews. This should in no way diminish the importance of this area of questioning. If you have put the candidate through the app test already the behavioural component could actually be considered the most important part.

You will ask questions which check the candidate fits with your company culture and the team’s way of working. It will also give the applicant some insight into how the company works. As with reviewing CVs, you should decide which characteristics are most important to you when deciding on your behavioural questions. For example:

Collaboration with other team members
Ability to learn new technologies and skills
Leadership qualities
Communication
How well they can learn from past mistakes

Please don’t ask all the obvious questions we all read about online, such as asking about their strengths and weaknesses.

Instead finding out about situations where they:

Had to learn how to use a new library quickly.
Dealt with a team member who strongly disagreed with their opinion on a code review.
Persuaded other team members to introduce a different app architecture.

Technical

How to run effective technical interviews is a very large and heavily discussed topic. You will also find people have many different opinions of how to go about it.

It is very common for interviewers to ask you to write solutions to problems on a whiteboard. Personally, I have never understood this approach as developers don’t generally spend their days finding substrings, detecting palindromes and writing code by hand on the wall.

Any coding you ask the candidate to do should match what they would do if they got the job. This doesn’t mean you have to get them working on the app they would actually work on. It does, however, mean that they work on an Android app, using the tools they would use and in the environment they would work in.

In reality, developers don’t remember absolutely everything and recall it perfectly on the spot. They sometimes forget the signature for a Compose modifier or the name of the Retrofit annotation they need to use. I think it's a good idea to tell candidates that they can use StackOverflow or the API documentation if they wish.

When working on an Android app, people use libraries like Coroutines, Retrofit and Dagger. This means when they are coding in the interview I think we should make it clear they can use whatever libraries they want to use. You could choose to force them to write plain Android code so you can check they know how to do it. However, I think it's most valuable to see how they would code in a real-world situation. You may even be able to ask why they chose a particular library or particular approach.

As I mentioned earlier, any technical questioning should be as conversational as possible. I generally write down a few topics I would like to find out about and then nudge the conversation in the right direction using my questions. For example:

Handling a slow internet connection
Automated testing
Dependency Injection
Keeping up-to-date with the world of Android development

Time for questions

It is very important that you leave time for candidates to ask you any questions they might have. If the interview was fairly conversational, this may already have been covered. However, if not then it is good to prompt them at the end just to make sure they get the chance to ask any. It is important to remember that you are trying to find the right developer for the team, but they are also trying to find the right company for them.

Closing thoughts

As I have said a few times, there are various different ways you can check candidates are right for the position. The techniques you choose to use and the questions you choose to ask, won’t be the same as other interviewers. If carefully put together, the process will help you find some really great developers who are a good fit for the team and for the company.