行の変更
ストアによっては、行の変更を、コミットされるたびに報告します。リポジトリはそれを、二種類の派生メソッドとして二通りに渡します。条件に関わる変更のストリームである changes…By と、そのような変更のたびにもう一度出されるクエリの結果である watch…By です。
使う理由
一覧を表示する画面は、数秒ごとに問い合わせるのではなく、一覧が変わったときに知りたいのです。ストアはそれを伝えられます。メモリ上のストアは自分のコミットを知っていて、別のパッケージのストアは自分のデータベースを購読できます (supabase ストアは Realtime を通してそうします)。変更のための一つの型と、「このクエリに関わる」の一つの意味があれば、同じコードがどのストアでも動きます。
例
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
RowChange<T> は、エンティティのテーブルの行の一つの変更で、変更がコミットされてから報告されます。
| メンバー | 意味 |
|---|---|
kind |
RowChangeKind.insert、update、delete のいずれか。 |
row |
変更後の行。挿入または更新の新しい行。削除では null。 |
previous |
変更前の行 (ストアが知っている場合)。挿入では null。ストアによっては、削除された行の ID だけを報告したり、更新された行の過去を何も報告しなかったりする。 |
id |
ストアが持つ、その行の ID。ストアが伝えない場合は null。 |
どのストアか
変更を報告するストアは、機能に changes を持ち、ChangeStreamDataStore を実装します。
| ストア | 変更 |
|---|---|
| メモリ上 | あり。コミット時に報告し、ロールバックするトランザクションからは決して報告しない |
| SQL (SQLite、PostgreSQL) | なし |
supabase (spring_boot_starter_supabase) |
あり (Realtime がある場合) |
変更のないストアで watch…By や changes…By のメソッドを持つリポジトリは、作成されるときに失敗し、ビルドがストアを知っている場合はビルド時に失敗します。
二種類のメソッド
どちらも派生メソッドで、派生クエリと同じように読まれます。
| プレフィックス | 戻り値 | 受け取るもの |
|---|---|---|
watch…By |
Stream<List<T>>: 最新に保たれるクエリの結果 |
find が受け取るもの: First / Top、Distinct、OrderBy、Sort または Pageable のパラメーター。 |
changes…By |
Stream<RowChange<T>>: 条件に一致する行の変更 |
条件だけ。名前に First、Top、Distinct、OrderBy は書けず、Sort や Pageable のパラメーターもない。 |
- それ以外の戻り値の型はビルドエラーで、期待される型が示されます。
Byの後に何もなければ、すべての行です。watchAllBy()、changesAllBy()。- watch メソッドに
@Lockは付けられません。 呼び出し元のトランザクションの外で読むためです。 stream…Byの意味は変わりません。結果を一度だけ、ストリームとして渡します。
ジェネレーターは、それぞれを定数の PartTree と、下で説明する operations.watch または operations.changes の呼び出しとして書きます。
変更のストリーム
RepositoryOperations.changes(tree, arguments) は、派生クエリの条件に関わる、コミットされた変更のストリームです。購読された瞬間から、購読がキャンセルされるまで続きます。
- 変更が条件に関わるのは、変更後の行か変更前の行が一致するときです。そのため、一致しなくなった行も報告されます。
- ストアが行を知らない変更は、常に条件に関わるものとして扱われます。
- ストアは、できる範囲で絞ります。 条件のすべてを適用できないストアはそう伝え (
filtersChanges)、操作がCriteriaMatcherで各変更を自分で検査します。 - 購読をキャンセルすると、ストアの報告は止まります。
最新に保たれる結果
RepositoryOperations.watch(tree, arguments, sort:, pageable:) は、購読されたときにクエリの結果を出し、それに関わるかもしれない変更がコミットされるたびに、クエリをもう一度実行して結果を出します。
- クエリが重なることはありません。 クエリの実行中に届いた変更は、いくつあっても、その後のちょうど一回のクエリで処理されます。そのため、最後に出される一覧は、常に最後の変更の後に読まれたものです。
- 一覧は、クエリのたびに出されます。 前のものと同じでも出されます。
- エラーはストリームを終わらせません。 クエリやストアの変更のエラーは転送され、次の変更がもう一度クエリを実行します。
- 一時停止した購読は何もクエリせず、再開したときに一回のクエリで追いつきます。このストリームの購読者は一つです。
- 呼び出し元のトランザクションの外で。 クエリは、購読するコードのトランザクションの外で実行されます。トランザクションの外で購読するか、コミットされた行だけが来るものと考えてください。
手で呼び出す
生成されたコードがない場合 (ライブラリ、テスト)、二つの操作は、派生クエリの PartTree を渡して呼び出します。
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 は、データベースなしで、インスタンス、行、RowChange を Criteria に対して検査します。メモリ上のストアが検索に使うもので、ストアが自分で絞れなかった変更のストリームを絞るものでもあります。
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
条件は SQL に従います。null との比較は偽で (IsNull と IsNotNull は別)、IgnoreCase は両辺を小文字にし、Like は % と _ を取り (\ でエスケープ)、Between は両端を含み、参照はその ID で比較されます。エンティティの列でないプロパティは、マッチャーが作られるときに InvalidDataAccessApiUsageException になります。
変更を報告するストア
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 は、ストリームが購読された瞬間から、各変更をコミットの後に、購読がキャンセルされるまで報告します。filtersChanges は、ストアが条件のすべてを適用できないときに false です。その場合、ストリームにはより多くの変更が含まれ、呼び出し元が各変更を自分で検査します。
Spring (Java) との対応
Spring Data JDBC にはありません。最も近いのは、Spring Data MongoDB の変更ストリーム (ChangeStreamEvent、ReactiveMongoOperations.changeStream) です。