CouchbaseSDKforJavaの概要

投稿日: 2019-10-19 2022-10-28
タグ: Couchbase, NoSQL, Persistence

1. 序章

このCouchbaseSDKfor Javaの概要では、Couchbase環境の作成、クラスターへの接続、データバケットのオープン、基本的な永続化操作の使用、ドキュメントの操作などの基本的な概念をカバーし、Couchbaseドキュメントデータベースを操作する方法を示します。レプリカ。

2. Mavenの依存関係

Mavenを使用している場合は、pom.xmlファイルに以下を追加します。

<dependency>
    <groupId>com.couchbase.client</groupId>
    <artifactId>java-client</artifactId>
    <version>2.2.6</version>
</dependency>

3. 入門

SDKは、 CouchbaseEnvironment インターフェイスと、クラスターおよびバケットへのアクセスを管理するためのデフォルト設定を含む実装クラスDefaultCouchbaseEnvironmentを提供します。セクション3.2で説明するように、必要に応じてデフォルトの環境設定を上書きできます。

重要：公式のCouchbase SDKドキュメントでは、JVMでアクティブな CouchbaseEnvironment が1つだけであることを確認するようにユーザーに警告しています。これは、2つ以上を使用すると予期しない動作が発生する可能性があるためです。

3.1. デフォルト環境でのクラスターへの接続

SDKにデフォルト設定でCouchbaseEnvironmentを自動的に作成させ、それをクラスターに関連付けるには、クラスター内の1つ以上のノードのIPアドレスまたはホスト名を指定するだけでクラスターに接続できます。

この例では、ローカルワークステーション上の単一ノードクラスターに接続します。

Cluster cluster = CouchbaseCluster.create("localhost");

マルチノードクラスターに接続するには、アプリケーションが接続を確立しようとしたときに1つが使用できない場合に備えて、少なくとも2つのノードを指定します。

Cluster cluster = CouchbaseCluster.create("192.168.4.1", "192.168.4.2");

注：初期接続を作成するときに、クラスター内のすべてのノードを指定する必要はありません。 CouchbaseEnvironment は、接続が確立されると、残りのノード（存在する場合）を検出するためにクラスターにクエリを実行します。

3.2. カスタム環境の使用

アプリケーションでDefaultCouchbaseEnvironmentによって提供される設定のいずれかを微調整する必要がある場合は、カスタム環境を作成し、クラスターに接続するときにその環境を使用できます。

以下は、カスタム CouchbaseEnvironment を使用して、10秒の接続タイムアウトと3秒のKey-Valueルックアップタイムアウトを使用して単一ノードクラスターに接続する例です。

CouchbaseEnvironment env = DefaultCouchbaseEnvironment.builder()
  .connectTimeout(10000)
  .kvTimeout(3000)
  .build();
Cluster cluster = CouchbaseCluster.create(env, "localhost");

また、カスタム環境でマルチノードクラスターに接続するには：

Cluster cluster = CouchbaseCluster.create(env,
  "192.168.4.1", "192.168.4.2");

3.3. バケットを開く

Couchbaseクラスターに接続すると、1つ以上のバケットを開くことができます。

Couchbaseクラスターを最初にセットアップすると、インストールパッケージにより、「default」という名前のバケットが空白のパスワードで自動的に作成されます。

パスワードが空白の場合に「デフォルト」バケットを開く1つの方法は次のとおりです。

Bucket bucket = cluster.openBucket();

バケットを開くときにバケット名を指定することもできます。

Bucket bucket = cluster.openBucket("default");

パスワードが空白のその他のバケットの場合は、バケット名を必ず指定する必要があります。

Bucket myBucket = cluster.openBucket("myBucket");

空白以外のパスワードを持つバケットを開くには、バケット名およびパスワードを指定する必要があります。

Bucket bucket = cluster.openBucket("bucketName", "bucketPassword");

4. 永続化操作

このセクションでは、CouchbaseでCRUD操作を実行する方法を示します。この例では、次のサンプルドキュメントのように、人を表す単純なJSONドキュメントを使用します。

{
  "name": "John Doe",
  "type": "Person",
  "email": "[email protected]",
  "homeTown": "Chicago"
}

“ type” 属性は必須ではありませんが、同じバケットに複数のタイプを格納する場合に備えて、ドキュメントタイプを指定する属性を含めるのが一般的な方法です。

4.1. ドキュメントID

Couchbaseに保存されている各ドキュメントは、ドキュメントが保存されているバケットに固有のidに関連付けられています。ドキュメントidは、従来のリレーショナルデータベース行の主キー列に類似しています。

ドキュメントidの値は、250バイト以下のUTF-8文字列である必要があります。

Couchbaseは、挿入時に id を自動的に生成するメカニズムを提供していないため、独自のメカニズムを提供する必要があります。

ids を生成するための一般的な戦略には、サンプルドキュメントに示されている「email」属性などの自然キーを使用した鍵導出、およびUUIDの使用が含まれます。文字列。

この例では、ランダムなUUID文字列を生成します。

4.2. ドキュメントの挿入

新しいドキュメントをバケットに挿入する前に、まずドキュメントの内容を含むJSONObjectのインスタンスを作成する必要があります。

JsonObject content = JsonObject.empty()
  .put("name", "John Doe")
  .put("type", "Person")
  .put("email", "[email protected]")
  .put("homeTown", "Chicago");

次に、id値とJSONObjectで構成されるJSONDocumentオブジェクトを作成します。

String id = UUID.randomUUID().toString();
JsonDocument document = JsonDocument.create(id, content);

バケットに新しいドキュメントを追加するには、insertメソッドを使用します。

