Google is committed to advancing racial equity for Black communities. See how.

SharedPreferencesMigration

class SharedPreferencesMigration<T> : DataMigration<T>
kotlin.Any
   ↳ androidx.datastore.migrations.SharedPreferencesMigration

DataMigration from SharedPreferences to DataStore.

Example usage:

val sharedPrefsMigration = SharedPreferencesMigration( context, mySharedPreferencesName ) { prefs: SharedPreferencesView, myData: MyData -> myData.toBuilder().setCounter(prefs.getCounter(COUNTER_KEY, default = 0)).build() }

Summary

Public constructors
<init>(context: Context, sharedPreferencesName: String, keysToMigrate: Set<String>? = MIGRATE_ALL_KEYS, deleteEmptyPreferences: Boolean = true, shouldRunMigration: suspend (T) -> Boolean = { true }, migrate: suspend (SharedPreferencesView, T) -> T)

DataMigration from SharedPreferences to DataStore.

Public methods
suspend Unit

Clean up any old state/data that was migrated into the DataStore.

suspend T
migrate(currentData: T)

Perform the migration.

suspend Boolean
shouldMigrate(currentData: T)

Return whether this migration needs to be performed.

Public constructors

<init>

SharedPreferencesMigration(
    context: Context,
    sharedPreferencesName: String,
    keysToMigrate: Set<String>? = MIGRATE_ALL_KEYS,
    deleteEmptyPreferences: Boolean = true,
    shouldRunMigration: suspend (T) -> Boolean = { true },
    migrate: suspend (SharedPreferencesView, T) -> T)

DataMigration from SharedPreferences to DataStore.

Example usage:

val sharedPrefsMigration = SharedPreferencesMigration( context, mySharedPreferencesName ) { prefs: SharedPreferencesView, myData: MyData -> myData.toBuilder().setCounter(prefs.getCounter(COUNTER_KEY, default = 0)).build() }

Parameters
context: Context Context used for getting SharedPreferences.
sharedPreferencesName: String The name of the SharedPreferences.
keysToMigrate: Set<String>? = MIGRATE_ALL_KEYS The list of keys to migrate. The keys will be mapped to datastore .Preferences with their same values. If the key is already present in the new Preferences, the key will not be migrated again. If the key is not present in the SharedPreferences it will not be migrated. If keysToMigrate is null, all keys will be migrated from the existing SharedPreferences.
deleteEmptyPreferences: Boolean = true If enabled and the SharedPreferences are empty (i.e. no remaining keys) after this migration runs, the leftover SharedPreferences file is deleted. Note that this cleanup runs only if the migration itself runs, i.e., if the keys were never in SharedPreferences to begin with then the (potentially) empty SharedPreferences won't be cleaned up by this option. This functionality is best effort - if there is an issue deleting the SharedPreferences file it will be silently ignored.
migrate: suspend (SharedPreferencesView, T) -> T maps SharedPreferences into T. Implementations should be idempotent since this may be called multiple times. See DataMigration.migrate for more information. The lambda accepts a SharedPreferencesView which is the view of the SharedPreferences to migrate from (limited to keysToMigrate and a T which represent the current data. The function must return the migrated data.

Public methods

cleanUp

suspend fun cleanUp(): Unit

Clean up any old state/data that was migrated into the DataStore. This will not be called if the migration fails. If cleanUp throws an exception, the exception will be propagated back to the DataStore call that triggered the migration and future calls to DataStore will result in DataMigrations being attempted again. This method may be run multiple times when any failure is encountered.

migrate

suspend fun migrate(currentData: T): T

Perform the migration. Implementations should be idempotent since this may be called multiple times. If migrate fails, DataStore will not commit any data to disk, cleanUp will not be called, and the exception will be propagated back to the DataStore call that triggered the migration. Future calls to DataStore will result in DataMigrations being attempted again. This method may be run multiple times when any failure is encountered.

Note that this will always be called before a call to cleanUp.

Parameters
currentData: T the current data (it might be populated from other migrations or from manual changes before this migration was added to the app)
Return
The migrated data.

shouldMigrate

suspend fun shouldMigrate(currentData: T): Boolean

Return whether this migration needs to be performed. If this returns false, no migration or cleanup will occur. Apps should do the cheapest possible check to determine if this migration should run, since this will be called every time the DataStore is initialized. This method may be run multiple times when any failure is encountered.

Note that this will always be called before each call to migrate.

Parameters
currentData: T the current data (which might already populated from previous runs of this or other migrations)