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. |
- Any other return type is a build error, naming the expected one.
- Nothing after
Bymeans every row:watchAllBy(),changesAllBy(). - No
@Lockon a watch method: it reads outside the caller's transaction. stream…Bykeeps its meaning: the result once, as a stream.
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 change concerns the conditions when the row after it or the row before it matches. So a row that stops matching is reported too.
- A change whose rows the store does not know always concerns them.
- A store filters as far as it can. One that cannot apply all of the conditions says so (
filtersChanges), and the operations test each change themselves, withCriteriaMatcher. - Cancelling the subscription stops the store's reporting.
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.
- The queries never overlap. Changes that arrive while one runs are answered by exactly one more query after it, however many they are. So the last list emitted is always read after the last change.
- A list is emitted after each query, also when it equals the one before.
- An error does not end the stream: an error of a query or of the store's changes is forwarded, and the next change queries again.
- A paused subscription queries nothing and catches up with one query when it resumes. The stream has one listener.
- Outside the caller's transaction. The queries run outside the transaction of the code that listens: listen outside a transaction, or expect the committed rows only.
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).