Обзор DataStore Library. Прощаемся с SharedPreference?

Привет, меня зовут Сергей, я работаю в команде Мобильного Банка Тинькофф. Недавно Google представила очередной инструмент для хранения данных. На этот раз это библиотека DataStore. В официальном блоге Google пишут, что она должна заменить SharedPreference. 

В отличие от SharedPreference, DataStore работает асинхронно. Вся работа с библиотекой выполняется с помощью Kotlin Coroutines и Flow. DataStore позволяет нам хранить данные двумя способами:

• По принципу «ключ — значение», аналогично SharedPreference.

• Хранить типизированные объекты, основанные на protocol buffers.

Все взаимодействие с DataStore происходит через интерфейс DataStore<T>, который содержит в себе всего два элемента:

interface DataStore<T> {    val data: Flow<T>    suspend fun updateData(transform: suspend (t: T) -> T): T }

Интерфейс очень прост. Все, что мы можем сделать с ним, это получить объект Flow<T> для чтения данных и вызвать метод updateData() для их записи.

Типы DataStore

• Preferences DataStore — хранит данные по принципу «ключ — значение» и не предоставляет нам никакой типобезопасности.

• Proto DataStore — хранит данные в объектах. Это дает нам типобезопасноть, но описывать схему нужно с помощью protocol buffers.

Поговорим о каждом из них.

Preferences DataStore

Для подключения библиотеки необходимо добавить зависимость в build.gradle нашего проекта:

// Preferences DataStore implementation "androidx.datastore:datastore-preferences:1.0.0-alpha01"

Как получить экземпляр Preferences DataStore

Для этого нам предоставляется extension-функция, которую можно вызвать из объекта Context:

context.createDataStore(     name = "user_data_store",     corruptionHandler = null     migrations = emptyList(),     scope = CoroutineScope(Dispatchers.IO + Job()) )

Здесь есть четыре параметра. Давайте рассмотрим каждый из них.

• name — обязательный параметр. Это название нашего DataStore. Под капотом будет создан файл, путь которого формируется на основании параметра name.

File(context.filesDir, "datastore/" + name + ".preferences_pb")

• corruptionHandler — этот параметр необязательный. CorruptionHandler вызывается, если DataStore бросает CorruptionException при попытке чтения данных. Если CorruptionHandler успешно подменит данные, то исключение будет поглощено. Если в процессе подмены данных мы получим еще одно исключение, то оно будет добавлено к оригинальному исключению, после чего нам будет выброшено оригинальное исключение.

• migrations — необязательный параметр, который позволяет легко мигрировать из SharedPreference. Сюда принимается список объектов DataMigration<Preferences>. На самом деле Google уже создала реализацию SharedPreferencesMigration. Все, что нам нужно, это описать логику переноса данных для каждого Shared Preference и передать их списком в параметр migrations:

fun getSharedPreferenceMigrationPref(): SharedPreferencesMigration<MutablePreferences> =    SharedPreferencesMigration(        context = context,        sharedPreferencesName = "pref_name",        deleteEmptyPreferences = true,        shouldRunMigration = { true },        migrate = { prefs, userPref ->            userPref[FIELD_NAME] = prefs.getString(KEY_NAME)            userPref[FIELD_LAST_NAME] = prefs.getString(KEY_LAST_NAME)            userPref[FIELD_AGE] = prefs.getInt(KEY_AGE, 0)            userPref[FIELD_ACTIVE] = prefs.getBoolean(KEY_IS_ACTIVE, false)            userPref        }    )

В отличие от обычных Shared Preference, в качестве ключа здесь не строка, но об этом мы поговорим чуть позже. 

• scope — тоже необязательный параметр. Здесь можно указать, в каком Coroutine Scope мы хотим выполнять операции с DataStore. По умолчанию там Dispatchers.IO.

Создание ключей

Чтобы сделать запись в DataStore, нам необходимо определить ключи, под которыми будут храниться наши данные. Как упоминалось выше, это не строки. Поля имеют тип Preferences.Key<T>. Создать подобное поле можно с помощью extension-функции:

object UserScheme {    val FIELD_NAME = preferencesKey<String>("name")    val FIELD_LAST_NAME = preferencesKey<String>("last_name")    val FIELD_AGE = preferencesKey<Int>("age")    val FIELD_ACTIVE = preferencesKey<Boolean>("active") }

Каждый ключ указывает на тип хранимых в нем данных и строковый ключ, по которому эти данные будут читаться. Поскольку при создании ключа мы указываем тип хранимых данных — мы получаем проверку на корректность передаваемого типа данных в compile time. 

