Spring Data Couchbase 3.x から 4.x への移行

この章は、4.x に導入された主な変更点のクイックリファレンスであり、移行時に考慮すべき事項の概要を示します。

Couchbase サーバーの最小バージョンは暗黙的に 5.5 以降にプルアップられており、少なくとも 6.0.x を実行することをお勧めします。

構成

主な目的は Java SDK 2 から 3 に移行することであったため、新しい SDK に適応するように構成が変更され、長期的にはスコープとコレクションを準備するために構成が変更されました (ただし、コレクションのサポートなしでも使用できます)。

XML 構成のサポートは廃止されたため、java/ アノテーションベースの構成のみがサポートされます。

設定は依然として AbstractCouchbaseConfiguration を継承する必要がありますが、RBAC (ロールベースのアクセス制御) が必須になっているため、設定するにはさまざまなプロパティをオーバーライドする必要があります: getConnectionString、getUserName、getPassword、getBucketName。デフォルト以外のスコープをオプションで使用したい場合は、次のようにすることができます。getScopeName メソッドをオーバーライドします。証明書ベースの認証を使用する場合、またはパスワード認証をカスタマイズする必要がある場合は、authenticator メソッドをオーバーライドしてこのタスクを実行できることに注意してください。

新しい SDK には構成に使用される環境がまだ残っているため、必要に応じて configureEnvironment メソッドをオーバーライドしてカスタム構成を提供できます。

詳しくは、インストールと構成を参照してください。

Spring Boot バージョンの互換性

Spring Boot 2.3.x 以降は Spring Data Couchbase 4.x に依存します。SDK 2 と 3 は同じクラスパス上に存在できないため、Couchbase の以前のバージョンは使用できません。

エンティティ

エンティティの処理方法は変更されていませんが、SDK ではアノテーションが提供されなくなったため、Spring-Data 関連のアノテーションのみがサポートされます。

具体的には:

com.couchbase.client.java.repository.annotation.Id が import org.springframework.data.annotation.Id になりました
com.couchbase.client.java.repository.annotation.Field が import org.springframework.data.couchbase.core.mapping.Field になりました

org.springframework.data.couchbase.core.mapping.Document アノテーションは変わりません。

詳しくは、エンティティのモデリングを参照してください。

自動インデックス管理

自動インデックス管理が再設計され、より柔軟なインデックス作成が可能になりました。新しいアノテーションが導入され、@ViewIndexed、@N1qlSecondaryIndexed、@N1qlPrimaryIndexed などの古いアノテーションが削除されました。

詳しくは、自動インデックス管理を参照してください。

テンプレートと ReactiveTemplate

Couchbase SDK 3 では RxJava のサポートが削除され、代わりに Reactor のサポートが追加されているため、couchbaseTemplate と reactiveCouchbaseTemplate の両方に AbstractCouchbaseConfiguration から直接アクセスできます。

テンプレートは完全に見直され、多くのメソッドオーバーロードの代わりに流れるような API を使用して構成するようになりました。これには、将来、ナビゲートを複雑にするオーバーロードをさらに導入することなく機能を継承できるという利点があります。

次の表では、3.x のメソッド名について説明し、4.x の同等のメソッド名と比較しています。

表 1: テンプレートメソッドの比較
SDC 3.x	SDC 4.x
save	Id による更新挿入
insert	Id による挿入
update	Id による置き換え
findById	findById
findByView	(削除されました)
findBySpatialView	(削除されました)
N1QL で見つける	findByQuery
findByN1QLProjection	findByQuery
クエリ N1QL	(SDK を直接呼び出す)
exists	existsById
remove	ID による削除
execute	(SDK を直接呼び出す)

さらに、3.x では利用できなかった次のメソッドが追加されました。

表 2: 4.x でのテンプレートの追加
名前	説明
removeByQuery	N1QL クエリを通じてエンティティを削除できるようにします
findByAnalytics	分析サービスを通じて検索を実行します
findFromReplicasById	findById と似ていますが、レプリカが考慮されます

API を基盤となる SDK セマンティクスに近づけて統合し、連携させ、相互に関連付けて操作しやすくすることを試みました。

詳しくは、テンプレートと直接操作を参照してください。

リポジトリとクエリ

org.springframework.data.couchbase.core.query.Query が org.springframework.data.couchbase.repository.Query になりました
org.springframework.data.couchbase.repository.ReactiveCouchbaseSortingRepository は削除されました。ReactiveSortingRepository または ReactiveCouchbaseRepository の拡張を検討してください
org.springframework.data.couchbase.repository.CouchbasePagingAndSortingRepository は削除されました。PagingAndSortingRepository または CouchbaseRepository の拡張を検討してください

ビューのサポートは削除され、N1QL クエリは、すべてのカスタムリポジトリメソッドおよびデフォルトの組み込みメソッドの第一級オブジェクトになりました。

動作自体は、クエリ導出がどのように機能するかについて、以前のバージョンから変更されていません。以前は機能していたが現在は機能しなくなったクエリが発生した場合は、お知らせください。

新しい ScanConsistency アノテーションを使用して、N1QL クエリのデフォルトのスキャン一貫性をオーバーライドすることができます。

メソッド getCouchbaseOperations() も削除されました。クラス CouchbaseTemplate または Cluster を介して、ネイティブ Java SDK からすべてのメソッドに引き続きアクセスできます。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.couchbase.core.CouchbaseTemplate;
import org.springframework.stereotype.Service;
import com.couchbase.client.java.Cluster;

@Service
public class MyService {

    @Autowired
    private CouchbaseTemplate couchbaseTemplate;

    @Autowired
    private Cluster cluster;
}

詳細については、Couchbase リポジトリを参照してください。

全文検索 (FTS)

FTS API は簡素化され、Cluster クラス経由でアクセスできるようになりました。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.couchbase.client.java.Cluster;
import com.couchbase.client.java.search.result.SearchResult;
import com.couchbase.client.java.search.result.SearchRow;
import com.couchbase.client.core.error.CouchbaseException;

@Service
public class MyService {

    @Autowired
    private Cluster cluster;

    public void myMethod() {
        try {
          final SearchResult result = cluster
            .searchQuery("index", SearchQuery.queryString("query"));

          for (SearchRow row : result.rows()) {
            System.out.println("Found row: " + row);
          }

          System.out.println("Reported total rows: "
            + result.metaData().metrics().totalRows());
        } catch (CouchbaseException ex) {
          ex.printStackTrace();
        }
    }
}

詳細については、FTS ドキュメント (英語) を参照してください。