DEV Community: Eric Donovan

I've just open sourced N8

Eric Donovan — Fri, 12 Apr 2024 16:06:24 +0000

Hiya

N8 is a pure kotlin, state based navigation library.

I've open sourced it a bit earlier than I usually would have 😬 but that means there is still stuff to do if anyone is interested...

There are some easy issues added already, but there is also more juicy stuff available (to do those, you'll need to understand what's there first though).

I think it's turning into something I'd like to use... but it's early days still.

It's a pretty small library, about 1000 lines at the moment. And the idea is to handle a back stack of locations for you, as your user navigates around the app.

The client code can call functions like this:

n8.navigateTo(Paris)
n8.navigateTo(Seoul)
n8.navigateTo(NewYork)
n8.navigateBack()
n8.navigateTo(Bangkok)

And N8 would maintain an immutable navigation state that looks like this:

backStackOf(
    endNodeOf(Paris),
    endNodeOf(Seoul),
    endNodeOf(Bangkok), <--- current location
)

You can use it to pass data to new locations, or pass data back to previous locations, it handles nested tab style navigation, handles screen rotations, persistence, deep links etc, and you can use it to drive the UI for a compose app like this:

setContent {

  N8Host { navigationState ->

    // this code runs whenever the navigation
    // state has changed e.g. the user has
    // pressed back or navigated to a new page

    val location = navigationState.currentPage()

    ModalNavigationDrawer(
        drawerContent = ...
        content = ...
    )
  }
}

The navigation state can get pretty complicated when nested tabs are involved:

backStackOf(
    endNodeOf(Welcome), <-- home location
    tabsOf(
        selectedTabHistory = listOf(0,2),
        tabHostId = "TABHOST_MAIN",
        backStackOf(
            endNodeOf(MyFeed),
            endNodeOf(Trending),
        ),
        backStackOf(
            endNodeOf(Subscriptions),
        ),
        backStackOf(
            endNodeOf(MyAccount),
            endNodeOf(Settings),
            tabsOf(
                selectedTabHistory = listOf(0),
                tabHostId = "TABHOST_SETTINGS",
                backStackOf(
                    endNodeOf(Audio),
                    endNodeOf(Dolby), <-- current location
                ),
                backStackOf(
                    endNodeOf(Video),
                )
            )
        ),
    )
)

But the idea is that N8 handles all that (and calculating the back operations) for you.

Early feedback and PRs welcome!

Eric

PS it also needs a logo...

Jetpack Compose and WindowSize Classes

Eric Donovan — Tue, 21 Feb 2023 09:32:41 +0000

Unlike iOS, Android was always envisioned as a platform that would run on a range of devices and screen types, created by different manufacturers.

As such, Android has various ways of creating UIs that work well with different physical screen types, and you might have been a little surprised (at least I was) that these techniques have largely been dropped when it comes to Jetpack Compose.

If you're new to Android, the situation can be a bit confusing, especially when pixel density comes in to play.
If you're an old hand you'll know how hard it can be to add responsive design to an app later rather than building it in from the beginning.

So here is a summary of what the modern android developer needs to think about when developing UIs that are expected to work across a large range of screen types.

Our adaptive counter app displayed in split screen mode with the font size settings taking up the other window

We start by reviewing density indepence, then discuss the difference between responsive and adaptive design. But feel free to skip straight ahead to the WindowSize class discussion here

I want things to look the same

Let's get screen density out of the way first as it's a really simple solution.

The problem:

physical pixels aren't the same size... they're not even all square

If you display a 50x50 pixel element on a screen made up of large pixels (the type that you can easily see with the human eye) that element is going to look fairly big (regardless of the physical size of the actual screen).

The same 50x50 pixel element on a screen with a much higher pixel density (i.e. small pixels, like the type that are so small you can't even see them) will be rendered much smaller.

This is probably not what you want. Mostly you want the element to look the same physical size, no matter what the pixel density is of the screen it's being displayed on (this is separate to the size of the screen itself, we'll get to that next)

So we tend to specify things in terms of dp, a type of virtual pixel that may be rendered with 1 physical pixel (if the screen has pixels that are quite large) or maybe 2.5 physical pixels (if the screen has very small pixels)

Obviously I've used images for these examples but the same issue exists for paddings, layout sizes etc.

In any case, I'd say that the screen density issue is mostly a solved problem on Android (especially when preferring vector images over raster-based images). We just need to understand the issue and avoid specifying things in terms of pixels. The Jetpack Compose API also does a good job of encouraging you to specify dimensions using dp, not pixels.

I want things to look big, on big screens

The problem:

Sometimes you don't actually want things to look the same physical size.

Sometimes you want your screen elements to take up more space if more space is available. What's the point of having all that lovely space on a tablet display, if your one-size-fits-all design is squeezed into a little corner?

The pre Jetpack Compose solution for this was to use size-buckets (beyond certain screen size breakpoints, the dimension of the box would be taken from a different bucket). So it could be a 50dp x 50dp element for small screens, but a 100dp x 100dp element for large screens.

Note: the screen sizes we consider here are specified in dp, so they are completely independent of pixel density. It's true that smaller screens are often cheaper and have larger pixels. And that larger, more expensive screens also often have higher pixel densities. But that relationship is not guaranteed. Screen size and pixel density are completely independent, and need to be considered separately.

In Compose, the size bucket system is being replaced by WindowSize classes. Nevertheless, I think what makes the most sense in a compose context is to design our UIs using percentages/proportions of the available space wherever possible.

Let's say an element should be 25% of the width of the screen. That's the same value, whether our screen is a small phone or a large tablet, or (crucially) somewhere in between. Where a particular screen size falls on the boundary between two WindowSizes, percentage based layouts will still work fine.

Another major advantage of this technique is the reduction in overhead needed. Designing, developing, and testing size-bucket style UIs, with multiple sets of dimensions, for multiple screen sizes can be a significant challenge for a large project. Percentage based dimensions also tend to be well understood by design, development and test teams.

For basic element sizes, fillMaxWidth() and fillMaxHeight() are very useful in this regard as they accept a fraction parameter:

  modifier = Modifier.fillMaxWidth(0.25f)

To derive other values from the space available, BoxWithConstraints is also very useful:

BoxWithConstraints {

  val derivedDimension = this.maxWidth * 0.10f // 10% of the width

  Box(modifier = Modifier.padding(derivedDimension)){
    // content
  }
}

Be careful here though. Depending on what your parent view is, the values for maxWidth or maxHeight can sometimes be Infinity.dp, there's a solution for that below

I want alternative layouts for different screen sizes

The problem:

Scaling the same design to be bigger or smaller will only get you so far, sometimes the actual design needs to change

Let's say we have a design for a TV Guide that we hope our users will enjoy using on their android tablet. Maybe we can have a nice big grid with a row per channel, and the programs on that channel going from left to right.

If we specify our dimensions in terms of percentage of the screen, it's possible that we can use this same design on a phone too (it'll work, it'll just look a little smaller).

But there will be a point where scaling things won't work. That same design on a watch sized display would be unusable. That requires a completely different TV Guide UI.

Replacing the layout with an alternative one more suited to our user's screen size, is what the Android docs call "Adaptive design" (as opposed to responsive design). And if we get to this point, we need to talk about WindowSize classes...

WindowSize Classes

The current Android docs do have some advice about this, but the advice comes pretty close to saying "do it yourself". That's especially true if you look at the kotlin views example:

enum class WindowSizeClass { COMPACT, MEDIUM, EXPANDED }

fun computeWindowSizeClasses() {

    val widthDp = //... from WindowMetricsCalculator

    val widthWindowSizeClass = when {
        widthDp < 600f -> COMPACT
        widthDp < 840f -> MEDIUM
        else -> EXPANDED
    }

    val heightDp = //... from WindowMetricsCalculator

    val heightWindowSizeClass = when {
        heightDp < 480f -> COMPACT
        heightDp < 900f -> MEDIUM
        else -> EXPANDED
    }

    // Use widthWindowSizeClass and heightWindowSizeClass.
}

At least with the compose version, they have provided that function for you, which does approximately the same thing:

val windowSizeClass = calculateWindowSizeClass(this)

Presumably this is intended to be used like this:

val boxPadding = when (windowSizeClass.widthSizeClass) {
    Compact -> 2.dp
    Medium -> 10.dp
    else -> 25.dp
}

Box(
    modifier = Modifier.padding(boxPadding)
) {
    // box content
}

Box {
    if (windowSizeClass.widthSizeClass == Compact) {
        SomeSmallLayout()
    } else {
        SomeLargeLayout()
    }
}

I've been a bit surprised at how basic / ad hoc this code seems to be, but the package is still marked as experimental currently.

Firstly, it doesn't look that maintainable. With a larger more complex UI, all the if statements might start to become problematic.

It also feels a bit risky that the breakpoints these classes are built on are hard coded, and we're only being given size classes for Width and Height (not Orientation or Minimum Dimension for example)

Something that might not be apparent to someone using this code until they need to implement a UI for a small screen: the sizes themselves are huge. COMPACT covers everything up to 600dp in width (which means there is no way to distinguish between large phones, small phones, or watch size screens).

Of course a lot of the time you won't need that level of granularity, but sometimes you will. And if we already built half of the app with a certain breakpoint scheme, it's a little late to realise it doesn't do what we need it to do for the next piece of UI we tackle.

// width
COMPACT < 600 <= MEDIUM < 840 <= EXPANDED
// height
COMPACT < 480 <= MEDIUM < 900 <= EXPANDED

Also, and this probably just my personal issue, but the naming... SMALL, MEDIUM, LARGE not good enough? this isn't Starbucks 😂

The maven package this code comes from is material3-window-size-class and maybe its going to improve as it is still experimental at the moment.

But the breakpoints are taken from the Material3 design guidelines themselves, so they probably won't change, and they may not be what you actually want (the docs do claim that it's "opinionated" and I assume that's why).

The trouble is it doesn't serve the needs of projects that:

a) aren't that interested in Material3 design beyond picking a few components and design elements or
b) want the option to write UI code that will work on any size of android screen, and not treat everything with a portrait width of less than 600dp as the same device!

Even the horizontal grid system discussed in Material2 and referenced by the Material3 docs, would not be implementable with the breakpoints provided by material3-window-size-class. For example:

600dp is the breakpoint to switch from 4 to 8 columns
905dp switches to 12 columns, with scaling margins
1240dp margins no longer scale, but content does
1440dp content stops scaling, margins take over again

I suspect there'll be a fair number of developers who don't have time to read an article like this one, or to investigate the material3 breakpoints themselves and live to regret building their UIs with these hard coded breakpoints. Only time will tell I guess.

An attempt at a better WindowSize class

Firstly in an ideal WindowSize scheme, we'd want to be able to select a preferred value, based on just SMALL vs LARGE. A lot of app projects are going to want to support two versions of a design and that's all. Here's how we would specify the responsive boxPadding example we had above:

val boxPadding = WidthBasedDp(s = 5.dp, l = 53.dp)

Maybe we have some rather specific designs that require a different value for screen sizes roughly equivalent to: watches, small phones, large phones, tablets, large desktops

val boxPadding = WidthBasedDp(
  xs = 2.dp,
  s = 3.dp,
  m = 5.dp,
  l = 20.dp,
  xl = 50.dp
)

There are a lot of ways to pick a value, it won't always be the width, so for example we can do this too:

val boxPadding = HeightBasedDp(s = 3.dp, m = 5.dp, l = 20.dp)
val boxPadding = AspectBasedDp(port = 3.dp, land = 15.dp, squarish = 5.dp)
val boxPadding = MinDimBasedDp(s = 3.dp, m = 5.dp, l = 20.dp)

And of course we don't just want adaptive dps, sometimes it's useful to have a Float or a TextUnit based on a WindowSize class too:

val myInt = WidthBasedInt(s = 3, m = 5, l = 20)
val myFontSize = AspectBasedTextUnit(port = 3.em, land = 6.sp)
val myFloat = HeightBasedFloat(s = 3.fl, l = 20.fl)

