DEV Community: Nicholas Fragiskatos

How to Use Memoization in React for Better Performance

Nicholas Fragiskatos — Thu, 16 May 2024 03:27:13 +0000

Memoization, not memorization, is a technique commonly used in functional programming to improve performance of an application. To put it simply, memoization is just caching the result of a function, then whenever that function is invoked again, as long the inputs are the same, the cached result can be returned instead of re-running the function. It is important to note that the memoized function would need to be a pure function. That is:

The returned value is always the same for an identical set of inputs.
The function does note mutate state outside of its scope, i.e., there are no side-effects.

React, which heavily encourages the use of a functional style of programming, naturally provides its own mechanisms for developers to optimize their application through memoization. With React.memo(...), useCallback(...), and useMemo(...), developers can have finer control over their application to prevent unnecessary re-rendering of components or heavy recalculations of data.

`React.memo(...)`

The purpose of React.memo(...) is to prevent unwanted re-rendering of a child component if its props have not changed when the parent component is re-rendered.

The Problem

Consider this <Parent/> component. It contains a button that, when clicked, increments a total state variable and it displays the current value of total. Lastly, it contains a <Child/> component that does not take any props.

import { useState } from "react"
import Child from "./Child"

const Parent = () => {

    const [total, setTotal] = useState(0)

    return (
        <div className="flex flex-col gap-1 w-1/5">
            <h1 className="text-3xl">Parent Component</h1>
            <div>Total: {total}</div>
            <button className="border-2 bg-cyan-600 p-1 border-black rounded-md text-white" onClick={() => setTotal(total + 1)}>Increment Parent Count</button>
            <div className="mt-3" />
            <Child />
        </div>
    )
}

export default Parent

The <Child/> component only displays how many times it has been rendered. There's a useRef(...) paired with a useEffect(...) that keeps track of the number of renders for the component, and it displays that count.

import { useEffect, useRef } from "react"

const Child = () => {
    console.log("Child Rendered")
    const renderCount = useRef(1)

    useEffect(() => {
        renderCount.current = renderCount.current + 1
    })

    return (
        <div>
            <div className="text-3xl">Child Component</div>
            <div>Render Count: {renderCount.current}</div>
        </div>
    )
}
export default Child

All together these two components create this UI

Let's see what happens when we press the button to increment the total state variable of the parent component.

The child component re-renders with the parent component. This seems odd, especially since the child component's props are not changing. In fact, it does not even have any props.

The Solution

Fortunately, the solution is simple; wrap the child component in React.memo(Component, proprsComparatorFunction). Now when the parent component re-renders the child component does not.

import { useEffect, useRef, memo } from "react" // import

const Child = () => {
    ...
}

export default memo(Child) // wrapping component

The Comparator Function

React.memo(...) has a second argument for a comparator function, which wasn't utilized in the example. By default, if no function is specified, then React will do a shallow comparison of the previous and new prop values. A shallow comparison is fine if using simple data types like comparing numbers or booleans, but if the prop is something more complex like an object, then a custom implementation might be necessary.

`useCallback(...)`

The purpose of useCallback(...) is to memoize a function that's defined in the component. If a function is defined in a component, then it will be recreated during each re-render. useCallback(...) can prevent his. The benefit to stopping the recreation of the function is exemplified best when functions are being passed down as props to child components.

The Problem

Consider the same <Parent/> and <Child/> components from before with the same React.memo(...) solution used to prevent re-renders. Except this time <Child/> defines a prop for a callback function, and <Parent/> defines a function called myFunction and passes it down to <Child/>. Also, aside from defining the callback prop, <Child/> doesn't even do anything with it.

import { useState } from "react"
import Child from "./Child"

const Parent = () => {

    const [total, setTotal] = useState(0)

    const myFunction = () => {
        console.log(`NON-Callback function called`)
    }

    return (
        <div className="flex flex-col gap-1 w-1/5">
            <h1 className="text-3xl">Parent Component</h1>
            <div>Total: {total}</div>
            <button className="border-2 bg-cyan-600 p-1 border-black rounded-md text-white" onClick={() => setTotal(total + 1)}>Increment Parent Count</button>
            <div className="mt-3" />
            <Child callback={myFunction} />
        </div>
    )
}

export default Parent

import { memo, useEffect, useRef } from "react"

const Child = ({ callback }: { callback: () => void }) => {

    console.log("Child Rendered")
    const renderCount = useRef(1)

    useEffect(() => {
        renderCount.current = renderCount.current + 1
    })

    return (
        <div>
            <div className="text-3xl">Child Component</div>
            <div>Render Count: {renderCount.current}</div>
        </div>
    )
}

export default memo(Child)

Again, let's see what happens when we change state in the parent component.

All of React.memo(...)'s hard work is undone. Although, React.memo(...) is doing exactly what it's supposed to be doing, but there are two problems:

Each re-render of <Parent/>, myFunction(...) gets recreated completely, and occupies a different space in memory, even though nothing has changed about it.
React.memo(...) is still doing a shallow comparison, but since the old function prop and the new function prop are not referencing the same spot in memory, it thinks that the prop is changed, so <Child/> needs to be re-rendered. Remember functions in JavaScript are objects and objects are compared by reference.

The Solution

Again, the solution is simple; stop recreating the function and just use the old function by using the useCallback(fn, dependencyList) hook. The first argument is the function to define whatever work needs to be done, and the second argument, similar to useEffect(...), is for a list of state variables that useCallback will check. As long as none of the state dependencies in the list change, then on every render the same function will be returned instead of creating a new one. Now since the function is the exact same, even from a referential perspective, React.memo(...)'s shallow comparison will not trigger a re-render of <Child/>

import { useCallback, useState } from "react"
import Child from "./Child"

const Parent = () => {

    const [total, setTotal] = useState(0)

    const myFunction = useCallback(() => {
        console.log(`Callback function called`)
    }, [])

    return (
        <div className="flex flex-col gap-1 w-1/5">
            <h1 className="text-3xl">Parent Component</h1>
            <div>Total: {total}</div>
            <button className="border-2 bg-cyan-600 p-1 border-black rounded-md text-white" onClick={() => setTotal(total + 1)}>Increment Parent Count</button>
            <div className="mt-3" />
            <Child callback={myFunction} />
        </div>
    )
}

export default Parent

`useMemo(...)`

Lastly, useMemo(...) is used to cache the result of a function. When rendering involves calling some function that produces some value, and the function is doing an expensive calculation but no inputs to the function are changing, then there's no point in the recalculation during each re-render.

The Problem

Continuing from the last code snippet, let's add a new state variable called myName, a function called uppercaseName, and then in the UI let's add a text field and a <p> tag to display the uppercase name.

import { useCallback, useState } from "react"
import Child from "./Child"

const Parent = () => {

    const [total, setTotal] = useState(0)
    const [myName, setMyText] = useState("michael scott")

    const myFunction = useCallback(() => {
        console.log(`Callback function called`)
    }, [])

    const uppercaseName = () => {
        console.log("Processing Name...")
        return myName.toUpperCase()
    }

    return (
        <div className="flex flex-col gap-1 w-1/5">
            <h1 className="text-3xl">Parent Component</h1>
            <div>Total: {total}</div>
            <input className="border-2 p-1" type="text" value={myName} onChange={(e) => setMyText(e.target.value)} />
            <button className="border-2 bg-cyan-600 p-1 border-black rounded-md text-white" onClick={() => setTotal(total + 1)}>Increment Parent Count</button>
            <p>{`Hello, this is ${uppercaseName()}`}</p>
            <div className="mt-3" />
            <Child callback={myFunction} />
        </div>
    )
}

export default Parent

Typing something in the text field will display an uppercase version in the paragraph below the button.

However, if we open the console and start using the button to increment the count, we can see the function is being ran each time during the re-render even though the name has not changed.

The Solution

We can use useMemo(...) to wrap the uppercaseName function in a similar way we used useCallback(...). Except this time the result of useMemo(...) is a value, and not a function. Like useCallback(...), it takes a dependency list, and as long as the state in the dependency list does not change, the result does not have to be recalculated.

import { useCallback, useState } from "react"import Child from "./Child"const Parent = () => { const [total, setTotal] = useState(0) const [myName, setMyText] = useState("michael scott") const myFunction = useCallback(() => { console.log(`Callback function called`) }, []) const uppercaseName = useMemo(() => { console.log("Processing Name...") return myName.toUpperCase() }, [myName]) return ( <div className="flex flex-col gap-1 w-1/5"> <h1 className="text-3xl">Parent Component</h1> <div>Total: {total}</div> <input className="border-2 p-1" type="text" value={myName} onChange={(e) => setMyText(e.target.value)} /> <button className="border-2 bg-cyan-600 p-1 border-black rounded-md text-white" onClick={() => setTotal(total + 1)}>Increment Parent Count</button> <p>{`Hello, this is ${uppercaseName}`}</p> <div className="mt-3" /> <Child callback={myFunction} /> </div> )}export default Parent

Over Optimization

After learning about these optimization techniques it may be tempting to start using them everywhere. However that might be overkill for most scenarios. In fact, the React documentation advises to only use these techniques for specific scenarios. However, it is ultimately up to you to decide what is best for your application and when to use what and where to use it.

Should you add React.memo everywhere?

Should you add useCallback everywhere?

Should you add useMemo everywhere?

Conclusion

React provides its own mechanisms to developers to optimize their application through memoization.

Through the use of React.memo(...) we can limit the number of re-renders of a child component when the parent component re-renders. React.memo(...) will memoize the child component and only re-render if its props have changed.

Utilizing useCallback(...) we can prevent the unnecessary recreation of functions each time a component gets re-rendered. Furthermore, we saw how this can be used in conjunction with React.memo(...) to limit child component re-renders when passing functions down as props.

Lastly, useMemo(...) can be used to avoid duplicate recalculations and data processing, especially if it is an expensive operation. As long as dependent state for the calculation does not change, there is no reason to perform the operation.

Thank you for taking the time to read my article. I hope it was helpful.

If you noticed anything in the article that is incorrect or isn't clear, please let me know. I always appreciate the feedback.

Git Reset Modes

Nicholas Fragiskatos — Wed, 06 Dec 2023 02:58:56 +0000

Sometimes when working with Git it would be useful to rewind your branch to an earlier commit. Maybe one of your recent commits introduced a bug or you just want to organize your changes differently between commits. Whatever the reason, Git provides this functionality through the git reset command.

In this article I will explain and demonstrate how to use the three most common modes of the git reset command, soft, mixed, and hard.

Important Background

Before diving into what git reset is and how it works, we need to have a basic understanding of these four important pieces of Git: working directory, repository, index, and HEAD.

Working Directory

The easiest piece to understand is the working directory, a.k.a. workspace. This is simply the main directory where all the source files live that you see and edit for your project.

Repository

Typically, when we are working on a project that Git is managing, the working directory houses another directory named .git. This directory is the repository and contains all the commit history, branch information, files, etc. for Git to manage the project. The .git directory is also all that's needed to rebuild (i.e. clone) the repository.

From Git's perspective the .git directory is the repository. However, the term repository is often used more generally to mean the working directory and everything inside it. The important point is that when Git references the repository it means the .git directory.

HEAD

The HEAD is a pointer to the latest commit in the commit history on the current branch reference. Each branch has only one HEAD that is unique to that specific branch. While often used interchangeably for convenience, branch and HEAD aren't the same, because a branch represents a collection of commits, while the HEAD is specifically the latest commit on the branch.

The repository stores all head references in .git/refs/heads/. Also, there is a HEAD file in the root of .git/ that points to a specific head reference in .git/refs/heads.

Index

The index is the storage space for all changes that will be included in the next commit and is stored within the repository. The index might also be referred to as the staging area, or cache. When we use the git add command, the file is then placed in the index.

Putting the Pieces Together

For visual clarity, below is a simple diagram of how these pieces are related. The working directory encompasses everything, then the repository(.git directory) contains the index and the HEAD.

The File Lifecycle

The example below demonstrates the three main stages for a file when working with Git. It starts in the working directory where It's either a new file or an existing file that has been modified. ¹ Next, when the file is done being modified, it's ready to be added to the index using the git add command.² Lastly, it is ready to be committed with git commit. Once committed it becomes part of the latest commit, and this latest commit becomes the new HEAD.³

It's important to know that none of the files are actually getting moved around. Instead, copies of files are being made (it's more complicated than a basic copy and paste, but for modeling purposes copy is accurate enough). All the files in the working directory stay in the working directory. When the file is staged, a copy of it is placed in the index. Then, when the file is committed, another copy is created and added to the repository as a part of the commit history.

With that being said, it is entirely possible and not uncommon for three different versions of a file to exist at a time between the working directory, index, and HEAD. Take for example, the figure below. Initially, the file is created/edited, staged, and then committed. Meaning all three areas have the same file.¹ If the file is edited and staged again, but not committed, then the working directory and the index will have a different version of the file than the HEAD.² Finally, if the file is edited again but not staged, then the working directory now contains a third version of the same file.

The Reset Command

A reset command has the following template, where MODE can be soft, mixed, or hard, and the COMMIT_HASH is the hash ID for a commit that can be found when viewing the log.

git reset --MODE COMMIT_HASH

E.x.

git reset --soft 78dffe9c5fa346d03458d15862a38325ebb2e896

At a minimum, a reset is just moving the head back to a previous commit. However, an important thing to consider is what happens to the commits between the new HEAD position and the old HEAD position. Each of those commits contain changes, and what happens to those changes is determined by the different reset modes.

This is most easily seen through an example. Consider the following branch, my_example_branch, from the figure below.¹ If for some reason we don't like commits D and E and we want to undo them, we can do a git reset C to move the head back to commit C.² This makes commits D and E orphaned and no longer part of the branch's commit history.

Soft Reset

For a soft reset, all current changes in the index remain in the index, all changes in the orphaned commits are placed back in the index, and the working directory is unchanged.

