
# ストアとその機能

リポジトリは `DataStore` と話します。メモリ上のストア、SQL のストア (`JdbcDataStore`)、または別のパッケージが `@UseStore` の名前で登録したストアです。どのストアも、集約を検索し保存します。それ以外に何を持つかは、ストアが `capabilities` で伝えます。それ以上を使うリポジトリは、作成されるときに、メソッド、ストア、対処を示して失敗します。

## 使う理由

ストアはそれぞれ違います。REST API の上のストアには、参加するトランザクションも、ロックする行もありません。SQLite のデータベースには関数がありません。SQL のデータベースは、行の変更を報告しません。宣言された一覧がなければ、そのようなストアでの `@Lock` は黙って無視されるか、本番での最初の呼び出しで失敗します。一覧があれば、アプリケーションは起動せず、メッセージが何をすべきかを伝えます。

## 例

```text
Invalid repository StockRepository:
  - StockRepository.findBySku: @Lock needs a store with row locks, and the
    rest store is none: use a SQL store (@UseStore('jdbc') with
    spring.datasource.url), or remove @Lock (a @Version checks concurrent
    writes without a lock)
```

リポジトリのすべての問題が、同じ一覧に入ります。

## 機能

| 機能 | 使うもの | メモリ | SQL | ストアのインターフェース |
|---|---|---|---|---|
| `transactions` | `@Transactional`、リポジトリのアトミックな書き込み | あり | あり | `TransactionalDataStore` |
| `locks` | [`@Lock`](locks.md) | あり | あり | |
| `queries` | [`@Query`](query.md) の SQL | なし | あり | |
| `functions` | [`@Procedure`](database-functions.md) (データベース関数) | なし | PostgreSQL で | `FunctionDataStore` |
| `changes` | [変更のストリーム](changes.md) | あり | なし | `ChangeStreamDataStore` |

別のパッケージのストアには、それ自身の行があります。[spring_boot_starter_supabase](../spring-boot-starter-supabase/data.md) の `supabase` ストアは、`functions` と、Realtime があれば `changes` を持ち、最初の三つは持ちません。

## リポジトリのストア

最初に当てはまるものが使われます。

1. その `@UseStore('name')`。
2. `@UseDataSource` があれば、SQL のストア。
3. 設定されていれば、`spring.data.store` (`memory`、`jdbc`、または他のストアの名前)。
4. プライマリーのデータソースがあれば `jdbc`、なければ `memory`。

```properties
spring.data.store=memory
```

どのストアにもない名前は、リポジトリが作成されるときに、存在するストアを示して失敗させます。

## 検査されること

リポジトリが作成されるとき、それが使うものが一つずつ、ストアと比較されます。

| リポジトリにあるもの | 必要な機能 | ない場合 |
|---|---|---|
| メソッドの `@Lock` | `locks` | 「SQL のストアを使うか、`@Lock` を外す (`@Version` は、ロックなしで同時の書き込みを検査する)」 |
| インターフェースの `@Transactional` | `transactions` | 「SQL のストアを使うか、`@Transactional` を外して、アトミックな処理を一つのデータベース関数 (`@Procedure`) で行う」 |
| `@Query` | `queries` | 「`spring.datasource.url` を設定してドライバーを追加するか、派生クエリを書く」 |
| `@Procedure` | `functions` | 「データベースに関数があるストア (PostgreSQL) を使うか、処理をリポジトリの呼び出しとして書く」 |
| 変更のストリーム | `changes` | 「変更を報告するストア (メモリのストア) を使うか、`Future` を返して、データが変わったかもしれないときにもう一度クエリする」 |

機能は、データベースに依存することがあります。SQL のストアは、PostgreSQL では `functions` を持ち、SQLite では持ちません。それは、アプリケーションの起動時に伝えられます。

## ビルドによる検査

パッケージは、その `lib/spring_auto_configuration.dart` の中の (またはそこからエクスポートされる) 定数で、自分のストアをビルドに記述します。スターターも同じ方法で `memory` と `jdbc` を記述しています (`memoryStore`、`jdbcStore`)。