JsonDocument inserted = bucket.insert(document);

返されるJsonDocumentには、元のドキュメントのすべてのプロパティに加えて、Couchbaseがバージョントラッキングに使用する「CAS」（コンペアアンドスワップ）値と呼ばれる値が含まれます。

指定されたidのドキュメントがバケットにすでに存在する場合、CouchbaseはDocumentAlreadyExistsExceptionをスローします。

upsert メソッドを使用することもできます。このメソッドは、ドキュメントを挿入するか（ id が見つからない場合）、ドキュメントを更新します（ id が見つかった場合）。）：：

JsonDocument upserted = bucket.upsert(document);

4.3. ドキュメントの取得

id でドキュメントを取得するには、getメソッドを使用します。

JsonDocument retrieved = bucket.get(id);

指定されたidのドキュメントが存在しない場合、メソッドはnullを返します。

4.4. ドキュメントの更新または置換

upsert メソッドを使用して、既存のドキュメントを更新できます。

JsonObject content = document.content();
content.put("homeTown", "Kansas City");
JsonDocument upserted = bucket.upsert(document);

セクション4.2で説明したように、 upsert は、指定されたidのドキュメントが見つかったかどうかに関係なく成功します。

最初にドキュメントを取得してから改訂されたドキュメントをアップサートしようとするまでに十分な時間が経過している場合、元のドキュメントが別のプロセスまたはユーザーによってバケットから削除されている可能性があります。

アプリケーションでこのシナリオを防ぐ必要がある場合は、代わりに replace メソッドを使用できます。このメソッドは、指定された id のドキュメントの場合、DocumentDoesNotExistExceptionで失敗します。 Couchbaseに見つかりません：

JsonDocument replaced = bucket.replace(document);

4.5. ドキュメントの削除

Couchbaseドキュメントを削除するには、removeメソッドを使用します。

JsonDocument removed = bucket.remove(document);

idで削除することもできます。

JsonDocument removed = bucket.remove(id);

返されるJsonDocumentオブジェクトには、idおよびCASプロパティのみが設定されています。他のすべてのプロパティ（JSONコンテンツを含む）は、返されたオブジェクトから削除されます。

指定されたidのドキュメントが存在しない場合、CouchbaseはDocumentDoesNotExistExceptionをスローします。

5. レプリカの操作

このセクションでは、Couchbaseの仮想バケットとレプリカのアーキテクチャについて説明し、ドキュメントのプライマリノードが利用できない場合にドキュメントのレプリカを取得するためのメカニズムを紹介します。

5.1. 仮想バケットとレプリカ

Couchbaseは、ドキュメント id のハッシュアルゴリズムを使用して、1024個の仮想バケットまたは vbuckets のコレクションにバケットのドキュメントを分散し、保存するvbucketを決定します。各ドキュメント。

各Couchbaseバケットは、各vbucketの1つ以上のreplicasを維持するように構成することもできます。ドキュメントが挿入または更新されてvbucketに書き込まれるたびに、Couchbaseは新しいまたは更新されたドキュメントをレプリカvbucketに複製するプロセスを開始します。

マルチノードクラスターでは、Couchbaseはvbucketsとreplicavbucketsをクラスター内のすべてのデータノードに分散します。 vbucketとそのreplicavbucket は、一定の高可用性を実現するために、別々のデータノードに保持されます。

5.2. レプリカからのドキュメントの取得

id でドキュメントを取得するときに、ドキュメントのプライマリノードがダウンしているか、ネットワークエラーのために到達できない場合、Couchbaseは例外をスローします。

アプリケーションに例外をキャッチさせ、getFromReplicaメソッドを使用してドキュメントの1つ以上のレプリカを取得しようとすることができます。

次のコードは、最初に見つかったレプリカを使用します。

JsonDocument doc;
try{
    doc = bucket.get(id);
}
catch(CouchbaseException e) {
    List<JsonDocument> list = bucket.getFromReplica(id, ReplicaMode.FIRST);
    if(!list.isEmpty()) {
        doc = list.get(0);
     }
}

アプリケーションを作成するときに、永続化とレプリケーションが完了するまで書き込み操作をブロックすることが可能であることに注意してください。ただし、パフォーマンス上の理由から、より一般的な方法は、ドキュメントのプライマリノードのメモリに書き込んだ直後にアプリケーションを書き込みから戻すことです。これは、ディスクの書き込みがメモリの書き込みよりも本質的に遅いためです。

後者のアプローチを使用する場合、更新が完全に複製される前に最近更新されたドキュメントのプライマリノードに障害が発生するかオフラインになると、レプリカの読み取りによってドキュメントの最新バージョンが返される場合と返されない場合があります。

また、Couchbaseがレプリカ（見つかった場合）を非同期で取得することにも注意してください。したがって、バケットが複数のレプリカ用に構成されている場合、SDKがそれらを返す順序は保証されません。アプリケーションに最新のレプリカバージョンが使用可能であることを確認するために、見つかったすべてのレプリカをループすることができます。

long maxCasValue = -1;
for(JsonDocument replica : bucket.getFromReplica(id, ReplicaMode.ALL)) {
    if(replica.cas() > maxCasValue) {
        doc = replica;
        maxCasValue = replica.cas();
    }
}

6. 結論

CouchbaseSDKの使用を開始するために必要となるいくつかの基本的な使用シナリオを紹介しました。

このチュートリアルで紹介するコードスニペットは、GitHubプロジェクトにあります。

SDKの詳細については、公式のCouchbaseSDK開発者向けドキュメントサイトをご覧ください。

getdocs

13036