
# 行の変更

ストアによっては、行の変更を、コミットされるたびに報告します。リポジトリはそれを、二種類の派生メソッドとして二通りに渡します。条件に関わる変更のストリームである `changes…By` と、そのような変更のたびにもう一度出されるクエリの結果である `watch…By` です。

## 使う理由

一覧を表示する画面は、数秒ごとに問い合わせるのではなく、一覧が変わったときに知りたいのです。ストアはそれを伝えられます。メモリ上のストアは自分のコミットを知っていて、別のパッケージのストアは自分のデータベースを購読できます (`supabase` ストアは Realtime を通してそうします)。変更のための一つの型と、「このクエリに関わる」の一つの意味があれば、同じコードがどのストアでも動きます。

## 例

```dart
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);
}
```

```dart
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`。 |

## どのストアか

変更を報告するストアは、[機能](stores.md)に `changes` を持ち、`ChangeStreamDataStore` を実装します。

| ストア | 変更 |
|---|---|
| メモリ上 | あり。コミット時に報告し、ロールバックするトランザクションからは決して報告しない |
| SQL (SQLite、PostgreSQL) | なし |
| `supabase` ([spring_boot_starter_supabase](../spring-boot-starter-supabase/realtime.md)) | あり (Realtime がある場合) |

変更のないストアで `watch…By` や `changes…By` のメソッドを持つリポジトリは、作成されるときに失敗し、ビルドがストアを知っている場合はビルド時に失敗します。

## 二種類のメソッド

どちらも派生メソッドで、[派生クエリ](derived-queries.md)と同じように読まれます。

| プレフィックス | 戻り値 | 受け取るもの |
|---|---|---|
| `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` を渡して呼び出します。

```dart
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` に対して検査します。メモリ上のストアが検索に使うもので、ストアが自分で絞れなかった変更のストリームを絞るものでもあります。

```dart
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` になります。

## 変更を報告するストア

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

## 関連項目

- [ストアとその機能](stores.md)
- [派生クエリ](derived-queries.md)
- [ジェネレーターとデータ](../spring-core-dart-generator/data.md)
- [Supabase Realtime](../spring-boot-starter-supabase/realtime.md)
