Java用Couchbase SDKの概要
1. 前書き
このJava用Couchbase SDKの紹介では、Couchbaseドキュメントデータベースと対話する方法を示します。Couchbase環境の作成、クラスターへの接続、データバケットのオープン、基本的な永続化操作の使用、ドキュメントの操作などの基本概念をカバーしますレプリカ。
2. Mavenの依存関係
Mavenを使用している場合、pom.xmlファイルに次を追加します。
com.couchbase.client
java-client
2.2.6
3. 入門
SDKは、CouchbaseEnvironmentインターフェースと、クラスターおよびバケットへのアクセスを管理するためのデフォルト設定を含む実装クラスDefaultCouchbaseEnvironmentを提供します。 セクション3.2で見るように、デフォルトの環境設定は必要に応じて上書きできます。
Important:公式のCouchbase SDKドキュメントでは、2つ以上を使用すると予期しない動作が発生する可能性があるため、JVMでアクティブなCouchbaseEnvironmentが1つだけであることを確認するようにユーザーに警告しています。
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");
Note:初期接続を作成するときに、クラスター内のすべてのノードを指定する必要はありません。 CouchbaseEnvironmentは、接続が確立されると、残りのノード(存在する場合)を検出するためにクラスターにクエリを実行します。
3.2. カスタム環境の使用
アプリケーションでDefaultCouchbaseEnvironmentが提供する設定のいずれかを微調整する必要がある場合は、カスタム環境を作成し、クラスターに接続するときにその環境を使用できます。
これは、10秒の接続タイムアウトと3秒のKey-Valueルックアップタイムアウトを使用してカスタム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");
パスワードが空白のその他のバケットの場合、mustでバケット名を指定します。
Bucket myBucket = cluster.openBucket("myBucket");
空白以外のパスワードを持つバケットを開くには、バケット名andパスワードを指定する必要があります。
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のドキュメントが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は、ドキュメントidのハッシュアルゴリズムを使用して各ドキュメントを保存するvbucketを決定し、1024個の仮想バケットまたはvbucketsのコレクションにバケットのドキュメントを配布します。
各Couchbaseバケットは、各vbucketの1つ以上のreplicasを維持するように構成することもできます。 ドキュメントが挿入または更新されてそのvbucketに書き込まれるたびに、Couchbaseは新しいドキュメントまたは更新されたドキュメントをそのreplica vbucketに複製するプロセスを開始します。
マルチノードクラスターでは、Couchbaseはクラスター内のすべてのデータノードにvbucketsとreplica vbucketsを分散します。 vbucketとそのreplica vbucketは、高可用性の特定の測定値を達成するために、別々のデータノードに保持されます。
5.2. レプリカからのドキュメントの取得
idでドキュメントを取得するときに、ドキュメントのプライマリノードがダウンしているか、ネットワークエラーが原因で到達できない場合、Couchbaseは例外をスローします。
アプリケーションで例外をキャッチし、getFromReplicaメソッドを使用してドキュメントの1つ以上のレプリカを取得しようとすることができます。
次のコードは、最初に見つかったレプリカを使用します。
JsonDocument doc;
try{
doc = bucket.get(id);
}
catch(CouchbaseException e) {
List 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を開始するために必要な基本的な使用シナリオをいくつか紹介しました。
このチュートリアルで紹介するコードスニペットは、GitHub projectにあります。
SDKの詳細については、公式のCouchbase SDK developer documentation siteを参照してください。