Datastore   Parte de Android Jetpack

Jetpack Datastore es una solución de almacenamiento de datos que te permite almacenar pares clave-valor u objetos escritos con búferes de protocolo. Datastore usa corrutinas y Flow de Kotlin para almacenar datos de manera asíncrona, coherente y transaccional.

Si actualmente usas SharedPreferences para almacenar datos, considera migrar a Datastore.

Preferences Datastore y Proto Datastore

Datastore ofrece dos implementaciones diferentes: Preferences Datastore y Proto Datastore.

  • Preferences Datastore almacena y accede a datos mediante claves. Esta implementación no requiere un esquema predefinido ni proporciona seguridad de tipo.
  • Proto Datastore almacena datos como instancias de un tipo personalizado de datos. Esta implementación requiere que definas un esquema con búferes de protocolo, pero proporciona seguridad de tipo.

Configuración

Para usar Jetpack Datastore en tu app, agrega lo siguiente a tu archivo de Gradle según la implementación que quieras usar:

Almacén de datos escritos

Groovy

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation "androidx.datastore:datastore:1.0.0-rc01"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.0.0-rc01"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-rxjava3:1.0.0-rc01"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-core:1.0.0-rc01"
    }
    

Kotlin

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation("androidx.datastore:datastore:1.0.0-rc01")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.0.0-rc01")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-rxjava3:1.0.0-rc01")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-core:1.0.0-rc01")
    }
    

Preferencias del almacén de datos

Groovy

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation "androidx.datastore:datastore-preferences:1.0.0-rc01"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.0.0-rc01"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-preferences-rxjava3:1.0.0-rc01"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-preferences-core:1.0.0-rc01"
    }
    

Kotlin

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation("androidx.datastore:datastore-preferences:1.0.0-rc01")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.0.0-rc01")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-preferences-rxjava3:1.0.0-rc01")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-preferences-core:1.0.0-rc01")
    }
    

Almacena pares clave-valor con Preferences Datastore

La implementación de Preferences Datastore usa las clases DataStore y Preferences para conservar pares clave-valor simples en el disco.

Crea un Preferences Datastore

Usa el delegado de propiedad que creó preferencesDataStore para crear una instancia de Datastore<Preferences>. Llámalo una vez en el nivel superior de tu archivo de Kotlin y accede a él a través de esta propiedad en el resto de tu aplicación. Esto hace que sea más fácil mantener tu DataStore como un singleton. De manera alternativa, usa RxPreferenceDataStoreBuilder si utilizas RxJava. El parámetro name obligatorio es el nombre de Preferences Datastore.

Kotlin

// At the top level of your kotlin file:
val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "settings")

Java

RxDataStore<Preferences> dataStore =
  new RxPreferenceDataStoreBuilder(context, /*name=*/ "settings").build();

Lee desde Preferences Datastore

Debido a que Preferences Datastore no usa un esquema predefinido, debes usar la función de tipo de clave correspondiente a fin de definir una clave para cada valor que necesites almacenar en la instancia DataStore<Preferences>. Por ejemplo, si deseas definir una clave para un valor int, usa intPreferencesKey(). Luego, usa la propiedad DataStore.data para exponer el valor almacenado adecuado mediante un Flow.

Kotlin

val EXAMPLE_COUNTER = intPreferencesKey("example_counter")
val exampleCounterFlow: Flow<Int> = context.dataStore.data
  .map { preferences ->
    // No type safety.
    preferences[EXAMPLE_COUNTER] ?: 0
}

Java

Preferences.Key<Integer> EXAMPLE_COUNTER = PreferencesKeys.int("example_counter");

Flowable<Integer> exampleCounterFlow =
  dataStore.data().map(prefs -> prefs.get(EXAMPLE_COUNTER));

Escribe en un Preferences Datastore

Preferences Datastore proporciona una función edit() que actualiza los datos de forma transaccional en un DataStore. El parámetro transform de la función acepta un bloque de código en el que puedes actualizar los valores según sea necesario. Todo el código que esté en el bloque de transformación se tratará como una sola transacción.

Kotlin

suspend fun incrementCounter() {
  context.dataStore.edit { settings ->
    val currentCounterValue = settings[EXAMPLE_COUNTER] ?: 0
    settings[EXAMPLE_COUNTER] = currentCounterValue + 1
  }
}

Java

Single<Preferences> updateResult =  dataStore.updateDataAsync(prefsIn -> {
  MutablePreferences mutablePreferences = prefsIn.toMutablePreferences();
  Integer currentInt = prefsIn.get(INTEGER_KEY);
  mutablePreferences.set(INTEGER_KEY, currentInt != null ? currentInt + 1 : 1);
  return Single.just(mutablePreferences);
});
// The update is completed once updateResult is completed.

Almacena objetos escritos con Proto Datastore

La implementación de Proto Datastore usa Datastore y búferes de protocolo para conservar los objetos escritos en el disco.

Define un esquema

Proto Datastore requiere un esquema predefinido en un archivo proto del directorio app/src/main/proto/. Este esquema define el tipo para los objetos que conserves en tu Proto Datastore. Si quieres obtener más información para definir un esquema proto, consulta la guía del lenguaje de protobuf.

syntax = "proto3";

option java_package = "com.example.application";
option java_multiple_files = true;

