Couchbase SDK for Javaの紹介

1前書き

このCouchbase SDK for 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で1つの CouchbaseEnvironment のみがアクティブになるようにユーザーに警告しています。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 で提供される設定を微調整する必要がある場合は、カスタム環境を作成してから、その環境をクラスターへの接続時に使用できます。

これは、10秒の接続タイムアウトと3秒のキー値検索タイムアウトを持つカスタム CouchbaseEnvironment を使用してシングルノードクラスタに接続する例です。

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” という名前のバケットを作成します。

パスワードが空白のときに “ default” バケットを開く方法の1つを次に示します。

Bucket bucket = cluster.openBucket();

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

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

パスワードが空白の他のバケットの場合は、バケット名を 必須 指定します。

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

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

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);

バケットに新しい文書を追加するには、 挿入 メソッドを使用します。

JsonDocument inserted = bucket.insert(document);

返される JsonDocument には、元のドキュメントのすべてのプロパティと、Couchbaseがバージョントラッキングに使用する “ CAS” (compare-and-swap)値として知られる値が含まれています。

指定された 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 を持つドキュメントがCouchbaseで見つからない場合は、 DocumentDoesNotExistException で失敗します。

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は、各ドキュメントを格納するための vbucket を決定するために、ドキュメント id に対してハッシュアルゴリズムを使用して、1024個の仮想バケット、または vbuckets のコレクションにバケットのドキュメントを分配します。

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

マルチノードクラスタでは、Couchbaseはクラスタ内のすべてのデータノードに vbuckets replica vbuckets を分配します。ある程度の高可用性を実現するために、 vbucket とその レプリカvbucket は別々のデータノードに保持されます。

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. 結論

Couchbase SDKを使い始めるために必要な基本的な使用シナリオをいくつか紹介しました。

このチュートリアルで紹介されているコードスニペットはhttps://github.com/eugenp/tutorials/tree/master/couchbase[GitHubプロジェクト]にあります。

SDKの詳細については、http://developer.couchbase.com/documentation/server/4.1/sdks/java-2.2/java-intro.html[Couchbase SDK開発者向けドキュメントサイト]を参照してください。