Changes of rows

Some stores report the changes of their rows as they are committed. A repository gives them two ways, as two kinds of derived methods: changes…By, a stream of the changes that concern the conditions, and watch…By, the query's result, emitted again after every such change.

Why

A screen that shows a list wants to know when the list changed, not to ask every few seconds. Stores can tell: the in-memory store knows its own commits, and a store of another package can listen to its database (the supabase store does, through Realtime). One type for a change and one meaning of "concerns this query" let the same code work on any of them.

Example

abstract interface class Tasks implements CrudRepository<Task, int> {
  // The result of the query, emitted when the stream is listened to and
  // again after every change that concerns it.
  Stream<List<Task>> watchByListIdOrderByPositionAsc(int listId);

  // Every task: nothing after `By`, as `findAllBy()`.
  Stream<List<Task>> watchAllBy(Sort sort);

  // The inserts, updates and deletes of the rows the conditions match,
  // each with the row after and before.
  Stream<RowChange<Task>> changesByListId(int listId);
}
tasks.watchByListIdOrderByPositionAsc(7).listen(show);

tasks.changesByListId(7).listen((change) {
  if (change.kind == RowChangeKind.delete) {
    remove(change.id);
  } else {
    put(change.row!);
  }
});

RowChange

A RowChange<T> is one change of a row of an entity's table, reported once the change is committed:

Member Meaning
kind RowChangeKind.insert, update or delete.
row The row after the change: the new row of an insert or an update; null for a delete.
previous The row before the change, when the store knows it; null for an insert. Some stores report only the id of a deleted row, or nothing of an updated row's past.
id The id of the row, as the store holds it; null when the store does not tell.

Which stores

A store that reports changes says changes in its capabilities and implements ChangeStreamDataStore.

Store Changes
in memory yes: at commit, never from a transaction that rolls back
SQL (SQLite, PostgreSQL) no
supabase (spring_boot_starter_supabase) yes, with Realtime

A repository with a watch…By or a changes…By method on a store without them fails when it is created, and at build time when the build knows the store.

The two kinds of methods

They are derived methods, read like a derived query:

Prefix Returns Takes
watch…By Stream<List<T>>: the query's result, kept up to date What a find takes: First / Top, Distinct, OrderBy, a Sort or a Pageable parameter.
changes…By Stream<RowChange<T>>: the changes of the rows the conditions match Conditions only: no First, Top, Distinct or OrderBy in its name, no Sort or Pageable parameter.

The generator writes each as a constant PartTree and a call of operations.watch or operations.changes, described below.

A stream of changes

RepositoryOperations.changes(tree, arguments) is the stream of the committed changes that concern the conditions of a derived query, from the moment it is listened to until the subscription is cancelled.

A result kept up to date

RepositoryOperations.watch(tree, arguments, sort:, pageable:) emits the query's result when it is listened to, and again after every committed change that may concern it, by running the query again.

By hand

Without generated code (a library, a test) the two operations are called with the PartTree of a derived query:

const byGenre = PartTree('changesByGenre', [
  OrPart([Part('genre')]),
]);
const watchByGenre = PartTree(
  'watchByGenreOrderByTitle',
  [
    OrPart([Part('genre')]),
  ],
  sort: Sort([SortOrder.asc('title')]),
);

final books = RepositoryFactory(
  mappingContext: mappingContext,
  converter: converter,
  stores: [store],
).operations<Book, int>('Books', annotations: [UseStore(store.name)]);

books.changes(byGenre, [Genre.science]).listen(apply);
books.watch(watchByGenre, [Genre.science]).listen(show);

CriteriaMatcher

CriteriaMatcher tests an instance, a row or a RowChange against a Criteria without a database. It is what the in-memory store finds with, and what filters a stream of changes the store could not filter itself.

final matcher = CriteriaMatcher<Book>(
  entity,
  Criteria(tree.predicate, ['Dune']),
  converter: converter,
);
matcher.matches(book);                                  // an instance
matcher.matchesRow({'title': 'Dune', 'year': 1965});    // a row
matcher.concerns(change);                               // a RowChange

The conditions follow SQL: a comparison with null is false (IsNull and IsNotNull aside), IgnoreCase lower-cases both sides, Like takes % and _ with \ to escape them, Between is inclusive, a reference is compared by its id. A property that is not a column of the entity is an InvalidDataAccessApiUsageException when the matcher is made.

A store that reports changes

abstract interface class ChangeStreamDataStore implements DataStore {
  Stream<RowChange<T>> changes<T extends Object>(
    PersistentEntity<T> entity, {
    Criteria? criteria,
  });

  bool filtersChanges<T extends Object>(
    PersistentEntity<T> entity,
    Criteria criteria,
  );
}

changes reports from the moment the stream is listened to, each change after it is committed, until the subscription is cancelled. filtersChanges is false when the store cannot apply all of the criteria: the stream then holds more, and the caller tests each change itself.

In Spring (Java)

None in Spring Data JDBC. The nearest is Spring Data MongoDB's change streams (ChangeStreamEvent, ReactiveMongoOperations.changeStream).

See also