行の変更

ストアによっては、行の変更を、コミットされるたびに報告します。リポジトリはそれを、二種類の派生メソッドとして二通りに渡します。条件に関わる変更のストリームである 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 のパラメーターもない。

ジェネレーターは、それぞれを定数の PartTree と、下で説明する operations.watch または operations.changes の呼び出しとして書きます。

変更のストリーム

RepositoryOperations.changes(tree, arguments) は、派生クエリの条件に関わる、コミットされた変更のストリームです。購読された瞬間から、購読がキャンセルされるまで続きます。

最新に保たれる結果

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) です。

関連項目