Progetto: /architecture/_project.yaml Libro: /architecture/_book.yaml parole chiave: datastore, architecture, api:JetpackDataStore description: Explore this app architecture guide on data layer libraries to learn about Preferences DataStore and Proto DataStore, Setup, and more. hide_page_heading: true

DataStore   Parte di Android Jetpack.

Prova con Kotlin Multiplatform

Kotlin Multiplatform consente di condividere il livello dati con altre piattaforme. Scopri come configurare e utilizzare DataStore in KMP

Configurare DataStore per KMP →

Jetpack DataStore è una soluzione di archiviazione dei dati che ti consente di archiviare coppie chiave-valore o oggetti digitati con protocol buffer. DataStore utilizza le coroutine Kotlin e Flow per archiviare i dati in modo asincrono, coerente e transazionale.

Se utilizzi SharedPreferences per archiviare i dati, valuta la possibilità di eseguire la migrazione a DataStore.

API DataStore

L'interfaccia DataStore fornisce la seguente API:

1. Un flusso che può essere utilizzato per leggere i dati da DataStore

   val data: Flow<T>
   

2. Una funzione per aggiornare i dati in DataStore

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

Configurazioni di DataStore

Se vuoi archiviare e accedere ai dati utilizzando le chiavi, utilizza l'implementazione Preferences DataStore, che non richiede uno schema predefinito e non fornisce la sicurezza dei tipi. Ha un'API simile a SharedPreferences, ma non presenta gli svantaggi associati alle preferenze condivise.

DataStore consente di rendere persistenti le classi personalizzate. Per farlo, devi definire uno schema per i dati e fornire un Serializer per convertirli in un formato persistente. Puoi scegliere di utilizzare Protocol Buffers, JSON o qualsiasi altra strategia di serializzazione.

Configura

Per utilizzare Jetpack DataStore nella tua app, aggiungi quanto segue al file Gradle a seconda dell'implementazione che vuoi utilizzare:

Datastore delle preferenze

Aggiungi le seguenti righe alla sezione delle dipendenze del file gradle:

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

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

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

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

Per aggiungere il supporto facoltativo di RxJava, aggiungi le seguenti dipendenze:

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

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

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

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

DataStore

Aggiungi le seguenti righe alla sezione delle dipendenze del file gradle:

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

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

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

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

Aggiungi le seguenti dipendenze facoltative per il supporto di RxJava:

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

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

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

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

Per serializzare i contenuti, aggiungi le dipendenze per la serializzazione di Protocol Buffer o JSON.

Serializzazione JSON

Per utilizzare la serializzazione JSON, aggiungi quanto segue al file 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")
    }
    

Serializzazione Protobuf

Per utilizzare la serializzazione Protobuf, aggiungi quanto segue al file 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")
                }
            }
        }
    }
    

Utilizzare correttamente DataStore

Per utilizzare DataStore correttamente, tieni sempre presente le seguenti regole:

1. Non creare mai più di un'istanza di DataStore per un determinato file nello stesso processo. In questo modo, tutte le funzionalità di DataStore potrebbero non funzionare più. Se sono attivi più DataStore per un determinato file nello stesso processo, DataStore genererà IllegalStateException durante la lettura o l'aggiornamento dei dati.

2. Il tipo generico di DataStore<T> deve essere immutabile. La modifica di un tipo utilizzato in DataStore invalida la coerenza fornita da DataStore e crea bug potenzialmente gravi e difficili da individuare. Ti consigliamo di utilizzare i buffer del protocollo, che contribuiscono a garantire l'immutabilità, un'API chiara e una serializzazione efficiente.

3. Non combinare gli utilizzi di SingleProcessDataStore e MultiProcessDataStore per lo stesso file. Se intendi accedere a DataStore da più di un processo, devi utilizzare MultiProcessDataStore.

Definizione dei dati

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

Devi specificare un nome per il file utilizzato per rendere persistenti i dati.

// 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,
)

Leggi da DataStore

Devi specificare un nome per il file utilizzato per rendere persistenti i dati.

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
}

Scrivi in DataStore

DataStore fornisce una funzione updateData() che aggiorna in modo transazionale un oggetto archiviato. updateData fornisce lo stato attuale dei dati come istanza del tipo di dati e aggiorna i dati in modo transazionale in un'operazione di lettura-scrittura-modifica atomica. Tutto il codice nel blocco updateData viene trattato come una singola transazione.

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 }
    }
}

Esempio di composizione

Puoi combinare queste funzioni in una classe e utilizzarle in un'app Compose.

val context = LocalContext.current
val coroutineScope = rememberCoroutineScope()
val preferencesDataStore = remember(context) { PreferencesDataStore(context) }

// Display counter value.
val exampleCounter by preferencesDataStore.counterFlow()
    .collectAsState(initial = 0, coroutineScope.coroutineContext)
Text(
    text = "Counter $exampleCounter",
    fontSize = 25.sp
)

// Update the counter.
Button(
    onClick = {
        coroutineScope.launch { preferencesDataStore.incrementCounter() }
    }
) {
    Text("increment")
}

val context = LocalContext.current
val coroutineScope = rememberCoroutineScope()
val jsonDataStore = remember(context) { JsonDataStore(context) }

