ストアとその機能
リポジトリは DataStore と話します。メモリ上のストア、SQL のストア (JdbcDataStore)、または別のパッケージが @UseStore の名前で登録したストアです。どのストアも、集約を検索し保存します。それ以外に何を持つかは、ストアが capabilities で伝えます。それ以上を使うリポジトリは、作成されるときに、メソッド、ストア、対処を示して失敗します。
使う理由
ストアはそれぞれ違います。REST API の上のストアには、参加するトランザクションも、ロックする行もありません。SQLite のデータベースには関数がありません。SQL のデータベースは、行の変更を報告しません。宣言された一覧がなければ、そのようなストアでの @Lock は黙って無視されるか、本番での最初の呼び出しで失敗します。一覧があれば、アプリケーションは起動せず、メッセージが何をすべきかを伝えます。
例
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 |
あり | あり | |
queries |
@Query の SQL |
なし | あり | |
functions |
@Procedure (データベース関数) |
なし | PostgreSQL で | FunctionDataStore |
changes |
変更のストリーム | あり | なし | ChangeStreamDataStore |
別のパッケージのストアには、それ自身の行があります。spring_boot_starter_supabase の supabase ストアは、functions と、Realtime があれば changes を持ち、最初の三つは持ちません。
リポジトリのストア
最初に当てはまるものが使われます。
- その
@UseStore('name')。 @UseDataSourceがあれば、SQL のストア。- 設定されていれば、
spring.data.store(memory、jdbc、または他のストアの名前)。 - プライマリーのデータソースがあれば
jdbc、なければmemory。
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)。
@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 なので、ストアは持っているものを宣言します。
@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 のない Map、List、Set をそこで拒否する。DataStoreDescriptor(collectionsNeedJson: true) は、同じチェックをビルドに求める。 |
これは、以前に書かれたストアにとっては破壊的な変更です。capabilities を追加しなければなりません。
コードで
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) は、そこにはそもそも存在しません。