Preferences DataStore を使用する

1. はじめに

DataStore とは

DataStore は、SharedPreferences に代わるものとして改善された新しいデータ ストレージ ソリューションです。Kotlin のコルーチンと Flow に基づいて構築された DataStore には、次の 2 種類の実装があります。プロトコル バッファに基づく型付きオブジェクトを保存する Proto DataStore と、Key-Value ペアを保存する Preferences DataStore です。データは、非同期で、一貫性を持ち、トランザクションとして保存されるため、SharedPreferences の欠点の一部が解消されます。

学習内容

  • DataStore の概要と使用すべき理由。
  • DataStore をプロジェクトに追加する方法。
  • Preferences DataStore と Proto DataStore の違い、およびそれぞれの利点。
  • Preferences DataStore の使用方法。
  • SharedPreferences から Preferences DataStore に移行する方法。

作業内容

この Codelab で使用するサンプルアプリでは、完了したステータスでフィルタリングでき、優先度と期限で並べ替えができるタスクのリストを表示します。

fcb2ffa4e6b77f33.gif

[Show completed tasks] フィルタのブール値フラグはメモリに保存されます。並べ替え順序は、SharedPreferences オブジェクトを使用してディスクに引き継がれます。

この Codelab では、次のタスクを完了して、Preferences DataStore の使用方法を確認します。

  • 完了ステータスのフィルタを DataStore に引き継ぐ。
  • 並べ替え順序を SharedPreferences から DataStore に移行する。

両者の違いを理解するために、Proto DataStore Codelab も使用してみることをおすすめします。

必要なもの

アーキテクチャ コンポーネントの概要については、Room と View の Codelab をご覧ください。Flow の概要については、Kotlin Flow と LiveData による高度なコルーチンの Codelab をご覧ください。

2. 設定方法

このステップでは、Codelab 全体のコードをダウンロードし、その後、簡単なサンプルアプリを実行します。

できるだけすぐに開始できるように、たたき台として利用できるスターター プロジェクトを用意しています。

git がインストールされている場合は、以下のコマンドをそのまま実行できます。git がインストールされているかどうかを確認するには、ターミナルまたはコマンドラインで「git --version」と入力し、正しく実行されることを確認します。

 git clone https://github.com/googlecodelabs/android-datastore

初期状態は master ブランチにあります。解答コードは preferences_datastore ブランチにあります。

git がない場合は、次のボタンをクリックして、この Codelab のすべてのコードをダウンロードできます。

ソースコードをダウンロード

  1. コードの ZIP ファイルを展開し、プロジェクトを Android Studio Arctic Fox で開きます。
  2. デバイスまたはエミュレータでアプリ実行構成を実行します。

b3c0dfdb92dfed77.png

アプリが実行され、タスクのリストが表示されます。

d3972939a2de88ba.png

3.プロジェクト概要

このアプリで、タスクのリストを表示できます。各タスクには、名前、完了ステータス、優先度、期限というプロパティがあります。

作業に必要なコードを簡素化するため、アプリで実施可能な作業は次の 2 つのみとします。

  • 完了したタスクの公開設定を切り替える - デフォルトでは、タスクは非表示になります
  • タスクを優先度、期限、または期限および優先度で並べ替える

アプリは、アプリ アーキテクチャ ガイドで推奨されているアーキテクチャに沿って実行されます。各パッケージの内容を以下に示します。

data

  • Task モデルクラス
  • TasksRepository クラス - タスクを提供します。わかりやすくするために、ハードコードされたデータを返し、それを Flow を介して公開することで、より現実的なシナリオを再現しています。
  • UserPreferencesRepository クラス - enum として定義された SortOrder を保持します。列挙値名に基づいて、現在の並べ替え順が String として SharedPreferences に保存されます。これにより、並べ替え順を保存および取得する同期メソッドが公開されます。

ui

  • RecyclerView を使用した Activity の表示に関するクラス。
  • TasksViewModel クラスは、UI ロジックに関与しています。