In fact, why not allow us to choose anything based on a WindowSize class:

val myLabel = AspectBasedValue<String>(
    port = "the view is portrait",
    land = "the view is landscape",
    squarish = "the view is approximately square"
)

Lastly we need to be able to select a Composable based on a WindowSize class in the event that we want a completely different layout:

private val MyAdaptiveLayout = MinDimBasedComposable(
    s = { SomeSmallLayout() },
    l = { SomeLargeLayout() },
)

That allows us to keep our Compose layout code a little clearer at the point of use:

Box {
    MyAdaptiveLayout(size)
}

In fact all of the above should reduce the amount of branching you need to do in subsequent layout code (less if statements)

And of course, we want this to be recomposed whenever the screen dimensions change (for example when a user displays your app in split screen mode, or opens their foldable)

val size: WindowSize = rememberWindowSize()

As a convenience for when we want to use the screen dimensions for calculating other dimensions (see above re BoxWithConstraints) I've left the original DpSize used to calculate WindowSize class inside of itself for easy access:

data class WindowSize(

    val width: Width,
    val height: Height,
    val minDim: MinDim,
    val aspect: Aspect,

    val dpSize: DpSize,
)

It also might be useful to implement Comparable (as the Material 3 WindowSizeClass does) so that we can do things like this when we absolutely have to:

if (size.height >= Height.Medium) {
  ...
}

(IMO though, this is a bit of an anti-pattern because it introduces imperative style code into our layouts. I almost didn't support it, but no doubt you could make a case for doing it sometimes, for pragmatic reasons or whatever)

Finally, it's a bit of an edge case, but the WindowSize implementation in the sample app below can be combined like this:

val shape = MinDimBasedValue(
    xs = AspectBasedValue(
        port = CircleShape,
        land = CircleShape,
        squarish = RectangleShape
    ),
    m = FixedValue(CircleShape),
    l = FixedValue(CircleShape),
)

That sets the shape to a circle unless: 1) the minimum dimension is xs and 2) window is squarish.

It's a bit clunky and the only thing I'm not delighted about to be honest, you'd need to use it like this: shape(size)(size), rather than just shape(size). (If you can think of a simple way to make that a little nicer, please send me a PR!)

BreakPoints

As a reminder, the dp values from Material3 are:

// width
COMPACT < 600 <= MEDIUM < 840 <= EXPANDED
// height
COMPACT < 480 <= MEDIUM < 900 <= EXPANDED

These are the breakpoints I think will be more widely useful for an android UI:

// width
XS < 250 <= S < 400 <= M < 500 <= L < 900 <= XL
// height
XS < 250 <= S < 700 <= M < 900 <= L < 1280 <= XL

Here's why I think that:

And plotted on a graph

It's a fairly small sample of devices, but enough to highlight some short comings of the Material3 breakpoints.

Ok 99.96% of phones in portrait mode are <600dp in width, but is that useful? Note: that's completely different to saying 99.96% of devices <600dp in width are phones in portrait mode.

(And what's the definition of a phone screen anyway? If you define a phone screen as something that has <600dp width, then it's 100% isn't it 🤔)

Here's the Material3 inspired COMPACT breakpoint expressed as a venn diagram:

So there are many android devices with screens much smaller than 600dp width that we might want to design for separately. But we also can't forget modes like "split-screen". Many of the larger phones when in split screen mode can give your app a window size equivalent to a very small phone. With "picture-in-picture" or "free-form" mode, all bets are off.

For instance I have a Samsung tablet with me right now which offers a "pop-up" mode that enables a user to resize the window of our sample counter app, to an arbitrary size.

Material3 design breakpoints don't consider any of these cases as it's a design system very focussed on the larger end of the screen size scale.

The data are here, please let me know if you come across any outlier devices that might be worth adding

Whichever breakpoints we chose, we want them to be configurable, just in case. That's certainly true if we want to build those values into a library. Having no way to change them would be asking for trouble.

But as long as we have the possibility to do something like this if we need to, things should be fine:

BreakPoints.overrideBreakPoints(
    ViewPortBreakPoints(
        widthSDpBelow = 400.dp,
        widthMDpBelow = 500.dp,
    )
)

The code that supports all this is here (it's less than 500 lines of code, so there's not much to it). There is a note in BreakPoints.kt about how to override the values to recreate the behaviour of the Material3 WindowSize classes if you wanted to.

I'll probably end up committing this to the fore compose package but until I do (or in case I don't) if you want it, just go ahead and copy it into your project (and please let me know if you improve on it!)

Example app

I've put together a very basic counter app demonstrating the use of all the code we've discussed so far.

Something I've found very helpful is to have a single preview function that uses the windowSize breakpoints to generate all the edge case preview sizes for you in one view

@Preview(widthDp = wXS_low, heightDp = hXS_low)
@Preview(widthDp = wXS_high, heightDp = hXS_high)
@Preview(widthDp = wS_low, heightDp = hS_low)
@Preview(widthDp = wS_high, heightDp = hS_high)
@Preview(widthDp = wM_low, heightDp = hM_low)
@Preview(widthDp = wM_high, heightDp = hM_high)
@Preview(widthDp = wL_low, heightDp = hL_low)
@Preview(widthDp = wL_high, heightDp = hL_high)
@Preview(widthDp = wXL_low, heightDp = hXL_low)
@Preview(widthDp = wXL_high, heightDp = hXL_high)
@Composable
fun MyPreview() {
    PreviewWithWindowSize {
        MyLayout(size = it)
    }
}

In the case above, our WindowSize class is being created directly from the width and height dimensions set on the Preview annotation, and then being passed into our compose layouts.

This gives me a view that looks like this so I can tell at a glance if there are likely to be any edge case issues with the design

That probably looks a little strange, so what's actually happening here is that the colour for the shape is selected based on the width dimension of the screen

val color = WidthBasedValue(
    xs = Color.Red,
    s = Color.Green,
    m = Color.Blue,
    l = Color.Magenta,
    xl = Color.Gray
)

The preview sizes have been deliberately picked so that they exist on the WindowSize class boundaries, because it's there we are more likely to uncover edge cases that don't work.

For example the 4th preview is the largest possible screen we can have which still counts as S (that's why the shape is green). The 5th preview, which is only 1.dp larger than the 4th preview, is the smallest screen we can have that still counts as M (that's why the shape is blue).

So the first two previews are XS Width, the next two are S Width, and so on until we reach the gray shapes which are both XL Width.

You'll notice that the shape is sometimes oval, sometimes rectangular. That's because the shape is selected based on the Orientation of the screen as follows:

val shape = AspectBasedValue(
    port = CircleShape,
    land = CircleShape,
    squarish = RectangleShape
)

The font sizes, buttons and thickness of the shape border are scaled directly from the screen dimensions. As our WindowSize class includes the DpSize of the window that was originally used to create it, we use that value to run our calculations (this avoids the gotcha we saw above with using BoxWithConstraints)

val minimumDimension = size.dpSize.minimumDimension()
val borderThickness = minimumDimension * 0.10f
val boxHeight = minimumDimension * 0.50f
val numberFontSize = (minimumDimension / 5f).value.sp

Finally there are also two slightly different diagnostics composables which are selected based on the Width class of the screen

@Composable
fun BoxScope.DiagnosticInfo(size: WindowSize) {
    WidthBasedComposable(
        xs = { sz -> MiniDiagnostics(sz) },
        m = { sz -> MiniDiagnostics(sz) },
        l = { sz -> RegularDiagnostics(sz) },
    )(size)
}

It's used like this in the layout:

Box {
  DiagnosticInfo(size)
}

Well that was a pretty long one, thanks for sticking around till the end!

The sample app which includes the Preview annotations and all the WindowSize code is available on github git clone git@github.com:erdo/compose-windowsize.git

Intro to Eithers in Android

Eric Donovan — Thu, 09 Jun 2022 09:06:19 +0000

It's not often you come across Eithers in android code, which I think is a shame given how awesome they are. (We've been using Eithers to chain networking results and handle errors in fore since late 2019).

The thing is, they are a little... weird.

I think we all instinctively understand what an Either is: it's a single type that represents either thing A or thing B; never both; never neither.

Nothing in that description talks about errors or successes, so, many implementations use the more generically applicable names: Left and Right. And by convention (if we are dealing with success / error data) Left is used for the error case, and Right is used for the success case (it's the "right" answer after all).

Either.left(ERROR_NETWORK)

bit weird.

One of the most famous implementations of Either is from the Arrow-Core library. For a while, they were using the names "a" and "b" (they use "value" now) to represent the data contained by the Left and Right either respectively, so we had this:

when(either){
    is Either.Left -> either.a // bad stuff
    is Either.Right -> either.b // good stuff
}

still weird.

Don't get me wrong, if Eithers are your bread and butter, this is normal stuff that fades into the background. Why would anyone put the success on the Left anyway???

Despite that though, I've found that Either's very slight weirdness (and the requirement that you need to remember that Left holds the error case) is enough to put non-functional developers off using them.

Which is a shame.

A less weird Either

There is nothing special about the words Left and Right, those words are only generic terms if you happen to not be developing a driving app for instance (where the words Left and Right would have a special significance). In fore (and probably in most cases) the Eithers are exclusively dealing with success / error data. And that's why fore changed its Either implementation to this instead (feel free to copy paste into your own project):

sealed class Either<out F, out S> {

  data class Fail<out F> internal constructor(val value: F) : Either<F, Nothing>() {
    companion object {
      operator fun <F> invoke(f: F): Either<F, Nothing> = Fail(f)
    }
  }

  data class Success<out S> internal constructor(val value: S) : Either<Nothing, S>() {
    companion object {
      operator fun <S> invoke(s: S): Either<Nothing, S> = Success(s)
    }
  }

  companion object {
    fun <S> success(value: S): Either<Nothing, S> = Success(value)
    fun <F> fail(value: F): Either<F, Nothing> = Fail(value)
  }
}

So now we can make them like this

success(serviceResponse)

/** or **/

fail(ERROR_NETWORK)

and use them like this

when(either){
    is Fail -> either.value // sad face
    is Success -> either.value // happy face
}

or with auto-complete

less weird.

Fail or Error

Why did we use Fail instead of Error? Because every time you type Error in your IDE when writing kotlin, you will immediately be referencing:

public actual typealias Error = java.lang.Error

Which is not what you want. Fail doesn't have this problem.

Converting Eithers

Just in case you wanted some other kind of Either (like the one from Arrow) it's very easy to convert between eithers:

fun <F, S> Either<F, S>.toArrow(): arrow.core.Either<F, S> {
    return when(this){
        is Fail ->  arrow.core.Either.left(this.value)
        is Success -> arrow.core.Either.right(this.value)
    }
}

/** which can be used like this **/

val arrowEither = foreEither.toArrow()

So you said Eithers were good?

That's probably a whole article in itself. But as long as you set them up properly, they can help you handle error conditions in such a way that the compiler will notice if you don't do it. That's why fore uses them in the networking CallWrapper classes.

The reason I absolutely love them though, is that they are so easy to chain together. With this little extension function we get some pretty amazing wins:

suspend fun <E, S, S2> Either<E, S>.carryOn(
        nextBlock: suspend (S) -> Either<E, S2>
): Either<E, S2> {
    return when (this) {
        is Either.Fail -> this
        is Either.Success -> nextBlock(value)
    }
}

What that does is to call the nextBlock() whenever the either is a Success (thus continuing the flow of code) or just return the either if it was a Fail. If you were pedantic enough, you might call that function carryOnIfThatLastOperationWasASuccess(). It lets us write things like this:

val response = createUserUseCase()
  .carryOn { user ->
    createUserTicketUseCase(user.userId)
  }.carryOn { ticket ->
    ticketRef = ticket.ticketRef
    getEstimatedWaitingTimeUseCase(it.ticketRef)
  }.carryOn { minutesWait ->
    if (minutesWait > 10) {
        cancelTicketUseCase(ticketRef)
    } else {
        confirmTicketUseCase(ticketRef)
    }
  }.carryOn {
    claimFreeGiftUseCase(ticketRef)
  }

when (response) {
    is Fail -> handleFailure(response.value)
    is Success -> handleSuccess(response.value)
}

If all those useCases return Eithers, we basically have:

no callback hell
highly dense business logic
complete confidence that errors are being handled

You can see this technique being used to create a weather report by calling separate wind speed, pollen level, and temperature services in this clean modules sample app

I'd highly encourage you to give Eithers a go if you haven't already, you might be pleasantly surprised! Check the Arrow link at the top if you want to dig deeper. Also check out fore :) it's meant to make things like this very easy and concise. Thanks for reading!

