RoomDatabaseKt
public final class RoomDatabaseKt
Summary
Public methods |
|
|---|---|
static final @NonNull Flow<@NonNull Set<@NonNull String>> |
invalidationTrackerFlow(Creates a |
static final @NonNull R |
<R extends Object> useReaderConnection(Acquires a READ connection, suspending while waiting if none is available and then calling the |
static final @NonNull R |
<R extends Object> useWriterConnection(Acquires a WRITE connection, suspending while waiting if none is available and then calling the |
static final @NonNull R |
<R extends Object> withTransaction(Calls the specified suspending |
Public methods
invalidationTrackerFlow
public static final @NonNull Flow<@NonNull Set<@NonNull String>> invalidationTrackerFlow(
@NonNull RoomDatabase receiver,
@NonNull String tables,
boolean emitInitialState
)
Creates a Flow that listens for changes in the database via the InvalidationTracker and emits sets of the tables that were invalidated.
The Flow will emit at least one value, a set of all the tables registered for observation to kick-start the stream unless emitInitialState is set to false.
If one of the tables to observe does not exist in the database, this Flow throws an IllegalArgumentException during collection.
The returned Flow can be used to create a stream that reacts to changes in the database:
fun getArtistTours(from: Date, to: Date): Flow<Map<Artist, TourState>> {
return db.invalidationTrackerFlow("Artist").map { _ ->
val artists = artistsDao.getAllArtists()
val tours = tourService.fetchStates(artists.map { it.id })
associateTours(artists, tours, from, to)
}
}
useReaderConnection
public static final @NonNull R <R extends Object> useReaderConnection(
@NonNull RoomDatabase receiver,
@NonNull SuspendFunction1<@NonNull Transactor, @NonNull R> block
)
Acquires a READ connection, suspending while waiting if none is available and then calling the block to use the connection once it is acquired. A RoomDatabase will have one or more READ connections. The connection to use in the block is an instance of Transactor that provides the capabilities for performing nested transactions.
Using the connection after block completes is prohibited.
The connection will be confined to the coroutine on which block executes, attempting to use the connection from a different coroutine will result in an error.
If the current coroutine calling this function already has a confined connection, then that connection is used.
A connection is a limited resource and should not be held for more than it is needed. The best practice in using connections is to avoid executing long-running computations within the block. If a caller has to wait too long to acquire a connection a SQLiteException will be thrown due to a timeout.
| Parameters | |
|---|---|
@NonNull SuspendFunction1<@NonNull Transactor, @NonNull R> block |
The code to use the connection. |
| Throws | |
|---|---|
androidx.sqlite.SQLiteException |
when the database is closed or a thread confined connection needs to be upgraded or there is a timeout acquiring a connection. |
| See also | |
|---|---|
useWriterConnection |
useWriterConnection
public static final @NonNull R <R extends Object> useWriterConnection(
@NonNull RoomDatabase receiver,
@NonNull SuspendFunction1<@NonNull Transactor, @NonNull R> block
)
Acquires a WRITE connection, suspending while waiting if none is available and then calling the block to use the connection once it is acquired. A RoomDatabase will have only one WRITE connection. The connection to use in the block is an instance of Transactor that provides the capabilities for performing nested transactions.
Using the connection after block completes is prohibited.
The connection will be confined to the coroutine on which block executes, attempting to use the connection from a different coroutine will result in an error.
If the current coroutine calling this function already has a confined connection, then that connection is used as long as it isn't required to be upgraded to a writer. If an upgrade is required then a SQLiteException is thrown.
A connection is a limited resource and should not be held for more than it is needed. The best practice in using connections is to avoid executing long-running computations within the block. If a caller has to wait too long to acquire a connection a SQLiteException will be thrown due to a timeout.
| Parameters | |
|---|---|
@NonNull SuspendFunction1<@NonNull Transactor, @NonNull R> block |
The code to use the connection. |
| Throws | |
|---|---|
androidx.sqlite.SQLiteException |
when the database is closed or a thread confined connection needs to be upgraded or there is a timeout acquiring a connection. |
| See also | |
|---|---|
useReaderConnection |
withTransaction
public static final @NonNull R <R extends Object> withTransaction(
@NonNull RoomDatabase receiver,
@NonNull SuspendFunction0<@NonNull R> block
)
Calls the specified suspending block in a database transaction. The transaction will be marked as successful unless an exception is thrown in the suspending block or the coroutine is cancelled.
Room will only perform at most one transaction at a time, additional transactions are queued and executed on a first come, first serve order.
Performing blocking database operations is not permitted in a coroutine scope other than the one received by the suspending block. It is recommended that all Dao function invoked within the block be suspending functions.
The internal dispatcher used to execute the given block will block an utilize a thread from Room's transaction executor until the block is complete.