// Display counter value.
val exampleCounter by jsonDataStore.counterFlow()
    .collectAsState(initial = 0, coroutineScope.coroutineContext)
Text(
    text = "Counter $exampleCounter",
    fontSize = 25.sp
)

// Update the counter.
Button(onClick = { coroutineScope.launch { jsonDataStore.incrementCounter() } }) {
    Text("increment")
}

val context = LocalContext.current
val coroutineScope = rememberCoroutineScope()
val protoDataStore = remember(context) { ProtoDataStore(context) }

// Display counter value.
val exampleCounter by protoDataStore.counterFlow()
    .collectAsState(initial = 0, coroutineScope.coroutineContext)
Text(
    text = "Counter $exampleCounter",
    fontSize = 25.sp
)

// Update the counter.
Button(onClick = { coroutineScope.launch { protoDataStore.incrementCounter() } }) {
    Text("increment")
}

Utilizzare DataStore nel codice sincrono

Uno dei principali vantaggi di DataStore è l'API asincrona, ma potrebbe non essere sempre possibile modificare il codice circostante in modo che sia asincrono. Questo potrebbe verificarsi se utilizzi una base di codice esistente che utilizza I/O del disco sincrono o se hai una dipendenza che non fornisce un'API asincrona.

Le coroutine Kotlin forniscono il builder di coroutine runBlocking() per colmare il divario tra codice sincrono e asincrono. Puoi utilizzare runBlocking() per leggere i dati da DataStore in modo sincrono. RxJava offre metodi di blocco su Flowable. I seguenti blocchi di codice bloccano il thread chiamante finché DataStore non restituisce i dati:

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

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

L'esecuzione di operazioni di I/O sincrone sul thread UI può causare errori ANR o UI che non risponde. Puoi mitigare questi problemi precaricando in modo asincrono i dati da DataStore:

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

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

In questo modo, DataStore legge i dati in modo asincrono e li memorizza nella cache in memoria. Le letture sincrone successive che utilizzano runBlocking() potrebbero essere più veloci o evitare del tutto un'operazione di I/O del disco se la lettura iniziale è stata completata.

Utilizzare DataStore nel codice multiprocesso

Puoi configurare DataStore per accedere agli stessi dati in processi diversi con le stesse proprietà di coerenza dei dati di un singolo processo. In particolare, DataStore fornisce:

• Le letture restituiscono solo i dati salvati su disco.
• Coerenza read-after-write.
• Le scritture vengono serializzate.
• Le letture non vengono mai bloccate dalle scritture.

Prendi in considerazione un'applicazione di esempio con un servizio e un'attività in cui il servizio viene eseguito in un processo separato e aggiorna periodicamente DataStore.

Questo esempio utilizza un datastore JSON, ma puoi utilizzare anche un datastore delle preferenze o proto.

@Serializable
data class Time(
    val lastUpdateMillis: Long
)

Un serializzatore indica a DataStore come leggere e scrivere il tipo di dati. Assicurati di includere un valore predefinito per il serializzatore da utilizzare se non è ancora stato creato alcun file. Di seguito è riportato un esempio di implementazione che utilizza 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()
        )
    }
}

Per poter utilizzare DataStore in diversi processi, devi creare l'oggetto DataStore utilizzando MultiProcessDataStoreFactory sia per l'app sia per il codice del servizio:

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

Aggiungi quanto segue a AndroidManifiest.xml:

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

Il servizio chiama periodicamente updateLastUpdateTime(), che scrive nel datastore utilizzando updateData.

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

L'app legge il valore scritto dal servizio utilizzando il flusso di dati:

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

Ora possiamo combinare tutte queste funzioni in una classe chiamata MultiProcessDataStore e utilizzarla in un'app.

Ecco il codice del servizio:

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()
    }
}

e il codice dell'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)
    }
}

Puoi utilizzare l'inserimento delle dipendenze Hilt in modo che l'istanza DataStore sia univoca per processo:

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

Gestire il danneggiamento dei file

In rari casi, il file persistente su disco di DataStore potrebbe danneggiarsi. Per impostazione predefinita, DataStore non esegue automaticamente il recupero in caso di danneggiamento e i tentativi di lettura causeranno la generazione di un errore CorruptionException.

DataStore offre un'API di gestione del danneggiamento che può aiutarti a eseguire il recupero in modo controllato in questo scenario ed evitare di generare l'eccezione. Se configurato, il gestore del danneggiamento sostituisce il file danneggiato con uno nuovo contenente un valore predefinito predefinito.

Per configurare questo gestore, fornisci un corruptionHandler quando crei l'istanza DataStore in by dataStore() o nel metodo factory DataStoreFactory:

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

Fornisci feedback

Condividi con noi il tuo feedback e le tue idee tramite queste risorse:

Issue Tracker:

Segnala i problemi per consentirci di correggere i bug.

Risorse aggiuntive

Per saperne di più su Jetpack DataStore, consulta le seguenti risorse aggiuntive:

Campioni

Blog

• Preferisci archiviare i dati con Jetpack DataStore

Codelab

• Utilizzare Preferences DataStore
• Utilizzare Proto DataStore