Tic-tac-toe: from MVP to Jetpack Compose

Eric Donovan — Tue, 01 Feb 2022 19:45:36 +0000

There are two fundamental ways of thinking about data that drives a UI.

We can think of our data as state or as events/messages. Here's what I mean:

I am 3 years old

That's a "state-y" way to represent someone's age, instead you could put it like this:

I was born I had a birthday I had a birthday I had a birthday

That's an "event-y" way to represent the same thing.

Notice how the events tend to occur at the state change boundaries (a birthday event happens when your age state changes from 2 to 3). It's almost like we have two parallel worlds representing the same thing, the state world and the event world.

Erm... okay. Why are you telling me this? MVP is a very event-y style architecture (yes I did just make that word up), whereas Jetpack Compose does really well with state-y style data. That's what makes migrating from MVP to Jetpack Compose a little tricky. But if we recognise this state vs event difference first, migrating can be relatively pain free.

Event-y

I'm not going to go into the details of how MVP is typically set up on android. There has been a long slow march away from MVP in android for almost 10 years, but there are still a lot of MVP apps around and chances are, if you're reading this article, you probably already have one in mind.

Let's just imagine the view interface / contract we might have with an MVP version of our tic-tac-toe app. Maybe something like this:

fun showLoadingSpinner()
fun hideLoadingSpinner()
fun populateTile(xPos: Int, yPos: Int, mark: Player)
fun showError()
fun hideError()
fun showNextPlayer(player: Player)
fun showWinner(player: Player)
fun hideWinner()
fun resetGameView()

This is why I say most MVP apps are event-y, they tell the view what to do or what happened (not what is).

Take a look at your own MVP app, you'll probably find the same thing.

State-y

So how would we re-write this in a state-y way? We just need to come up with a state that covers every possible situation our view will need to display. Kotlin data classes are pretty good for this, but by no means mandatory. This should do the trick:

data class GameViewState {
   val isLoading: Boolean,
   val error: Error?,
   val nextPlayer: Player,
   val winner: Player,
   val board: List<List<Player>>
}

sealed class Player {
    object X : Player()
    object O : Player()
    object Nobody : Player()
}

This happens to be an immutable state, so it's easy to guarantee that it won't change while the view is updating the screen.

It doesn't have to be immutable though, we could also manage this state inside a regular class. The view just needs to be told to sync itself whenever any of the state changes (you have to be aware of threading issues with this one, but it also works fine):

class Game {

   ...

   fun isLoading(): Boolean {...}
   fun error(): Error? {...}
   fun winner(): Player {...}
   fun tile(xPos: Int, yPos: Int): Player {...}
}

The point is, with state-y driven code we are telling the view what is (not what to do or what happened).

How we calculate this state (the actual logic of the game) is kept safely away from the view layer. The logic of a tic-tac-toe game doesn't need to know anything about android activities or fragments. It's plain logic, and it would be the same logic if it was driving an iOS tic-tac-toe app (it would be a good contender for keeping in a kotlin only domain module if we were writing a clean architecture app).

Imperative vs Declaritive

Take a moment to notice that event-y style code sounds a lot like imperative programming - telling your view what to do. And state-y style code sounds a lot like declaritive programming - telling your view what is

Drawing the Non-Compose UI

Back to our pre-compose tic-tac-toe app for the moment. We've changed the type of data that is driving our view, so now we also need to change how the view is drawn.

Let's take the loading spinner, our event-y MVP code looks like this:

fun showLoadingSpinner() {
   spinner.visibility = View.VISIBLE
}

fun hideLoadingSpinner() {
   spinner.visibility = View.GONE
}

it's fairly easy to write a more state-y version like this:

If (viewState.isLoading) {
   spinner.visibility = View.VISIBLE
} else {
   spinner.visibility = View.GONE
}

But the secret is to put the focus on the UI attribute itself, so we can instead write:

spinner.visibility = if (viewState.isLoading) VISIBLE else GONE

If you do this correctly you can have a single line for each UI attribute (and typically that means far fewer lines of code than the event-y version)

We've actually seen this trick before when we re-wrote the android architecture blue prints todo sample app. In that case the event-y view code went from over 100 lines to an almost embarrassing 8 lines of state-y code. If you haven't read that article, you probably find that hard to believe - but it's not an exaggeration.

Reactivity

The final piece of the puzzle is that we need some way of letting the view know that it's time to redraw itself. There are loads of ways to do this, basically some kind of observer implementation: RxJava, Flow, LiveData, etc. I'm going to use fore because a) I wrote it 😬 and b) it's impossible to do it with less boiler plate.

class TicTacToeActivity : FragmentActivity(R.layout.activity_tictactoe), SyncableView {

  //models that we want to observe
  private val gameModel: GameModel = OG[GameModel::class.java]

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

    //setup observers
    lifecycle.addObserver(LifecycleObserver(this, gameModel))

    //setup click listeners
    viewResetBtn.setOnClickListener { gameModel.reset() }
    ...

  }

  //called on the UI thread, whenever the gameModel state changes
  //you could instead observe some LiveData state, or collect a Flow here
  override fun syncView() {
    gameModel.state.apply {
      viewResetBtn.enabled = !loading
      viewIsBusyProg.showOrInvisible(loading)
      viewWinnerText.text = winner
      viewWinnerText.showOrInvisible(winner != Player.Nobody)

      // more ui elements
      ...
    }
  }
}

Congratulations 🎉 you now have "state-y" data driving your UI 😬 It's performant, supports rotation, and doesn't have any memory leaks - so this is a good place to be already. Access your GameModel via a ViewModel, and you'll have a basic MVVM app.

Now we're driving our UI with state, the entire view layer of our app (the Activity class in this case) takes up around 70 lines of code including imports. If we had started out with something like MVI rather than MVP, we would probably be a lot closer to this level already.

Replacing the view layer with Compose

If you get to this point in your migration, you can now focus just on Compose itself. The game model won't need to change, and the rest of the app won't even be aware that it's now driving a compose view layer.

The whole of Jetpack Compose is driven by state, and state is what we already have - but first we need to convert our state to an instance of Google's State<> class.

Most flavours of observable have an extension function that will do the conversion for you.

// Fore
val gameVS by gameModel.observeAsState { gameModel.state }
// Flow
val gameVS by gameModel.gameFlow.collectAsState(GameViewState())
// LiveData
val gameVS by gameModel.gameLiveData.observeAsState(GameViewState())

