DataStore   Parte de Android Jetpack.

Probar con Kotlin Multiplatform

Kotlin Multiplatform permite compartir la capa de datos con otras plataformas. Aprende a configurar y trabajar con DataStore en KMP

Configurar DataStore para KMP →

Jetpack DataStore es una solución de almacenamiento de datos que te permite almacenar pares clave-valor o 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 usas SharedPreferences para almacenar datos, considera migrar a Datastore.

API de DataStore

La interfaz DataStore proporciona la siguiente API:

1. Un flujo que se puede usar para leer datos de DataStore

   val data: Flow<T>
   

2. Una función para actualizar datos en DataStore

   suspend updateData(transform: suspend (t) -> T)
   

Configuraciones de DataStore

Si deseas almacenar datos y acceder a ellos mediante claves, usa la implementación de Preferences DataStore, que no requiere un esquema predefinido y no proporciona seguridad de tipos. Tiene una API similar a SharedPreferences, pero no tiene los inconvenientes asociados con las preferencias compartidas.

DataStore te permite conservar clases personalizadas. Para ello, debes definir un esquema para los datos y proporcionar un Serializer para convertirlos en un formato persistente. Puedes elegir usar búferes de protocolo, JSON o cualquier otra estrategia de serialización.

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:

Preferences DataStore

Agrega las siguientes líneas a la parte de dependencias de tu archivo de Gradle:

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

        // Alternatively - without an Android dependency.
        implementation "androidx.datastore:datastore-preferences-core:1.2.1"
    }
    

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

        // Alternatively - without an Android dependency.
        implementation("androidx.datastore:datastore-preferences-core:1.2.1")
    }
    

