DataStoreFactory

Public factory for creating DataStore instances.

Summary

Public functions
DataStore<T>
<T : Any?> create(
    storage: Storage<T>,
    corruptionHandler: ReplaceFileCorruptionHandler<T>?,
    migrations: List<DataMigration<T>>,
    scope: CoroutineScope
)
Cmn
android
DataStore<T>
<T : Any?> create(
    serializer: Serializer<T>,
    corruptionHandler: ReplaceFileCorruptionHandler<T>?,
    migrations: List<DataMigration<T>>,
    scope: CoroutineScope,
    produceFile: () -> File
)

Create an instance of SingleProcessDataStore.
android
DataStore<T>
<T : Any?> create(
    serializer: Serializer<T>,
    corruptionHandler: ReplaceFileCorruptionHandler<T>?,
    migrations: List<DataMigration<T>>,
    scope: CoroutineScope,
    produceFile: () -> File
)

Create an instance of SingleProcessDataStore.
android
DataStore<T>
@RequiresApi(value = 24)
<T : Any?> createInDeviceProtectedStorage(
    context: Context,
    fileName: String,
    serializer: Serializer<T>,
    corruptionHandler: ReplaceFileCorruptionHandler<T>?,
    migrations: List<DataMigration<T>>,
    scope: CoroutineScope
)

Create an instance of SingleProcessDataStore that can be used during direct boot.
android

Public functions

create

Cmn android 
fun <T : Any?> create(
    storage: Storage<T>,
    corruptionHandler: ReplaceFileCorruptionHandler<T>? = null,
    migrations: List<DataMigration<T>> = listOf(),
    scope: CoroutineScope = CoroutineScope(ioDispatcher() + SupervisorJob())
): DataStore<T>

create

android 
fun <T : Any?> create(
    serializer: Serializer<T>,
    corruptionHandler: ReplaceFileCorruptionHandler<T>? = null,
    migrations: List<DataMigration<T>> = listOf(),
    scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob()),
    produceFile: () -> File
): DataStore<T>

Create an instance of SingleProcessDataStore. Never create more than one instance of DataStore for a given file; doing so can break all DataStore functionality. You should consider managing your DataStore instance as a singleton. If there are multiple DataStores active, DataStore will throw IllegalStateException when reading or updating data. A DataStore is considered active as long as its scope is active.

T is the type DataStore acts on. The type T must be immutable. Mutating a type used in DataStore invalidates any guarantees that DataStore provides and will result in potentially serious, hard-to-catch bugs. We strongly recommend using protocol buffers: https://developers.google.com/protocol-buffers/docs/javatutorial - which provides immutability guarantees, a simple API and efficient serialization.

It is important to note that if a produceFile lambda to produce a file in the User Encrypted (UE) storage via a Context is used, this file will not be available during direct boot, and may result in a DirectBootUsageException via a java.io.FileNotFoundException or a silent failure. To create an instance of a DataStore to be used safely during direct boot mode, please use createInDeviceProtectedStorage.

Parameters
serializer: Serializer<T>

Serializer for the type T used with DataStore. The type T must be immutable.
corruptionHandler: ReplaceFileCorruptionHandler<T>? = null

The corruptionHandler is invoked if DataStore encounters a CorruptionException when attempting to read data. CorruptionExceptions are thrown by serializers when data can not be de-serialized.
migrations: List<DataMigration<T>> = listOf()

Migrations are run before any access to data can occur. Migrations must be idempotent.
scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob())

The scope in which IO operations and transform functions will execute.
produceFile: () -> File

Function which returns the file that the new DataStore will act on. The function must return the same path every time. No two instances of DataStore should act on the same file at the same time.
Returns
DataStore<T>

a new DataStore instance with the provided configuration

create

android 
fun <T : Any?> create(
    serializer: Serializer<T>,
    corruptionHandler: ReplaceFileCorruptionHandler<T>? = null,
    migrations: List<DataMigration<T>> = listOf(),
    scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob()),
    produceFile: () -> File
): DataStore<T>

Create an instance of SingleProcessDataStore. Never create more than one instance of DataStore for a given file; doing so can break all DataStore functionality. You should consider managing your DataStore instance as a singleton. If there are multiple DataStores active, DataStore will throw IllegalStateException when reading or updating data. A DataStore is considered active as long as its scope is active.

T is the type DataStore acts on. The type T must be immutable. Mutating a type used in DataStore invalidates any guarantees that DataStore provides and will result in potentially serious, hard-to-catch bugs. We strongly recommend using protocol buffers: https://developers.google.com/protocol-buffers/docs/javatutorial - which provides immutability guarantees, a simple API and efficient serialization.

Parameters
serializer: Serializer<T>

Serializer for the type T used with DataStore. The type T must be immutable.
corruptionHandler: ReplaceFileCorruptionHandler<T>? = null

The corruptionHandler is invoked if DataStore encounters a CorruptionException when attempting to read data. CorruptionExceptions are thrown by serializers when data can not be de-serialized.
migrations: List<DataMigration<T>> = listOf()

Migrations are run before any access to data can occur. Migrations must be idempotent.
scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob())

The scope in which IO operations and transform functions will execute.
produceFile: () -> File

Function which returns the file that the new DataStore will act on. The function must return the same path every time. No two instances of DataStore should act on the same file at the same time.
Returns
DataStore<T>

a new DataStore instance with the provided configuration

createInDeviceProtectedStorage

android 
@RequiresApi(value = 24)
fun <T : Any?> createInDeviceProtectedStorage(
    context: Context,
    fileName: String,
    serializer: Serializer<T>,
    corruptionHandler: ReplaceFileCorruptionHandler<T>? = null,
    migrations: List<DataMigration<T>> = listOf(),
    scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob())
): DataStore<T>

Create an instance of SingleProcessDataStore that can be used during direct boot.

This API always creates the DataStore in the Device Encrypted storage.

Parameters
context: Context

The DeviceProtectedStorageContext which will be used to create the file that the new DataStore will act on.
fileName: String

the filename relative to Context.createDeviceProtectedStorageContext().filesDir that DataStore acts on. The File is obtained from deviceProtectedDataStoreFile. It is created in the "/datastore" subdirectory, in the device encrypted storage.
serializer: Serializer<T>

Serializer for the type T used with DataStore. The type T must be immutable.
corruptionHandler: ReplaceFileCorruptionHandler<T>? = null

The corruptionHandler is invoked if DataStore encounters a CorruptionException when attempting to read data. CorruptionExceptions are thrown by serializers when data can not be de-serialized.
migrations: List<DataMigration<T>> = listOf()

Migrations are run before any access to data can occur. Migrations must be idempotent.
scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob())

The scope in which IO operations and transform functions will execute.
Returns
DataStore<T>

a new DataStore instance with the provided configuration