(While writing the extension function for fore I used a demo app to investigate the behaviour of the LiveData and Flow implementations, it's here in case you find it useful.)

Here's (most of) the Compose UI code for an equivalent view. It's a lot of code, but we'll discuss that in a sec:

@Composable
fun GameScreen(
    game: Game,
    modifier: Modifier = Modifier,
    switchToNonComposeUI: () -> Unit
) {

    val viewState by game.observeAsState { game.state }

    Box(
        modifier = Modifier
            .fillMaxSize()
            .padding(dimensionResource(id = R.dimen.common_space_small))
            .then(modifier),
    ) {

        HeaderLayout(viewState, retry = { game.retryAutoPlayer() }, Modifier.align(TopCenter))

        BoardLayout(
            viewState.isLoading,
            viewState.error,
            viewState.board,
            Modifier.align(Center)
        ) { x, y ->
            game.play(x, y)
        }

        Column(
            modifier = Modifier
                .wrapContentSize()
                .align(BottomCenter),
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            Button(
                modifier = Modifier
                    .wrapContentSize(),
                onClick = { game.newGame() },
                enabled = !viewState.isLoading
            ) {
                Text(stringResource(id = R.string.reset))
            }
            Spacer(modifier = Modifier.width(dimensionResource(id = R.dimen.common_space_small)))
            Button(
                modifier = Modifier
                    .wrapContentSize(),
                onClick = { switchToNonComposeUI() },
            ) {
                Text(stringResource(id = R.string.non_compose_ui))
            }
        }
    }
}

@Composable
fun HeaderLayout(
    viewState: GameState,
    retry: () -> Unit,
    modifier: Modifier = Modifier
) {
    Column(
        modifier = Modifier
            .wrapContentSize()
            .then(modifier),
        verticalArrangement = Arrangement.Top,
        horizontalAlignment = Alignment.CenterHorizontally
    ) {

        if (viewState.gameFinished()) {
            Text(
                text = stringResource(viewState.winner.winMessageRes),
                color = colorResource(id = R.color.colorTextTitle),
                fontSize = fontSizeResource(id = R.dimen.common_textsize_extra_large),
                fontWeight = Bold
            )
        } else {
            Text(
                text = "${viewState.whoseTurn().label} ${stringResource(id = R.string.to_play)}",
                color = colorResource(id = R.color.colorTextTitle),
                fontSize = fontSizeResource(id = R.dimen.common_textsize_extra_large)
            )
        }

        if (viewState.isLoading) {
            CircularProgressIndicator(
                modifier = Modifier
                    .wrapContentSize()
                    .padding(dimensionResource(id = R.dimen.common_space_small)),
            )
        }

        if (viewState.error != ErrorMsg.NoError) {
            Text(
                modifier = Modifier.wrapContentSize(),
                text = stringResource(viewState.error.msgRes),
                color = colorResource(R.color.colorWarning),
                fontSize = fontSizeResource(id = R.dimen.common_textsize_extra_large)
            )
            Button(
                modifier = Modifier.wrapContentSize(),
                onClick = { retry() }
            ) {
                Text(stringResource(id = R.string.retry_autoplayer))
            }
        }
    }
}

@Composable
fun BoardLayout(
    isLoading: Boolean,
    error: ErrorMsg?,
    board: List<List<Player>>,
    modifier: Modifier = Modifier,
    tileClick: (x: Int, y: Int) -> Unit
) {
    Column(
        modifier = Modifier
            .wrapContentSize()
            .then(modifier)
    ) {
        var colorIndex = 0
        for (y in board.size - 1 downTo 0) {
            Row {
                for (x in board.indices) {
                    if (isLoading || error != ErrorMsg.NoError) {
                        GameSquare(colorPastels[colorIndex++ % colorPastels.size], board[x][y]) { }
                    } else {
                        GameSquare(colorPastels[colorIndex++ % colorPastels.size], board[x][y]) {
                            tileClick(x, y)
                        }
                    }
                }
            }
        }
    }
}

Compose Yourself!

Wait a second... that legacy state-y view layer code looked clearer than the Compose version 🤔 It was also smaller and slightly more performant, so what's going on here?

While that might be true (even if we allow for the fact that the compose code did away with the XML layouts), I believe that's somewhat missing the point of Compose.

Dynamic UIs are the future

Compose is looking to a future where devices are more performant, not less. The UIs of tomorrow are likely to be much more dynamic and animated. And animating changes are the achilles heel of state-y driven UIs.

Let me explain that. If you think about when you might want to animate something on screen, it's typically at the state change boundaries. When someone goes from being 2 years old to 3 years old, you might wish to run a "happy 3rd birthday" animation. But that's a one time thing, if you ever get in to a situation where you're wishing someone happy birthday twice in the same day, well... that's weird.

That's something event-y driven architectures excel at because they're already event based. When the UI layer receives the "3rd birthday" event -> it runs the "happy 3rd birthday" animation. Easy.

State-y driven architectures have a problem here. When our UI layer receives the latest state, it knows that person is 3 years old (age=3). But did they become 3 just now?, have they been 3 for 6 months already? Did the UI already wish them happy birthday, and then they just left the room and came back (i.e. rotated the screen)?. The UI layer doesn't know without resorting to storing the latest state and looking for changes. There are many, many, many ways to handle this of course (and fore has its own solution too). It's a universal, if not very often discussed, problem.

Well this is where Compose really shines, that whole looking-for-changes-to-state thing is what Compose does for us (Compose is actually two systems, but that's outside the scope of this article), we just provide it with our latest state whenever we have it, and compose handles the rest for us. As the number of animations in a typical UI increases, you can probably appreciate how this could start to be the more scalable solution from a complexity point of view.

A few more thoughts

Composables are functions, and are very well suited for reuse provided they're written with that in mind. Sure we can do that with XML based layouts too, but it's not pretty.
A lot of state driven UIs have a function where all the UI states are set. In the example above we have syncView(), in an MVI app you might have a render() function. If this function is written correctly, most UI inconsistencies can be quickly narrowed down to a single line of code in a 10-20 line function. It's an incredibly powerful way to debug UIs, but I don't see a way that would be possible with Compose at the moment.

But Compose is pretty new! I'm interested to know what you think about it in the comments

Thanks for reading, hope you get a chance to play a few rounds 😂

Note: if you do, the auto player makes a real network connection to mocky.io so it will take up to 30 seconds to wake up on first play

Also, the auto player is not a particularly smart opponent, but know that when ~~playing~~ testing this game, I still lost to it several times 🤦

Clone the app on github

Android: Apollo3 and GraphQL

Eric Donovan — Tue, 19 Oct 2021 18:42:14 +0000

There is a pre-primer here if you're completely new to GraphQL and Apollo.

Let's run through a small GraphQL driven Android app. We'll touch on a few things which are specific to Apollo3 as we go, but most of this post applies to the previous Apollo version too. [At the time of publication, Apollo3 is still in alpha, but 3.0.0 is coming soon. You can check the maven repo to see the latest releases]

Why Upgrade

Here's why you might consider upgrading to Apollo3 soon:

Pure kotlin (like Ktor), which opens up the possibility of using it in a KMP project
True coroutine API so no need to use latches etc for unit testing
Apollo3's autogenerated DTOs make much better use of query fragments, so your mapping code will be DRYer (no more Node1, Node2, Node3 classes)

Why Apollo3 not just Apollo v3? for the same reason it's Retrofit2. The different name space allows your app to migrate to Apollo3 in stages. Or to migrate your app code to Apollo3 while continuing to use libraries that might still be tied to the previous Apollo.

Adding Apollo3 to your android project

Go ahead and clone the sample app, but the basic steps if you're doing it for your own app are:

add the plugin

plugins {
  ...
  id("com.apollographql.apollo3").version("3.0.0")
}

configure the plugin

apollo {
    packageName.set("foo.bar.myapp")
    srcDir("src/main/graphql")
}

add a dependency on apollo-runtime

implementation("com.apollographql.apollo3:apollo-runtime:3.0.0")

download the server schema from the command line

./gradlew downloadApolloSchema \
  --endpoint="https://stuff.thing/graphql-endpoint" \
  --schema="app/src/main/graphql/schema.json"

If you're doing this at work, you'll probably need to be on your company's VPN to download the schema and it might only be downloadable from the staging server, not from the prod server, but they should match anyway

add a graphQL request file and put it next to where the schema file has been downloaded, this one is called LaunchList.graphql

query Launches {
 launches {
  cursor
  hasMore
  launches {
    id
    site
    mission {
      name
      missionPatch(size: SMALL)
    }
    isBooked
  }
 }
}

You won't be able to see these files in the regular Android view, you'll need to switch to the Project view:

Sync the project and click Build -> Make Project and you should be able to see the autogenerated Apollo DTOs from your autocomplete. Once everything is done, try typing LaunchesQuery

Make the call

The basic Apollo3 call looks like this. LaunchesQuery() is generated for you by Apollo, based on the query we added above, and apolloClient.query() is a suspend function so we need to call this from within a coroutine

apolloResponse = apolloClient.query(LaunchesQuery())

Code like this is a little bit raw, we can get all sorts of edge cases here because a network call is being made. We need to ensure we are not just handling the ApolloResponse (which can contain success data, or error(s), or both), but we also need to handle any issues that could happen in the HTTP server or cache layer before we even get to the GraphQL bit (e.g. 500s or 404s), and also exceptions that can be thrown before we even manage to get a network connection (e.g. java.io.IOException).

I will leave that as an exercise for the reader... just kidding 😬

Robustness / Error Handling
Testing
Diagnostics / Logging

These are the things that separate a proof of concept app from a production quality commercial app, so let's dig in to those areas as they relate to Apollo.

Robustly handling network errors

The first thing I'd recommend, is to handle these errors in some centralised, consistent way (a lot of the error handling is common to every call we will make, so there is no point in repeating it). Here's the ErrorHandler for our sample app.

My second recommendation for your consideration, is to handle these errors in your networking or data layer or wherever it is you place the apollo query code. This makes the first recommendation easier, because errors will be caught before they bubble up to potentially many different parts of the app's UI to be handled there (or more likely not handled at all).

In the sample app, we are using a CallProcessor class (from the fore library) to wrap the Apollo calls and enforce error handling.

val result = callProcessor.processCallAwait {
  apolloClient.query(LaunchesQuery())
}

When the calls are wrapped like this, you won't need to handle any exceptions, or networking issues (well actually you are handling them, the CallProcessor just delegates this responsibility to the ErrorHandler class and requires that you provide it - see above). The result you get back will contain an Either<Failure, SuccessResult>

A SuccessResult in this case looks like this:

data class SuccessResult<S, F>(
  val data: S,
  val partialErrors: List<F> = listOf(),
  val extensions: Map<String, Any?> = hashMapOf(),
  val executionContext: ExecutionContext = Empty
)

(data will be the auto generated network DTOs containing your stuff)

The Failure class is something you define yourself (a kotlin data class or an enum would be ideal) and it's created by the ErrorHandler linked to above.

In a previous clean architecture sample, we had something like this:

sealed class DataError(val resolution: DomainError) {
  object Misc: DataError(RETRY_LATER)
  object Network: DataError(CHECK_NETWORK_THEN_RETRY)
  object Client: DataError(RETRY_LATER)
  object RateLimited: DataError(RETRY_LATER)
  object SessionTimedOut: DataError(LOGIN_THEN_RETRY)
  object Busy: DataError(RETRY_LATER)
}

The next step usually involves mapping your network/data layer objects to domain objects, or whatever you like (according to your architecture).

when (result) {
  is Right -> // handle success
  is Left -> // handle failure
}

In the absence of this kind of error handling strategy, what usually happens when a generic networking bug is raised in production in a specific part of the app's UI: it will only be addressed in that specific place, without porting that error handling code to all the other places that network requests are being made.

Partial successes

One of the interesting things about GraphQL is that it provides for partial success results that have some errors attached.

If you want to take advantage of these half-success results with the CallProcessor, then you can set the allowPartialSuccesses flag to true. In which case your SuccessResults may include a non empty partialErrors list. (if that flag is set to false, these half-success cases are considered normal Failures).

Testing

Your architecture will somewhat dictate where you can put the boundaries of your test code.

Unit Testing

If you are making your requests directly on the apolloClient instance, and this is being passed in to the class you are trying to test, that would be a convenient place to mock. (During a test, your mocked apolloClient instance can return ApolloResponse objects containing valid DTOs or throw exceptions as appropriate).

If you are wrapping the Apollo calls like we do in the sample app with a CallProcessor or similar, it's arguably a little easier. This time during a test, you will be mocking the CallProcessor to return an Either<Success> or an Either<Failure>, with no need to have your mocks throw exceptions. There's an example of this test strategy in the apollo3 sample in the main fore repo.

Both the strategies above will require you to mock the autogenerated Apollo DTOs. This is probably the worst part of Apollo Android IMO, mocking these DTOs can be fiddly for even basic APIs like the one in the sample. Once you move to larger commercial GraphQL APIs, this mocking is extremely tedious.

If you are making the Apollo requests from inside some form of data-source class as part of a clean architecture app, depending on how you arrange your module boundaries, you can switch to mocking domain objects rather than the autogenerated DTOs (which will be much easier). There is an example of this structure in the clean architecture sample app. That sample uses Ktor and a rest API rather than Apollo and a GraphQL API, but it uses a CallProcessor class in the same manner to this sample. See this class which returns Domain objects rather than Data / DTO objects, for example.

Integration Testing

This strategy probably gives us the most bang for our buck. Because Apollo3 is using OkHttp3 under the hood, we can use a regular OkHttp3 interceptor to trick Apollo into thinking it is receiving data from the network (when in fact the data has come from static test files that are read locally). Once again there is an example of that kind of test in the Apollo3 sample that comes with the main fore repo.

Logging network calls

During development, being able to see what network traffic your app is sending and receiving is crucial in understanding what's going on IMO, especially for any members of the team who are dealing with GraphQL for the first time. You can turn it off for release builds.

There is an interesting gotcha here that you might come across if you're using multiple network related libraries likes Ktor, Coil, Apollo3 etc in the same app. OkHttp3 is almost ubiquitous, but there is a difference between OkHttp3 v3.x.x (preferred by Coil and Apollo3 for instance) and OkHttp3 v4.x.x (preferred by Ktor). Specifically the v3 functions: method(), body(), code() are replaced by the fields: method, body, code in v4. This can cause problems when logging network traffic if you don't know which version you are dealing with, or if a transitive dependency changes on you.

Anyway, if you already use an OkHttp interceptor class to log your network traffic with Retrofit or Ktor, the chances are it's going to work with Apollo3 too (but if it doesn't, it's probably related to that v3 / v4 gotcha).

For the sample app, we're using the InterceptorLogging class from fore which uses reflection to choose the correct logging method and works with both OkHttp3 v3 and v4:

val apolloClient = CustomApolloBuilder.create(
  globalRequestInterceptor,
  InterceptorLogging(logger)
)

This will give you logs that look like this:

Note the 5EFD7: this is a randomly generated string which is constant across a specific request and response cycle. It's a very basic way to deal with the problem of logging interleaved requests. If you see a request marked 5EFD7, and a response marked 6EDFG, then they are not related to each other (look further down in logcat to find the matching response which will also be marked 5EFD7).

Well that's all I have to share relating to Apollo3, I've used it a little (not in production yet) but it already seems to be working well. If you're interested, keep an eye on the official v3 docs to see when it hits stable.

Thanks for reading! and here's the sample android app on github.

GraphQL pre-primer for app developers

Eric Donovan — Tue, 19 Oct 2021 18:41:31 +0000

We can use GraphQL in various ways, but for this article we're going to focus on the most common situation faced by mobile client app developers: GraphQL over HTTP

HTTP

This means sending:

a method (like POST, PUT, GET etc)
headers
and a body

And receiving back:

an HTTP Code (like 200 or 404)
headers
and a body.

Here's an example HTTP POST request, we send this to the server:

POST /someapi/addtree HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 73
Host: trees.com

{
  "name": "tiffany the tree",
  "description": "brown with green bits"
}

the server replies with this response:

HTTP/1.1 201 OK
Content-Length: 47
Content-Type: application/json

{
  "message": "thanks for submitting a tree"
}

The body can contain HTML, JSON or any other text based content, or nothing (the response can just be the HTTP code). For a static website it'll be HTML, for an app it's usually JSON, and that's what we've used in the examples above

An HTTP GET however, has no body (the request data is embedded in the URL query string) it looks like this:

GET /someapi/tree?name=trevor HTTP/1.1
Accept: application/json
Host: trees.com

You might get a response like this back:

HTTP/1.1 200 OK
Content-Length: 47
Content-Type: application/json

{
  "id":"102",
  "name":"trevor",
  "description": "green with brown bits"
}

HTTP is almost ubiquitous, it's how most of the web works, including your favourite website. There are 3 common ways that apps built on top of HTTP communicate effectively with a server side, let's quickly cover each of them:

RESTful style

For our RESTful style tree service, things might look like this:

request (just showing the HTTP method line):

GET /someapi/trees HTTP/1.1

the response (just showing the body):

[
  {
    "id":"101",
    "name":"tiffany"
  },
  {
    "id":"102",
    "name":"trevor"
  },
  {
    "id":"103",
    "name":"tricia"
  }
]

and then for each tree id, request:

GET /someapi/trees/101 HTTP/1.1

the response:

{
  "id": 101,
  "name": "tiffany",
  "fullName": "tiffany the tree",
  "description": "brown with green bits",
  "imgUrl": "http://www.treeimages.com/oaktree.jpg"
{

RESTful style endpoints use the full range of HTTP methods and can be pretty popular with server side devs, and there are some benefits to using HTTP verbs with defined characteristics (for example PUT is defined as being idempotent).

IMO RESTful endpoints can be a little less popular with client app developers (you can see that if you wanted to display a list of tree images, it would require multiple requests to the server side)

GraphQL style

GraphQL requests can be sent inside the body of HTTP POSTs (but GETs are used too), and the GraphQL (Query Language) lets clients specify exactly which fields they want in the response:

request body:

{
  "operationName": "TreeList",
  "variables": {},
  "query": "query
    TreeList {
      trees {
        hasMore
        trees {
          id
          name
          imgUrl
        }
      }
    }"
}

response body:

{
  "data": {
    "trees": {
      "hasMore": false,
      "trees": [
        {
          "id": "101",
          "name":"tiffany",
          "imgUrl": "http://www.treeimages.com/oaktree.jpg"
        },
        {
          "id": "102",
          "name":"trevor",
          "imgUrl": "http://www.treeimages.com/ashtree.jpg"
        },
        {
          "id": "103",
          "name":"tricia",
          "imgUrl": "http://www.treeimages.com/birchtree.jpg"
        }
      ]
    }
  }
}

Getting all the data in one go is better for a client app, and the server only sent us the fields we asked for (id, name, imgUrl). But you'll see the request suddenly got a bit more complicated, and they can get a lot more complicated than that (handling that complication is what a library like Apollo is for)

RPC style

Hang on a second (you might be thinking) why can't the server devs just give me an API like this?

request:

GET /someapi/treesummarieslikeiwantthem HTTP/1.1

response:

{
  "id": "101",
  "name":"tiffany",
  "imgUrl": "http://www.treeimages.com/oaktree.jpg"
},
{
  "id": "102",
  "name":"trevor",
  "imgUrl": "http://www.treeimages.com/ashtree.jpg"
},
{
  "id": "103",
  "name":"tricia",
  "imgUrl": "http://www.treeimages.com/birchtree.jpg"
}

Well... they can! But they might have some good reasons not to. For a large organisation, server sides are often supporting multiple versions of multiple client technologies and giving each of them their own custom endpoint becomes very difficult to maintain.

GraphQL has its complications but it does allow client apps maximum flexibility in asking for exactly what they want, while letting server devs work on a generic solution to support multiple client requirements at the same time.

It's also a great way to create a BFF implementation (Backend For Frontend) which sits between the mobile client apps and various micro-services. That means the mobile apps don't have to re-implement the same micro-services integration work in each client. It can be done once on the server side, and the mobile apps can just talk to the GraphQL service.

Apollo

Because most of the time GraphQL is sent in HTTP POST or GET messages, you could actually talk to a GraphQL server using only an HTTP library like OkHttp.

But don't do that, Apollo helps by autogenerating your network DTOs for you - based on the GraphQL queries that you write using GraphQL (there's a good video on writing GraphQL queries here).

Let's get to the code already!

I hope that's filled in some knowledge gaps, or at least served as a refresher, if you're an android developer here is another post with a full sample app using Apollo3

Clean Architecture (minus Reactive Streams)

Eric Donovan — Thu, 12 Aug 2021 19:00:38 +0000

Before we get started

If you're a beginner android dev: don't drop this knowledge in an android interview 😬 IMO most interviewers today (August 2021) will expect to hear about clean architecture, stateless usecases, coroutines, flow, and maybe jetpack compose.

If you've been around long enough to remember android before reactive streams (perhaps not very fondly!): I ask you to keep an open mind, we have nearly 10 years more experience than we had back then, the classic mistakes are much easier to avoid this time around.

For everyone else: Reactive streams has been used in android architectures since a few years after android was first released (initially just as a way to replace AsyncTask - google's clunky way of creating a thread). It's completely understandable if you thought there was no other reasonable way to write an android app, but it turns out there is...

The current state of play

We're going to consider clean architecture specifically here, but this applies to any android architecture where you have a view layer reacting to state changes.

Many Android implementations of clean architecture use reactive streams (usually RxJava or Kotlin Flow) to connect architectural layers together.

Over the years, I've come to believe that reactive streams is completely the wrong abstraction for architecting android applications and implementing non-trivial reactive UIs. Please note, I'm not saying you shouldn't use reactive streams in android! - there are plenty of good reasons to use reactive streams in general.

Reactive Streams

Let's first back up a little. Reactive Streams could just as well have been called Observable Streams, and you can consider it a combination of two concepts:

Observers (tell me whenever you’ve changed)
Streams (data and operators like .map .filter etc)

For some specific use cases: handling streams of changing data, which you want to process on various threads (like the raw output of an IoT device for example) reactive streams is a natural fit. The needs of most android app architectures however tend to be a little more along the lines of:

connect to a network to download discreet pieces of data (always on an IO thread)
update a UI based on some change of state (always on the UI thread)

You certainly can treat everything as a reactive stream if you wish, and if parts of your app actually aren’t a great match for reactive streams, you can just have your functions return a Single<Whatever> anyway. Regular code that touches reactive streams often gets "reactive-streamified" like this (even code that isn’t, and has no need to be, reactive in the first place).

Anyway, it’s entirely possible to treat these two concepts separately. We can consider a piece of code’s observable nature separate to the data that actually changed (I explain how below). This means your function signatures don’t have to change, you can continue returning a Boolean if that’s what you need to do, and Observable<Somethings> won’t slowly spread throughout your code base.

Back to current architectures

The typical android clean architecture example you'll find on the internet is also only reactive in a fairly trivial way: UI triggers a request -> then receives a response, sometimes with updates (essentially a callback).

Once you include reacting to things which aren't triggered by the UI though (like in real apps), things get complicated. Let's say you want your UI to react to a change of network status, or an external accessory being plugged in, or a notification being received to the device (or all of these at the same time). Add Android's infamous lifecycle into the mix with its self-destroying views, and the abstraction starts to look a little shakey.

Here, caching and memory references start to be a big problem for android (whereas they might not be such a problem on the server side).

The typical solution to this is to turn everything into a reactive stream, and with enough RxJava operators you can of course fix all the caching and memory reference problems - but these are problems that only exist because of choosing an inappropriate abstraction in the first place. Remove Reactive Streams from your android architecture and you remove the problems

Enough talking, show me the money

Here's the UI from a sample clean architecture app (the code is on github). It displays various fake weather data fetched from the internet, downloaded on a real network connection.

I'd recommend you clone the repo and play with the app on a device, it's hard to get a feel of just how dynamic the screen is from a screen shot.

The view is divided into two halves so you can see how it works, the graphics on the left hand side are completely driven by the data on the right hand side. So for example, the MAX and MIN temperature indicators are positioned according to the maxTempC and minTempC states.

DashboardViewState(
    weather=WeatherViewState(
        maxTempC=16,
        minTempC=0,
        windSpeedKmpH=33,
        pollenLevel=MEDIUM
    ),
    autoRefresh=AutoRefreshViewState(
        timeElapsedPcent=0.0,
        autoRefreshing=false
    ),
    errorResolution=null,
    isUpdating=false
)

Any time the state changes, the UI updates itself automatically. If the user gets back from making a phone call, or rotates their screen, the UI just refreshes whatever state is provided. Any animations are fired on state changes (for instance when the temperature values change)

Because all the heavy lifting is being done elsewhere, the view code is thin: about 100 lines (50 if we remove the animations). This makes it easy to maintain or change.

The ViewModel which creates this immutable view state is observing two main things: a WeatherModel and a RefreshModel (if that sounds unfamiliar to you, you can think of these models as ViewModels that have application level scope, or see what wikipedia has to say about domain models).

Even though this app is still quite simple, it does more than the typical "trigger a request -> receive a response" sample code. Some of the changes it's observing don't directly originate from the the UI. Despite this complication, what's missing from the view model here is most of the boiler plate associated with reactive streams. Rotating the screen also doesn't cause any additional network requests to be fired, it doesn't require a dedicated caching strategy either because the state of the models in the domain layer hasn't changed (this tracks reality much closer - why would the weather state need to be re-queried as a result of a screen rotation anyway?).

What's a bit surprising for people who come across this technique for the first time, is that the benefits become even more apparent as more things are observed (let's say we also wanted to observe a NetworkAvailabilityModel and a NotificationModel, it would be an extra line for each in the ViewModel, and still no memory leaks).

So how does it work then?

Basically, the observer pattern.

In this sample, the observable pattern is implemented with a library (fore) but it's important to realise that the actual code is fairly simple, it boils down to a list of observers (usually the observers are in the UI layer somewhere, added and removed in line with the view lifecycle) that implement this interface:

interface Observer {
    fun somethingChanged()
}

The only requirement back in the domain layer, is that all observable models need to call notifyObservers() whenever their state has changed.

These notifications get fired either on the UI thread (which is what you want when updating your UI) or the current thread (which is what you want during a unit test).

We hinted at it earlier, but the key innovation here is that we have separated a piece of code’s observable nature from the data that actually changed.

This means we no longer have multiple observable APIs to deal with such as an Observable<WeatherState>, an Observable<RefreshState> and an Observable<NetworkState> (or Flow<WeatherState>, Flow<RefreshState> Flow<NetworkState>, etc.) Everything is observable in exactly the same way: something changed, or it didn't.

That turns out to be unbelievably helpful when removing boiler plate and driving complex reactive UIs (there are some robustness wins too). That level of simplicity won't be any good for processing streams of IoT data - that we can do using Flow, but for tying together android architectural layers in a large complex reactive app it's pretty unbeatable.

The full app is on github

Kotlin library to store data classes persistently

Eric Donovan — Sat, 15 May 2021 19:08:06 +0000

I made a tiny library, it lets you store single instances of kotlin data classes persistently with not much effort / boilerplate https://github.com/erdo/persista

I'm using it to recover state after process death (my app's state is held in immutable data classes). There is a sample app bundled with the repo so you can play around with it.

Issues / PRs are open :D

Tutorial: Kotlin Coroutines, Retrofit and fore

Eric Donovan — Sun, 12 Jan 2020 20:15:55 +0000

This is part of a series on android fore

Tutorials in Series
1) Tutorial: Spot the deliberate bug
2) Tutorial: Android fore basics
3) Tutorial: Android architecture, full todo app (MVO edition)
4) Tutorial: Android state v. event
5) Tutorial: Kotlin Coroutines, Retrofit and fore

