Pengenalan Couchbase SDK untuk Java

1. Pengenalan

Dalam pengenalan ini ke Couchbase SDK untuk Java, kami menunjukkan cara berinteraksi dengan pangkalan data dokumen Couchbase, yang merangkumi konsep asas seperti membuat persekitaran Couchbase, menyambung ke kluster, membuka keranjang data, menggunakan operasi ketekunan dasar, dan bekerja dengan dokumen replika.

2. Pergantungan Maven

Sekiranya anda menggunakan Maven, tambahkan yang berikut ke fail pom.xml anda:

 com.couchbase.client java-client 2.2.6 

3. Bermula

SDK menyediakan antara muka CouchbaseEnvironment dan kelas pelaksanaan DefaultCouchbaseEnvironment yang mengandungi tetapan lalai untuk menguruskan akses ke kelompok dan baldi. Tetapan persekitaran lalai boleh diganti jika perlu, seperti yang akan kita lihat di bahagian 3.2.

Penting: Dokumentasi Couchbase SDK rasmi memberi peringatan kepada pengguna untuk memastikan bahawa hanya satu CouchbaseEnvironment aktif dalam JVM, kerana penggunaan dua atau lebih boleh menyebabkan tingkah laku yang tidak dapat diramalkan.

3.1. Menyambung ke Kluster Dengan Persekitaran Lalai

Untuk mempunyai SDK secara automatik membuat CouchbaseEnvironment dengan tetapan lalai dan mengaitkannya dengan kluster kami, kami dapat menyambung ke kluster hanya dengan memberikan alamat IP atau nama host satu atau lebih node dalam kluster.

Dalam contoh ini, kami menyambung ke kluster simpul tunggal di stesen kerja tempatan kami:

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

Untuk menyambung ke kluster multi-node, kami akan menentukan sekurang-kurangnya dua node sekiranya salah satunya tidak tersedia ketika aplikasi berusaha untuk membuat sambungan:

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

Catatan: Tidak perlu menentukan setiap simpul dalam kluster ketika membuat sambungan awal. The CouchbaseEnvironment akan bertanyakan kelompok sekali sambungan diwujudkan untuk mengetahui nod baki (jika ada).

3.2. Menggunakan Persekitaran Tersuai

Sekiranya aplikasi anda memerlukan pengaturan yang baik dari salah satu tetapan yang disediakan oleh DefaultCouchbaseEnvironment , anda boleh membuat persekitaran khusus dan kemudian menggunakan persekitaran tersebut ketika menyambung ke kluster anda.

Berikut adalah contoh yang menghubungkan ke kluster simpul tunggal menggunakan CouchbaseEnvironment tersuai dengan tamat masa sambungan sepuluh saat dan masa tamat carian nilai kunci tiga saat:

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

Dan untuk menyambung ke kluster berbilang nod dengan persekitaran tersuai:

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

3.3. Membuka Baldi

Setelah anda menyambung ke kluster Couchbase, anda boleh membuka satu atau lebih baldi.

Semasa pertama kali menyiapkan kluster Couchbase, pakej pemasangan secara automatik membuat baldi bernama "lalai" dengan kata laluan kosong.

Inilah salah satu cara untuk membuka baldi "lalai" apabila mempunyai kata laluan kosong:

Bucket bucket = cluster.openBucket();

Anda juga boleh menentukan nama baldi semasa membukanya:

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

Untuk baldi lain dengan kata laluan kosong, anda mesti memberikan nama baldi:

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

Untuk membuka baldi yang mempunyai kata laluan kosong, anda mesti memberikan nama dan kata laluan baldi :

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

4. Operasi Kegigihan

Di bahagian ini, kami menunjukkan cara melakukan operasi CRUD di Couchbase. Dalam contoh kami, kami akan bekerja dengan dokumen JSON ringkas yang mewakili seseorang, seperti dalam contoh dokumen ini:

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

The "type" atribut tidak diperlukan, namun ia adalah amalan biasa untuk memasukkan sifat menyatakan jenis dokumen dalam kes satu memutuskan untuk menyimpan pelbagai jenis dalam baldi yang sama.

4.1. ID Dokumen

Setiap dokumen yang disimpan di Couchbase dikaitkan dengan id yang unik untuk baldi di mana dokumen tersebut disimpan. Id dokumen serupa dengan lajur kunci utama dalam baris pangkalan data hubungan tradisional.

Nilai id dokumen mestilah rentetan UTF-8 250 atau kurang bait.

