DataMigration
Interface for migrations to DataStore. Methods on this migration (shouldMigrate, migrate and cleanUp) may be called multiple times, so their implementations must be idempotent. These methods may be called multiple times if DataStore encounters issues when writing the newly migrated data to disk or if any migration installed in the same DataStore throws an Exception.
If you're migrating from SharedPreferences see SharedPreferencesMigration.
Functions
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.
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.
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.