Thread based networking

If you've been using fore to wrap your Retrofit networking calls, you'll be familiar with the Java / Thread based CallProcessor:

callProcessor.processCall(
  service.getThingsFromTheInternet(),
  workMode,
  things -> handleSuccess(things),
  failureMessage -> handleFailure(failureMessage)
);

You would call this from a model (or repository, or usecase etc) and what it does is to insulate the code that we are in, from any specific considerations to do with HTTP and network connections.

At this level

we don't want to care about HTTP 200s : we care about the things we get back
we don't care about 403s : we care about the VIDEO_ACCOUNT_SUSPENDED failureMessage (for instance)
we don't care about IOExceptions : we care about the NO_CONNECTION failureMessage.

(failureMessage is your own enum or other class that needs to implement a certain interface, and you decide exactly what the values are and what they represent, you just don't do it here, but as part of the api layer).

We can also easily test this code by mocking callProcessor to return whatever things, or whatever failureMessage we want.

(If you're not familiar with this, you can take a look at the retrofit sample app with tests that's in the fore repo.)

It all works quite nicely, but you can see the potential for nested callbacks if you want to chain more than one network request together. So we'll take a look at fore's Coroutine version of this class next.

Coroutine based networking

The Kotlin / Coroutine based CallProcessor has a slimmer API:

val deferredResult = callProcessor.processCallAsync {
    service.getThingsFromTheInternet()
}

when (val result = deferredResult.await()) {
    is Left -> handleFailure(result.a)
    is Right -> handleSuccess(result.b)
}

The main difference is that the callbacks have gone. Instead we return a Deferred<Either<F, S>> from the processCallAsync() functions, or a straight Either<F, S> from the processCallAwait() functions. (The Retrofit service is also now defined as suspended).

Obviously this version isn't driven by threads, the network calls are run with Dispatcher.IO and the results will be returned to you on Dispatchers.Main, so like the Java CallProcessor you won't need to do anything special to get back to the UI thread.

Quick refresher on "callback hell"

Let's back up a little and remind ourselves of one of the reasons why Coroutines are cool: they help us to write asynchronous code as if it was synchronous (similar ideas exist in lots of languages of course).

The idea is to avoid what's commonly known as "callback hell" which can sometimes happen if you need to write a lot of nested callbacks and you're not careful about it. So with Coroutines we can go from writing code like this:

callService1("input") { response1 ->
    callService2(response1) { response2 ->
        callService3(response2) { response3 ->
            doSomethingElse(response3)
        }
    }
}

(I realise this nested code doesn't look too bad! - but imagine those nested callbacks spread out over a few pages, with lots of code in between, then it can start to become a problem.)

to writing code like this

val deferredResult1 = CoroutineScope(Dispatchers.IO).async {
    callServiceA("input")
}

val deferredResult2 = CoroutineScope(Dispatchers.IO).async {
    callServiceA(deferredResult1.await())
}

val deferredResult3 = CoroutineScope(Dispatchers.IO).async {
    callServiceA(deferredResult2.await())
}

CoroutineScope(Dispatchers.Main).launch {
    doSomethingElse(deferredResult3.await())
}

The CallProcessor and carryOn

But here's a little snag: because network connections sometimes fail, you'll notice there is still a place where we branch for success or failure (and therefore the potential for nesting when we chain more than one network request together - even though we're using coroutines).

when (val result = deferredResult.await()) {
    is Left -> handleFailure(result.a)
    is Right -> handleSuccess(result.b)
}

Does that mean we're back to where we started and could end up in call-back hell again? Well no actually, especially when we look at what we can do with Kotlin.

A good example is the carryOn extension function that we have in the fore-network-kt package.

TLDR;

The CallProcessor API takes a functional type, we can write whatever we want inside that function as long as it ends up returning the type that the function is expecting. And carryOn will let you write code like this:

val deferredResult = callProcessor.processCallAsync {
    service.doSomething0().carryOn {
      service.doSomething1(it)
    }.carryOn {
      service.doSomething2(it)
    }.carryOn {
      service.doSomething3(it)
    }

}

And even though it doesn't look like it at first glance, carryOn completely covers you for any error cases you might encounter from any of the network calls.

The full explanation

Let's suppose our service looks like this:

interface MyService {
    suspend fun doSomething0(): Response<Int>
    suspend fun doSomething1(number: Int): Response<String>
    suspend fun doSomething2(text: String): Response<Double>
    suspend fun doSomething3(dNumber: Double): Response<Float>
}

If we needed to chain those calls together it might look like this:

suspend fun attempt1(svc: MyService) {

  var response: Any? = func {

    val error: Any?
    val resp0 = svc.doSomething0() //returns Response<Int>

    if (resp0.isSuccessful) {
      val resp1 = svc.doSomething1(resp0.body()!!) //Response<String>
      if (resp1.isSuccessful) {
        val resp2 = svc.doSomething2(resp1.body()!!) //Response<Double>
        if (resp2.isSuccessful) {
          return@func svc.doSomething3(resp2.body()!!) //Response<Float>
        } else {
          error = resp2
        }
      } else {
        error = resp1
      }
    } else {
      error = resp0
    }

    error
  }
}

The first call to doSomething0() is going to return an Int wrapped in a Retrofit Response object: Response<Int> (which we assign to resp0).

If that call fails, then we return the error and stop, if the call is successful, then we use response Int to call doSomething1(). This time we get a Response<String> back and the pattern continues until we finally return the Response<Float> object we get from doSomething3 (which may or may not have succeeded).

Apart from the nesting, we loose type information here, func expects to return a Response<Float> (whether it succeeded or failed), but further up the chain we may only have a Response<Int> (for example, if doSomething0() failed).

suspend fun attempt2(svc: MyService) {

  var response: Response<Float> = func<Float> {

    val resp0 = svc.doSomething0() //returns Response<Int>

    val resp1 = resp0.body()?.let {
      svc.doSomething1(it) //Response<String>
    } ?: run {
      return@func Response.error(resp0.errorBody()!!, resp0.raw())
    }

    val resp2 = resp1.body()?.let {
      svc.doSomething2(it) //Response<Double>
    } ?: run {
      return@func Response.error(resp1.errorBody()!!, resp1.raw())
    }

    val resp3 = resp2.body()?.let {
      svc.doSomething3(it) //Response<Float>
    } ?: run {
      return@func Response.error(resp2.errorBody()!!, resp2.raw())
    }

    resp3
  }
}

This is a little better, we've used Kotlin to lose the nesting and we also keep the Type information - remember that the generic of the Retrofit Response objects only matters for the success case where you return a String or an Int etc, the errors are all the same and aren't concerned about the generic. This lets us create a synthetic Response<Float> error, using the data we got from our failed Response<[whatever]> objects.

But with a little extension function, we can take care of making this synthetic Response error. Hence the carryOn function:

suspend fun attempt3(svc: MyService) {

  var response: Response<Float> = func<Float> {

    val resp0 = svc.doSomething0()

    val resp1 = resp0.carryOn {
      svc.doSomething1(it)
    }

    val resp2 = resp1.carryOn {
      svc.doSomething2(it)
    }

    val resp3 = resp2.carryOn {
      svc.doSomething3(it)
    }

    resp3
  }
}

And to tidy it up a little further:

suspend fun attempt4(svc: MyService) {

  var response: Response<Float> = func<Float> {

    svc.doSomething0().carryOn {
      svc.doSomething1(it)
    }.carryOn {
      svc.doSomething2(it)
    }.carryOn {
      svc.doSomething3(it)
    }
  }
}

Here is a more complicated example, as part of fore's CallProcessor

callProcessor.processCallAsync {

    var ticketRef = ""
    ticketSvc.createUser() //Response<UserPojo>
    .carryOn {
      ticketSvc.createTicket(it.userId) //Response<TicketPojo>
    }
    .carryOn {
      ticketRef = it.ticketRef
      ticketSvc.getEstWaitingTime(it.ticketRef) //Response<TimePojo>
    }
    .carryOn {
      if (it.minutesWait > 10) {
        ticketSvc.cancelTicket(ticketRef) //Response<ResultPojo>
      } else {
        ticketSvc.confirmTicket(ticketRef) //Response<ResultPojo>
      }
   }
}

So the carryOn extension function you'll find in fore is just one example of how to use Kotlin and Coroutines to prevent getting nested callbacks - the same techniques can be used in your own code to banish callback hell.

Just to be clear here, carryOn is not a magic bullet - there are restrictions when you use it: you're still required to return a single object type wrapped in a Response object at the end of the function (in this case Response). But it handles moderate chain complexity pretty well, and together with the CallProcessor it does cover you completely for any error cases (which is surprisingly not the case for a lot of commercial networking code I've encountered over the years).

If your chains are more complicated than this, it could be time to roll up your developer sleeves and write some software to coordinate the process explicitly.

Update: fore now also supports Ktor and Apollo using the same CallProcessor and carryOn techniques discussed here, see the fore repo sample apps for each of those libraries.

As always, there is a full example app in the fore repo which includes a comprehensive set of unit tests and instrumentation tests.

Thanks for reading!

Tutorial: Spot the deliberate bug

Eric Donovan — Sat, 02 Mar 2019 15:12:35 +0000

This is part of a series on android fore

Tutorials in Series
1) Tutorial: Spot the deliberate bug
2) Tutorial: Android fore basics
3) Tutorial: Android architecture, full todo app (MVO edition)
4) Tutorial: Android state v. event
5) Tutorial: Kotlin Coroutines, Retrofit and fore