Oleh kerana Couchbase tidak menyediakan mekanisme untuk menghasilkan id secara automatik semasa penyisipan, kami mesti menyediakannya sendiri.

Strategi umum untuk menghasilkan id termasuk derivasi kunci menggunakan kunci semula jadi, seperti atribut "e-mel" yang ditunjukkan dalam contoh dokumen kami, dan penggunaan rentetan UUID .

Sebagai contoh, kami akan menghasilkan rentetan UUID rawak .

4.2. Memasukkan Dokumen

Sebelum kita memasukkan dokumen baru ke dalam baldi kita, kita mesti membuat contoh JSONObject yang mengandungi kandungan dokumen terlebih dahulu :

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

Seterusnya, kami membuat objek JSONDocument yang terdiri daripada nilai id dan JSONObject :

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

Untuk menambahkan dokumen baru ke baldi, kami menggunakan kaedah sisipan :

JsonDocument inserted = bucket.insert(document);

The JsonDocument returned contains all of the properties of the original document, plus a value known as the “CAS” (compare-and-swap) value that Couchbase uses for version tracking.

If a document with the supplied id already exists in the bucket, Couchbase throws a DocumentAlreadyExistsException.

We can also use the upsert method, which will either insert the document (if the id is not found) or update the document (if the id is found):

JsonDocument upserted = bucket.upsert(document);

4.3. Retrieving a Document

To retrieve a document by its id, we use the get method:

JsonDocument retrieved = bucket.get(id);

If no document exists with the given id, the method returns null.

4.4. Updating or Replacing a Document

We can update an existing document using the upsert method:

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

As we mentioned in section 4.2, upsert will succeed whether a document with the given id was found or not.

If enough time has passed between when we originally retrieved the document and our attempt to upsert the revised document, there is a possibility that the original document will have been deleted from the bucket by another process or user.

If we need to guard against this scenario in our application, we can instead use the replace method, which fails with a DocumentDoesNotExistException if a document with the given id is not found in Couchbase:

JsonDocument replaced = bucket.replace(document);

4.5. Deleting a Document

To delete a Couchbase document, we use the remove method:

JsonDocument removed = bucket.remove(document);

You may also remove by id:

JsonDocument removed = bucket.remove(id);

The JsonDocument object returned has only the id and CAS properties set; all other properties (including the JSON content) are removed from the returned object.

If no document exists with the given id, Couchbase throws a DocumentDoesNotExistException.

5. Working With Replicas

This section discusses Couchbase's virtual bucket and replica architecture and introduces a mechanism for retrieving a replica of a document in the event that a document's primary node is unavailable.

5.1. Virtual Buckets and Replicas

Couchbase distributes a bucket's documents across a collection of 1024 virtual buckets, or vbuckets, using a hashing algorithm on the document id to determine the vbucket in which to store each document.

Each Couchbase bucket can also be configured to maintain one or more replicas of each vbucket. Whenever a document is inserted or updated and written to its vbucket, Couchbase initiates a process to replicate the new or updated document to its replica vbucket.

In a multi-node cluster, Couchbase distributes vbuckets and replica vbuckets among all the data nodes in the cluster. A vbucket and its replica vbucket are kept on separate data nodes in order to achieve a certain measure of high-availability.

5.2. Retrieving a Document From a Replica

When retrieving a document by its id, if the document's primary node is down or otherwise unreachable due to a network error, Couchbase throws an exception.

You can have your application catch the exception and attempt to retrieve one or more replicas of the document using the getFromReplica method.

The following code would use the first replica found:

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

Note that it is possible, when writing your application, to have write operations block until persistence and replication are complete. However the more common practice, for reasons of performance, is to have the application return from writes immediately after writing to memory of a document's primary node, because disk writes are inherently slower than memory writes.

When using the latter approach, if a recently updated document's primary node should fail or go offline before the updates have been fully replicated, replica reads may or may not return the latest version of the document.

It is also worth noting that Couchbase retrieves replicas (if any are found) asynchronously. Therefore if your bucket is configured for multiple replicas, there is no guarantee as to the order in which the SDK returns them, and you may want to loop through all the replicas found in order to ensure that your application has the latest replica version available:

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

6. Conclusion

We have introduced some basic usage scenarios that you will need in order to get started with the Couchbase SDK.

Code snippets presented in this tutorial can be found in the GitHub project.

Anda boleh mengetahui lebih lanjut mengenai SDK di laman dokumentasi pembangun Couchbase SDK rasmi.