# InvalidationTracker

Artifact: [androidx.room:room-runtime](https://developer.android.com/jetpack/androidx/releases/room) [View Source](https://cs.android.com/search?q=file:androidx/room/InvalidationTracker.+class:androidx.room.InvalidationTracker) Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

*** ** * ** ***

Common/AllAndroid/JVMNative/C/iOSJavaScript
- Cmn

  ```
  class InvalidationTracker
  ```
- android

  ```
  open class InvalidationTracker
  ```

*** ** * ** ***

The invalidation tracker keeps track of tables modified by queries and notifies its created `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html`s about such modifications.

A `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` tracking one or more tables can be created via `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker#createFlow(kotlin.Array,kotlin.Boolean)`. Once the `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` stream starts being collected, if a database operation changes one of the tables that the `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` was created from, then such table is considered 'invalidated' and the `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` will emit a new value.

## Summary

| ### Nested types |
|---|
| `abstract class https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker.Observer` An observer that can listen for changes in the database by subscribing to an `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker`. |

| ### Public functions |
|---|---|---|
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/WorkerThread https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker#addObserver(androidx.room.InvalidationTracker.Observer)(observer: https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker.Observer)` Adds the given observer to the observers list and it will be notified if any table it observes changes. | android |
| `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>>` | `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker#createFlow(kotlin.Array,kotlin.Boolean)(vararg tables: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, emitInitialState: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Creates a `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` that tracks modifications in the database and emits sets of the tables that were invalidated. | Cmn android N |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker#refreshAsync()()` Refresh created `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html`s asynchronously, emitting new values on those whose tables have been invalidated. | Cmn android N |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker#refreshVersionsAsync()()` Enqueues a task to refresh the list of updated tables. | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/WorkerThread https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker#removeObserver(androidx.room.InvalidationTracker.Observer)(observer: https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker.Observer)` Removes the observer from the observers list. | android |

## Public functions

### addObserver

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
@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 `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`.

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

| Parameters |
|---|---|
| `observer: https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker.Observer` | The observer which listens the database for changes. |

### createFlow

Cmn android N

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

Creates a `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` that tracks modifications in the database and emits sets of the tables that were invalidated.

The `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` will emit at least one value, a set of all the tables registered for observation to kick-start the stream unless `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker#createFlow(kotlin.Array,kotlin.Boolean)` is set to `false`.

If one of the tables to observe does not exist in the database, this functions throws an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`.

The returned `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` can be used to create a stream that reacts to changes in the database:

```kotlin
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)
  }
}
```

| Parameters |
|---|---|
| `vararg tables: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the tables or views to track. |
| `emitInitialState: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | Set to `false` if no initial emission is desired. Default value is `true`. |

### refreshAsync

Cmn android N Added in [2.7.0](https://developer.android.com/jetpack/androidx/releases/room#2.7.0)

```
fun refreshAsync(): Unit
```

Refresh created `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html`s 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 `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#useConnection(kotlin.Boolean,kotlin.coroutines.SuspendFunction1)` you might need to invoke this function manually to trigger invalidation.

### refreshVersionsAsync

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
open fun refreshVersionsAsync(): Unit
```

Enqueues a task to refresh the list of updated tables.

This method is automatically called when `https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase#endTransaction()` is called but if you have another connection to the database or directly use `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase`, you may need to call this manually.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker#refreshAsync()` |   |

### removeObserver

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0)

```
@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.

| Parameters |
|---|---|
| `observer: https://developer.android.com/reference/kotlin/androidx/room/InvalidationTracker.Observer` | The observer to remove. |