Don't worry if you're not an Android developer for this one, anyone can spot this bug (but surprisingly few do until it's too late - even with this warning!).

We are about to illustrate how complicated UI code can become (even for simple views), and then what to do about it.

Here's an ugly looking UI for a queue busting app that lets roaming staff sell $1 bottles of water at a festival.

ugly water seller app

As usual with MVO, we started by writing a model first (see the second tutorial if you want to know how). We won't discuss the model here any further, other than to say: we called it Basket; it is Observable; it's quick and easy to unit test; the full kotlin source is in the github repo linked to below; and it has these public functions:

fun addBottle()
fun removeBottle()
fun setIsDiscounted(isDiscounted: Boolean)

fun getTotalItems(): Int
fun getTotalPrice(): Int
fun getIsDiscounted(): Boolean
fun getTotalSaving(): Int

The View Code

The rule of thumb for applying syncView() in MVO is: "If a model being observed changes in any way, then the entire view is refreshed.".

Let's first see what happens when we don't do that (i.e. how a lot of view layer code is written - especially in event driven architectures like MVP for example):

Step 1 of 3

Let's start super simple:

ugly water seller app, first version

All we need to do is hook up the add and remove buttons in the UI and make sure we remember to update the total price. Something like this would be typical:

addButton.setOnClickListener {
    basket.addBottle()
    updateTotalPriceView()
}

removeButton.setOnClickListener {
    basket.removeBottle()
    updateTotalPriceView()
}

Don't worry about how we get the references for addButton and removeButton - this works fine as pseudo code (you can check the github source below if you're interested).

For the updateTotalPriceView() call we will end up setting the text in the UI to what the model tells us. In a real app, depending on the architecture in place, the code will often go through various components first, but if we follow it through to the end, we will eventually reach a piece of code that does something like this:

totalPriceView.text = basket.getTotalPrice()

Step 2 of 3

The designers have some inspiration and decide they want to add a basket icon:

ugly water seller app, second version

This change is pretty easy as our model already supports it, so we just add an updateTotalNumberOfItemsView() method, which does exactly what you think it does. We'll also change the button click listeners so that they call both updateTotalPriceView() and updateTotalNumberOfItemsView()

addButton.setOnClickListener {
    basket.addBottle()
    updateTotalPriceView()
    updateTotalNumberOfItemsView()
}

removeButton.setOnClickListener {
    basket.removeBottle()
    updateTotalPriceView()
    updateTotalNumberOfItemsView()
}

Step 3 of 3

The business asks us to support a 10% discount for students. No problem, because we read ahead (...ahem), our model already has that capability.

ugly water seller app, final version

So for the discount checkbox, we call basket.setIsDiscounted(isChecked) and then refresh the UI: updateTotalSavingsView() which shows the discount amount that has been applied, and also updateTotalPriceView() as that will have changed.

We don't call updateTotalNumberOfItemsView() (because of course, discounts have no effect there).

apply10PercOff.setOnCheckedChangeListener { isChecked ->
    basket.setIsDiscounted(isChecked)
    updateTotalPriceView()
    updateTotalSavingsView()
}

We end up with something like this to implement the view layer (this doesn't compile as we're only showing the important bits here - see the github repo for the full code):

lateinit var addItemButton: Button
lateinit var removeItemButton: Button
lateinit var apply10PercOff: CheckBox

lateinit var totalItemsView: TextView
lateinit var totalPriceView: TextView
lateinit var totalSavingView: TextView