The example below demonstrates this. We start with a series of five commits: A, B, C, D, and E, all with various changes.¹ The notation F1A specifies version A of a file named F1. It's important to note that in this state we also have changes in the working directory with F3C that haven't been staged, and changes in the index with F2E that haven't been committed.

Performing a git reset --soft C² moves the HEAD back to commit C. This causes commits D and E to be orphaned. Commit D has changes F1C and F3B placed back into the index. Notice that F3C and F3B now exist simultaneously in the working directory and index, respectively. Commit E has change F4A placed back into the index. However, change F2D is a little different. Since F2E already exists in the index, and is more recent than F2D, the more recent change is kept.

Example - Setup Commands

mkdir soft_reset       
cd soft_reset
git init
touch F1
echo "F1A" >> F1
touch F2
echo "F2A" >> F2
git add .
git commit -m "Commit A"
touch F3
echo "F3A" >> F3
echo "F2B" >> F2 
git add .
git commit -m "Commit B"
echo "F1B" >> F1
echo "F2C" >> F2
git add .
git commit -m "Commit C"
echo "F1C" >> F1
echo "F3B" >> F3
git add .
git commit -m "Commit D"
echo "F2D" >> F2
touch F4
echo "F4A" >> F4
git add .
git commit -m "Commit E"
echo "F2E" >> F2
git add F2
echo "F3C" >> F3

Example - Setup State

$ git log --name-only

commit b8ed5b6fb95681eb02a1de265a374ef300ad27b9 (HEAD -> main)
Author: ...
Date: ...

    Commit E

F2
F4

commit e961b6e8eee949fc6f83b89861cafec036686212
Author: ...
Date: ...

    Commit D

F1
F3

commit 78dffe9c5fa346d03458d15862a38325ebb2e896
Author: ...
Date: ...

    Commit C

F1
F2

commit b132b2646c3f6203d27319d6296a1292710f2782
Author: ...
Date: ...

    Commit B

F2
F3

commit 75f789b08f5f7dc11557614fddcb941270829fdc
Author: ...
Date: ...

    Commit A

F1
F2

$ git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified: F2

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified: F3

Example - Soft Reset to Commit C

After running git reset --soft 78dffe9c5fa346d03458d15862a38325ebb2e896:

$ git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified: F1
    modified: F2
    modified: F3
    new file: F4

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified: F3

To show that we have the correct F2E change we can run git diff --cached F2 to get the difference between the index and HEAD versions. It shows the inclusion of the 2 lines from both changes, F2D and F2E.

$ git diff --cached F2

diff --git a/F2 b/F2
index a2e06c8..3a24ea5 100644
--- a/F2
+++ b/F2
@@ -1,3 +1,5 @@
 F2A
 F2B
 F2C
+F2D
+F2E

Mixed Reset

For a mixed reset, all changes in the orphaned commits are placed back in the working directory and all currently staged changes are unstaged, i.e., moved back into the working directory. This means the index now matches the HEAD.

💡
The mixed mode is the default mode when performing a reset, and in this case the_mode_flag can be omitted. The following two commands are equivalent:

git reset --mixed COMMIT_HASH`


git reset COMMIT_HASH

To demonstrate a mixed reset we can use the same setup as before. From the example below, we again start with a series of five commits: A, B, C, D, and E.¹ Also, as before, in this state we have changes in the working directory with F3C that haven't been staged, and changes in the index with F2E that haven't been committed.

Performing a git reset --mixed C² moves the HEAD back to commit C. This causes commits D and E to be orphaned. All changes from the orphaned commits and any staged changes are placed back into the working directory. Similarly to the previous example, there are overlaps between F2D/F2E, and F3B/F3C resulting in the most recent changes being kept, F2E and F3C. One last thing to note is that F4A is now considered an untracked file because from the commit history's perspective it's a new file that has never been staged.

Example - Setup Commands

mkdir mixed_reset       
cd mixed_reset
git init
touch F1
echo "F1A" >> F1
touch F2
echo "F2A" >> F2
git add .
git commit -m "Commit A"
touch F3
echo "F3A" >> F3
echo "F2B" >> F2 
git add .
git commit -m "Commit B"
echo "F1B" >> F1
echo "F2C" >> F2
git add .
git commit -m "Commit C"
echo "F1C" >> F1
echo "F3B" >> F3
git add .
git commit -m "Commit D"
echo "F2D" >> F2
touch F4
echo "F4A" >> F4
git add .
git commit -m "Commit E"
echo "F2E" >> F2
git add F2
echo "F3C" >> F3

Example - Setup State

$ git log --name-only

commit fc52174c53e4f3af9f7c85be2f5e15edd51a4e3f (HEAD -> main)
Author: ...
Date: ...

    Commit E

F2
F4

commit ef5162ee0dc249bc3df73f6330b9bdab20462623
Author: ...
Date: ...

    Commit D

F1
F3

commit efada051fe9b3ac195184008c2dac4a14b501402
Author: ...
Date: ...

    Commit C

F1
F2

commit 4dbd5152f6ee12fc6f8124667513789f3d9466ed
Author: ...
Date: ...

    Commit B

F2
F3

commit 9e3f1ac4b98ab0791183dfa0f06d9a7620706b21
Author: ...
Date: ...

    Commit A

F1
F2

$ git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified: F2

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified: F3

Example - Mixed Reset to Commit C

After running git reset --mixed efada051fe9b3ac195184008c2dac4a14b501402:

$ git status

On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified: F1
    modified: F2
    modified: F3

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    F4

no changes added to commit (use "git add" and/or "git commit -a")

To show that we have the correct F2E and F3C file versions we can just view their contents:

$ cat F2

F2A
F2B
F2C
F2D
F2E

$ cat F3

F3A
F3B
F3C

Hard Reset

A hard reset is the simplest but should be used carefully because it is also destructive. All changes from the index, working tree, and orphaned commits are deleted.

💡
While any uncommitted changes in the working directory or index are lost after a hard reset, it is possible to recover changes from orphaned commits using thereflog. However, that's outside the scope of this article.

From the example below, we again start with a series of five commits: A, B, C, D, and E.¹ Also, as before, in this state we have changes in the working directory with F3C that haven't been staged, and changes in the index with F2E that haven't been committed.

Performing a git reset --hard C² moves the HEAD back to commit C. Changes in the index and working directory are discarded, as well as any changes from the orphaned commits, D and E. This leaves the working directory, index, and head all in sync.

Example - Setup Commands

mkdir hard_reset       
cd hard_reset
git init
touch F1
echo "F1A" >> F1
touch F2
echo "F2A" >> F2
git add .
git commit -m "Commit A"
touch F3
echo "F3A" >> F3
echo "F2B" >> F2 
git add .
git commit -m "Commit B"
echo "F1B" >> F1
echo "F2C" >> F2
git add .
git commit -m "Commit C"
echo "F1C" >> F1
echo "F3B" >> F3
git add .
git commit -m "Commit D"
echo "F2D" >> F2
touch F4
echo "F4A" >> F4
git add .
git commit -m "Commit E"
echo "F2E" >> F2
git add F2
echo "F3C" >> F3

Example - Setup State

$ git log --name-only

commit b379b56b724c2ad9074d84ea2bae38c3394769a7 (HEAD -> main)
Author: ...
Date: ...

    Commit E

F2
F4

commit 82e8bfef9df0e6d53ff6cb21ddf17d4196de340f
Author: ...
Date: ...

    Commit D

F1
F3

commit 967ccf7ce4ec657dcbc9d9985349eda675fb0379
Author: ...
Date: ...

    Commit C

F1
F2

commit f3c30c1d6fc908df990673899264022461914ac6
Author: ...
Date: ...

    Commit B

F2
F3

commit 784afdf9e7d3b7189f457bd5c8cfb6df538eaf15
Author: ...
Date: ...

    Commit A

F1
F2

$ git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified: F2

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified: F3

Example - Hard Reset to Commit C

After running git reset --hard 967ccf7ce4ec657dcbc9d9985349eda675fb0379:

$ git status

On branch main
nothing to commit, working tree clean

Conclusion

The git reset command is a useful feature of Git that allows us to rewind a branch by moving the HEAD to an earlier commit. When rewinding a branch, we can control what happens to changes in the working directory, index, and any orphaned commits by using the three different reset modes: soft, mixed, and hard.

A soft reset will preserve any changes in the index at the time of reset while also placing any changes from orphaned commits back into the index. The working directory is left completely unchanged.

A mixed reset preserves all current changes in the working directory. Also, all changes from the index and the orphaned commits are moved back into the working directory. The index is left empty and in sync with the HEAD.

Lastly, a hard reset is the simplest because all changes from the working directory, index, and orphaned commits are just deleted.

Thank you for taking the time to read my article. I hope it was helpful.

If you noticed anything in the article that is incorrect or isn't clear, please let me know. I always appreciate the feedback.

Saving Simple Data in Android - SharedPreferences and DataStore APIs

Nicholas Fragiskatos — Fri, 24 Nov 2023 16:22:38 +0000

When it comes to data persistence and storing structured data on an Android device, the first solution that comes to mind might involve using a database, like SQLite, paired with an ORM like Room. However, if the goal is to store some configuration flags, user preferences, settings, or some other relatively small handful of simple data, then reaching for a database might be unnecessary.

Fortunately, the Android framework provides a few different storage solution APIs just for this use case: SharedPreferences , Preferences DataStore, and Proto DataStore. In this article, we will look at what they are, how they differ, and how to work with them.

I created an example app to demonstrate the different solutions. I will provide small code snippets where needed, but the full sample project can be found here on GitHub.

Project Setup

The project was created using Android Studio's "Empty Views Activity" template. Then I created three new Activities, one for each storage implementation:

SharedPreferencesActivity
PrefsDataStoreActivity
ProtoDataStoreActivity

Each activity contains the same form inputs and a button that when clicked will persist three string values and an integer value. The difference between each activity is which API is used.

Saved Data File Locations

Each API creates its own unique file in app-specific storage to save all the data. Being in app-specific storage means the data will persist until the user either clears the app data, or uninstalls the app.

Data stored using the SharedPreferences API is located in

/data/data/<APP_NAME>/shared_prefs/<SHARED_PREF_FILE>

Data stored using the DataStore API (both Preference and Proto) is located in

/data/data/<APP_NAME>/files/datastore/<DATASTORE_FILE>

To view these files outside of the app, we can use the Device Explorer tool in Android Studio.

View -> Tool Windows -> Device Explorer

SharedPreferences API

The SharedPreferences API is the original solution, and also the simplest. It stores a collection of key-value pairs where the values are simple data types (String, Float, Int, Long, Boolean) and are stored in an XML file. For example:

/data/data/com.nicholasfragiskatos.preferancestorageexample/shared_prefs/my_prefs.xml

The shared preference file is created using a file name, so any number of preference files can exist at a time for the app as long as a unique name is used. We can have one file for the whole application, one for an Activity, or some combination depending on the business logic and data organization strategies.

Creating and Retrieving a Shared Preference File

Creating or retrieving a shared preference file requires using Context.getSharedPreferences(String name, int mode). Typically this will be through an Activity since an Activity is a Context.

class SharedPreferencesActivity : AppCompatActivity() {

    // ....

    // References My_Shared_Prefs.xml
    val mySharedPrefs = getSharedPreferences("My_Shared_Prefs", Context.MODE_PRIVATE)

    // ...
}

💡
There are four different modes: MODE_PRIVATE, MODE_WORLD_READABLE, MODE_WORLD_WRITEABLE, and MODE_MULTI_PROCESS. However, since this is an old API, the only mode that is not deprecated is MODE_PRIVATE.

The Activity class has a wrapper function named getPreferences(int mode). Although, all that does is invoke getSharedPreferences(...) using the class name of the current Activity as the name of the file. For example:

class SharedPreferencesActivity : AppCompatActivity() {

    // ....

    // References SharedPreferencesActivity.xml
    val mySharedPrefs = getPreferences(Context.MODE_PRIVATE)

    // ...
}

💡
If the preference file does not already exist, then it will only be created when a value is written. Just calling getSharedPreferences(...) will not create the file.

Writing Data

Writing to the file requires invoking SharedPreferences.edit() to obtain an Editor that helps facilitate the file IO. Then, similar to how we work with a Bundle, we use putInt(...), putString(...), etc., functions provided by the Editor to modify the preferences. Each function requires a key and value parameters, where the key is a String. Lastly, to actually write the changes to disk, we either invoke commit(), or apply().

val demographicsPrefs = getSharedPreferences(DEMOGRAPHICS_FILE_KEY, Context.MODE_PRIVATE)

demographicsPrefs.edit().apply {  
    putString(FIRST_NAME_PREF_KEY, "Leslie")  
    putString(LAST_NAME_PREF_KEY, "Knope")  
    apply()  
}

Example XML file:

<?xml version='1.0' encoding='utf-8' standalone='yes' ?>  
<map>  
    <string name="com.nicholasfragiskatos.preferancestorageexample.FIRST_NAME_PREF_KEY">Leslie</string>  
    <string name="com.nicholasfragiskatos.preferancestorageexample.LAST_NAME_PREF_KEY">Knope</string>  
</map>

`apply()` vs `commit()`

commit() writes the data synchronously, and it returns a boolean on whether or not the new values were successfully written.

apply() commits its changes first to the in-memory SharedPreferences immediately, and also starts an asynchronous commit to the disk. However, it does not return any value to signal success or failure.

Unless you need the return value, it's advised to just use apply().

Reading Data

SharedPreferences provides getInt(...), getString(...), etc., functions to read data from the preference file. These functions require the same key parameter used to write the value and a default value parameter in case the value doesn't exist.

val demographicsPrefs = getSharedPreferences(DEMOGRAPHICS_FILE_KEY, Context.MODE_PRIVATE)

val firstName = demographicsPrefs.getString(FIRST_NAME_PREF_KEY, "")  
val lastName = demographicsPrefs.getString(LAST_NAME_PREF_KEY, "")

DataStore

DataStore is the new API that is meant to replace SharedPreferences. Again, the values are simple data types (String, Float, Int, Long, Boolean). However, unlike SharedPreferences, DataStore uses Kotlin coroutines and Flows to store data asynchronously and guarantee data consistency across multi-process access.

There are two flavors of DataStore provided to us, Preferences DataStore and Proto DataStore. While both are an improvement over regular SharedPreferences, each requires a bit more complexity, with Proto DataStore being the most complex by including Protocol Buffers, as we'll see later.

💡
Creating more than one DataStore object that references the same file in the same process will break functionality and result in an IllegalStateException error when reading/writing data.

Viewing DataStore Files

The DataStore implementation used will determine what type of file is created on the device. If the preferences approach is used, then a .preferences_pb file will be created. If the proto approach is used then a .proto file will be created. For example:

/data/data/com.nicholasfragiskatos.preferancestorageexample/files/datastore/MyPrefsDataStore.preferences_pb

/data/data/com.nicholasfragiskatos.preferancestorageexample/files/datastore/MyProtoSchema.proto

Unfortunately, both file types need to be decoded first before they can be viewed outside of the app. Google provides a command line utility called protoc for Mac and Linux. protoc can be used as follows.

protoc --decode_raw < MyProtoSchema.proto

Preferences DataStore

To get started with Preference DataStore implementation, we first need to add a dependency to the Gradle file.

implementation "androidx.datastore:datastore-preferences:1.0.0"

Similar to SharedPreferences, we need to create a handle to the file we want to read/write from. This time though it's a DataStore object that will manage the transactions. To obtain it we use the preferencesDataStore(...) property delegate on an extension property of Context.

// make sure to use androidx.datastore.preferences.core.Preferences
val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "MyPrefsDataStore")

Defining Keys for Values

Like SharedPreferences, we access DataStore preferences with a key, but instead of a simple String key, we need to create a Preferences.Key<T> for each value. This allows the key-value pair to be typed. These keys are created using stringPreferencesKey(...), intPreferencesKey(...), etc.

val FIRST_NAME_PREF_KEY = stringPreferencesKey("${BuildConfig.APPLICATION_ID}.FIRST_NAME_PREF_KEY")  
val LAST_NAME_PREF_KEY = stringPreferencesKey("${BuildConfig.APPLICATION_ID}.LAST_NAME_PREF_KEY")  
val FAVORITE_COLOR_PREF_KEY = stringPreferencesKey("${BuildConfig.APPLICATION_ID}.FAVORITE_COLOR_PREF_KEY")  
val FAVORITE_ICE_CREAM_PREF_KEY = intPreferencesKey("${BuildConfig.APPLICATION_ID}.FAVORITE_ICE_CREAM_PREF_KEY")

Writing Data

Writing to the file requires invoking the DataStore.edit(...) extension function that takes a suspending lambda function parameter, suspend (MutablePreferences) -> Unit.

The MutablePreferences object implements the index get/set operator functions, so we can read/write values with our defined preference keys using the same syntax as we would for a Map.

val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "MyPrefsDataStore")

class PrefsDataStoreActivity : AppCompatActivity() {

    // ...

    private suspend fun savePreferences() {
        val firstName = "Ron"
        val lastName = "Swanson"
        val favoriteColor = "Blue"  
        val iceCreamId = 2131231085 // some id for radio button

        applicationContext.dataStore.edit { settings: MutablePreferences ->  
            settings[FIRST_NAME_PREF_KEY] = firstName  
            settings[LAST_NAME_PREF_KEY] = lastName  
            settings[FAVORITE_COLOR_PREF_KEY] = favoriteColor  
            settings[FAVORITE_ICE_CREAM_PREF_KEY] = iceCreamId  
        }
    }

    // ...
}

MyPrefsDataStore.preferences_pb content:

protoc --decode_raw < MyPrefsDataStore.preferences_pb

1 {
  1: "com.nicholasfragiskatos.preferancestorageexample.FIRST_NAME_PREF_KEY"
  2 {
    5: "Ron"
  }
}
1 {
  1: "com.nicholasfragiskatos.preferancestorageexample.LAST_NAME_PREF_KEY"
  2 {
    5: "Swanson"
  }
}
1 {
  1: "com.nicholasfragiskatos.preferancestorageexample.FAVORITE_COLOR_PREF_KEY"
  2 {
    5: "Brown"
  }
}
1 {
  1: "com.nicholasfragiskatos.preferancestorageexample.FAVORITE_ICE_CREAM_PREF_KEY"
  2 {
    3: 2131231085
  }
}

Reading Data

Reading from the file is done by collecting on the DataStore.data property, which is a Flow.

val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "MyPrefsDataStore")

class PrefsDataStoreActivity : AppCompatActivity() {
    private suspend fun initFromPreferences() {  
        applicationContext.dataStore.data.collect { settings: Preferences ->  

            val firstName = settings[FIRST_NAME_PREF_KEY] ?: ""  
            val lastName = settings[LAST_NAME_PREF_KEY] ?: ""  
            val favoriteColor = settings[FAVORITE_COLOR_PREF_KEY] ?: ""  
            val favoriteIceCreamId = settings[FAVORITE_ICE_CREAM_PREF_KEY] ?: R.id.rbChocolate  
        }  
    }
}

Proto DataStore

Using the Proto DataStore implementation requires significantly more setup than the previous two methods. However, despite the overhead, this approach does ensure type safety, and read and writes are defined by updating a custom, generated class object with named properties instead of relying on keys.

To begin, we need the following changes in the Gradle file:

Add Protobuf plugin
Add Proto DataStore, and ProtoBuf dependencies
Create a custom Protobuf configuration

plugins {  
    // ...
    id "com.google.protobuf" version "0.9.1"  
}

// ...

dependencies {  
    // ...

    implementation "androidx.datastore:datastore:1.0.0"  
    implementation "com.google.protobuf:protobuf-javalite:3.25.0"  

}

protobuf {  
    protoc {  
        artifact = "com.google.protobuf:protoc:3.21.7"  
    }  

    generateProtoTasks {  
        all().each { task ->  
            task.builtins {  
                java {  
                    option 'lite'  
                }  
            }  
        }  
    }  
}

Next, we need to create a schema in the app/src/main/proto directory of the project. It's a simple text file with the extension .proto. Here's a basic example for the sample application, but the Protocol Buffer Documentation provides more details.

syntax = "proto3";  

option java_package = "com.nicholasfragiskatos.preferancestorageexample";  
option java_multiple_files = true;  

message MySettings {  
    string first_name = 1;  
    string last_name = 2;  
    string favorite_color = 3;  
    int32 favorite_ice_cream_flavor = 4;  
}

With the schema defined, a MySettings class will be generated for us. The generated class implementation is extensive, but one convenient thing to point out is that it has a corresponding property for each property defined in the schema. For example, the schema defines a first_name property, so MySettings will have a firstName property.

The next part of the setup is to create a custom Serializer that tells DataStore how to read and write our custom data type (MySettings) as defined by the schema. This is largely boilerplate code.

object MySettingsSerializer : Serializer<MySettings> {  

    override val defaultValue: MySettings = MySettings.getDefaultInstance()  
    override suspend fun readFrom(input: InputStream): MySettings {  
        try {  
            return MySettings.parseFrom(input)  
        } catch (exception: InvalidProtocolBufferException) {  
            throw CorruptionException("cannot read proto.", exception)  
        }  
    }  

    override suspend fun writeTo(t: MySettings, output: OutputStream) {  
        t.writeTo(output)  
    }  
}

Now, when we read from the file DataStore provides a MySettings object, and when we write to the file we give DataStore a MySettings object.

Lastly, similar to preferences DataStore, we need to create a DataStore object that will manage the transactions. This time we use the dataStore(...) property delegate on an extension property of Context.

val Context.myProtoDataStore: DataStore<MySettings> by dataStore("MyProtoSchema.proto", serializer = MySettingsSerializer)

Writing Data

Writing to the file requires invoking the DataStore.updateData(...) function that takes a suspending lambda function parameter, suspend (MySettings) -> MySettings. We use the builder pattern to create and return an updated MySettings object to save.

val Context.myProtoDataStore: DataStore<MySettings> by dataStore("MyProtoSchema.proto", serializer = MySettingsSerializer)  

class ProtoDataStoreActivity : AppCompatActivity() {  

private lateinit var binding: ActivityProtoDataStoreBinding  

    // ...

    private suspend fun savePreferences() {  
        val firstName = "Ben"
        val lastName = "Wyatt"
        val favoriteColor = "Green"
        val iceCreamId = 2131231084 // some id for radio button

        applicationContext.myProtoDataStore.updateData { settings ->  
            settings.toBuilder()  
            .setFirstName(firstName)  
            .setLastName(lastName)  
            .setFavoriteColor(favoriteColor)  
            .setFavoriteIceCreamFlavor(iceCreamId)  
            .build()  
        }  
    }  
}

MyProtoSchema.proto content:

protoc --decode_raw < MyProtoSchema.proto
1: "Ben"
2: "Wyatt"
3: "Green"
4: 2131231084

Reading Data

Like Preferences DataStore, reading from the file is done by collecting on the DataStore.data property, which is a Flow.

val Context.myProtoDataStore: DataStore<MySettings> by dataStore("MyProtoSchema.proto", serializer = MySettingsSerializer)  

class ProtoDataStoreActivity : AppCompatActivity() {  

private lateinit var binding: ActivityProtoDataStoreBinding  

    // ...

    private suspend fun initFromPreferences() {  
        applicationContext.myProtoDataStore.data.collect { settings ->  
            binding.etFirstName.setText(settings.firstName)  
            binding.etLastName.setText(settings.lastName)  
            binding.etFavoriteColor.setText(settings.favoriteColor)  
            binding.rgIceCreamFlavor.check(settings.favoriteIceCreamFlavor)  
        }  
    }  

    // ...
}

Conclusion

The Android framework provides the developer with SharedPreferences , Preferences DataStore, and Proto DataStore APIs to persist sets of structured data without having to rely on a database. All three APIs write and read simple values (String, Float, Int, Long, Boolean) to a file in app-specific storage.

SharedPreferences is the original solution and is built into the Context interface with the getSharedPreferences(...) function. We write and read values to an XML file using String keys. While simple and convenient, it does rely on managing unique keys for all values. Also, it could perform synchronous file I/O on the main UI thread if using commit(), and even if apply() is used instead of commit() then there is no mechanism for signaling success or failure.

The Preferences DataStore API improves upon SharedPreferences by taking advantage of Kotlin coroutines and Flows to store data asynchronously and guarantee data consistency across multi-processor access. While this solution also relies on keys to write data, this time they are not String values but instead Preferences.Key<T> objects that allow the key-value pair to be typed.

Lastly, we learned about Proto DataStore. Like Preferences DataStore, it provides the benefits of asynchronous writes using coroutines and Flows. Another major benefit is that instead of managing key-value pairs, we get a custom, schema-backed, generated class with regular named properties. Proto DataStore provides this custom object when reading from storage, and we provide the same object when writing back to storage. However, these benefits come at the cost of much greater complexity in setup and configuration.

Thank you for taking the time to read my article. I hope it was helpful.

If you noticed anything in the article that is incorrect or isn't clear, please let me know. I always appreciate the feedback.

Object Relationships in Room ORM Library for Android

Nicholas Fragiskatos — Wed, 15 Nov 2023 23:37:24 +0000

Object Relational Mapping (ORM) libraries are common tools for back-end development for interacting with a relational database. As the name implies they help facilitate mapping your data that is stored in a relational database to objects used in your application code. Room is the standard ORM library that sits between your Android application and its SQLite database.

While not necessary, ORMs provide a lot of functionality out of the box to save the developer time. Using an ORM allows the developer to interact with the database with the same language used in the back end. Instead of having to concern themselves with creating complex SQL queries, interactions with the database can look as simple as a normal function call.

ORMs typically support object references between entities. Or more specifically, nested entity relationships. For example, consider the following Java code snippet for a Hibernate entity relationship (Hibernate is another popular ORM):

@Entity
public class StudentEntity {

    @Id
    @Column(name = "STUDENT_ID")
    public Long id;

    //....

    @JoinColumn(name = "ADDRESS_ID")
    public AddressEntity address;

    // ...
}

@Entity
public class AddressEntity {

    @Id
    @Column(name = "ADDRESS_ID")
    public Long id;

    @Column(name = "STREET_NAME")
    public String streetName;

    // ...
}

The StudentEntity object has an AddressEntity object as a member of its class. This means that when a StudentEntity is fetched from the database the AddressEntity object will also be fetched, either eagerly or lazily, and be readily available to access from the StudentEntity object.

someStudent.address.streetName

While Room provides a lot of features, it intentionally does not support this behavior. The focus of this article is to see how we can establish and manage object relationships in Room without relying on nested entities. As we'll see, there are a few different approaches, each valid in its own way depending on the use case.

💡
In case you are wondering why exactly Room doesn't allow this behavior, there is a section in the Android documentation explaining their reasoning. However, in short, nested models can either be loaded lazily, meaning they are loaded at the time of access, or eagerly, meaning all entities are loaded at once. On Android, lazy loading would occur on the UI thread, and even a fast database query could result in the system being unable to meet the 16 ms time limit to calculate and redraw a frame. Eager loading is the other option, but this could result in lots of data being loaded even if the UI doesn't require it, therefore wasting memory.

I will provide code snippets throughout the article, however, a full sample project can be found here on my GitHub. Since the focus of this article is on the database and not the UI, the UI is bare bones, but it provides enough functionality to demonstrate the different approaches.

`@Embedded` Annotation

The easiest approach is to embed the nested object into the entity. This is done by annotating the nested object with @Embedded which tells Room to create additional columns in the parent entity's table for all the fields in the nested object. Essentially, Room is destructuring the nested object and treating all its fields as if it were part of the parent entity.

The following shows an example model setup. Notice that the nested address object is a simple data class, not an entity. I did add @ColumnInfo annotations to the fields in the nested object just for naming clarity, but it does not affect functionality.

@Entity(tableName = "studentWithEmbedded")  
data class StudentWithEmbeddedEntity(  
    @PrimaryKey(autoGenerate = true)  
    val id: Long = 0,  

    @ColumnInfo(name = "first_name")  
    val firstName: String,  

    @ColumnInfo(name = "last_name")  
    val lastName: String,  

    @Embedded  
    val address: AddressForEmbedded,  
)

data class AddressForEmbedded(  
    @ColumnInfo(name = "house_number_embedded")  
    val houseNumber: String,  

    @ColumnInfo(name = "street_name_embedded")  
    val streetName: String,  

    @ColumnInfo(name = "street_type_embedded")  
    val streetType: String,  

    @ColumnInfo(name = "city_embedded")  
    val city: String,  

    @ColumnInfo(name = "state_embedded")  
    val state: String,  

    @ColumnInfo(name = "postal_code_embedded")  
    val postalCode: String,  
)

Now when Room creates the studentWithEmbedded table in the database, every field in the nested AddressForEmbedded object will be its own column. Therefore, a full list of columns in the studentWithEmbedded table will be:

id
first_name
last_name
house_number_embedded
street_name_embedded
street_type_embedded
city_embedded
state_embedded
postal_code_embedded

Pros and Cons

Pros:

Probably the simplest of all the approaches
Can handle one-to-one relationships, one student has only one address
The address data is queryable

Cons:

Can not handle a one-to-many, or many-to-many relationship. This means a row in the studentWithEmbedded table can only have one and only one address association.
If multiple students are associated with the same address, then multiple rows in the studentWithEmbedded table will have identical values in the associated address columns, i.e., duplicate data.

Type Converters

Another approach is to use a Type Converter to serialize the child object to a JSON string, and then store the whole object as a string in one of the table's columns for the parent entity. When the parent entity is fetched from the database the Type Converter will deserialize the string into the correct object.

The model setup is almost the same as before. The only real differences are the lack of the @Embedded annotation, and the addition of an id field in the address object. While an ID is not technically necessary for this to work, this approach can handle one-to-many and many-to-many relationships, so an ID is helpful.

@Entity(tableName = "studentWithJson")  
data class StudentWithJsonEntity(  
    @PrimaryKey(autoGenerate = true)  
    val id: Long = 0,  

    @ColumnInfo(name = "first_name")  
    val firstName: String,  

    @ColumnInfo(name = "last_name")  
    val lastName: String,  

    @ColumnInfo(name = "address_json")
    val address: AddressForJson,  
)

data class AddressForJson(  
    val id: Long = 0,  
    val houseNumber: String,  
    val streetName: String,  
    val streetType: String,  
    val city: String,  
    val state: String,  
    val postalCode: String,  
)

With the models set, we can then create a Type Converter to go back and forth between AddressForJson and String. For this example, I'm using the Moshi library to handle the JSON conversions.

@ProvidedTypeConverter  
class MyRoomTypeConverters(private val moshi: Moshi) {  

    @TypeConverter  
    fun fromAddressJson(json: String): AddressForJson {  
        return moshi.adapter(AddressForJson::class.java).fromJson(json)!!  
    }  

    @TypeConverter  
    fun toAddressJson(address: AddressForJson): String {  
        return moshi.adapter(AddressForJson::class.java).toJson(address)  
    }  
}

Room will create the StudentWithJsonEntity database table with the following columns:

id
first_name
last_name
address_json

Pros and Cons

Pros:

Still relatively simple
Can handle a one-to-one relationship.
Can handle a one-to-many relationship, one student can have multiple addresses. In this case, the entity would instead have a field for List<AddressForJson>.

Cons:

The same duplicate data problem as before, if multiple students are associated with the same address, then multiple rows in the studentWithJson table will have identical values in the address_json data.
From the duplicate data issue in the first point, this approach technically can't handle a many-to-many relationship. While students can have multiple addresses and an address can be used by multiple students, since all addresses are stored in their separate JSON strings, there are no relationships between two identical addresses from different student rows.
The address data is not queryable.

Intermediate Models

The last approach is the most complex, but also the most powerful since it best leverages Room and SQLite. An important distinction between this approach and the previous two is that both objects we are trying to relate are entities with their own respective tables. We can define relationships between entities by using a few different components together:

Room's @Relation annotation
Room's @ForeignKey annotation
Room's @Embedded annotation
Intermediate model

Unlike the previous two approaches where we try and have a nested relationship, this approach avoids that by using a third model called the intermediate model. The intermediate model contains two fields, one for the parent entity and one for the child entity(s).

The @Relation annotation is used on the child entity in the intermediate model, and it is important because it defines how to relate both tables when retrieving data.

The @ForeignKey annotation is important because it helps enforce the relational structure when inserting/modifying data. If you try and insert a row into the child table with a value for the foreign key column that doesn't match any primary key in the parent table an exception will be thrown.

android.database.sqlite.SQLiteConstraintException: FOREIGN KEY constraint failed (code 787 SQLITE_CONSTRAINT_FOREIGNKEY)

Ultimately, the power of this approach is that depending on how we use these components we can model a one-to-one, one-to-many, or many-to-many relationship.

One-to-One Relationship

Starting with the simplest relation type, consider again the student and address objects.

@Entity(tableName = "studentWithOneToOneRelation")  
data class StudentWithOneToOneRelationEntity(  
    @PrimaryKey(autoGenerate = true)  
    val studentId: Long = 0,  
    val firstName: String,  
    val lastName: String  
)

@Entity(tableName = "addressForOneToOneRelation")
data class AddressForOneToOneRelationEntity(  

    @PrimaryKey(autoGenerate = true)  
    val id: Long = 0,  
    val houseNumber: String,  
    val streetName: String,  
    val streetType: String,  
    val city: String,  
    val state: String,  
    @ColumnInfo(name = "postal_code")  
    val postalCode: String,  

    val studentOwnerId: Long  
)

There are two things to note:

The StudentWithOneToOneRelationEntity does not have a nested AddressForOneToOneRelationEntity field.
The AddressForOneToOneRelationEntity has a reference (studentOwnerId) that points back to the primary key for StudentWithOneToOneRelationEntity.

With our two entities defined, we now need to create the intermediate object:

data class StudentWithAddressOneToOneIntermediate(  
    @Embedded  
    val student: StudentWithOneToOneRelationEntity,  

    @Relation(  
        parentColumn = "studentId",  
        entityColumn = "studentOwnerId"  
    )  
    val address: AddressForOneToOneRelationEntity?  
)

As discussed before, there are only two fields, one for student and one for address. The student field is marked with @Embedded since it is the parent, and the address field has the @Relation annotation, since it is the child. The @Relation annotation needs to be configured with two properties: parentColumn, which is the name of the primary key column in the parent entity, and entityColumn, which is the name of the column in the child entity that references the parent entity's primary key.

With the relationship configured, we can define a query function in the DAO interface for the student.

@Dao  
interface StudentWithOneToOneRelationDao {  

    // ... 

    @Transaction  
    @Query("SELECT * from studentWithOneToOneRelation")  
    fun getAllStudentsWithAddresses(): List<StudentWithAddressOneToOneIntermediate>  
}

The function is annotated with @Query that selects from the student table as we would normally do. However, there are two important differences:

The list that is being returned contains intermediate objects (StudentWithAddressOneToOneIntermediate) instead of the table's entity (StudentWithOneToOneRelationEntity)
The query is marked as a transaction. This is because Room will query the fields in the intermediate object separately, therefore it needs to make sure that all separate query operations are complete before returning.

Foreign Key Constraint

What we've done so far is enforce a one-to-one relationship between StudentWithOneToOneRelationEntity and AddressForOneToOneRelationEntity, but only when retrieving data. We still need to complete the circle and enforce the one-to-one relationship during the time of insertion/modification, because right now there are two issues. First, it's still possible to insert a row into the address table where the studentOwnerId value does not match any studenId in the student table. Second, it's possible to have two rows in the address table refer to the same student, therefore breaking the one-to-one relationship.

To fix the first issue, we just need to update the child entity, AddressForOneToOneRelationEntity, by adding a foreign key.

@Entity(  
    tableName = "addressForOneToOneRelation",  

    foreignKeys = [  
        ForeignKey(  
            entity = StudentWithOneToOneRelationEntity::class,  
            parentColumns = arrayOf("studentId"),  
            childColumns = arrayOf("studentOwnerId"),
            onDelete = ForeignKey.CASCADE    
        )  
    ],  
)  
data class AddressForOneToOneRelationEntity(  
    // ...   
)

Where:

entity - The name of the parent table.
parentColumns - The name of the column in the parent table that the foreign key references.
childColumns - The name of the column in the child table that contains the foreign key value.
onDelete - Defines how to treat the child entity when the parent entity it references is deleted. In the case of cascade, when the parent entity is deleted the child entity is also deleted.

To fix the second issue we once again update the @Entity annotation for AddressForOneToOneRelationEntity. It has an indices property in which we can add an Index for the foreign key column, and require it to be unique in the table.

@Entity(  
    tableName = "addressForOneToOneRelation", 

    foreignKeys = [  
        ForeignKey(  
            entity = StudentWithOneToOneRelationEntity::class,  
            parentColumns = arrayOf("studentId"),  
            childColumns = arrayOf("studentOwnerId"),
            onDelete = ForeignKey.CASCADE       
        )  
    ],  

    indices = [Index(value = ["studentOwnerId"], unique = true)]  
)  
data class AddressForOneToOneRelationEntity(  
    // ...
)

Now if we try and insert rows with duplicate studentOwnerId values an exception will be thrown.

Process: com.nicholasfragiskatos.objectrelationshipsinroom, PID: 10239
android.database.sqlite.SQLiteConstraintException: UNIQUE constraint failed: addressForOneToOneRelation.studentOwnerId (code 2067 SQLITE_CONSTRAINT_UNIQUE)

One-to-Many Relationship

Luckily, the one-to-many relationship is almost identical to the one-to-one relationship except for a couple of minor tweaks.

The child entity no longer needs the unique index.
The intermediate model has a list of addresses instead of just one.

@Entity(tableName = "studentWithOneToManyRelation")  
data class StudentWithOneToManyRelationEntity(  
    @PrimaryKey(autoGenerate = true)  
    val studentId: Long = 0,  
    val firstName: String,  
    val lastName: String  
)

@Entity(  
    tableName = "addressForOneToManyRelation",  

    foreignKeys = [  
        ForeignKey(  
            entity = StudentWithOneToManyRelationEntity::class,  
            parentColumns = arrayOf("studentId"),  
            childColumns = arrayOf("studentOwnerId"),
            onDelete = ForeignKey.CASCADE   
        )  
    ]  
)  
data class AddressForOneToManyRelationEntity(  

    @PrimaryKey(autoGenerate = true)  
    val id: Long = 0,  
    val houseNumber: String,  
    val streetName: String,  
    val streetType: String,  
    val city: String,  
    val state: String,  
    @ColumnInfo(name = "postal_code")  
    val postalCode: String,  

    val studentOwnerId: Long  
)

data class StudentWithAddressOneToManyIntermediate(  
    @Embedded  
    val student: StudentWithOneToManyRelationEntity,  

    @Relation(  
    parentColumn = "studentId",  
    entityColumn = "studentOwnerId"  
    )  
    val address: List<AddressForOneToManyRelationEntity>?  
)

@Dao  
interface StudentWithOneToManyRelationDao {  

    // ... 

    @Transaction  
    @Query("SELECT * from studentWithOneToManyRelation")  
    fun getAllStudentsWithAddresses(): List<StudentWithAddressOneToManyIntermediate>  
}

Many-to-Many Relationship

For this approach, the parent entity stays the same again, but the child entity no longer uses a foreign key, which also means it no longer needs the studentOwnerId field.

@Entity(tableName = "studentWithManyToManyRelation")  
data class StudentWithManyToManyRelationEntity(  
    @PrimaryKey(autoGenerate = true)  
    val studentId: Long = 0,  
    val firstName: String,  
    val lastName: String  
)

@Entity(tableName = "addressForManyToManyRelation")  
data class AddressForManyToManyRelationEntity(  
    @PrimaryKey(autoGenerate = true)  
    val addressId: Long = 0,  
    val houseNumber: String,  
    val streetName: String,  
    val streetType: String,  
    val city: String,  
    val state: String,  
    @ColumnInfo(name = "postal_code")  
    val postalCode: String  
)

The Many-to-Many relationship is slightly more involved, and requires the use of a junction table (I've also seen this referred to as an Association Table, or Join Table), which like any other table, is modeled with an entity class. It's a two-column table where one column holds a reference to the primary key of the parent table and the other column holds a reference to the primary key of the child table. This helps resolve the many-to-many relationship. The primary key for the junction table itself is the composite of both columns.

For this example, the junction table entity contains two fields, one for the student ID and one for the address ID. Then we make sure to specify both fields as primary keys in the @Entity annotation. Since this is a many-to-many relationship there can be multiple rows with duplicate student IDs, and multiple rows with duplicate address IDs, but there can not be multiple rows with a duplicate combination of IDs. It's also probably a good idea to define two foreign keys with cascade deletes, one pointing to the student entity, and one pointing to the address entity. This will avoid having orphaned rows in the table when either a student or address is deleted.

@Entity(  
    tableName = "studentAddressCrossRef",  

    primaryKeys = ["studentId", "addressId"],  

    foreignKeys = [  
        ForeignKey(  
            entity = StudentWithManyToManyRelationEntity::class,  
            parentColumns = ["studentId"],  
            childColumns = ["studentId"],  
            onDelete = ForeignKey.CASCADE  
        ),  
        ForeignKey(  
            entity = AddressForManyToManyRelationEntity::class,  
            parentColumns = ["addressId"],  
            childColumns = ["addressId"],  
            onDelete = ForeignKey.CASCADE  
        )  
    ]  
)  
data class StudentAddressCrossRef(  
    val studentId: Long,  
    val addressId: Long  
)

In the intermediate object the @Relation annotation now refers to the junction table. The parentColumn property points to the studentId column in the junction table, and the entityColumn property points to the addressId column in the junction table. Lastly, there is the addition of the associateBy property that specifies the junction table entity class.

data class StudentWithAddressManyToManyIntermediate(  
    @Embedded  
    val student: StudentWithManyToManyRelationEntity,  

    @Relation(  
        parentColumn = "studentId",  
        entityColumn = "addressId",  
        associateBy = Junction(StudentAddressCrossRef::class)  
    )  
    val address: List<AddressForManyToManyRelationEntity>?  
)

Finally, we define the DAO interface as before.

@Dao  
interface StudentWithManyToManyRelationDao {  

    @Insert(onConflict = OnConflictStrategy.REPLACE)  
    fun saveStudent(student: StudentWithManyToManyRelationEntity): Long  

    @Insert(onConflict = OnConflictStrategy.REPLACE)  
    fun saveAddress(address: AddressForManyToManyRelationEntity): Long  

    @Insert(onConflict = OnConflictStrategy.REPLACE)  
    fun saveStudentAddressCrossRef(ref: StudentAddressCrossRef): Long  

    @Insert(onConflict = OnConflictStrategy.REPLACE)  
    @Transaction  
    fun saveAddress(address: AddressForManyToManyRelationEntity, studentId: Long) {  
        saveAddress(address)  
        saveStudentAddressCrossRef(StudentAddressCrossRef(studentId, address.addressId))  
    }  

    @Query("DELETE FROM studentWithManyToManyRelation where studentId = :studentId")  
    fun deleteStudent(studentId: Long): Int  

    @Query("DELETE FROM addressForManyToManyRelation where addressId = :addressId")  
    fun deleteAddress(addressId: Long): Int  

    @Transaction  
    @Query("SELECT * from studentWithManyToManyRelation")  
    fun getAllStudentsWithAddresses(): List<StudentWithAddressManyToManyIntermediate>  
}

It's important to note that when it comes to inserting new student or address data, if there is a relationship then the junction table needs to be manually updated. The business logic of when and how a relationship is formed is entirely up to your use case. However, the important point is that just saving a new student or address using the standard @Insert functions do not automatically create a new entry in the junction table.

As a simple example, I added the following utility functions to the DAO to facilitate inserting a new address and junction table row within one transaction.

@Insert(onConflict = OnConflictStrategy.REPLACE)  
fun saveStudentAddressCrossRef(ref: StudentAddressCrossRef): Long  

@Insert(onConflict = OnConflictStrategy.REPLACE)  
@Transaction  
fun saveAddress(address: AddressForManyToManyRelationEntity, studentId: Long) {  
    saveAddress(address)  
    saveStudentAddressCrossRef(StudentAddressCrossRef(studentId, address.addressId))  
}

Conclusion

Room is a powerful and convenient ORM for Android app development, but it does not support nested entity relationships like other ORMs that are used on more traditional back ends. This limitation stems from the need to preserve the responsiveness of the UI and avoid consuming unnecessary memory resources. Despite this limitation, there are still ways to create object relationships.

First, we looked at embedding the child object into the parent object using Room's @Embedded annotation. This approach is simple, but it can only support one-to-one relationships, and it does not efficiently handle identical child data being referenced by multiple parent entities.

Next, we looked at using a Type Converter to serialize the child object to a JSON string to store the whole object as a string in one of the columns for the parent entity. When the parent entity is fetched from the database the Type Converter will deserialize the string into the correct object. This approach can handle one-to-one and one-to-many relationships, but it also requires duplicating data. However, what might be even worse is that the child data is not easily queryable.

Finally, we learned about the most complex, but powerful approach which best leverages Room and SQLite by treating both parent and child objects as entities, and using a combination of the@Relation annotation, embedded objects, foreign keys, and intermediate models. This approach allows us to define one-to-one, one-to-many, and many-to-many relationships between objects all while keeping the data queryable without data duplication.

Thank you for taking the time to read my article. I hope it was helpful.

If you noticed anything in the article that is incorrect or isn't clear, please let me know. I always appreciate the feedback.

Launch Modes in Android - with Examples

Nicholas Fragiskatos — Tue, 07 Nov 2023 22:30:52 +0000

A Task is a model that the Android system uses to manage a collection of Activities that the user is interacting with through some application's workflow. In the simplest, default case we would have a one-to-one mapping between one task and one application's set of Activities. When a user is navigating through a multi-activity application, each new Activity that is launched is added to the associated Task.

To keep everything organized, a Task places its Activities in a Back Stack; with each successively opened Activity being added to the top of the stack. This is also what helps facilitate the back navigation when the user presses the back button or swipes back; the current activity gets popped off the stack to be replaced with the Activity underneath it.

As noted earlier, one Task for one application's set of Activities is the default behavior. However, the Android framework does provide the developer with the power to manipulate this behavior either through the manifest file when declaring the Activity to the system, or by using Intent flags.

In this article, I want to focus on the Android manifest file and all the different ways in which we can manipulate the Activity-Task association behavior when defining different Activities in the app's manifest.

I've created a toy app to easily exemplify all the different behaviors. I will provide small code snippets where needed, but the full sample project can be found here on GitHub.

Project Setup

I created a brand new project using Android Studio's "Empty Views Activity" template. Then I created six new Activities:

ActivityA
ActivityB
ActivityC
ActivityD
ActivityE
ActivityF

Each Activity is basically the same in terms of layout and functionality. Their layout contains a TextView at the top to easily distinguish between each Activity. Then they also contain six buttons, each to open one of the Activities when clicked.

Also, in each Activity, I overrode the onNewIntent(...) function and displayed a Toast each time it was called. This function will be important later. An example of what it looks like in ActivityA:

class ActivityA : AppCompatActivity() {
    // ...

    override fun onNewIntent(intent: Intent?) {  
        super.onNewIntent(intent)  
        Toast.makeText(  
            this,  
            "onNewIntent called for Activity A",  
            Toast.LENGTH_LONG,  
        ).show()  
    }
}

Lastly, instead of just renaming MainActivity, I updated the AndroidManifest.xml to make ActivityA the default launched Activity instead of MainActivity.

<manifest ...>  
  ...
<application ...>  
 ...
    <activity  
        android:name=".launchactivities.ActivityA"  
        android:exported="true"  
        <intent-filter>  
            <action android:name="android.intent.action.MAIN" />  

            <category android:name="android.intent.category.LAUNCHER" />  
        </intent-filter>  
    </activity>  
    <activity  
        android:name=".MainActivity"  
        android:exported="true">  
    <!-- <intent-filter>-->  
    <!-- <action android:name="android.intent.action.MAIN" />-->  

    <!-- <category android:name="android.intent.category.LAUNCHER" />-->  
    <!-- </intent-filter>-->  
    </activity>  
</application>  

</manifest>

A Quick Note on a Task's Affinity

Each Activity, whether explicitly defined or not, has an Affinity. For a Task, its Affinity would be the Affinity for the Activity at the root of the Task. This holds even if there are multiple Activities with differing Affinities all in one Task (this is possible if all activities are using the standard Launch Mode that we'll discuss later). For example, say a Task has a Back Stack of the following Activities with Affinities:

A (.MyAffinity) -> B (.MyOtherAffinity) -> C (.YetAnotherAffinity)

Then the Affinity for the task would be .MyAffinity.

An Affinity denotes to Android which Task an Activity prefers to be in. By default, every Activity in an application has the same Affinity. However, there are no hard rules on which Affinity an Activity can have. All Activities in the same application can each have distinct Affinities, and even one Activity from one application can share an Affinity with an Activity from another application.

An Affinity is only one criterion for the OS to determine which Task to place a new Activity in. As we will see later, the Affinity combines with the Launch Mode to ultimately determine the placement of the newly opened Activity.

To set the Affinity of an Activity, you can use the taskAffinity XML attribute for the <activity> tag in the AndroidManifest.xml. If the taskAffinity attribute is not set, then the default Affinity is the value for the namespace property in the build.gradle file.

<manifest ...>  
  ...
<application ...>  
 ...
    <activity  
        android:name=".launchactivities.ActivityB"  
        android:taskAffinity="my.Affinity"
        android:exported="true"   
    </activity>    
</application>  
</manifest>


// build.gradle
android {   
    ...
    // default Affinity value
    namespace = "com.nicholasfragiskatos.androidlaunchmodes"      
}

Valid `taskAffinity` Values

The only rule I could find about appropriate values is from this part of the documentation where it says,

The taskAffinity attribute takes a string value that must be different than the default package name declared in the <manifest> element.

However, I noticed that the value requires a period separator somewhere in the name. Having something like taskAffinity="MyAffinity" causes a build error:

Error running 'app': The application could not be installed: INSTALL_PARSE_FAILED_MANIFEST_MALFORMED

The following values seem to be OK:

.myAffinity
my.Affinity
myAffinity.
..myAffinity
. (yes, just a period)

Viewing Tasks on the System

I could not find a good graphical way to view all running Tasks on an emulator in Android Studio. There were some options, but they appeared to be old and incompatible with modern versions of the IDE. The best alternative I could find is using the Android Debugging Bridge (ADB) on the command line and looking through the output of the following command:

adb shell dumpsys activity recents

This will give you a list of recent Tasks, and show the list of Activities for the Task, as well as the Affinity, among other information. For example: (output formatted and abbreviated)

Recent tasks: Recent #0:{54288a5 #148 type=standard A=10164:.com.nicholasfragiskatos.androidlaunchmodes}

...

affinity=10164:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{50c032f u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t107}, 
ActivityRecord{eca6d90 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t107}, 
ActivityRecord{a3a3a7 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t107}, 
ActivityRecord{419e7d8 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t107}
]

Recent Numbering

The numbering changes based on which Task you viewed most recently. It's best to ignore the number and follow the Task ID (#148 from the example below):

Recent #0:{54288a5 # 148 type=standard A=10164:.com.nicholasfragiskatos.androidlaunchmodes}

Launch Modes

Launch Modes are a way for the user to specify to the system how a new instance of an Activity should be related to the current Task. We can specify a Launch Mode in either the AndroidManifest.xml when defining the Activity to the system or in Intent flags when launching the new Activity. There are five different Launch Modes.

`standard`

For this Launch Mode, a new instance of the Activity is created each time regardless of if there already exists an instance of the Activity in the Task. This is the default behavior. You can have as many of the same instances of an Activity across multiple tasks. For instance, all three of these examples are valid states when using the standard Launch Mode:

In the example project, to demonstrate this, launch ActivityA multiple times.

adb shell dumpsys activity recents output:

Recent tasks:

Recent #0: 

... 

Activities=[ 
ActivityRecord{449ced3 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t114}, 
ActivityRecord{5d70c45 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t114}, 
ActivityRecord{7a9c8d3 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t114}, 
ActivityRecord{948d5c1 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t114}, 
ActivityRecord{bffb7c9 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t114}
]

💡
By default, the new instance of the Activity will be created and placed in the same Task that it was launched from. However, as we will see later, depending on other factors it is not guaranteed.

`singleTop`

This Launch Mode is almost identical to standard. The only difference is that if the Activity you are trying to launch already has an existing instance at the top of the current Task's stack, then instead of creating a new instance, the system will just call the Activity's onNewIntent(...) function.

Considering the example below with the state of the stack being A -> B -> C -> D -> E,¹ if we try and launch E again no new instance of ActivityE is created since it's at the top. Instead, the system re-uses the existing instance and just calls onNewIntent(...).² However, when we try and launch ActivityC again, an instance already exists on the stack, but it's not at the top, so a new instance is created and added to the stack.³

In the example project, to demonstrate this, first, we set the Launch Mode in the manifest for ActivityE:

<manifest>  
    ... 
<application  
    ...
    <activity  
        android:name=".launchactivities.ActivityE"  
        android:launchMode="singleTop"  
        android:exported="false" />  
    ...
    <activity  
        android:name=".launchactivities.ActivityC"  
        android:launchMode="singleTop"  
        android:exported="false" />
</application>  
</manifest>

Then, remember that we overrode the onNewIntent(...) function for each Activity to display a Toast:

override fun onNewIntent(intent: Intent?) {  
    super.onNewIntent(intent)  
    Toast.makeText(  
        this,  
        "onNewIntent called for Activity E",  
        Toast.LENGTH_LONG,  
    ).show()  
}

Starting Activities A -> B -> C -> D -> E -> E will result in the onNewIntent(...) function being called, but no additional instance of ActivityE is being added to the stack.

adb shell dumpsys activity recents output:

Recent tasks:

Recent #0: 

... 

Activities=[ 
ActivityRecord{f04dc64 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t118}, 
ActivityRecord{97af3cc u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t118}, 
ActivityRecord{15ff5c9 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t118}, 
ActivityRecord{6efecbf u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t118}, 
ActivityRecord{5ff0a89 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityE} t118}, 
]

However, starting ActivityC again will result in it being added to the stack.

Recent tasks:

Recent #0: 

... 

Activities=[ 
ActivityRecord{f04dc64 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t118}, 
ActivityRecord{97af3cc u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t118}, 
ActivityRecord{15ff5c9 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t118}, 
ActivityRecord{6efecbf u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t118}, 
ActivityRecord{5ff0a89 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityE} t118}, 
ActivityRecord{582171d u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t118}
]

`singleTask`

With this Launch Mode, the goal for the system is to maintain a single instance of the Activity at a time. The system will either re-use an existing instance of the Activity, create a new task with the Activity at the root of the stack or use an existing Task that shares the same Affinity. The behavior depends on whether there is already an existing instance of the Activity in some Task, and then whether there's a Task with the same Affinity.

Existing Activity

If the system can find an existing instance of the Activity in either the current Task or another Task then the launched Intent will be routed to the existing Activity to re-use it, and the Activity's onNewIntent(...) function is invoked, similar to what happens in singleTop. However, what also happens is that all Activities that are above the re-used Activity will be popped off the stack, leaving the re-used activity back at the top of the stack for the Task.

In the following example, for the original state, we have Task #1 and Task #2. ActivityD is set as singleTask and has .MyAffinity. All other Activities have the standard Launch Mode with the default Affinity.

If we try and start ActivityD again either in Task #1 or Task #2, then the system will find the existing ActivityD instance, and route the Intent there. This will result in all other Activities above it being removed from the stack.

To demonstrate this in the example project, we update the Launch Mode and Affinity in the manifest for ActivityD. Set all other Activities back to standard Launch Mode.

<activity  
    android:name=".launchactivities.ActivityD"  
    android:taskAffinity=".myAffinity"  
    android:launchMode="singleTask"  
    android:exported="false" />

Starting Activities A -> B -> C -> D -> E -> A -> B will get us to the original state from the example above where Task #1 has A -> B -> C in its Back Stack, and Task #2 has D -> E -> A -> B in its stack.

adb shell dumpsys activity recents output:

Recent tasks: 

Recent #0: Task{54288a5 #148 type=standard A=10164:.myAffinity}

...

affinity=10164:.myAffinity

...

Activities=[ 
ActivityRecord{e2e12b1 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t148}, 
ActivityRecord{94e9d35 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityE} t148}, 
ActivityRecord{c8cccf7 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t148}, 
ActivityRecord{a2fb2ef u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t148}]

...

Recent #1: Task{cb4f549 #147 type=standard A=10164:com.nicholasfragiskatos.androidlaunchmodes}

...

affinity=10164:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{9d069aa u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t147}, 
ActivityRecord{53edb1a u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t147}, 
ActivityRecord{aa7fbe u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t147}
]

If we start ActivityD again from either Activity the onNewIntent(...) function will be called for ActivityD and the Activities above it (E, A, B) will be removed from the stack.

adb shell dumpsys activity recents output:

Recent tasks: Recent #0: Task{54288a5 #148 type=standard A=10164:.myAffinity ...

affinity=10164:.myAffinity

...

Activities=[ 
ActivityRecord{e2e12b1 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t148}
]

Activity Does Not Exist - Shared Affinity

If the Activity does not already exist and it shares the same Affinity with a Task, then when it is created for the first time it will be placed at the top of the Back Stack of that Task. Every subsequent Activity that is launched will continue to be added to the stack like normal (assuming the other Activities are using the standard Launch Mode).

In the diagram below, we start with an original state of A -> B -> C.¹ ActivityD has been set as singleTask with the default Affinity. Since the Affinity matches, launching ActivityD will result in ActivityD being placed at the top of the current Task.² We can then add A -> B -> C again.³ If we try and launch ActivityD again, the OS sees that an instance already exists so it routes the Intent to onNewIntent(...) and all Activities above ActivityD are popped off the stack until ActivityD is at the top.⁴

To demonstrate this in the example project, we update the Launch Mode in the manifest for ActivityD. Set all other Activities back to standard Launch Mode.

<activity  
    android:name=".launchactivities.ActivityD"  
    android:launchMode="singleTask"  
    android:exported="false" />

Starting Activities A -> B -> C will get us to the original state in the diagram.

adb shell dumpsys activity recents output:

Recent tasks: Recent #0: Task{ed463cf #170 type=standard A=10164:com.nicholasfragiskatos.androidlaunchmodes}

...

affinity=10164:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{e19f818 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t170}, 
ActivityRecord{36def6e u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t170}, 
ActivityRecord{96afca3 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t170}
]

Starting ActivityD places the Activity in the current Task.

adb shell dumpsys activity recents output:

Recent tasks: Recent #0: Task{ed463cf #170 type=standard A=10164:com.nicholasfragiskatos.androidlaunchmodes}

...

affinity=10164:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{e19f818 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t170}, 
ActivityRecord{36def6e u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t170}, 
ActivityRecord{96afca3 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t170}, 
ActivityRecord{f802a9e u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t170}
]

Starting A -> B -> C again from the new Task will create new instances on the stack above ActivityD.

adb shell dumpsys activity recents output:

Recent tasks: Recent #0: Task{ed463cf #170 type=standard A=10164:com.nicholasfragiskatos.androidlaunchmodes}

...

affinity=10164:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{e19f818 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t170}, 
ActivityRecord{36def6e u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t170}, 
ActivityRecord{96afca3 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t170}, 
ActivityRecord{f802a9e u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t170}, 
ActivityRecord{bacf62a u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t170}, 
ActivityRecord{7f315f6 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t170}, 
ActivityRecord{356f985 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t170}
]

If we start ActivityD again the onNewIntent(...) function will be called for ActivityD and the Activities above it (A, B, C) will be removed from the stack.

adb shell dumpsys activity recents output:

Recent tasks: Recent #0: Task{ed463cf #170 type=standard A=10164:com.nicholasfragiskatos.androidlaunchmodes}

...

affinity=10164:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{e19f818 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t170}, 
ActivityRecord{36def6e u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t170}, 
ActivityRecord{96afca3 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t170}, 
ActivityRecord{f802a9e u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t170}]

Activity Does Not Exist - Different Affinity

If the Activity does not already exist and it does not share the same Affinity with an existing Task, then when it is created for the first time it will be placed at the root of a new Task. Every subsequent Activity that is launched in this new Task will continue to be added to the stack like normal (assuming the other Activities are using the standard Launch Mode).

In the diagram below, we start with one Task using the default Affinity (Task #1) with an original state of A -> B -> C.¹ ActivityD has been set as singleTask with .MyAffinity. Since there is no existing instance of ActivityD, and no Task shares the same Affinity, starting ActivityD will result in a new Task (Task #2) being created and ActivityD being placed at the root.². And of course, from here, we can expect normal behavior. Starting A -> B -> C while in Task #2 will create those Activities and place them on the stack.³ If we try and launch ActivityD again, the OS sees that an instance already exists so it routes the Intent to onNewIntent(...) and all Activities above ActivityD are popped off the stack until ActivityD is at the top.⁴

To demonstrate this in the example project, we update the Launch Mode and Affinity in the manifest for ActivityD. Set all other Activities back to standard Launch Mode.

<activity  
    android:name=".launchactivities.ActivityD"  
    android:taskAffinity=".MyAffinity"  
    android:launchMode="singleTask"  
    android:exported="false" />

Starting Activities A -> B -> C will get us to the original state in the diagram.

adb shell dumpsys activity recents output:

Recent tasks:

Recent #0: Task{1aa5d3a #161 type=standard A=10164:com.nicholasfragiskatos.androidlaunchmodes

...

affinity=10164:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{9fa33e2 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t161}, 
ActivityRecord{1104ae6 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t161}, 
ActivityRecord{a23a934 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t161}
]

Starting ActivityD creates the new Task.

adb shell dumpsys activity recents output:

Recent tasks:

Recent #0: Task{28ea774 #162 type=standard A=10164:.MyAffinity}

...

affinity=10164:.MyAffinity

...

Activities=[ 
ActivityRecord{53ca0ba u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t162}
]

Starting A -> B -> C again from the new Task will create new instances on the stack above ActivityD.

adb shell dumpsys activity recents output:

Recent tasks:

Recent #0: Task{28ea774 #162 type=standard A=10164:.MyAffinity

...

affinity=10164:.MyAffinity

...

Activities=[ 
ActivityRecord{53ca0ba u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t162}, 
ActivityRecord{b15cb2e u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t162}, 
ActivityRecord{31480bf u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t162}, 
ActivityRecord{3de0f78 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t162}
]

And finally, starting ActivityD again will result in onNewIntent(...) being called and the stack is cleared until ActivityD is at the top.

adb shell dumpsys activity recents output:

Recent tasks:

Recent #0: Task{28ea774 #162 type=standard A=10164:.MyAffinity}

...

affinity=10164:.MyAffinity

...

Activities=[ 
ActivityRecord{53ca0ba u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t162}
]

`singleInstance`

This Launch Mode is similar to singleTask in a few ways:

The system maintains a single instance of the Activity at a time
Creating an instance of a singleInstance Activity will always create a new Task if there is no existing instance already in the system.
If an existing instance of the singleInstance Activity already exists, then it is re-used and its onNewIntent(...) function is invoked.

There's no need to go over the similarities again, but there is one important difference; an Activity with singleInstance will always be the only Activity in a Task. This means that any other Activity launched by the singleInstance Activity will always be placed in a different Task.

In the diagram below, we start with one Task (Task #1) with an original state of A -> B -> C.¹ ActivityD has been set as singleInstance. Since no existing instance of ActivityD exists starting ActivityD will result in a new Task (Task #2) being created and ActivityD being placed at the root.². Starting E -> F while in Task #2 will create the Activities in Task #1.³

To demonstrate this in the example project, we update the Launch Mode and Affinity in the manifest for ActivityD. Set all other Activities back to standard Launch Mode.

<activity  
    android:name=".launchactivities.ActivityD"  
    android:taskAffinity=".MyAffinity"  
    android:launchMode="singleInstance"  
    android:exported="false" />

Starting Activities A -> B -> C will get us to the original state in the diagram.

adb shell dumpsys activity recents output:

Recent tasks:

Recent #0: Task{513838 #184 type=standard A=10164:com.nicholasfragiskatos.androidlaunchmodes}

...

affinity=10164:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{1722f24 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t184}, 
ActivityRecord{dc1435 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t184}, 
ActivityRecord{2327270 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t184}
]

Starting ActivityD creates the new Task.

adb shell dumpsys activity recents output:

Recent tasks:

Recent #0: Task{5194c82 #185 type=standard A=10164:.MyAffinity}

...

affinity=10164:.MyAffinity

...

Activities=[ 
ActivityRecord{34baff u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD} t185}
]

Starting E -> F in the new Task will create new instances in the original Task.

adb shell dumpsys activity recents output:

Recent tasks:

Recent #0: Task{513838 #184 type=standard A=10164:com.nicholasfragiskatos.androidlaunchmodes

...

affinity=10164:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{1722f24 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA} t184}, 
ActivityRecord{dc1435 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB} t184}, 
ActivityRecord{2327270 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC} t184}, 
ActivityRecord{628a66 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityE} t184}, 
ActivityRecord{dfb1fee u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityF} t184}
]

`singleInstancePerTask`

The last Launch Mode is similar to both singleTask and singleInstance in a few ways:

Like singleInstance, the new Activity will always be created in a new Task if there is no existing instance regardless of Affinity.
Like singleTask, other Activities can exist within the Task.
Like singleTask, if the singleInstancePerTask Activity is already a member of a Task, and if we try and launch the Activity again, then all Activities above it in the stack will be removed.

Both the singleTask and the singleInstance Launch Mode shared the singleton property, in which the system will always maintain only a single instance of the Activity at a time across all Tasks. Unlike the latter, it is possible for the singleInstancePerTask Activity to be started in multiple Tasks while still maintaining only one instance per Task. This behavior is possible through the use of the FLAG_ACTIVITY_MULTIPLE_TASK, or FLAG_ACTIVITY_NEW_DOCUMENT Intent flags. This article only covers Launch Modes as defined through the manifest, but I thought it important enough to mention.

Sharing Affinity

For the singleInstancePerTask Launch Mode, the Activity will always be created in a new Task if there is no existing instance, regardless of Affinity. This holds even with matching Affinities, but the behavior is a little different.

Typically, when a new Task has been launched a new window shows up in the app switcher on the device, like the screenshot below:

However, if we try and launch a singleInstancePerTask Activity and there's an existing Task that shares the same Affinity then the system hides the original Task, and we only see one entry in the app switcher.

In the diagram below we start with one Task (Task #1) with an original state of A -> B.¹ ActivityE is started using the singleInstancePerTask Launch Mode and .MyAffinity which results in a Task #2 being created.² ActivityF is started using the singleInstancePerTask Launch Mode and .MyOtherAffinity which results in Task #3 being created.³ ActivityA and ActivityB are started in Task #2 and placed on the top of the stack.⁴ Next, ActivityD is started using singleInstancePerTask and .MyAffinity which results in Task #4 being created. Since Task #2 is also already using .MyAffinity, Task #2 is hidden.⁵ Lastly, ActivityC is started using singleInstancePerTask and the default Affinity which results in Task #5 being created. Since Task #1 is also using the default Affinity, Task #1 is hidden.⁶

To replicate this in the example project start by setting ActivityC, ActivityD, ActivityE, and ActivityF as follows:

<activity  
    android:name=".launchactivities.ActivityF"  
    android:taskAffinity=".MyOtherAffinity"  
    android:launchMode="singleInstancePerTask"  
    android:exported="false" />  
<activity  
    android:name=".launchactivities.ActivityE"  
    android:taskAffinity=".MyAffinity"  
    android:launchMode="singleInstancePerTask"  
    android:exported="false" />  
<activity  
    android:name=".launchactivities.ActivityD"  
    android:taskAffinity=".MyAffinity"  
    android:launchMode="singleInstancePerTask"  
    android:exported="false" />  
<activity  
    android:name=".launchactivities.ActivityC"  
    android:launchMode="singleInstancePerTask"  
    android:exported="false" />

Starting Activities A -> B will get us to the original state in the diagram.

adb shell dumpsys activity recents output:

Recent tasks:

Recent #0: Task{5936bd5 #103 type=standard A=10193:com.nicholasfragiskatos.androidlaunchmodes

...

affinity=10193:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{68ab88c u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA t103}, 
ActivityRecord{aa8eee0 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB t103}
]

Then after launching ActivityE and ActivityF we have 3 tasks total.

adb shell dumpsys activity recents output: Recent tasks:

Recent #0: Task{d80e152 #105 type=standard A=10193:.MyOtherAffinity

...

affinity=10193:.MyOtherAffinity

...

Activities=[ 
ActivityRecord{f68d1dd u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityF t105} 
]

Recent #1: Task{ba9599a #104 type=standard A=10193:.MyAffinity}

...

affinity=10193:.MyAffinity

...

Activities=[ 
ActivityRecord{7d25e45 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityE t104} 
]

Recent #2: Task{5936bd5 #103 type=standard A=10193:com.nicholasfragiskatos.androidlaunchmodes

...

affinity=10193:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{68ab88c u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityA t103}, 
ActivityRecord{aa8eee0 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityB t103}
]

After launching ActivityD we see a new Task created, as expected, to house ActivityD. We also notice that the previous Task with .MyAffinity (id=104, has ActivityE) is no longer in the recent Task list, but it does show up in an extra line above the recent tasks list as part of an mHiddenTasks output value.

adb shell dumpsys activity recents output: Recent tasks:

mHiddenTasks=[
Task{ba9599a #104 type=standard A=10193:.MyAffinity}
]

Recent tasks:

Recent #0: Task{4a12fcd #106 type=standard A=10193:.MyAffinity

...

affinity=10193:.MyAffinity

...

Activities=[ 
ActivityRecord{815b164 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityD t106}
]

Likewise, after launching ActivityC, a new singleInstancePerTask Activity is created with the default Affinity, and now the previous Task with the default Affinity (id=103) is added to the hidden Task list.

adb shell dumpsys activity recents output: Recent tasks:

mHiddenTasks=[
Task{ba9599a #104 type=standard A=10193:.MyAffinity}, 
Task{5936bd5 #103 type=standard A=10193:com.nicholasfragiskatos.androidlaunchmodes}
]

Recent tasks:

Recent #0: Task{5ece29 #107 type=standard A=10193:com.nicholasfragiskatos.androidlaunchmodes}

...

affinity=10193:com.nicholasfragiskatos.androidlaunchmodes

...

Activities=[ 
ActivityRecord{2bf9fb0 u0 com.nicholasfragiskatos.androidlaunchmodes/.launchactivities.ActivityC t107}
]

Conclusion

The Android framework allows the developer to customize how the system manages the relationships between Activities, Tasks, and its Back Stack.

The main goal of this article was to review how we can utilize different Launch Modes to manipulate the Task-Activity relationship, but before that, we needed to lay down some groundwork. First we learned about Tasks and Affinities, and how they are related to Activities. Then we learned what an Affinity is and how manipulating an Activity's Affinity can alter how an Activity associates with a particular Task. Lastly, to help facilitate our understanding we utilized ADB to show the current state of Tasks on a device.

With the groundwork in place, we were able to dive into manipulating an Activity's Launch Mode in its manifest declaration. Each <activity> tag supports a launchMode attribute that has five different valid values: standard, singleTop, singleTask, singleInstance, and singleInstancePerTask. We studied each Launch Mode in detail and saw how they behave in theory and in a real demo application. While many of the Launch Modes shared behavior with one or more of the other Launch Modes, they all provided their own unique behavior.

If you noticed anything in the article that is incorrect or isn't clear, please let me know. I always appreciate the feedback.

Starting Activities for Results in Android

Nicholas Fragiskatos — Tue, 24 Oct 2023 20:53:42 +0000

There are many situations in Android where we need to start a second activity from the current activity or fragment. This second activity could either be another internal activity as defined by your application, or it could be from some external application that we can leverage to do something such as take a picture, choose from a list of contacts, or view something in Google Maps.

Furthermore, it's very likely that when we want to leverage some other application's functionality we also want that other application to provide us with a result. Luckily, Android provides us with a mechanism for receiving information back from other activities.

In this article, I want to go over the two different approaches that are available to us to solve this issue: one is the original, but deprecated approach, and the other is the modern approach.

I will provide small code snippets where needed, but the full sample project can be found here on GitHub

💡
Both solutions are available in activities and fragments. However, for brevity, I'll just be referencing activities.

Project Setup

To start, I created a brand new project using Android Studio's "Empty Views Activity" template. Then along with the provided MainActivity I added a SecondActivity

I added one button to the layout of MainActivity that when clicked will open SecondActivity. In the layout of SecondActivity I have a TextView to display any input passed from MainActivity, an EditText to input a result to send back to MainActivity, and lastly a Button that when clicked will finish the activity and return the result.

MainActivity:

SecondActivity:

The Legacy Approach

The legacy solution is simple enough to implement, and it revolves around two key functions: startActivityForResult(...), and onActivityResult(...). Both are provided by the activity's parent class.

Starting `SecondActivity` with an Input

In MainActivity, I implemented a click listener for the button:

binding.btnStartSecondActivityOld.setOnClickListener {  
    startSecondActivityForResultUsingOldWay()  
}

private fun startSecondActivityForResultUsingOldWay() {  
    val intent = Intent(this, SecondActivity::class.java).putExtra(  
        MAIN_ACTIVITY_BUNDLE_ID,  
        "Input From Main Activity Old Way"  
    )  

    startActivityForResult(  
        intent,  
        MAIN_ACTIVITY_REQUEST_CODE  
    )  
}

First, I create an Intent that specifies the current context and the name of the activity's class I wish to start. Also, I used putExtra to store a String in the Bundle of the Intent, which will be accessible to SecondActivity as input. Then once I have the Intent created, all I have to do is call startActivityForResult(...) passing along the Intent and a request code.

💡
The request code can be anything. It can be used to keep track of different requests if you expect to be dealing with multiple requests.

Handling Input and Returning a Result

In SecondActivity.onCreate(...), I first retrieve the input from the Bundle of the Intent and display it. Then I add a click-listener to the button that when fired will return the result. The click listener creates its own Intent to bundle the return data. Then it calls setResult(...) to send the Intent and a result code back to MainActivity. Lastly, it calls finish() to end the activity.

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

    val inputFromMainActivity = intent.getStringExtra(MainActivity.MAIN_ACTIVITY_BUNDLE_ID)  

    binding.tvInput.text = inputFromMainActivity

    binding.btnSendResult.setOnClickListener {  
        val result = binding.etResult.text.toString()  
        val intent = Intent().putExtra(SECOND_ACTIVITY_BUNDLE_ID, result)  
        setResult(SECOND_ACTIVITY_RESULT_CODE, intent)  
        finish()  
    }
}

💡
Much like the request code, the result code can also be any integer. For convenience, the Activity class already has some predefined constants, like Activity.RESULT_OK.

Handling the Result

To process the result back in MainActivity we override the onActivityResult(...) function. onActivityResult(...) has arguments for a request code and a result code so you can uniquely handle each result based on where it came from. It also has an Intent argument which stores the returned result.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {  
    super.onActivityResult(requestCode, resultCode, data)  

    if (requestCode == MAIN_ACTIVITY_REQUEST_CODE && resultCode == SecondActivity.SECOND_ACTIVITY_RESULT_CODE) {  
        data?.getStringExtra(SecondActivity.SECOND_ACTIVITY_BUNDLE_ID)?.let {  
            Toast.makeText(this, "Got Result: $it", Toast.LENGTH_SHORT).show()  
        }  
    }  
}

Limitations

This seems straightforward enough to implement, so why would this be deprecated?

One problem is that since the request code is just an integer there is a possibility of duplication between two unrelated requests, or even the wrong integer value being used by mistake which could lead to confusing behavior. A way to circumvent these issues is to define a library of request code constants for each type of request, but that is still not ideal if there are many codes to manage.

A similar issue is that onActivityResult(...) is a single function that has to handle all requests. Depending on the number of requests, this function could just turn into one large, messy switch statement.

The New Activity Result API

The new Activity Result API centers on three new classes: ActivityResultContract, ActivityResultCallback, and ActivityResultLauncher. These three classes are used in the registerForActivityResult(...) function, which is provided to us by the activity or fragment.

@NonNull   
public final <I, O> ActivityResultLauncher<I> registerForActivityResult(  
    @NonNull ActivityResultContract<I, O> contract,  
    @NonNull ActivityResultCallback<O> callback
)

As the name implies, registerForActivityResult(...) will register your callback, but it will not launch anything. That is the responsibility of the ActivityResultLauncher object that registerForActivityResult(...) returns. We can use the ActivityResultLauncher wherever in our code we are ready to launch the request.

The first argument we need to pass registerForActivityResult(...) is an instance of an ActivityResultContract. This contract is essentially a way to define the input and output for the request in a type-safe way. We'll look more into the details of contracts in a later section when we implement our own. Luckily, there's an existing ActivityResultContracts class (notice the additional 's' on the end) that contains several prebuilt contracts to use.

Finally, the last piece is the ActivityResultCallback argument. This is what is called when the result is ready to be returned. The callback is given the type of result as defined by the output of the contract.

Implementation

First, I defined a top-level ActivityResultLauncher property for the MainActivity class.

private val startSecondActivityForResultLauncher: ActivityResultLauncher<Intent> = 
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { activityResult: ActivityResult ->  
        if (activityResult.resultCode == SecondActivity.SECOND_ACTIVITY_RESULT_CODE) {
            activityResult.data?.getStringExtra(SecondActivity.SECOND_ACTIVITY_BUNDLE_ID)?.let {  
                Toast.makeText(this, "Got Result: $it", Toast.LENGTH_SHORT).show()  
            }  
        }  
    }

For the contract, I am passing the prebuilt StartActivityForResult contract, which defines an Intent as an input and an ActivityResult as the output.

Therefore, in the callback function, I can take the ActivityResult, do some code comparisons and then grab the data from the bundle just like in onActivityResult(...) from the legacy approach.

For the UI I add another button to my view and then define an on-click to launch the request:

<Button  
    android:id="@+id/btnStartSecondActivityNew"  
    android:layout_width="wrap_content"  
    android:layout_height="wrap_content"  
    android:text="Start SecondActivity (new)"  
    app:layout_constraintEnd_toEndOf="parent"  
    app:layout_constraintStart_toStartOf="parent"  
    app:layout_constraintTop_toBottomOf="@+id/btnStartSecondActivityOld" 
/>

binding.btnStartSecondActivityNew.setOnClickListener {  
    startSecondActivityUsingNewApi()  
}

private fun startSecondActivityUsingNewApi() {  
    val intent = Intent(  
        this,  
        SecondActivity::class.java  
    ).putExtra(  
        MAIN_ACTIVITY_BUNDLE_ID,  
        "Input From Main Activity New API"  
    )  
    startSecondActivityForResultLauncher.launch(intent)
}

Since the StartActivityForResult contract takes an Intent as an input, I create one in the same way that I did when calling startActivityForResult(...) for the legacy approach. The Intent defines the context, the activity class to start, as well as some input String value. Then it's as simple as calling the launch(...) function on our ActivityResultLauncher object and passing in the Intent as input.

Benefits

This approach provides us with a few very nice benefits over the deprecated approach:

We no longer have to worry about request code handling and maintenance. Each separate request that's launched has its own callback. We are no longer limited to one callback function (onActivityResult(...)) handling all requests.
Because we are using the ActivityResultContract class, we get the convenience of a strongly typed input and output.
ActivityResultContract also wraps up some of the boilerplate code for managing the input and output of the request. We will see in the next section that if we create our own custom contract we can move even more input and output logic into the contract.

Activity Result API with a Custom Contract

Creating our own custom contract involves implementing two functions from ActivityResultContract: one to define how our input is processed and one to define how the output is processed.

abstract class ActivityResultContract<I, O> {
    abstract fun createIntent(context: Context, input: I): Intent

    abstract fun parseResult(resultCode: Int, intent: Intent?): O
}

You'll notice that for the implementation, all we are doing is moving some code from the activity into these functions. In createIntent(...) I'm creating the same intent as before. Then in parseResult(...) I'm doing the same result code checks and getting the result from the Bundle as before.

class MyCustomContract : ActivityResultContract<String, String?>() {  
    override fun createIntent(context: Context, input: String): Intent {  
        val intent = Intent(  
            context,  
            SecondActivity::class.java  
        ).putExtra(  
            MAIN_ACTIVITY_BUNDLE_ID,  
            input  
        )
        return intent
    }  

    override fun parseResult(resultCode: Int, intent: Intent?): String? {  
        if (resultCode == SecondActivity.SECOND_ACTIVITY_RESULT_CODE) {  
            intent?.getStringExtra(SecondActivity.SECOND_ACTIVITY_BUNDLE_ID)?.let {  
                return it  
            }  
        }  
        return null  
    }   
}

Now that I have my custom contract I can go ahead and define another top level ActivityResultLauncher property for the MainActivity class. Notice that now I don't have to handle any result code checking in the callback since I handle all of that in MyCustomContract.parseResult(...) instead.

private val startSecondActivityCustomContractLauncher =
        registerForActivityResult(MyCustomContract()) { result: String? ->
            result?.let {
                Toast.makeText(this, "Got Result: $it", Toast.LENGTH_SHORT).show()
            }
        }

I again updated the UI with another button and click listener. Similarly to the simplified callback definition, the launch call is also simplified since all I have to do is pass the input and MyCustomContract.createIntent(...) handles any Intent building logic.

<Button  
    android:id="@+id/btnStartSecondActivityCustomContract"  
    android:layout_width="wrap_content"  
    android:layout_height="wrap_content"  
    android:text="Start SecondActivity (Custom Contract)"  
    app:layout_constraintEnd_toEndOf="parent"  
    app:layout_constraintStart_toStartOf="parent"  
    app:layout_constraintTop_toBottomOf="@+id/btnStartSecondActivityNew" 
/>

binding.btnStartSecondActivityCustomContract.setOnClickListener {  
    startSecondActivityCustomContractLauncher.launch("Custom Contract Input")  
}

Conclusion

The Activity Result API provides us with a safer and more convenient way of launching activities that are expected to return some result.

We first looked at the old approach and its straightforward implementation. However, although it works well for simple cases, it can get messy for complex cases where we need to handle many different requests. Managing request code uniqueness, and having one large callback function to handle all requests is less than ideal from a maintainability standpoint.

We then explored how to utilize ActivityResultContract, ActivityResultCallback, ActivityResultLauncher, and registerForActivityResult(...) from the Activity Result API. This implementation removed the need for request code handling, brought us type safety, and cleaned up the code by allowing for individual callbacks for each request type.

Lastly, we looked at how to create our own ActivityResultContract implementation. By rolling our own, we were able to further clean up the code in the activity by moving the intent creation and much of the result handling into the contract.

If you noticed anything in the article that is incorrect or isn't clear, please let me know. I always appreciate the feedback.

Function Types with Receivers in Kotlin - The Power Behind Kotlin's apply, with, and run Scope Functions

Nicholas Fragiskatos — Wed, 18 Oct 2023 04:12:30 +0000

When we invoke one of Kotlin's Scope functions (apply, run, let, also, or with) a temporary scope/context is created for the object, and you can access the object without its name. Depending on the function you can reference the context object using either it, or implicitly with this.

The apply, run, and with functions provide the context object with this, and most interestingly, as a result, they let you define your function block as if it were a native member of the object's type.

For example, consider the following:

val myList = mutableListOf("Ron", "Leslie", "Ben", "Ann")  

myList.apply {  
    add("Chris")  
    remove("Ron")  
}

println("[${myList.joinToString(", ")}]")

// Output: ["Leslie", "Ben", "Ann", "Chris"]

add and remove are both functions as defined by the MutableList interface, but because of the lambda's implicit this context, we can reference them without any qualifiers. Unlike if using let, for example. However, even with let, we can achieve the same outcome:

val myList = mutableListOf("Ron", "Leslie", "Ben", "Ann") 

myList.let {  
    it.add("Chris")  
    it.remove("Ron")  
}

println("[${myList.joinToString(", ")}]")

// Output: ["Leslie", "Ben", "Ann", "Chris"]

We can take a look at the definition of the apply function and see it's very short. The real functionality that we are interested in lies in the function's argument, and the last two lines.

@kotlin.internal.InlineOnly  
public inline fun <T> T.apply(block: T.() -> Unit): T {  
    contract {  
        callsInPlace(block, InvocationKind.EXACTLY_ONCE)  
    }  
    block()  
    return this  
}

💡

We can disregard thecontract{}block. That's a Kotlin feature that allows the developer to share some extra metadata with the compiler.Here is a good blog post about it. For this discussion about Function Types with Receivers, it's not necessary.

From just naively using the apply function, we know that it runs some block of code that we pass to it and that block of code is within the this context, and lastly the apply function returns the context object itself as a result.

That's exactly what we see happening in the last two lines of the function. There's an invocation of block, which is the functional parameter passed by the caller, and then finally it just returns this.

However, block doesn't seem to be a regular functional parameter. We notice that its type is a little different. It looks more like an Extension Function

block: T.() -> Unit

The parameter is similar but not quite an extension function. It is instead a Function Type with a Receiver. Let's dive deeper into what that means by first starting with breaking this feature down into its two key parts, function types and receivers.

Function Types

Just like variables, functions in Kotlin can also have a type. A function type uses special notation that defines the function's arguments and return type. Function types have the following general template:

(A, B, C,...) -> Z

This is a type that represents a function with arguments of types A, B, C, etc. and returns a value of type Z.

Some concrete examples:

() -> Unit, a function that takes no arguments, and returns nothing.
(String) -> Int, a function that takes a String argument and returns an Int.
((Char) -> Unit) -> Unit, a higher-order function that takes a function as an argument and returns nothing.

Kotlin, like many other programming languages, treats functions as first-class citizens. This means you can use a function in the same ways you would use any other type: assigning functions to variables, passing them as arguments to other functions (higher-order functions), and even returning a function as a result of another function.

Kotlin provides us with a good bit of freedom with how we can define an implementation of a function type. No matter which way it is defined it can still be used in a higher-order function and it will provide the same results.

As an example, let's take a look at the filter function that we have access to when working with a Collection. When we call filter all we must do is make sure to provide it with a function type that accepts an argument of type T and returns a boolean.

public inline fun <T> Iterable<T>.filter(predicate: (T) -> Boolean): List<T> {  
    return filterTo(ArrayList<T>(), predicate)  
}

Here are the different ways we can satisfy this functional argument when invoking filter.

Lambda Functions

Lambda functions allow the developer to quickly and conveniently define an implementation for a functional argument when invoking a higher-order function without first having to define it elsewhere. This is probably the most common way of invoking functions with a functional argument.

val myList = mutableListOf("Ron", "Leslie", "Ben", "Anne", "Chris")

val filterByLambda: List<String> = myList.filter { str: String ->  
    str.isNotBlank() && str.length > 4  
} 

println("filterByLambda: [${filterByLambda.joinToString(", ")}]")

// Output: 
// filterByLambda: ["Leslie", "Chris"]

Anonymous Functions

Anonymous functions are similar to lambda functions but with different syntax.

val myList = mutableListOf("Ron", "Leslie", "Ben", "Anne", "Chris")

val filterByAnonymous: List<String> = myList.filter(fun(str): Boolean {  
    return str.isNotBlank() && str.length > 4  
})  

println("filterByAnonymous: [${filterByAnonymous.joinToString(", ")}]")

// Output: 
// filterByAnonymous: ["Leslie", "Chris"]

Function Variables

We can also store a function literal inside a variable with a matching function type. Then you just pass that variable to the function like you would any other argument.

val myList = mutableListOf("Ron", "Leslie", "Ben", "Anne", "Chris")

val myFilterFunctionVariable: (String) -> Boolean = { str: String ->  
    str.isNotBlank() && str.length > 4  
}  

val filterByFunctionVariable: List<String> = myList.filter(myFilterFunctionVariable)  

println("filterByFunctionVariable: [${filterByFunctionVariable.joinToString(", ")}]")

// Output: 
// filterByFunctionVariable: ["Leslie", "Chris"]

Function Declarations to Function Types

Lastly, we can take an existing, traditional declaration of a function and use the member reference operator (::) to create an instance of a function type from the declaration.

val myList = mutableListOf("Ron", "Leslie", "Ben", "Anne", "Chris")

fun myFilterPredicate(str: String) : Boolean {  
    return str.isNotBlank() && str.length > 4  
}

val filterByNamedFunction: List<String> = myList.filter(::myFilterPredicate)  

println("filterByNamedFunction: [${filterByNamedFunction.joinToString(", ")}]")

// Output: 
// filterByNamedFunction: ["Leslie", "Chris"]

Receivers

Receivers are something we use all the time, but we just don't think about it. Essentially, any time you are using dot notation to reference some member function for a specific instance of an object, you are using a receiver. For example, if we have myObj.someFunction(), myObj is considered the receiver of the function call someFunction.

Each receiver has its own context and within that context this references that specific object instance. Furthermore, inside a class, any reference to a member property or function always has an implicit this attached to it. Although, for syntax convenience, we never have to type it.

Now consider the following:

class MyCustomObject(val id: String) {

    fun getFormattedId() : String {
        return "MyCustomObject-${id}" // (implicit this reference for id)
        // or equivalently
        // return "MyCustomObject-${this.id}" (explicit this reference)
    }
}

val pawnee = MyCustomObject("Pawnee")
val eagleton = MyCustomObject("Eagleton")

println(pawnee.getFormattedId()) // prints MyCustomObject-Pawnee
println(eagleton.getFormattedId()) // prints MyCustomObject-Eagleton

When we have pawnee.getFormattedId(), the pawnee instance variable is considered the receiver of the function call getFormattedId and this.id points to "Pawnee". Likewise, when we have eagleton.getFormattedId(), the eagleton instance variable is now the receiver of that function call and this.id points to "Eagleton". This is how the getFormattedId function knows which id to get.

Function Types with Receivers

As we discussed earlier, (A) -> B denotes a function type for a function that has one argument of type A and has a return value of type B. Optionally, a function type can also have a receiver type, which is defined with the following form:

R.(A) -> B

This represents a function that has one argument of type A and has a return value of type B, as before, but additionally is called on a receiver type R.

Here is an example of a function that has a receiver with type String, an argument with type String, and that returns a type Boolean:

val isLonger : String.(String) -> Boolean = { other: String ->  
    this.length > other.length  
}

We can then invoke this function by prepending a receiver to the function, similarly to how we invoke any other object's function:

val result1_a: Boolean = "Leslie".isLonger("Anne")
val ben = "Ben"
val result2_a: Boolean = ben.isLonger("Chris")

println("Is Longer, Result1: $result1_a") // true  
println("Is Longer, Result2: $result2_a") // false

We can also invoke a function type with a receiver without prepending the receiver, but instead, pass the receiver as the first argument to the function:

val ben = "Ben"
val result1_b = isLonger("Leslie", "Anne")  
val result2_b: Boolean = isLonger(ben, "Chris")  

println("Is Longer, Result1_b: $result1_b") // true
println("Is Longer, Result2_b: $result2_b") // false

val result1_c = isLonger.invoke("Leslie", "Anne")  
val result2_c: Boolean = isLonger.invoke(ben, "Chris")  

println("Is Longer, Result1_c: $result1_c") // true
println("Is Longer, Result2_c: $result2_c") // false

The Comparison to Extension Functions

Extension functions are full static function declarations with one implementation. When we create an extension function, the class isn't modified but instead the actual code compiles to a static function declaration. For example, when we define an extension function like:

fun String.countNumberOfVowels() : Int {  
    val vowels: Set<Char> = setOf('a', 'e', 'i', 'o', 'u', 'A', 'E', 'I', 'O', 'U')  
    var count = 0  

    for (char in this) {  
        if (char in vowels) {  
            ++count  
        }  
    } return count  
}

val vowels = "Hello, World".countNumberOfVowels()

The extension function definition and usage are syntactic sugar, and what the extension function ultimately gets resolved to is:

fun countNumberOfVowels(word: String) : Int {  
    val vowels: Set<Char> = setOf('a', 'e', 'i', 'o', 'u', 'A', 'E', 'I', 'O', 'U')  
    var count = 0  

    for (char in word) {  
        if (char in vowels) {  
            ++count  
        }  
    } return count  
}

val vowels = countNumberOfVowels("Hello, World")

In fact, if you try and define both of these functions in the same package you will receive a build error:

Kotlin: Platform declaration clash: The following declarations have the same JVM signature (countNumberOfVowels(Ljava/lang/String;)I):

fun countNumberOfVowels(word: String): Int defined in root package

fun String.countNumberOfVowels(): Int defined in root package

Similarities

Extension functions and function types with receivers are the same in that they are largely just syntactic sugar, and they both achieve the same thing:

Extending the functionality of a class without actually modifying the class.
Providing a this scope within the function literal so the user can implement the function literal as if it were a native member of the class.

Differences

Extension functions are function declarations, and as the name implies, function types with receivers are just types, like any other type. In the case of higher-order functions, the type's implementation only gets defined when called.
We saw earlier that a function type with a receiver can be invoked with and without specifying the receiver.
Extension functions are a way to avoid having to resort to either inheritance, the decorator design pattern, or defining and using a bunch of util classes when extending a class' functionality. Function types with receivers are more concerned about making life easier when working with higher-order functions.

Conclusion

Function types with receivers are a powerful feature and a key part of how Kotlin's apply, with, and run scope functions work. It's a feature that allows for greater convenience and code clarity when developing in Kotlin.

To fully understand this feature, we dove deeper into smaller concepts like function types (learning how to define and use them), as well as receivers (what they are and how they fit together with function types). Lastly, we looked at how a function type with a receiver compares to and contrasts with an extension function.

If you noticed anything in the article that is incorrect or isn't clear, please let me know. I always appreciate the feedback.

DEV Community: Nicholas Fragiskatos

How to Use Memoization in React for Better Performance

React.memo(...)

The Problem

The Solution

The Comparator Function

useCallback(...)

The Problem

The Solution

useMemo(...)

The Problem

The Solution

Over Optimization

Conclusion

Git Reset Modes

Important Background

Working Directory

Repository

HEAD

Index

Putting the Pieces Together

The File Lifecycle

The Reset Command

Soft Reset

Example - Setup Commands

Example - Setup State

Example - Soft Reset to Commit C

Mixed Reset

Example - Setup Commands

Example - Setup State

Example - Mixed Reset to Commit C

Hard Reset

Example - Setup Commands

Example - Setup State

Example - Hard Reset to Commit C

Conclusion

Saving Simple Data in Android - SharedPreferences and DataStore APIs

Project Setup

Saved Data File Locations

SharedPreferences API

Creating and Retrieving a Shared Preference File

Writing Data

apply() vs commit()

Reading Data

DataStore

Viewing DataStore Files

Preferences DataStore

Defining Keys for Values

Writing Data

Reading Data

Proto DataStore

Writing Data

Reading Data

Conclusion

Object Relationships in Room ORM Library for Android

@Embedded Annotation

Pros and Cons

Type Converters

Pros and Cons

Intermediate Models

One-to-One Relationship

Foreign Key Constraint

One-to-Many Relationship

Many-to-Many Relationship

Conclusion

Launch Modes in Android - with Examples

Project Setup

A Quick Note on a Task's Affinity

Valid taskAffinity Values

Viewing Tasks on the System

Recent Numbering

Launch Modes

standard

singleTop

singleTask

Existing Activity

Activity Does Not Exist - Shared Affinity

Activity Does Not Exist - Different Affinity

singleInstance

singleInstancePerTask

`React.memo(...)`

`useCallback(...)`

`useMemo(...)`

`apply()` vs `commit()`

`@Embedded` Annotation

Valid `taskAffinity` Values

`standard`

`singleTop`

`singleTask`

`singleInstance`

`singleInstancePerTask`

Starting `SecondActivity` with an Input