TasksViewModel - UI に表示される必要があるデータの構築に必要なすべての要素(タスクのリスト、showCompleted フラグ、sortOrder フラグ)を保持します。それらの要素は TasksUiModel オブジェクトでラップされます。これらの値が変更されるたびに、新しい TasksUiModel を構築し直す必要があります。そのために、次の 3 つの要素を組み合わせます。

  • Flow<List<Task>>TasksRepository から取得されます。
  • 最新の showCompleted フラグを保持する MutableStateFlow<Boolean>。これは、メモリにのみ保持されます。
  • 最新の sortOrder 値を保持する MutableStateFlow<SortOrder>

UI の正しい更新を確実に実施するために、アクティビティの開始時にのみ LiveData<TasksUiModel> を公開します。

コードにはいくつかの問題があります。

  • UserPreferencesRepository.sortOrder を初期化すると、ディスク IO の UI スレッドがブロックされます。その結果、UI ジャンクが発生することがあります。
  • showCompleted フラグはメモリにのみ保持されるため、ユーザーがアプリを開くたびにリセットされます。sortOrder と同様に、これはアプリを閉じた後も効力を有するよう引き継がれる必要があります。
  • 現在はデータの引き継ぎに SharedPreferences を使用していますが、ここでは MutableStateFlow をメモリに保持することで、手動で変更し、変更の通知を受け取れるようにしています。アプリ内の他の場所で値が変更されると、これは機能しません。
  • UserPreferencesRepository では、並べ替え順序を変更する 2 つのメソッド、enableSortByDeadline()enableSortByPriority() を公開します。どちらのメソッドも現在の並べ替え順の値に依存していますが、一方が終了する前に他方が呼び出されると、最終的に誤った値になります。さらに、これらのメソッドは UI スレッドで呼び出されるので、UI ジャンクと厳格モードの違反を引き起こす可能性があります。

では、DataStore を使ってこうした問題に対処する方法を確認しましょう。

4. DataStore - 基本事項

小規模またはシンプルなデータセットの保存が必要になる状況に、皆さんもよく遭遇することでしょう。その場合、以前は SharedPreferences を使用したかもしれませんが、この API にはいくつかの欠点もあります。Jetpack DataStore ライブラリは、このような問題の解決を目指して、よりシンプルで安全な非同期のデータ格納 API を作成します。これは、次の 2 つの実装を提供します。

  • Preferences DataStore
  • Proto DataStore

機能

SharedPreferences

PreferencesDataStore

ProtoDataStore

非同期 API

✅(リスナーを介して変更された値を読み取る場合のみ)

✅(Flow、RxJava 2 & 3 Flowable 経由)

✅(Flow、RxJava 2 & 3 Flowable 経由)

同期 API

✅(ただし、UI スレッドで安全に呼び出せない)

UI スレッドで安全に呼び出せる

❌1

✅(処理は内部で Dispatchers.IO に移動)

✅(処理は内部で Dispatchers.IO に移動)

エラーのシグナルを送信できる

ランタイム例外から保護される

❌2

強整合性保証を備えたトランザクション API がある

データの移行を処理する

型の安全性

✅(プロトコル バッファを使用)

1 SharedPreferences には、UI スレッドで呼び出しても安全に見える同期 API がありますが、これは実際にはディスク I/O オペレーションを行います。さらに、apply()fsync() で UI スレッドをブロックします。fsync() 呼び出しの保留は、サービスが開始または停止するたび、およびアプリのどこかでアクティビティが開始または停止するたびにトリガーされます。UI スレッドは、apply() によってスケジュール設定された保留中の fsync() 呼び出しでブロックされ、多くの場合、ANR の発生元になります。

2 SharedPreferences は、ランタイム例外として解析エラーをスローします。

Preferences DataStore と Proto DataStore