private fun setupButtonListeners() {

  addButton.setOnClickListener {
      basket.addBottle()
      updateTotalPriceView()
      updateTotalNumberOfItemsView()
  }

  removeButton.setOnClickListener {
      basket.removeBottle()
      updateTotalPriceView()
      updateTotalNumberOfItemsView()
  }

  apply10PercOff.setOnCheckedChangeListener { isChecked ->
      basket.setIsDiscounted(isChecked)
      updateTotalPriceView()
      updateTotalSavingsView()
  }
}

private fun updateTotalNumberOfItemsView() {
    totalItemsView.text = basket.getTotalItems()
}

private fun updateTotalPriceView() {
    totalPriceView.text = basket.getTotalPrice()
}

private fun updateTotalSavingsView() {
    totalSavingView.text = basket.getTotalSaving()
}

private fun updatePostRotation(){
    updateTotalNumberOfItemsView()
    updateTotalPriceView()
    updateTotalSavingsView()
}

The updatePostRotation() method is there to handle android rotations. We probably also want some code to disable the remove button when the basket is empty etc, but this will do for our purposes - it's already complicated enough.

The Bug

The reason I say it's complicated enough, is that we already managed to introduce the bug. Did you spot it? How about if we just concentrate on the click listeners? (it's not a syntax bug, the bug is still present below if we treat the click listeners as psuedo code)

  addButton.setOnClickListener {
      basket.addBottle()
      updateTotalPriceView()
      updateTotalNumberOfItemsView()
  }

  removeButton.setOnClickListener {
      basket.removeBottle()
      updateTotalPriceView()
      updateTotalNumberOfItemsView()
  }

  apply10PercOff.setOnCheckedChangeListener { isChecked ->
      basket.setIsDiscounted(isChecked)
      updateTotalPriceView()
      updateTotalSavingsView()
  }

In case you haven’t worked out the bug yet, follow the code in the click listeners when these actions are performed in sequence (focus on the amount in the savings field):

start with an empty basket
select the discount checkbox first
then add an item

recreating the bug

We forgot to call updateTotalSavingsView() from the add and remove click listeners, so the savings value will be incorrect in the view unless the discount checkbox is toggled again.

UI consistency bugs like this happen all the time, even in simple views.

Unfortunately the view layer is slow and annoying to test (at least on Android), and even with automated tests, these types of bugs are very hard to spot. In this case, an automated test or human tester would have had to have performed specific actions in the correct sequence just to see it.

And this is why syncView() does what it does. "If a model being observed changes in any way, then the entire view is refreshed.".

Applying that principle, our code can be re-written like this:


lateinit var addItemButton: Button
lateinit var removeItemButton: Button
lateinit var apply10PercOff: CheckBox

lateinit var totalItemsView: TextView
lateinit var totalPriceView: TextView
lateinit var totalSavingView: TextView

private fun setupButtonListeners() {

  addButton.setOnClickListener {
      basket.addBottle()
  }

  removeButton.setOnClickListener {
      basket.removeBottle()
  }

  apply10PercOff.setOnCheckedChangeListener { isChecked ->
      basket.setIsDiscounted(isChecked)
  }
}

fun syncView() {
    totalItemsView.text = basket.getTotalItems()
    totalPriceView.text = basket.getTotalPrice()
    totalSavingView.text = basket.getTotalSaving()
}

This skips some details, if you want to know how it's all hooked up that's discussed here. For our purposes it's good enough to know that whenever our basket model changes, syncView() gets called.

What's surprising about this, is that it's not only more robust, it’s also less code. (And any android view can be written like this, including those using adapters).

Here are some tips for writing great syncView() functions.

full app, rotation support as standard

This very simple app has no animation code, but it is: clear; robust; has no memory leaks; it's testable; and it supports rotation - which is a great place to be with android before you start adding beautiful animations and finishing touches.

Thanks for reading! I hope you got something out of that, even if you're not an Android developer. If you're thinking of using fore in your team for an android project, the fore docs have most of the basics covered in easy to digest sample apps, e.g. adapters, networking or databases.

here’s the complete code for the tutorial

Tutorial: android architecture blueprints, full todo app (MVO edition)

Eric Donovan — Tue, 19 Feb 2019 22:19:02 +0000

This is part of a series on android fore

Tutorials in Series
1) Tutorial: Spot the deliberate bug
2) Tutorial: Android fore basics
3) Tutorial: Android architecture, full todo app (MVO edition)
4) Tutorial: Android state v. event
5) Tutorial: Kotlin Coroutines, Retrofit and fore

The Android Architecture Blueprints* showcase different android architectures by implementing the same to-do type app, multiple times (once for each architecture variant).

*Note that the Android Architecture Blueprints repo has now abandoned the original v1 of the todo app - the MVO implementation here remains the Java implementation with the fewest lines of code by quite a wide margin.

I'm leaving this article up as it provides quite a good guide to how and why we can move away from MVP architectures and towards something more state driven like MVVM, this post takes it a step further and implements a full MVO style project (which is why the code count dropped so dramatically). If after reading this you want something in kotlin, the clean architecture post is a good place to head next - or just see any of the very simple fore sample apps that exist, like the one that comes with the persista library

In this post we throw another architecture into the mix: MVO implemented with fore.

screen shots of the MVO todo app

Our fork is written in Java, it's based on the reference MVP implementation.

it uses less code that any other Java implementation (1971 lines, 3261 lines inc. tests)
a Kotlin-MVO version would use even less
a lot of the remaining code has been moved out of the view layer
the structure of the app is arguably a lot clearer.

It's not a perfect comparison though: our MVO version handles mocking the server in a different way, and we have added a basic Dagger 2 implementation for DI (though we've left a pure DI implementation class there so you can compare the two). Our MVO version actually has more functionality than the original, we support animated list changes using DiffUtil, and there is a robust networking implementation to fetch tasks from a back end (some json hosted at mocky.io) - despite this it still clocks in with less code.

Let's see how we did that...

(Note: there are a lot of references to Task in the following code, in this situation a task means a real world physical task, like a chore, or a todo item. It's got nothing to do with Android Task or AsyncTask.)

Original MVP package structure

original package structure

The package structure of the MVP version mixes concepts slightly: data and util are self-explanatory, but addedittask, statistics, taskdetail, tasks all refer to sections of the app's UI, (they map to the add/edit screen, the statistics screen, and so on).

view layer package contents

Indeed, inside those UI packages we see android UI stuff like Activities, Fragments, plus the usual MVP classes: the Contract and Presenter.

The overall structure makes it look as if the entire app is its UI (plus the data and a few utility methods). In terms of separating the view layer from the rest of the app, we can do a lot better than this.

(Presenters are written for the specific views they drive, but in most apps even this small one the views are different windows onto the same data, and a lot of what happens in presenter classes is repeated in multiple presenters. One of the things that MVO does is to move this code closer toward the application and away from specific views that might want to use it. This means it can be written and tested once, dramatically improving DRY, and still supporting multiple, thinner views, which are easier to change.)

MVO package structure

new package structure

For the MVO implementation, we've split the data package into api and db (it's useful to keep these two separate, for instance it lets us handle minor api changes without affecting our db model too much).

We'll leave the util package as it is - it's not central to our discussion.

message contains our globally applicable application messages like ERROR_BUSY or ERROR_SESSION_TIMED_OUT - we don't really want anything outside of our api package to know about things like HTTP error codes or networking exceptions. The code in the api package handles the mapping between HTTP and these messages for us without letting any of the networking details leak into the rest of the app.

Everything above is a good idea in my opinion, but not specific to MVO, the next two packages are what really defines an MVO structure though: ui and feature...

ui package

view layer packages

The ui package is where you will find the addedit, statistics, taskdetail, and tasks sub-packages which map to the screens of the app. Everything here is closely related to the UI and therefore the Android framework, code here is difficult and slow to test, so we want to make it as thin and as simple as we can. So here you'll find the Activity and Fragment classes, plus occasionally Adapters, or any other class directly related to that specific view. There are no Presenter or Contract classes required here though.

feature package

Now for the feature package. If you imagine the app as existing in its own right, without reference to any specific UI, then the feature package is where the bulk of it would reside. This is what you would call the domain layer if you wanted to name things in line with clean architecture.

For this small app there is only one "feature" - todo/task management, so there is only one sub-package here: tasks. Most commercial apps are going to have a lot more features here, typical examples would be things like: account, shoppingbasket, favourites, chat, loyalty, inbox, playlists etc.

This is where the models in MVO live. It's the business logic of the app, and the code here should be easy to unit test: these classes should know as little as possible about Android, contexts and certainly not know anything about fragment lifecycles etc. You can refer to the fore docs for complete guidelines about how to write these models - it's standard advice that also applies to writing ViewModels.

Tasks feature

tasks feature, MVO implementation

This is a substantial re-write of the code that exists in the MVP implementation.

TaskItem

This is the app's definition of a task.

It looks similar, but not the same as the task class in the api package that we deliberately called TaskItemPojo so that we don't get confused.
It looks similar, but not the same as the task class found in the db package that we deliberately called TaskItemEntity, again so that we don't get confused.

(This might seem like a lot of effort, and you could write a single task class that satisfies all the requirements of your api, your database model, and your feature if you want - things can get complicated when you have changing requirements and apis though, so just be aware of the tradeoffs here)

Here's the rest of the feature:

tasks feature

TaskFetcher

All this does is: connect to the network, fetch tasks from a back end, and add them to local storage.

A lot of the work associated with connecting to a network: parsing responses; handling errors; threading; etc is handled by fore's CallProcessor which is a thin wrapper over Retrofit and OkHttp (there is also one for Apollo and one for Ktor). We pass the downloaded tasks straight to the TaskListModel which handles the database work. So all we're left with in this class is a little business logic.

It's observable, so it will let any observers know when its state has changed (e.g. when isBusy() switches back to false).

The full code is here.

TaskListModel

This class wraps the database and takes care of all the threading so that the view layer doesn't need to worry about it. Any access to the database goes through here so that the db is transparent to the rest of the app.

This class is designed to support an Android adapter so it includes public methods like size() and get().

This class is also observable, so any observers will be informed of any changes to the task list. As we are wrapping a Room db, we simply hook into Room's own InvalidationTracker for this, which is directly analogous to fore's Observers.

Animated list updates: because we plan to animate changes to the list of tasks, we implement the Diffable interface here (that's a small helper from fore that let's us automate most of the complication of using DiffUtil).

The full code is here.

CurrentTaskModel

This class drives any views that are related to a specific task (currently taskdetail and addedit).

For this it has public methods like setTitle(), getDescription(), saveChanges() etc

As with the other models, it is written with the assumption that all the methods will be called on the same thread. Any threading is managed internally away from the view layer.

And again it's observable, so that any observers know when to sync their view.

Fixing the view layer

Now we're on to the easy bit! Take a look at some of the set / show methods that exist in the old view layer code:

@Override
public void setLoadingIndicator(final boolean active) {
  if (getView() == null) {
    return;
  }
  final SwipeRefreshLayout srl =
    (SwipeRefreshLayout) getView().findViewById(R.id.refresh_layout);

  // Make sure setRefreshing() is called after the layout is done with everything else.
  srl.post(new Runnable() {
    @Override
    public void run() {
      srl.setRefreshing(active);
    }
  });
}

@Override
public void showTasks(List<Task> tasks) {
  mListAdapter.replaceData(tasks);
  mTasksView.setVisibility(View.VISIBLE);
  mNoTasksView.setVisibility(View.GONE);
}

@Override
public void showNoActiveTasks() {
  showNoTasksViews(
    getResources().getString(R.string.no_tasks_active),
    R.drawable.ic_check_circle_24dp,
    false
  );
}