```dart
@DataStoreDeclaration()
const documentStore = DataStoreDescriptor(
  'documents',
  capabilities: DataStoreCapabilities(changes: true),
  // The default store when the application's application.yml (without a
  // profile) sets every `whenProperty` and none of `unlessProperty`.
  defaultWhen: DataStoreDefault(
    whenProperty: ['documents.url'],
    unlessProperty: ['spring.datasource.url', 'spring.data.store'],
  ),
  // The store's own fix for what it lacks, said before the general one.
  fixes: {
    DataStoreCapability.transactions:
        'set documents.sql-url to keep the documents in SQL',
  },
);
```

ビルドがリポジトリのストアを知っていて、そのストアが記述されている場合、上のエラーはビルドエラーになり、リポジトリの問題の一覧に入ります。ビルドは、次のものからストアを知ります。

- リポジトリの `@UseStore` または `@UseDataSource`。
- `application.yml` または `application.properties` (プロファイルのないファイル) の `spring.data.store`。
- `defaultWhen` が成り立つ、最初の記述されたストア。

そこから、次のことも決まります。

- **任意の Bean の `@Transactional`** (`transactionManager:` なし) は、アプリケーションのデフォルトのストアがトランザクションなしと記述されている場合、ビルドエラーになります。
- **データベースに依存する機能** (SQL のストアの `functions`) は `true` と宣言され、起動時に決まります。動くかもしれないものを、ビルドが拒否してはならないためです。
- **何も記述していないストア**は、起動時にだけ検査されます。ビルドがストアを判断できないリポジトリも同じです。
- 定数の `DataStoreDescriptor` 以外に付けた `@DataStoreDeclaration` は、ビルドエラーです。

## 独自のストア

`DataStore` には、`DataStoreCapabilities get capabilities` というメンバーがあります。指定しない限りすべて `false` なので、ストアは持っているものを宣言します。

```dart
@override
DataStoreCapabilities get capabilities =>
    const DataStoreCapabilities(transactions: true, locks: true);
```

| 機能 | ストアが実装するもの |
|---|---|
| `transactions` | `TransactionalDataStore`: `transactionManager`。リポジトリと `@DataTest` が使うマネージャー。 |
| `functions` | `FunctionDataStore`: `callFunction(name, arguments)`。 |
| `changes` | `ChangeStreamDataStore`: `changes(entity, criteria:)` と `filtersChanges(entity, criteria)`。 |
| データベースの形式のままの行 | `RowReadingDataStore`: `valueReader` と `readAggregates`。`@Procedure` の結果を読むために使われる。 |
| エンティティのうち保持できないもの | `EntityCheckingDataStore`: `mappingProblems(entity)`。リポジトリが作られるときに呼ばれる。SQL のストアは、[`@Json`](json-columns.md) のない `Map`、`List`、`Set` をそこで拒否する。`DataStoreDescriptor(collectionsNeedJson: true)` は、同じチェックをビルドに求める。 |

これは、以前に書かれたストアにとっては破壊的な変更です。`capabilities` を追加しなければなりません。

## コードで

```dart
Future<void> refreshTotals(DataStore store) async {
  if (store.capabilities.functions && store is FunctionDataStore) {
    await store.callFunction('refresh_totals', const {});
  }
}

store.capabilities.supports(DataStoreCapability.locks);   // the same, by the enum
```

`DataStoreCapability` は enum です (`transactions`、`locks`、`queries`、`functions`、`changes`)。各値は、そのエラーの言葉 (`usedBy`、`need`、`fix`) を持ちます。`StoreRequirement(method, capability)` は、一つのメソッドが必要とするものです。`RepositoryFactory.operations(requirements:)` がそれを受け取ります。

## Spring (Java) との対応

対応するものはありません。Spring Data にはストアごとにモジュールがあり、モジュールにない機能 (Spring Data Redis での `@Lock`) は、そこにはそもそも存在しません。

## 関連項目

- [リポジトリ](repositories.md)
- [データベース関数](database-functions.md)
- [行の変更](changes.md)
- [ロック](locks.md)
- [すべてのプロパティ](properties.md)
- [ジェネレーターとデータ](../spring-core-dart-generator/data.md)
- [Supabase: データ](../spring-boot-starter-supabase/data.md)
