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 で使用するサンプルアプリでは、完了したステータスでフィルタリングでき、優先度と期限で並べ替えができるタスクのリストを表示します。
[Show completed tasks] フィルタのブール値フラグはメモリに保存されます。並べ替え順序は、SharedPreferences オブジェクトを使用してディスクに引き継がれます。
この Codelab では、次のタスクを完了して、Preferences DataStore の使用方法を確認します。
- 完了ステータスのフィルタを DataStore に引き継ぐ。
- 並べ替え順序を SharedPreferences から DataStore に移行する。
両者の違いを理解するために、Proto DataStore Codelab も使用してみることをおすすめします。
必要なもの
- Android Studio Arctic Fox。
- 次のアーキテクチャ コンポーネントに精通していること: LiveData、ViewModel、ビュー バインディング、およびアプリ アーキテクチャ ガイドで提案されているアーキテクチャ。
- コルーチンと Kotlin Flow に精通していること。
アーキテクチャ コンポーネントの概要については、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 のすべてのコードをダウンロードできます。
- コードの ZIP ファイルを展開し、プロジェクトを Android Studio Arctic Fox で開きます。
- デバイスまたはエミュレータでアプリ実行構成を実行します。
アプリが実行され、タスクのリストが表示されます。
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 | ✅（リスナーを介して変更された値を読み取る場合のみ） | ✅（ | ✅（ |
同期 API | ✅（ただし、UI スレッドで安全に呼び出せない） | ❌ | ❌ |
UI スレッドで安全に呼び出せる | ❌1 | ✅（処理は内部で | ✅（処理は内部で |
エラーのシグナルを送信できる | ❌ | ✅ | ✅ |
ランタイム例外から保護される | ❌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()） - 内部状態への変更可能な参照が返されない
- 型付けされたキーを使用して
MapやMutableMapのような 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 で保持されています。
まず、UserPreferencesRepository に UserPreferences データクラスを作成することから始めましょう。現時点では、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
) { ... }
次に、TasksActivity の UserPreferencesRepository の構造を更新し、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() という UserPreferences の showCompleted プロパティを更新できるようにする 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 を更新しましょう。
showCompletedFlow と sortOrderFlow を削除し、その代わりに userPreferencesRepository.userPreferencesFlow で初期化される userPreferencesFlow という値を作成します。
private val userPreferencesFlow = userPreferencesRepository.userPreferencesFlow
tasksUiModelFlow を作成するときに、showCompletedFlow と sortOrderFlow を userPreferencesFlow に置き換えます。必要に応じてパラメータを変更してください。
filterSortTasks を呼び出すときは、userPreferences の showCompleted と sortOrder を渡します。コードの内容は次のようになります。
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 をクリーンアップする
不要になったフィールドとメソッドを削除しましょう。以下を削除できます。
_sortOrderFlowsortOrderFlowupdateSortOrder()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 を備え、データの移行を処理し、データの整合性を保証して、データの破損を処理します。