Стоит помнить, что создавать ключи можно только для примитивных типов данных: Int, Long, Boolean, Float, String. В противном случае мы получим исключение. 

Также мы можем хранить Set<String>: 

val FIELD_STRINGS_SET = preferencesSetKey<Set<String>>("strings_set")

Скорее всего, количество типов будет расширяться, так как сейчас методы prefrencesKey() и prefrencesSetKey() на вход принимают дженерик и ограничение по типам сделано руками.

Запись данных

Для записи данных DataStore предоставляет нам два метода для изменения данных:

DataStore.updateData

coroutineScope.launch {    prefDataStore.updateData { prefs ->        prefs.toMutablePreferences().apply {            set(UserScheme.FIELD_NAME, "John")            set(UserScheme.FIELD_LAST_NAME, "Show")            set(UserScheme.FIELD_AGE, 100)            set(UserScheme.FIELD_IS_ACTIVE, false)        }    } }

DataStore.edit

coroutineScope.launch {    prefDataStore.edit { prefs ->        prefs[UserScheme.FIELD_NAME] = "John"        prefs[UserScheme.FIELD_LAST_NAME] = "Show"        prefs[UserScheme.FIELD_AGE] = 100        prefs[UserScheme.FIELD_IS_ACTIVE] = false    } } 

В обоих случаях мы получаем объект Preferences с разницей лишь в том, что во втором случае приведение к мутабельности спрятано под капотом «функции обертки» edit().

Preferences очень похожа на Generic Map, в которую мы в качестве ключа указываем определенные нами ранее preferenceKey. Для работы с Preferences есть всего четыре метода get(), contains(), asMap() и set(). Метод set() доступен только в MutablePreferences. Запись в Preferences происходит асинхронно, и корутина завершается после того, как данные сохраняются на диске.

Чтение данных

DataStore предоставляет сохраненные данные в объекте Preferences. Все действия производятся на определенном нами при создании Dispatcher:

coroutineScope.launch {    prefDataStore.data        .collect { pref: Preferences ->            val name: String? = pref[UserScheme.FIELD_NAME]            val lastName: String? = pref[UserScheme.FIELD_LAST_NAME]            val age: Int? = pref[UserScheme.FIELD_AGE]            val isActive: Boolean? = pref[UserScheme.FIELD_IS_ACTIVE]        } }

DataStore возвращает объект Flow, который будет возвращать нам либо значение, либо исключение, в случае ошибки чтения с диска.

Proto DataStore

Для подключения добавляем зависимость:

// Proto DataStore implementation  "androidx.datastore:datastore-core:1.0.0-alpha01"

Перед работой с Proto DataStore нужно выполнить несколько действий:

• В build.gradle добавить плагин:

plugins {    id "com.google.protobuf" version "0.8.12" }

• Подключить зависимость в build.gradle:

implementation  "com.google.protobuf:protobuf-javalite:3.10.0"

• Создать модель данных, используя protocol buffers.

Для этого нужно создать файл в app/src/main/proto/ с расширением .proto:

syntax = "proto3";  option java_package = "com.example.jetpackdatasource"; option java_multiple_files = true;  message UserProto {  string name = 1;  string last_name = 2;  int32 age = 3;  bool is_active = 4; }

Здесь есть подробное руководство по работе с proto buffer файлами.

Это будет наша схема хранения данных. Система сгенерирует модель, которую мы можем сохранять в наш DataStore.

Когда вы все это сделаете, Android Studio предложит установить плагин Protocol Buffer Editor. Он сделает вашу работу с файлами .proto удобной. Плагин будет подсвечивать синтаксические элементы, проводить семантический анализ и др.

Как получить экземпляр Proto DataStore

Для этого у нас тоже есть extension-функция:

context.createDataStore(        fileName ="user.pb",        serializer = UserSerializer,        corruptionHandler = null,        migrations = emptyList(),        scope = CoroutineScope(Dispatchers.IO + Job()) )

Здесь все почти то же самое, как и с Preference DataStore. Но есть два отличия:

• Первое — это путь, по которому будет сохраняться файл префов: File(context.filesDir, "datastore/$fileName").

• Второе — наличие поля serializer. Давайте рассмотрим его подробнее. Чтобы Proto DataStore понимал, как ему сохранять данные в файл, мы должны к каждому модели прописать свой Serializer. Для этого нужно реализовать интерфейс Serializer<T>, в котором мы и опишем логику записи/чтения нашего файла:

object UserSerializer : Serializer<User> {     override fun readFrom(input: InputStream): User {        try {            return User.parseFrom(input)        } catch (exception: InvalidProtocolBufferException) {            throw CorruptionException("Cannot read proto.", exception)        }    }     override fun writeTo(t: User, output: OutputStream) = t.writeTo(output) }

В остальном тут все так же, как в Preference DataStore.

Запись данных

Для записи данных DataStore предоставляет нам функцию DataStore.updateData(). Она возвращает текущее состояние сохраненных данных. В качестве параметра мы получаем экземпляр модели, которую мы определили в файле .proto:

coroutineScope.launch {    protoDataStore.updateData { user ->        user.toBuilder()            .setName(nameField.text.toString())            .setLastName(lastNameField.text.toString())            .setAge(ageField.text.toString().toIntOrNull() ?: 0)            .setIsActive(isActiveSwitch.isChecked)            .build()    } }

Модель предоставляет нам билдер для записи данных в DataStore. Для каждого поля, указанного в модели, описанной в .proto-файле, мы имеем свой set-метод.

Чтение данных

Есть два способа для чтения данных из Proto DataStore:

Вызвать метод DataStore.updateData(). Так как в нем мы получаем актуальное состояние объекта, ничего не мешает прочитать их отсюда. Нюанс в том, что там нужно вернуть актуальное состояние модели в лямбде:

coroutineScope.launch {    protoDataStore.updateData { user ->        val name: String = user.name        val lastName: String = user.lastName        val age: Int = user.age        val isActive: Boolean = user.isActive        return@updateData user    } }

Получить объект data : Flow<T>, который вернет нам реактивный поток. Результатом этого Flow будет актуальный экземпляр хранимой в DataStore модели:

coroutineScope.launch(Dispatchers.Main) {    protoDataStore.data        .collect { user ->            val receivedUser: User = user        } }

SharedPreference vs DataStore

• DataStore предоставляет асинхронный API для записи и чтения данных, в отличие от Shared Preference, который предоставляет асинхронный API только при чтении данных.

• DataStore безопасен для работы на UI-потоке, так как есть возможность указать подходящий для нас Dispatcher.

• DataStore защищает от ошибок в рантайме, в то время как Shared Preference может бросить ошибку парсинга в рантайме.

• Proto DataStore предоставляет лучшую типобезопасность из коробки.

Тут стоит отдельно поговорить о транзакционности.

В Shared Preference транзакционность может быть достигнута за счет связки edit() -> apply()/commit(). Мы должны получить объект SharedPreferences.Editor, внести изменения и все это зафиксировать методами commit() или apply():

val editor: SharedPreferences.Editor = pref.edit() editor.putString(KEY_LAST_NAME, lastName) editor.putBoolean(KEY_IS_ACTIVE, isActive) editor.apply()

В androidx этот же код будет выглядеть вот так:

pref.edit(commit = false) {    putString(KEY_LAST_NAME, lastName)    putBoolean(KEY_IS_ACTIVE, isActive) }

По завершении операций в блоке edit{} внутри функции вызовется commit() или apply(), в зависимости от флага commit.

DataStore создает транзакцию всякий раз при вызове методов DataStore.updateData() или DataStore.edit() и делает запись после выполнения всех операций внутри этих функций.

DataStore vs Room

Если вам нужны частичные обновления, ссылочная целостность или поддержка больших/сложных наборов данных, подумайте об использовании Room вместо DataStore.

DataStore идеально подходит для небольших простых наборов данных и не поддерживает частичные обновления или ссылочную целостность.

Rx Java

В данный момент поддержки RX Java в DataStore нет. Поэтому, если мы хотим в проект на RX затащить DataStore, придется писать свои обертки. Как вариант, можно использовать тулы для совместимости вроде этой. 

Вывод

У SharedPreferences есть несколько недостатков: 

• Синхронный API, который может показаться безопасным для вызова на UI-потоке, но фактически он выполняет операции дискового ввода-вывода.

• Отсутствует механизм сигнализации об ошибках, транзакционный API и многое другое.

DataStore — это замена SharedPreferences, которая устраняет большинство этих недостатков. DataStore включает в себя полностью асинхронный API, использующий Kotlin Coroutines и Flow. Дает нам очень простой и удобный инструмент для миграции данных. Гарантирует согласованность данных и обработку поврежденных данных.

В данный момент библиотека находится в альфе, но вы всегда можете проверить последнюю версию в документации.