Even for simple UIs, code like this can get very complicated and can cause subtle, hard to spot bugs in the UI. Here is the full list of methods needed to support just the main tasks UI (note these are just the method signatures, we're not even showing the full methods which run to over a hundred lines of code in the original implementation):

@Override
public void setLoadingIndicator(final boolean active) {...}

@Override
public void showTasks(List<Task> tasks) {...}

@Override
public void showNoActiveTasks() {...}

@Override
public void showNoTasks() {...}

@Override
public void showNoCompletedTasks() {...}

@Override
public void showSuccessfullySavedMessage() {...}

private void showNoTasksViews(String mainText, int iconRes, boolean showAddView) {...}

@Override
public void showActiveFilterLabel() {...}

@Override
public void showCompletedFilterLabel() {...}

@Override
public void showAllFilterLabel() {...}

@Override
public void showAddTask() {...}

@Override
public void showTaskDetailsUi(String taskId) {...}

@Override
public void showTaskMarkedComplete() {...}

@Override
public void showTaskMarkedActive() {...}

@Override
public void showCompletedTasksCleared() {...}

@Override
public void showLoadingTasksError() {...}

The MVO syncView() convention is about to let us delete all of these methods. It's a little shocking if you're not used to the syncView() convention, but in fact everything above can be replaced with:

@Override
public void syncView() {
  tasksView.setVisibility(taskListModel.hasVisibleTasks() ? View.VISIBLE :View.GONE);

  noTasksView.setVisibility(taskListModel.hasVisibleTasks() ? View.GONE :View.VISIBLE);
  noTaskMsg.setText(taskListModel.getCurrentFilter().noTasksStringResId);
  noTaskIcon.setImageDrawable(getResources().getDrawable(taskListModel.getCurrentFilter().noTasksDrawableResId));
  noTaskAddView.setVisibility(taskListModel.hasVisibleTasks() ? View.GONE : View.VISIBLE);
  filteringLabelView.setText(getResources().getString(taskListModel.getCurrentFilter().labelStringResId));
  swipeRefreshLayout.setRefreshing(taskFetcher.isBusy());

  listAdapter.notifyDataSetChangedAuto();
}

By the time we have done all the views, we have removed a lot of unnecessary code.

The power of the syncView() convention is discussed at length here. If you're familiar with MVI, it has similar purpose to the render() function.

Animated list changes

Did you spot the notifyDataSetChangedAuto()? (rather than the more usual notifyDataSetChanged()) - this is fore's way of supporting animated list changes, in this case it's backed by Android's DiffUtil but there is another more performant version that you can use for a simple in memory list demonstrated here. Either way it's a simple call to notifyDataSetChangedAuto() from within your syncView().

At this point you might be thinking that fore must be some huge complicated library to support all this, actually it's tiny (like 500 lines of code tiny). A lot of the power comes from the MVO concept itself.

Rotation support

rotation support as standard

It wouldn't be MVO if rotation support and testability didn't come as standard.

Testing

Some of the original tests work with no changes necessary, some have been tweaked, and others have had to be re-written. The testing for the MVO app is slightly more focussed on the feature package and uses plain JUnit tests. But there are still plenty of Android UI tests though (for these we use a Dagger2 TestAppModule to mock the models driving the view layer - but a PureDI solution would work just as well)

Things we haven't really improved...

Our view layer now looks much thinner, but we still need quite a bit of boiler plate in the activity classes to support things like the ActionBar, NavigationView, PopUpMenu and handling the options menu. That's just how Android has been designed unfortunately - there is a limit to how much we can avoid these native classes and the boiler plate that comes with them.

Single Activity apps and Google's Navigation Component may be offering a way out of this, or maybe not. (If you're new to Android development, you'll quickly learn to take Google's recommendations with a pinch of salt. They are just trying to work things out, the same as the rest of us - sometimes it's helpful, sometimes less so.)

The nice thing about MVO is that it removes so much code from the view layer, it's not so difficult to completely re-write that view layer (using a new navigation structure for instance) and barely have to touch the rest of the app code.

Thanks for reading! If you're thinking of using fore in your team, the fore docs have most of the basics covered in easy to digest sample apps, e.g. adapters, networking or databases.

here’s the complete code for our MVO fork.

Tutorial: android state v. event

Eric Donovan — Tue, 29 Jan 2019 21:05:03 +0000

This is part of a series on android fore

Tutorials in Series
1) Tutorial: Spot the deliberate bug
2) Tutorial: Android fore basics
3) Tutorial: Android architecture, full todo app (MVO edition)
4) Tutorial: Android state v. event
5) Tutorial: Kotlin Coroutines, Retrofit and fore

GUIs can be driven by two different types of data: state or events. It's a universal but under-appreciated concept. Let's grok the difference (it'll come in handy whether we're using MVI, MVVM, MVO or something else)...

We’ll make a tiny game using the fore library and the MVO architectural pattern. We'll also touch on the SyncTrigger class which is fore's way of bridging the two worlds of state and events.

game of life

Game rules:

Players start with an identical number of coins
Each turn, a player gives one of their coins to another player, chosen at random

That's it. Of course if they have no coins to give, they skip their turn. We highlight the number of the player who is about to play (not the player who has just played).

Model

We'll tackle the M in MVO first like we did in the basics tutorial (if you haven't read that tutorial, you should probably check it out first).

See the repo below for the full source of our GameModel, but these are our public functions:

class GameModel() : Observable by ObservableImp(workMode) {

  fun next() {
    ...
  }

  fun clear() {
    ...
  }

  fun getPlayerAmount(playerNumber: Int): CashAmount {
    ...
  }

  fun isPlayersTurn(playerNumber: Int): Boolean {
    ...
  }

  fun getRound(): Int {
    ...
  }

}

The model knows nothing about android view layer classes or contexts
We are calling notifyObservers() whenever any of our model’s state changes
All the public functions can be called at any time on the UI thread, and we guarantee that their results will be consistent

A checklist for writing models when you’re using fore (or indeed something like MVVM) is maintained here.

View

Previously in these tutorials we've written custom view classes for our view layer, this time we’ll use an activity for our view layer (just because), we’re going to call it GameOfLifeActivity.

As usual, our view layer class (which is now an activity) is going to handle the following things:

get a reference to all the view elements we need
get a reference to the GameModel so we can draw our UI based on it
hook up the button listeners so that they interact with the model
sync our view so that it matches the state of the GameModel at all times (show the right number of coins for each user etc)

class GameOfLifeActivity : AppCompatActivity {

    //models that we need
    private lateinit var gm: GameModel
    private lateinit var logger: Logger

    ...

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        //(get view references handled for us by kotlin tools)

        getModelReferences()

        setClickListeners()
    }

    private fun getModelReferences() {
        gm = App.inst.appComponent.gameModel
        logger = App.inst.appComponent.logger
    }

    private fun setClickListeners() {
        life_next_btn.setOnClickListener { gm.next() }
        life_reset_btn.setOnClickListener { gm.clear() }
    }

    ...

}

Observer

We want a reactive view, which syncs itself automatically whenever the game model changes, without us having to worry about it. So as we've done before, we add and remove our observer in line with android lifecycle methods.


class GameOfLifeActivity : AppCompatActivity() {

  ...

  override fun onStart() {
    super.onStart()
    gm.addObserver(observer)
    syncView() //  <- don't forget this
  }

  override fun onStop() {
    super.onStop()
    gm.removeObserver(observer)
  }

  override fun syncView() {    
    life_player1cash_img.setImageResource(gm.getPlayerAmount(0).resId)
    life_player2cash_img.setImageResource(gm.getPlayerAmount(1).resId)
    life_player3cash_img.setImageResource(gm.getPlayerAmount(2).resId)
    life_player4cash_img.setImageResource(gm.getPlayerAmount(3).resId)

    life_player1icon_img.setImageResource(if (gm.isPlayersTurn(0)) 
          R.drawable.player_01_highlight
       else
          R.drawable.player_01)
    life_player2icon_img.setImageResource(if (gm.isPlayersTurn(1)) 
          R.drawable.player_02_highlight
       else
          R.drawable.player_02)
    life_player3icon_img.setImageResource(if (gm.isPlayersTurn(2)) 
          R.drawable.player_03_highlight
       else
          R.drawable.player_03)
    life_player4icon_img.setImageResource(if (gm.isPlayersTurn(3)) 
          R.drawable.player_04_highlight
       else
          R.drawable.player_04)

    life_round_txt.text =
       resources.getString(R.string.round, gm.getRound())

  }

}

Dependency Injection

Last time we rolled our own pure DI solution. This time we are using a bare-bones Dagger 2.0 implementation, just because.

gameModel = App.inst.appComponent.gameModel

As before, this provides the view with the same instance of the model each time, so that everything remains consistent, even when we rotate the screen.

rotation support as standard

As always with MVO and fore: rotation support and testability come as standard.

Introducing an Event

At the moment our UI is driven by state, held in the GameModel. It's because of the "statey-ness" of MVO that we can so easily support rotation on android - all we need to do to keep our UI totally consistent is to re-sync with the model by calling syncView() whenever we want.

But let's add a new design requirement:

When the game transitions to an economy where at least one player has no coins, we want to display a Snackbar indicating that this transition (or event) took place, and the same in reverse.

We can easily add this piece of state to our game model and provide access to it like this: fun hasBankruptPlayers(): Boolean

But the Snackbar UI component is much more suited to event type data, and using syncView() to trigger a Snackbar would cause us problems. A robust implementation of syncView() needs to make no assumptions about the number of times it is called, it might be called more than we expect - we definitely don't want to show 3 duplicate Snackbars by mistake.

It's an issue you find in all "statey" architectures like MVVM, MVO, and MVI (not so much in MVP as that's more "eventy").

What we need here is a way to take us from the state world (where things are set, and remain that way until set again) to the event world (where things are dispatched and then are gone, unless they are dispatched again). There are a number of ways of bridging these two worlds. In fore we use something called a SyncTrigger.

SyncTrigger

We need to specify 2 main things to use a SyncTrigger:

the threshold required to trip the trigger (network connectivity goes from connected->disconnected; an error state goes from false->true; the amount of money in an account goes below a certain limit; a timer goes beyond a certain duration, etc)
what we want to happen when it is triggered (typically show a snackbar or a dialog; start an activity; or run an animation)

We are going to add two SyncTriggers to the app:


private fun setupTriggers() {

  showHasBankruptciesTrigger = SyncTrigger({ gameModel.hasBankruptPlayers() }){
    Snackbar.make(this, context.getString(R.string.bankruptcies_true), LENGTH_SHORT).show()
  }

  showNoBankruptciesTrigger = SyncTrigger({ !gameModel.hasBankruptPlayers() }){
    Snackbar.make(this, context.getString(R.string.bankruptcies_false), LENGTH_SHORT).show()
  }
}

We also need to check them each time we run through syncView():

override fun syncView() {

  ...

  showHasBankruptciesTrigger.checkLazy()
  showNoBankruptciesTrigger.checkLazy()
}

Because these SyncTriggers exist in our view layer, they will be destroyed and recreated by android if we rotate our view. If their threshold conditions are already breached, they will be fired immediately upon rotation (when syncView() is called). If the device is rotated again, they will be fired again etc. This is probably not what we want. Hence checkLazy() ignores a threshold breach if it happens the first time you check a newly constructed SyncTrigger. If you do actually want the trigger fired the first time it's checked, you can call check() instead of checkLazy().

Reset behaviour

Until it is reset, a SyncTrigger will fire only once, and it will fire the first time the trigger condition goes from being false to true (when checked).

By default, a SyncTrigger is reset according to the ResetRule.ONLY_AFTER_REVERSION, which means that the trigger condition needs to flip back to false, before it is eligible for re-triggering.

Alternatively you can construct a SyncTrigger with the flag: ResetRule.IMMEDIATELY, this means that the SyncTrigger can be continually triggered each time it is checked and the trigger condition is true. Be careful with this one, it could tie your code to depending on syncView() being called a certain number of times - which is a way of writing fragile code.

KISS

SyncTriggers are a great way of firing off nice animations in response to state changes happening in models.

You won't always need them though, button click listeners are event based already for example. I recommend taking a look at the discussion about this in the fore docs.

There's a presentation which examines the effect of treating your data as state or events on the fore documentation site here - click s to see the slide notes as they provide a lot more context

Thanks for reading! If you're thinking of using fore in your team, the fore docs have most of the basics covered in easy to digest sample apps, e.g. adapters, networking or databases.

here’s the complete code for the tutorial