message Settings {
  int32 example_counter = 1;
}

Cómo crear un Proto Datastore

Hay dos pasos relacionados con la creación de un Proto Datastore para almacenar tus objetos escritos:

  1. Define una clase que implemente Serializer<T>, en la que T es el tipo definido en el archivo proto. Esta clase de serializador le indica a Datastore cómo leer y escribir el tipo de datos. Asegúrate de incluir un valor predeterminado para que el serializador se use si aún no se creó un archivo.
  2. Usa el delegado de propiedad que creó dataStore para crear una instancia de DataStore<T>, en la que T es el tipo definido en el archivo .proto. Llámalo una vez en el nivel superior de tu archivo de Kotlin y accede a él mediante este delegado de propiedad en el resto de tu app. El parámetro filename le indica a Datastore qué archivo debe usar para almacenar los datos, y el parámetro serializer le indica el nombre de la clase de serializador definida en el paso 1.

Kotlin

object SettingsSerializer : Serializer<Settings> {
  override val defaultValue: Settings = Settings.getDefaultInstance()

  override suspend fun readFrom(input: InputStream): Settings {
    try {
      return Settings.parseFrom(input)
    } catch (exception: InvalidProtocolBufferException) {
      throw CorruptionException("Cannot read proto.", exception)
    }
  }

  override suspend fun writeTo(
    t: Settings,
    output: OutputStream) = t.writeTo(output)
}

val Context.settingsDataStore: DataStore<Settings> by dataStore(
  fileName = "settings.pb",
  serializer = SettingsSerializer
)

Java

private static class SettingsSerializer implements Serializer<Settings> {
  @Override
  public Settings getDefaultValue() {
    Settings.getDefaultInstance();
  }

  @Override
  public Settings readFrom(@NotNull InputStream input) {
    try {
      return Settings.parseFrom(input);
    } catch (exception: InvalidProtocolBufferException) {
      throw CorruptionException(“Cannot read proto.”, exception);
    }
  }

  @Override
  public void writeTo(Settings t, @NotNull OutputStream output) {
    t.writeTo(output);
  }
}

RxDataStore<Byte> dataStore =
    new RxDataStoreBuilder<Byte>(context, /* fileName= */ "settings.pb", new SettingsSerializer()).build();

Lee desde un Proto Datastore

Usa DataStore.data para exponer un Flow de la propiedad correspondiente desde tu objeto almacenado.

Kotlin

val exampleCounterFlow: Flow<Int> = context.settingsDataStore.data
  .map { settings ->
    // The exampleCounter property is generated from the proto schema.
    settings.exampleCounter
  }

Java

Flowable<Integer> exampleCounterFlow =
  dataStore.data().map(settings -> settings.getExampleCounter());

Escribe en un Proto Datastore

Proto Datastore proporciona una función updateData() que actualiza un objeto almacenado de forma transaccional. updateData() te muestra el estado actual de los datos como una instancia de tu tipo de datos y los actualiza de forma transaccional en una operación atómica de lectura, escritura y modificación.

Kotlin

suspend fun incrementCounter() {
  context.settingsDataStore.updateData { currentSettings ->
    currentSettings.toBuilder()
      .setExampleCounter(currentSettings.exampleCounter + 1)
      .build()
    }
}

Java

Single<Settings> updateResult =
  dataStore.updateDataAsync(currentSettings ->
    Single.just(
      currentSettings.toBuilder()
        .setExampleCounter(currentSettings.getExampleCounter() + 1)
        .build()));

Usa Datastore en código síncrono

Uno de los beneficios principales de Datastore es la API asíncrona, pero quizás no siempre se pueda cambiar el código que lo rodea para que sea asíncrono. Este podría ser el caso si trabajas con una base de código existente que usa operaciones síncronas de E/S del disco o si tienes una dependencia que no proporciona una API asíncrona.

Las corrutinas de Kotlin proporcionan el compilador de corrutinas runBlocking() para ayudar a cerrar la brecha entre el código síncrono y el asíncrono. Puedes usar runBlocking() para leer datos de Datastore de forma síncrona. RxJava ofrece métodos de bloqueo en Flowable. El siguiente código bloquea el subproceso de llamada hasta que Datastore muestre datos:

Kotlin

val exampleData = runBlocking { context.dataStore.data.first() }

Java

Settings settings = dataStore.data().blockingFirst();

Realizar operaciones de E/S síncronas en el subproceso de IU puede provocar ANR o bloqueos de IU. Para mitigar estos problemas, puedes precargar los datos de Datastore de forma asíncrona:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    lifecycleScope.launch {
        context.dataStore.data.first()
        // You should also handle IOExceptions here.
    }
}

Java

dataStore.data().first().subscribe();

De esta manera, Datastore lee de modo asíncrono los datos y los almacena en caché, en la memoria. Las lecturas síncronas posteriores con runBlocking() pueden ser más rápidas o evitar por completo una operación de E/S del disco si se completó la lectura inicial.

Envía comentarios

Comparte tus comentarios e ideas con nosotros por medio de estos recursos:

Herramienta de seguimiento de errores
Informa los problemas para que podamos corregir los errores.

Recursos adicionales

Para obtener más información sobre Jetpack Datastore, consulta los siguientes recursos adicionales:

Blogs

Codelabs