State Machine

Table of Contents

1. States and Events
2. Building a Machine
   1. Gradle Dependency
   2. Basics
   3. Usage
3. Using a Machine on Android
   1. Gradle Dependency
   2. States and View Models
   3. Dispatchers
   4. Usage
4. Unit Testing Machines
   1. Gradle Dependency
   2. Usage

States and Events

A state machine takes three generic parameters: the events it takes in, the states it spits out, and the arguments it finishes with. These could be sealed classes, or plain classes & objects.

sealed class Event {
  data class InputText(val text: String) : Event()
  
  object ClickedButton : Event()
}

sealed class State {
  abstract val showProgress: Boolean

  data class Idle(val currentInput: String = "") : State() {
     override val showProgress: Boolean = false
  }
  
  data class Submitting(val currentInput: String) : State() {
     override val showProgress: Boolean = true
  }
  
  object Success : State() {
     override val showProgress: Boolean = false
  }
  
  data class Failure(val reason: String) : State() {
     override val showProgress: Boolean = false
  }
}

data class Result(val success: Boolean)

Building a Machine

A basic machine only requires the core module without any extensions.

Gradle Dependency

dependencies {
   ...
   implementation "com.afollestad:statemachine:0.0.1-alpha1"
}

Basics

Your state machine should be a subclass of the StateMachine class.

When the react method is called, your machine should setup handlers for states. Each state handles a set of events, each event returns a state. The state should propagate to the UI, and the UI should send in events when there is interaction. It's a loop, which is basically what a state machine is.

class MyStateMachine : StateMachine<Event, State, Result>() {
  override suspend fun react() {
    onState<Idle> {
      onEvent<InputText> {
        state.copy(currentInput = event.text)
      }
      onEvent<ClickedButton> {
        Submitting(currentInput = state.currentInput)
      }
    }
    onState<Submitting> {
      onEnter { doServerWork(state) }
    }
    onState<Success> {
      onEnter {
        delay(2000) // A synthetic delay
        finish(Result(true)) // Kills the state machine.
      }
    }
    onState<Failure> {
      onEnter {
        delay(5000) 
        Idle() 
      }
    }
  }

  private suspend fun doServerWork(state: Submitting): State {
    delay(2000)
    return if (state.currentInput == "fail") {
      Failure(reason = "Your wish is my command.")
    } else {
      Success
    }
  }
}

Usage

This example below demonstrates usage from a JVM command-line program.

fun main() {
  val stateMachine = MyStateMachine()
  
  // Listen for state changes in the background
  GlobalScope.launch {
    stateMachine.stateFlow()
        .collect { state ->
          println("Current state: $state")
        }
  }
  
  // Start the machine with an initial state, launches the event looper.
  stateMachine.start(Idle()) { args ->
    // This callback is invoked when the machine is finished.
    // It cannot be re-used after this point.
    println("Goodbye.")
  }

  val inputReader = Scanner(System.`in`)
  while (stateMachine.isActive) {
    when (val input = inputReader.nextLine()) {
      "send" -> {
        // The invoke operator on the machine streams in events.
        stateMachine(ClickedButton)
      }
      "exit" -> {
        // The finish() method destroys the state machine.
        // This releases resources and shuts down the event looper.
        stateMachine.finish()
      }
      else -> stateMachine(InputText(input))
    }
  }
}

Using a Machine on Android

On Android, there are extension modules that you can use to make connecting your states and UI much easier. Annotation processing is used to generate view models from your state.

Gradle Dependency

On Android, your application should depend on the core-android module as an implementation dependency, and the core-android-processor module as an annotation processor (with kapt).

dependencies {
   ...
   implementation "com.afollestad:statemachine-android:0.0.1-alpha1"
   kapt "com.afollestad:statemachine-android-processor:0.0.1-alpha1"
}

States and View Models

Your state must be tagged with the @StateToViewModel annotation. Only the parent class should be tagged.

@StateToViewModel
sealed class MyState {
  abstract val buttonEnabled: Boolean

