ストアとその機能

リポジトリは 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 を持ち、最初の三つは持ちません。

リポジトリのストア

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

  1. その @UseStore('name')。
  2. @UseDataSource があれば、SQL のストア。
  3. 設定されていれば、spring.data.store (memory、jdbc、または他のストアの名前)。
  4. プライマリーのデータソースがあれば 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',
  },
);

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

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

独自のストア

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) は、そこにはそもそも存在しません。

関連項目