InvalidationTracker

@WorkerThread
open fun addObserver(observer: InvalidationTracker.Observer): Unit

Adds the given observer to the observers list and it will be notified if any table it observes changes.

Database changes are pulled on another thread so in some race conditions, the observer might be invoked for changes that were done before it is added.

If the observer already exists, this is a no-op call.

If one of the tables in the Observer does not exist in the database, this method throws an IllegalArgumentException.

This method should be called on a background/worker thread as it performs database operations.

fun createFlow(vararg tables: String, emitInitialState: Boolean = true): Flow<Set<String>>

Creates a Flow that tracks modifications in the database 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 functions throws an IllegalArgumentException.

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.invalidationTracker.createFlow("Artist").map { _ ->
    val artists = artistsDao.getAllArtists()
    val tours = tourService.fetchStates(artists.map { it.id })
    associateTours(artists, tours, from, to)
  }
}

fun refreshAsync(): Unit

Refresh created Flows asynchronously, emitting new values on those whose tables have been invalidated.

This function should be called after any write operation is performed on the database, such that tracked tables and its associated flows are notified if invalidated. In most cases Room will call this function automatically but if a write operation is performed on the database via another connection or through RoomDatabase.useConnection you might need to invoke this function manually to trigger invalidation.

open fun refreshVersionsAsync(): Unit

Enqueues a task to refresh the list of updated tables.

This method is automatically called when RoomDatabase.endTransaction is called but if you have another connection to the database or directly use androidx.sqlite.db.SupportSQLiteDatabase, you may need to call this manually.

@WorkerThread
open fun removeObserver(observer: InvalidationTracker.Observer): Unit

Removes the observer from the observers list.

This method should be called on a background/worker thread as it performs database operations.