Preferences DataStore と Proto DataStore はどちらもデータを保存できますが、その方法はそれぞれ異なります。

  • Preferences DataStore は、SharedPreferences と同様に、スキーマを事前に定義することなく、キーに基づいてデータにアクセスします。
  • Proto DataStore は、プロトコル バッファを使用してスキーマを定義します。Protobuf を使用すると、厳密に型付けされたデータを保持できます。XML やその他類似のデータ形式よりも、高速で小さくシンプル、かつ具体的です。Proto DataStore では新しいシリアル化メカニズムを学ぶことが求められますが、Proto DataStore がもたらす強力な型付けという利点には充分な価値があると考えられます。

Room と DataStore

部分更新、参照整合性、大規模なデータセットや複雑なデータセットが必要な場合は、DataStore の代わりに Room を使用することを検討してください。DataStore は、小規模で単純なデータセットに適しており、部分更新や参照整合性をサポートしていません。

5. Preferences DataStore の概要

Preferences DataStore API は SharedPreferences と類似していますが、次のようないくつかの違いがあります。

  • データ更新をトランザクションとして処理する
  • データの現在の状態を表す Flow を公開する
  • データの永続化メソッドがない(apply()commit()
  • 内部状態への変更可能な参照が返されない
  • 型付けされたキーを使用して MapMutableMap のような API を公開する

Preferences DataStore API をプロジェクトに追加し、SharedPreferences を DataStore に移行してみましょう。

依存関係を追加する

build.gradle ファイルを更新して、以下の Preference DataStore の依存関係を追加します。

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

6. Preferences DataStore のデータを永続化する

showCompleted フラグと sortOrder フラグはどちらもユーザー設定ですが、現時点では 2 つの異なるオブジェクトとして表現されています。今回の目標の 1 つは、これら 2 つのフラグを UserPreferences クラスの下で統合し、DataStore を使用して UserPreferencesRepository に保存することです。現在、showCompleted フラグはメモリに TasksViewModel で保持されています。

まず、UserPreferencesRepositoryUserPreferences データクラスを作成することから始めましょう。現時点では、showCompleted フィールドが 1 つだけ必要です。並べ替え順は後で追加します。

data class UserPreferences(val showCompleted: Boolean)

DataStore の作成

DataStore インスタンスを作成するには、preferencesDataStore デリゲートを使用し、レシーバーとして Context を使用します。わかりやすくするために、この Codelab では、TasksActivity でこの操作を行いましょう。

private const val USER_PREFERENCES_NAME = "user_preferences"

private val Context.dataStore by preferencesDataStore(
    name = USER_PREFERENCES_NAME
)

preferencesDataStore デリゲートにより、DataStore の単一インスタンスが、その名前でアプリ内に存在するようになります。現在、UserPreferencesRepository はシングルトンとして実装されています。sortOrderFlow が保持され、TasksActivity のライフサイクルと関連付けられないようにしているためです。UserPreferenceRepository は新しいオブジェクトを作成、保存せずに DataStore のデータを処理するだけであるため、シングルトン実装は削除することができます。

  • companion object を削除する
  • constructor を一般公開にする

UserPreferencesRepository は、コンストラクタのパラメータとして DataStore インスタンスを取得する必要があります。ここでは、Context をパラメータとして保持できますが(SharedPreferences に必要なため)、後で削除します。

class UserPreferencesRepository(
    private val userPreferencesStore: DataStore<UserPreferences>,
    context: Context
) { ... }

次に、TasksActivityUserPreferencesRepository の構造を更新し、dataStore を渡しましょう。

viewModel = ViewModelProvider(
    this,
    TasksViewModelFactory(
        TasksRepository,
        UserPreferencesRepository(dataStore, this)
    )
).get(TasksViewModel::class.java)

Preferences DataStore からのデータの読み取り

Preferences DataStore は、設定が変更されるたびに出力される Flow<Preferences> に保存されたデータを公開します。Preferences オブジェクト全体ではなく、UserPreferences オブジェクトを公開します。そうするには、Flow<Preferences> をマッピングし、目的のブール値を取得し、キーに基づいて UserPreferences オブジェクトを作成する必要があります。

したがって、最初に必要なのは show_completed キーを定義することです。これは、プライベート PreferencesKeys オブジェクト内のメンバーとして宣言できる booleanPreferencesKey 値です。

private object PreferencesKeys {
  val SHOW_COMPLETED = booleanPreferencesKey("show_completed")
}

dataStore.data: Flow<Preferences> に基づいて作成された userPreferencesFlow: Flow<UserPreferences> を公開します。これはマッピングされ、適切な設定が取得できるようになります。

val userPreferencesFlow: Flow<UserPreferences> = dataStore.data
    .map { preferences ->
        // Get our show completed value, defaulting to false if not set:
        val showCompleted = preferences[PreferencesKeys.SHOW_COMPLETED]?: false
        UserPreferences(showCompleted)
    }

データ読み取り中の例外の処理

DataStore がファイルからデータを読み取る際、データの読み取り中にエラーが発生すると IOExceptions がスローされます。これに対処するには、map() の前に catch() Flow 演算子を使用し、スローされた例外が IOException であった場合に emptyPreferences() を出力します。別の種類の例外がスローされた場合は、もう一度スローします。

val userPreferencesFlow: Flow<UserPreferences> = dataStore.data
    .catch { exception ->
        // dataStore.data throws an IOException when an error is encountered when reading data
        if (exception is IOException) {
            emit(emptyPreferences())
        } else {
            throw exception
        }
    }.map { preferences ->
        // Get our show completed value, defaulting to false if not set:
        val showCompleted = preferences[PreferencesKeys.SHOW_COMPLETED]?: false
        UserPreferences(showCompleted)
    }

Preferences DataStore へのデータの書き込み

データを書き込むために、DataStore には suspend 関数 DataStore.edit(transform: suspend (MutablePreferences) -> Unit) が用意されています。この関数は、DataStore 内の状態をトランザクション的に更新できるようにする transform ブロックを受け入れます。

変換ブロックに渡された MutablePreferences は、以前に実行した編集によって最新の状態になります。transform ブロックの MutablePreferences に対するすべての変更は、transform の完了後と edit の完了前にディスクに適用されます。MutablePreferences で 1 つの値を設定すると、その他のすべての設定は変更されないままとなります。

注: 変換ブロックの外部で MutablePreferences を変更しようとしないでください。

updateShowCompleted() という UserPreferencesshowCompleted プロパティを更新できるようにする suspend 関数を作成してみましょう。この関数は、dataStore.edit() を呼び出して新しい値を設定します。

suspend fun updateShowCompleted(showCompleted: Boolean) {
    dataStore.edit { preferences ->
        preferences[PreferencesKeys.SHOW_COMPLETED] = showCompleted
    }
}

edit() は、ディスクの読み取りまたは書き込み中にエラーが発生した場合、IOException をスローできます。変換ブロックでその他のエラーが発生した場合、edit() によってスローされます。

この時点で、アプリのコンパイルは行われるはずですが、UserPreferencesRepository で作成したばかりの機能は使用されません。

7. Preferences DataStore への SharedPreferences

並べ替え順は SharedPreferences に保存されます。それを DataStore に移行しましょう。実行するには、まず UserPreferences の更新からはじめます。これも並べ替え順に保存します。

data class UserPreferences(
    val showCompleted: Boolean,
    val sortOrder: SortOrder
)

SharedPreferences からの移行

DataStore に移行できるようにするには、DataStore ビルダーを更新して、SharedPreferencesMigration で移行のリストに渡すことができるようにする必要があります。DataStore は自動的に SharedPreferences から DataStore に移行できるようになります。移行は、DataStore 内でデータアクセスが行われる前に実行されます。つまり、DataStore.data が値を出力する前と DataStore.edit() でデータが更新される前に、移行が成功している必要があります。

注: キーが SharedPreferences から移行されるのは 1 回のみです。そのため、コードが DataStore に移行されたら、古い SharedPreferences の使用を中止する必要があります。

まず、TasksActivity で DataStore 作成のコードを更新しましょう。

private const val USER_PREFERENCES_NAME = "user_preferences"

private val Context.dataStore by preferencesDataStore(
    name = USER_PREFERENCES_NAME,
    produceMigrations = { context ->
        // Since we're migrating from SharedPreferences, add a migration based on the
        // SharedPreferences name
        listOf(SharedPreferencesMigration(context, USER_PREFERENCES_NAME))
    }
)

次に、sort_order を Google の PreferencesKeys に追加します。

private object PreferencesKeys {
    ...
    // Note: this has the the same name that we used with SharedPreferences.
    val SORT_ORDER = stringPreferencesKey("sort_order")
}

すべてのキーが DataStore に移行され、ユーザー設定 SharedPreferences から削除されます。これで、Preferences から、SORT_ORDER キーに基づいて SortOrder を取得して更新できるようになります。

DataStore からの並べ替え順の読み取り

userPreferencesFlow を更新して、map() 変換でも並べ替え順序を取得できるようにしましょう。

val userPreferencesFlow: Flow<UserPreferences> = dataStore.data
    .catch { exception ->
        if (exception is IOException) {
            emit(emptyPreferences())
        } else {
            throw exception
        }
    }.map { preferences ->
        // Get the sort order from preferences and convert it to a [SortOrder] object
        val sortOrder =
            SortOrder.valueOf(
                preferences[PreferencesKeys.SORT_ORDER] ?: SortOrder.NONE.name)

        // Get our show completed value, defaulting to false if not set:
        val showCompleted = preferences[PreferencesKeys.SHOW_COMPLETED] ?: false
        UserPreferences(showCompleted, sortOrder)
    }

DataStore に並べ替え順を保存する

現在、UserPreferencesRepository では並べ替え順フラグの設定には同期的な方法しか公開されていないため、同時実行の問題があります。Google は、並べ替え順序を更新する 2 つのメソッドとして enableSortByDeadline()enableSortByPriority() を公開しています。どちらのメソッドも現在の並べ替え順の値に依存しますが、一方のメソッドがもう片方のメソッドが終了する前に呼び出された場合、最終的に誤った値になります。

DataStore ではデータの更新がトランザクションとして行われることを保証しているため、この問題は発生しなくなります。次のように変更します。

  • enableSortByDeadline()enableSortByPriority() を、dataStore.edit() を使用する suspend 関数になるように更新します。
  • edit() の変換ブロックでは、_sortOrderFlow フィールドからではなく Preference パラメータから currentOrder を取得します。
  • updateSortOrder(newSortOrder) を呼び出す代わりに、設定内で並べ替え順を直接更新できます。

実装は次のようになります。

suspend fun enableSortByDeadline(enable: Boolean) {
    // edit handles data transactionally, ensuring that if the sort is updated at the same
    // time from another thread, we won't have conflicts
    dataStore.edit { preferences ->
        // Get the current SortOrder as an enum
        val currentOrder = SortOrder.valueOf(
            preferences[PreferencesKeys.SORT_ORDER] ?: SortOrder.NONE.name
        )

        val newSortOrder =
            if (enable) {
                if (currentOrder == SortOrder.BY_PRIORITY) {
                    SortOrder.BY_DEADLINE_AND_PRIORITY
                } else {
                    SortOrder.BY_DEADLINE
                }
            } else {
                if (currentOrder == SortOrder.BY_DEADLINE_AND_PRIORITY) {
                    SortOrder.BY_PRIORITY
                } else {
                    SortOrder.NONE
                }
            }
        preferences[PreferencesKeys.SORT_ORDER] = newSortOrder.name
    }
}

suspend fun enableSortByPriority(enable: Boolean) {
    // edit handles data transactionally, ensuring that if the sort is updated at the same
    // time from another thread, we won't have conflicts
    dataStore.edit { preferences ->
        // Get the current SortOrder as an enum
        val currentOrder = SortOrder.valueOf(
            preferences[PreferencesKeys.SORT_ORDER] ?: SortOrder.NONE.name
        )

        val newSortOrder =
            if (enable) {
                if (currentOrder == SortOrder.BY_DEADLINE) {
                    SortOrder.BY_DEADLINE_AND_PRIORITY
                } else {
                    SortOrder.BY_PRIORITY
                }
            } else {
                if (currentOrder == SortOrder.BY_DEADLINE_AND_PRIORITY) {
                    SortOrder.BY_DEADLINE
                } else {
                    SortOrder.NONE
                }
            }
        preferences[PreferencesKeys.SORT_ORDER] = newSortOrder.name
    }
}

これで、context コンストラクタ パラメータと使用されているすべての SharedPreferences を削除できます。

8. TasksViewModel を更新して UserPreferencesRepository を使用する

UserPreferencesRepository は、show_completed フラグと sort_order フラグの両方を DataStore に保存して、Flow<UserPreferences> を公開します。これらが使用されるように TasksViewModel を更新しましょう。

showCompletedFlowsortOrderFlow を削除し、その代わりに userPreferencesRepository.userPreferencesFlow で初期化される userPreferencesFlow という値を作成します。

private val userPreferencesFlow = userPreferencesRepository.userPreferencesFlow

tasksUiModelFlow を作成するときに、showCompletedFlowsortOrderFlowuserPreferencesFlow に置き換えます。必要に応じてパラメータを変更してください。

filterSortTasks を呼び出すときは、userPreferencesshowCompletedsortOrder を渡します。コードの内容は次のようになります。

private val tasksUiModelFlow = combine(
        repository.tasks,
        userPreferencesFlow
    ) { tasks: List<Task>, userPreferences: UserPreferences ->
        return@combine TasksUiModel(
            tasks = filterSortTasks(
                tasks,
                userPreferences.showCompleted,
                userPreferences.sortOrder
            ),
            showCompleted = userPreferences.showCompleted,
            sortOrder = userPreferences.sortOrder
        )
    }

showCompletedTasks() 関数は更新され、userPreferencesRepository.updateShowCompleted() を呼び出すようになりました。これは suspend 関数であるため、viewModelScope に新しいコルーチンを作成します。

fun showCompletedTasks(show: Boolean) {
    viewModelScope.launch {
        userPreferencesRepository.updateShowCompleted(show)
    }
}

userPreferencesRepository 関数の enableSortByDeadline()enableSortByPriority() は、suspend 関数になったため、viewModelScope で開始された新しいコルーチンでも呼び出す必要があります。

fun enableSortByDeadline(enable: Boolean) {
    viewModelScope.launch {
       userPreferencesRepository.enableSortByDeadline(enable)
    }
}

fun enableSortByPriority(enable: Boolean) {
    viewModelScope.launch {
        userPreferencesRepository.enableSortByPriority(enable)
    }
}

UserPreferencesRepository をクリーンアップする

不要になったフィールドとメソッドを削除しましょう。以下を削除できます。

  • _sortOrderFlow
  • sortOrderFlow
  • updateSortOrder()
  • private val sortOrder: SortOrder

これでアプリのコンパイルが正常に行われるようになりました。実行して、show_completed フラグと sort_order フラグが正しく保存されているかを確認してみましょう。

Codelab repo の preferences_datastore ブランチを確認して、変更を比較します。

9. まとめ

これで、Preferences DataStore への移行が完了しました。学習内容をおさらいしましょう。

  • SharedPreferences には、UI スレッドで呼び出しても安全に見える同期 API がある、エラーをシグナルさせるメカニズムがない、トランザクション API の不足といった一連のデメリットがあります。
  • DataStore は、その API の欠点のほとんどに対応した、SharedPreferences に代わるものです。
  • DataStore は、Kotlin のコルーチンと Flow を使用する完全非同期の API を備え、データの移行を処理し、データの整合性を保証して、データの破損を処理します。