UML for Android Engineers

Understanding Asynchronous Invocations

If your app is using some sort of asynchronous APIs like LiveData or, more generally, coroutines, how can you represent your code in a sequence diagram? Open the MovieListFragment.kt file in the ui.screen package and look at the following method:

  private fun search(query: String) {
    searchJob?.cancel()
    searchJob = lifecycleScope.launch {
      viewModel.searchMovie(query).collectLatest {
        movieAdapter.submitData(it)
      }
    }
  }

How would you represent it in a sequence diagram? Consider the following diagram that represents a simplified version of the method without the cancellation:

Sequence Diagram with Async messages

Sequence Diagram with Async messages

This is a very interesting diagram because there are some symbols for representing asynchronous messages, but there isn’t a unique way to represent them for Android. However, this sequence diagram has many interesting things to note.

1. You have four different instances at the higher level of the diagram: :MovieListFragment, lifecycleScope:LifecycleCoroutineScope, :MovieViewModel and :MovieAdapter. This tells you that, in the context of the description of what happens in search(), they already exist.
2. This diagram describes what happens when some client invoked search(). This triggers the launch() message on lifecycleScope. It’s important to note here that the launch() message is synchronous and you use a closed arrow at the end of the horizontal line.
3. The previous note isn’t true for the searchMovie() message on :MovieViewModel. This happens in the scope of the coroutine and you can represent it as an asynchronous message using a horizontal line ending in an open arrow.
4. searchMovie() creates and returns a Flow<PagingData<UiMovie>>. In this diagram, you make the return type explicit using a horizontal dotted line, from right to left, ending in an open arrow. This is how you represent return values in a sequence diagram.
5. In this diagram, you also see an activation symbol close to another. When you send the launch() message, you’re also passing a lambda that you can represent using the second activation symbol.
6. The last thing to note is the cross symbol that represents the end of the life of a particular instance. In this case, you represent the end of Flow<PagingData<UiMovie>>.

This diagram is also an example of how important it is to focus on a single detail of the code you want to describe. This way, you can avoid the creation of overly complex and large diagrams.

Understanding State Diagrams

The state is a fundamental concept in modern Android development. You can define a state as a set of values an item has in a specific instant. A typical example in Android is about Activity that can be in different states that define the activity lifecycle. The Lifecycle Architecture Component defines the states you can find in the following state diagram:

State Diagram – Lifecycle Component

State Diagram – Lifecycle Component

This is a very simple state diagram that contains some of the main symbols you can use:

1. The full circle represents the initial state. This is the state of your item when it starts to exist. As you see in the diagram, once you exit that state, you never return.
2. Your system remains in the same state until “something happens”, and then it moves to another state, represented by a rectangle with rounded corners and its name inside.
3. As you learned, the system moves from one state to another when “something happens”. This could be anything, like the invocation of a method or some asynchronous operation. In the diagram, the transition from CREATED to STARTED happens when the ON_CREATE happens.
4. In a state diagram, you represent the final state with a circle with a smaller full black circle inside. As the name says, this is the final state, and you cannot exit from it.

There are other things you can represent in a state diagram and it’s worth having a quick look.

Diving Deeper Into State Diagrams

To learn more conventions about state diagrams, look at the following one:

State Diagram with Conditions

State Diagram with Conditions

This diagram contains two more pieces of information. In it, you:

1. Represent a state with a round-cornered box split into two parts. The upper contains the name of the state. The lower contains the action that the system does while in that state. For instance, the system displays a spinner while in the Loading state.
2. Know that you can move from one state to another when “something happens”. Most of the time, it’s because of a message or method invocation with a condition that you represent with [condition]. This means that the transition happens if the event happens and the [condition] is true.

State diagrams are one of the most useful UML diagrams you can use, but, as always, be careful to focus on a single aspect of the system you’re describing.

Where to Go From Here?

Great job completing the tutorial! You learned how to create the most important UML diagrams for documenting your app. It’s fundamental to understand that UML is a language you can modify however you want, just as long as it’s easy to understand. Very complicated diagrams with a lot of symbols and details generally do more harm than good and introduce confusion rather than clarity.

You can checkout this dedicated UML website to learn more about UML.

We hope you enjoyed this tutorial! If you have any comments or questions, feel free to join the discussion below.