  data class Idle(val currentInput: String = "") : State() {
     override val buttonEnabled = true
  }
  data class Submitting(val currentInput: String) : State() {
     override val buttonEnabled = false
  }
  object Success : State() {
     override val buttonEnabled = false
  }
  data class Failure(val errorMessage: String) : State() {
     override val buttonEnabled = true
  }
}

This will generate a ViewModel that you can use in your UI. From the above state, you'd get something similar to this (some details are omitted because they aren't relevant):

class MyStateViewModel : ViewModel(), StateConsumer<MyState> {
  val onButtonEnabled: LiveData<Boolean> = // ...
  val onCurrentInput: LiveData<String> = // ...
  val onErrorMessage: LiveData<String> = // ...
  
  override fun accept(state: MyState) {
    ...
     // This is filled automatically to propagate state changes into the live data fields above.
  }
}

Dispatchers

On Android, being thread conscious is important. StateMachine's constructor takes two coroutine dispatchers - one for background execution, and one for the main thread.

class MyStateMachine : StateMachine<Event, State, Result>(
   executionContext = Dispatchers.IO,
   mainContext = Dispatchers.Main
) {
  ...
}

Usage

In your Activity, Fragment, etc. you can use the generated ViewModels like you would without this library.

class MyActivity : AppCompatActivity() {
  private lateinit var button: Button
  private lateinit var input: EditText
  private lateinit var error: TextView

  private lateinit var stateMachine: MyStateMachine

  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      // ...
      
      stateMachine = MyStateMachine()
      
      val viewModel = ViewModelProviders.of(this)
         .get(MyStateViewModel::class.java)
      
      viewModel.onButtonEnabled
         .observe(this, button::setEnabled)
      viewModel.onCurrentInput
         /** Filtering here is important to we don't end up with an input/output loop */
         .filter { it != input.text.toString() }
         .observe(this, input::setText)
      viewModel.onErrorMessage
         .observe(this, error::setTextAndVisibility)
          
      input.onTextChanged { text -> 
         stateMachine(InputText(text = text)) 
      }
      button.setOnClickListener { 
         stateMachine(ClickedSubmit) 
      }
      
      // This is important on Android! This will automatically finish your state machine
      // when `this` (a LifecycleOwner) is destroyed. You could of course use plain `start()` 
      // here and remember to call `finish` somewhere below later, e.g. on `onDestroy()`.
      startMachine.startWithOwner(this)
  }
  
  private fun TextView.setTextAndVisibility(text: String) {
     setText(text)
     visibility = if (text.isNotEmpty()) VISIBLE else GONE
  }
}

Your UI will automatically receive propagated values from your states as they come in. The generated view model will automatically distinct values as well, so you won't receive duplicate emissions (which could result in unnecessary UI invalidation).

If you're familiar with LiveData, you'll also know that this implementation is totally lifecycle safe. LiveData will not emit if the lifecycle owner is no longer started.

Unit Testing Machines

A core-test module is provided to aid in unit testing your state machines.

Gradle Dependency

dependencies {
   ...
   testImplementation "com.afollestad:statemachine-test:0.0.1-alpha1"
}

Usage

Here's a simple example of a JUnit test, for the state machine above.

class MyTests {
  // The core-test module exposes a `test()` extension method.
  private val stateMachine = MyStateMachine().test()
  
  @Test fun `idle state accepts input`() {
     val initialState = Idle()
     stateMachine.start(initialState)
     // send an event in
     stateMachine(InputText(text))
     // assert the initial state and new state
     stateMachine.assertStates(initialState, Idle(text))
  }
  
  @Test fun `click button in idle submits`() {
     val initialState = Idle("hello world")
     stateMachine.start(initialState)
     // send an event in
     stateMachine(ClickedButton)
     // assert the initial state and new states
     // Submitting's `onEnter` brings us to the Success state.
     stateMachine.assertStates(initialState, Submitting(text), Success)
  }
  
  @After fun shutdown() {
     // Ensure resources are released and the event looper is stopped.
     stateMachine.destroy()
  }
}