Para agregar compatibilidad opcional con RxJava, agrega las siguientes dependencias:

    dependencies {
        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.2.1"

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

    dependencies {
        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.2.1")

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

DataStore

Agrega las siguientes líneas a la parte de dependencias de tu archivo de Gradle:

    dependencies {
        // Typed DataStore for custom data objects (for example, using Proto or JSON).
        implementation "androidx.datastore:datastore:1.2.1"

        // Alternatively - without an Android dependency.
        implementation "androidx.datastore:datastore-core:1.2.1"
    }
    

    dependencies {
        // Typed DataStore for custom data objects (for example, using Proto or JSON).
        implementation("androidx.datastore:datastore:1.2.1")

        // Alternatively - without an Android dependency.
        implementation("androidx.datastore:datastore-core:1.2.1")
    }
    

Agrega las siguientes dependencias opcionales para la compatibilidad con RxJava:

    dependencies {
        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.2.1"

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

    dependencies {
        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.2.1")

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

Para serializar contenido, agrega dependencias para la serialización de Protocol Buffers o JSON.

Serialización de JSON

Para usar la serialización de JSON, agrega lo siguiente a tu archivo de Gradle:

    plugins {
        id("org.jetbrains.kotlin.plugin.serialization") version "2.2.20"
    }

    dependencies {
        implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0"
    }
    

    plugins {
        id("org.jetbrains.kotlin.plugin.serialization") version "2.2.20"
    }

    dependencies {
        implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0")
    }
    

Serialización de Protobuf

Para usar la serialización de Protobuf, agrega lo siguiente a tu archivo de Gradle:

    plugins {
        id("com.google.protobuf") version "0.9.5"
    }
    dependencies {
        implementation "com.google.protobuf:protobuf-kotlin-lite:4.32.1"

    }

    protobuf {
        protoc {
            artifact = "com.google.protobuf:protoc:4.32.1"
        }
        generateProtoTasks {
            all().forEach { task ->
                task.builtins {
                    create("java") {
                        option("lite")
                    }
                    create("kotlin")
                }
            }
        }
    }
    

    plugins {
        id("com.google.protobuf") version "0.9.5"
    }
    dependencies {
        implementation("com.google.protobuf:protobuf-kotlin-lite:4.32.1")
    }

    protobuf {
        protoc {
            artifact = "com.google.protobuf:protoc:4.32.1"
        }
        generateProtoTasks {
            all().forEach { task ->
                task.builtins {
                    create("java") {
                        option("lite")
                    }
                    create("kotlin")
                }
            }
        }
    }
    

Cómo usar DataStore correctamente

Ten siempre en cuenta las siguientes reglas para usar DataStore de forma correcta:

1. Nunca crees más de una instancia de DataStore para un archivo determinado en el mismo proceso. Esta acción puede dañar toda la funcionalidad de DataStore. Si hay varios servicios de DataStore activos para un archivo determinado en el mismo proceso, DataStore lanzará IllegalStateException cuando lea o actualice datos.

2. El tipo genérico de DataStore<T> debe ser inmutable. La mutación de uno de los tipos usados hará que todas las garantías que DataStore proporcione sean no válidas y creará errores potencialmente graves y difíciles de detectar. Te recomendamos que uses búferes de protocolo, que ayudan a garantizar la inmutabilidad, una API clara y una serialización eficiente.

3. No mezcles usos de SingleProcessDataStore y MultiProcessDataStore para el mismo archivo. Si deseas acceder a la DataStore desde más de un proceso, debes usar MultiProcessDataStore.

Definición de datos

val EXAMPLE_COUNTER = intPreferencesKey("example_counter")

@Serializable
data class Settings(
    val exampleCounter: Int
)

object SettingsSerializer : Serializer<Settings> {

    override val defaultValue: Settings = Settings(exampleCounter = 0)

    override suspend fun readFrom(input: InputStream): Settings =
        try {
            Json.decodeFromString<Settings>(
                input.readBytes().decodeToString()
            )
        } catch (serialization: SerializationException) {
            throw CorruptionException("Unable to read Settings", serialization)
        }

    override suspend fun writeTo(t: Settings, output: OutputStream) {
        output.write(
            Json.encodeToString(t)
                .encodeToByteArray()
        )
    }
}

syntax = "proto3";

option java_package = "com.example.datastore.snippets.proto";
option java_multiple_files = true;

message Settings {
  int32 example_counter = 1;
}

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) {
        return t.writeTo(output)
    }
}

Crea un DataStore

Debes especificar un nombre para el archivo que se usa para conservar los datos.

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

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

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

Lee desde DataStore

Debes especificar un nombre para el archivo que se usa para conservar los datos.

fun counterFlow(): Flow<Int> = context.dataStore.data.map { preferences ->
    preferences[EXAMPLE_COUNTER] ?: 0
}

fun counterFlow(): Flow<Int> = context.dataStore.data.map { settings ->
    settings.exampleCounter
}

fun counterFlow(): Flow<Int> = context.dataStore.data.map { settings ->
    settings.exampleCounter
}

Usa collectAsStateWithLifecycle para consumir el Flow que produce un ViewModel en un elemento que admite composición. Esto convierte de forma segura el flujo de DataStore en un estado de Compose que activa la recomposición.

@Composable
fun SomeScreen(counterFlow: Flow<Int>) {
  val counter by counterFlow.collectAsStateWithLifecycle(initialValue = 0)
  Text(text = "Example counter: ${counter}")
}

Para obtener más información sobre collectAsStateWithLifecycle, consulta El estado y Jetpack Compose.

Escribe en DataStore

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. Todo el código que esté en el bloque updateData se tratará como una sola transacción.

suspend fun incrementCounter() {
    context.dataStore.updateData {
        it.toMutablePreferences().also { preferences ->
            preferences[EXAMPLE_COUNTER] = (preferences[EXAMPLE_COUNTER] ?: 0) + 1
        }
    }
}

suspend fun incrementCounter() {
    context.dataStore.updateData { settings ->
        settings.copy(exampleCounter = settings.exampleCounter + 1)
    }
}

suspend fun incrementCounter() {
    context.dataStore.updateData { settings ->
        settings.copy { exampleCounter = exampleCounter + 1 }
    }
}

Usa DataStore en una app de Compose

Para usar DataStore en una app de Compose, sigue los lineamientos de la arquitectura de apps para Android manteniendo las operaciones de DataStore en tu capa de datos (como un repositorio) y exponiendo los datos a tu IU a través de un ViewModel.

Evita leer o escribir en DataStore directamente dentro de tus funciones que admiten composición.

1. Expón DataStore a través de un ViewModel. Pasa tu repositorio (que encapsula DataStore) a tu ViewModel y convierte el Flow en un StateFlow para que la IU pueda observarlo con facilidad, como se muestra en el siguiente fragmento:

   class SettingsViewModel(
       private val userPreferencesRepository: UserPreferencesRepository
   ) : ViewModel() {
   
       // Expose the DataStore flow as a StateFlow for Compose
       val userSettings: StateFlow<UserSettings> = userPreferencesRepository.userSettingsFlow
           .stateIn(
               scope = viewModelScope,
               started = SharingStarted.WhileSubscribed(5000),
               initialValue = UserSettings.getDefaultInstance()
           )
   
       fun updateCounter(newValue: Int) {
           viewModelScope.launch {
               userPreferencesRepository.updateCounter(newValue)
           }
       }
   }
   

2. Observa y escribe desde tu elemento que admite composición. Usa collectAsStateWithLifecycle para observar de forma segura el StateFlow en tu IU y llama a las funciones ViewModel para controlar las escrituras, como se muestra en el siguiente fragmento:

   @Composable
   fun SettingsScreen(
       viewModel: SettingsViewModel = viewModel()
   ) {
       // Safely collect the state
       val settings by viewModel.userSettings.collectAsStateWithLifecycle()
   
       Column(modifier = Modifier.padding(16.dp)) {
           Text(text = "Current counter: ${settings.counter}")
   
           Spacer(modifier = Modifier.height(8.dp))
   
           Button(onClick = { viewModel.updateCounter(settings.counter + 1) }) {
               Text("Increment Counter")
           }
       }
   }
   

Cómo usar DataStore en código de varios procesos

Puedes configurar DataStore para acceder a los mismos datos en diferentes procesos con las mismas propiedades de coherencia de datos que brinda un solo proceso. En particular, DataStore proporciona las siguientes propiedades:

• Las lecturas solo mostrarán los datos conservados en el disco.
• Habrá coherencia de la lectura después de escritura.
• Habrá una serialización en las escrituras.
• Las escrituras nunca bloquearán lecturas.

Piensa en una aplicación de muestra con un servicio y una actividad en la que el servicio se ejecuta en un proceso separado y actualiza el almacén de datos de forma periódica.

En este ejemplo, se usa un almacén de datos JSON, pero también puedes usar un Preferences o Proto DataStore.

@Serializable
data class Time(
    val lastUpdateMillis: Long
)

Un serializador le indica a DataStore cómo leer y escribir tu tipo de datos. Asegúrate de incluir un valor predeterminado para que el serializador se use si aún no se creó un archivo. A continuación, se muestra un ejemplo de implementación con kotlinx.serialization:

object TimeSerializer : Serializer<Time> {

    override val defaultValue: Time = Time(lastUpdateMillis = 0L)

    override suspend fun readFrom(input: InputStream): Time =
        try {
            Json.decodeFromString<Time>(
                input.readBytes().decodeToString()
            )
        } catch (serialization: SerializationException) {
            throw CorruptionException("Unable to read Time", serialization)
        }

    override suspend fun writeTo(t: Time, output: OutputStream) {
        output.write(
            Json.encodeToString(t)
                .encodeToByteArray()
        )
    }
}

Para usar DataStore en diferentes procesos, debes construir el objeto DataStore con MultiProcessDataStoreFactory para el código de la app y el servicio:

val dataStore = MultiProcessDataStoreFactory.create(
    serializer = TimeSerializer,
    produceFile = {
        File("${context.filesDir.path}/time.pb")
    },
    corruptionHandler = null
)

Agrega lo siguiente a tu AndroidManifiest.xml:

<service
    android:name=".TimestampUpdateService"
    android:process=":my_process_id" />

El servicio llama periódicamente a updateLastUpdateTime, que escribe en el almacén de datos con updateData.

suspend fun updateLastUpdateTime() {
    dataStore.updateData { time ->
        time.copy(lastUpdateMillis = System.currentTimeMillis())
    }
}

La app lee el valor que escribió el servicio con el flujo de datos:

fun timeFlow(): Flow<Long> = dataStore.data.map { time ->
    time.lastUpdateMillis
}

Ahora, podemos juntar todas estas funciones en una clase llamada MultiProcessDataStore y usarla en una app.

Este es el código del servicio:

class TimestampUpdateService : Service() {
    val serviceScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
    val multiProcessDataStore by lazy { MultiProcessDataStore(applicationContext) }


    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        serviceScope.launch {
            while (true) {
                multiProcessDataStore.updateLastUpdateTime()
                delay(1000)
            }
        }
        return START_NOT_STICKY
    }

    override fun onDestroy() {
        super.onDestroy()
        serviceScope.cancel()
    }
}

Y el código de la app:

val context = LocalContext.current
val coroutineScope = rememberCoroutineScope()
val multiProcessDataStore = remember(context) { MultiProcessDataStore(context) }

// Display time written by other process.
val lastUpdateTime by multiProcessDataStore.timeFlow()
    .collectAsState(initial = 0, coroutineScope.coroutineContext)
Text(
    text = "Last updated: $lastUpdateTime",
    fontSize = 25.sp
)

DisposableEffect(context) {
    val serviceIntent = Intent(context, TimestampUpdateService::class.java)
    context.startService(serviceIntent)
    onDispose {
        context.stopService(serviceIntent)
    }
}

Puedes usar la inserción de dependencia Hilt para que tu instancia de DataStore sea única por proceso:

@Provides
@Singleton
fun provideDataStore(@ApplicationContext context: Context): DataStore<Settings> =
   MultiProcessDataStoreFactory.create(...)

Controla la corrupción de archivos

En ocasiones inusuales, el archivo persistente en el disco de DataStore podría dañarse. De forma predeterminada, DataStore no se recupera automáticamente de la corrupción, y los intentos de leerlo harán que el sistema lance una CorruptionException.

DataStore ofrece una API de controlador de corrupción que puede ayudarte a recuperarte correctamente en ese caso y evitar que se lance la excepción. Cuando se configura, el controlador de corrupción reemplaza el archivo dañado por uno nuevo que contiene un valor predeterminado predefinido.

Para configurar este controlador, proporciona un corruptionHandler cuando crees la instancia de DataStore en by dataStore o en el método de fábrica DataStoreFactory:

val dataStore: DataStore<Settings> = DataStoreFactory.create(
   serializer = SettingsSerializer(),
   produceFile = {
       File("${context.filesDir.path}/myapp.preferences_pb")
   },
   corruptionHandler = ReplaceFileCorruptionHandler { Settings(lastUpdate = 0) }
)

Proporcionar comentarios

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

Issue Tracker:

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:

Ejemplos

Blogs

• Opta por almacenar datos con Jetpack Datastore

Codelabs

• Cómo trabajar con Preferences Datastore
• Cómo trabajar con Proto DataStore