Einführung in Couchbase SDK für Java
1. Einführung
In dieser Einführung in das Couchbase-SDK für Java wird die Interaktion mit einer Couchbase-Dokumentendatenbank erläutert. Es werden grundlegende Konzepte behandelt, z Repliken.
2. Maven-Abhängigkeiten
Wenn Sie Maven verwenden, fügen Sie Ihrer pom.xml-Datei Folgendes hinzu:
com.couchbase.client
java-client
2.2.6
3. Anfangen
Das SDK bietet dieCouchbaseEnvironment-Schnittstelle und eine ImplementierungsklasseDefaultCouchbaseEnvironment mit Standardeinstellungen für die Verwaltung des Zugriffs auf Cluster und Buckets. Die Standardeinstellungen für die Umgebung können bei Bedarf überschrieben werden, wie in Abschnitt 3.2 beschrieben.
Important: In der offiziellen Couchbase SDK-Dokumentation wird der Benutzer darauf hingewiesen, dass nur einCouchbaseEnvironment in der JVM aktiv ist, da die Verwendung von zwei oder mehr zu unvorhersehbarem Verhalten führen kann.
3.1. Herstellen einer Verbindung zu einem Cluster mit einer Standardumgebung
Damit das SDK automatisch einCouchbaseEnvironment mit Standardeinstellungen erstellt und es unserem Cluster zuordnet, können wir eine Verbindung zum Cluster herstellen, indem wir einfach die IP-Adresse oder den Hostnamen eines oder mehrerer Knoten im Cluster angeben.
In diesem Beispiel stellen wir eine Verbindung zu einem Einzelknotencluster auf unserer lokalen Arbeitsstation her:
Cluster cluster = CouchbaseCluster.create("localhost");Um eine Verbindung zu einem Cluster mit mehreren Knoten herzustellen, geben Sie mindestens zwei Knoten an, falls einer von ihnen nicht verfügbar ist, wenn die Anwendung versucht, die Verbindung herzustellen:
Cluster cluster = CouchbaseCluster.create("192.168.4.1", "192.168.4.2");Note: Es ist nicht erforderlich, beim Erstellen der ersten Verbindung jeden Knoten im Cluster anzugeben. DieCouchbaseEnvironment fragen den Cluster ab, sobald die Verbindung hergestellt ist, um die verbleibenden Knoten (falls vorhanden) zu ermitteln.
3.2. Verwenden einer benutzerdefinierten Umgebung
Wenn Ihre Anwendung eine Feinabstimmung der vonDefaultCouchbaseEnvironment bereitgestellten Einstellungen erfordert, können Sie eine benutzerdefinierte Umgebung erstellen und diese Umgebung dann verwenden, wenn Sie eine Verbindung zu Ihrem Cluster herstellen.
Hier ist ein Beispiel, das mithilfe eines benutzerdefiniertenCouchbaseEnvironment mit einem Zeitlimit für die Verbindung von zehn Sekunden und einem Zeitlimit für die Suche nach Schlüsselwerten von drei Sekunden eine Verbindung zu einem Cluster mit einem einzelnen Knoten herstellt:
CouchbaseEnvironment env = DefaultCouchbaseEnvironment.builder()
.connectTimeout(10000)
.kvTimeout(3000)
.build();
Cluster cluster = CouchbaseCluster.create(env, "localhost");So stellen Sie mit der benutzerdefinierten Umgebung eine Verbindung zu einem Cluster mit mehreren Knoten her:
Cluster cluster = CouchbaseCluster.create(env,
"192.168.4.1", "192.168.4.2");3.3. Einen Eimer öffnen
Sobald Sie eine Verbindung zum Couchbase-Cluster hergestellt haben, können Sie einen oder mehrere Eimer öffnen.
Wenn Sie zum ersten Mal einen Couchbase-Cluster einrichten, erstellt das Installationspaket automatisch einen Bucket mit dem Namen“default” mit einem leeren Kennwort.
Hier ist eine Möglichkeit, den Bucket von“default”zu öffnen, wenn er ein leeres Kennwort hat:
Bucket bucket = cluster.openBucket();Sie können den Bucket-Namen auch beim Öffnen angeben:
Bucket bucket = cluster.openBucket("default");Für jeden anderen Bucket mit einem leeren Passwort geben Siemustden Bucket-Namen an:
Bucket myBucket = cluster.openBucket("myBucket");Um einen Bucket mit einem nicht leeren Kennwort zu öffnen, müssen Sie das Kennwort des Bucket-Namensandangeben:
Bucket bucket = cluster.openBucket("bucketName", "bucketPassword");4. Persistenzoperationen
In diesem Abschnitt wird gezeigt, wie CRUD-Operationen in Couchbase ausgeführt werden. In unseren Beispielen werden wir mit einfachen JSON-Dokumenten arbeiten, die eine Person darstellen, wie in diesem Beispieldokument:
{
"name": "John Doe",
"type": "Person",
"email": "[email protected]",
"homeTown": "Chicago"
}Das Attribut“type” ist nicht erforderlich. Es ist jedoch üblich, ein Attribut einzuschließen, das den Dokumenttyp angibt, falls mehrere Typen im selben Bucket gespeichert werden sollen.
4.1. Dokument-IDs
Jedes in Couchbase gespeicherte Dokument ist mit einemid verknüpft, der für den Bucket eindeutig ist, in dem das Dokument gespeichert wird. Das Dokumentid ist analog zur Primärschlüsselspalte in einer herkömmlichen relationalen Datenbankzeile.
Die Werte von Dokumentidmüssen UTF-8-Zeichenfolgen mit 250 oder weniger Bytes sein.
Da Couchbase keinen Mechanismus zum automatischen Generieren derid beim Einfügen bietet, müssen wir unseren eigenen bereitstellen.
Zu den gängigen Strategien zum Generieren vonidsgehören die Schlüsselableitung mithilfe eines natürlichen Schlüssels, z. B. das in unserem Beispieldokument gezeigte Attribut“email”, und die Verwendung vonUUID-Zeichenfolgen.
In unseren Beispielen generieren wir zufälligeUUID-Strings.
4.2. Einfügen eines Dokuments
Bevor wir ein neues Dokument in unseren Bucket einfügen können, müssen wir zuerst eine Instanz vonJSONObject erstellen, die den Inhalt des Dokuments enthält:
JsonObject content = JsonObject.empty()
.put("name", "John Doe")
.put("type", "Person")
.put("email", "[email protected]")
.put("homeTown", "Chicago");Als nächstes erstellen wir einJSONDocument-Objekt, das aus einemid-Wert und demJSONObject-Wert besteht:
String id = UUID.randomUUID().toString();
JsonDocument document = JsonDocument.create(id, content);Um dem Bucket ein neues Dokument hinzuzufügen, verwenden wir die Methodeinsert:
JsonDocument inserted = bucket.insert(document);Die zurückgegebenenJsonDocument enthalten alle Eigenschaften des Originaldokuments sowie einen Wert, der als“CAS”-Wert (Vergleichen und Austauschen) bezeichnet wird und von Couchbase für die Versionsverfolgung verwendet wird.
Wenn bereits ein Dokument mit den angegebenenid im Bucket vorhanden ist, wirft Couchbase einDocumentAlreadyExistsException aus.
Wir können auch die Methodeupsert verwenden, mit der entweder das Dokument eingefügt wird (wennid nicht gefunden wird) oder das Dokument aktualisiert wird (wennid gefunden wird):
JsonDocument upserted = bucket.upsert(document);4.3. Ein Dokument abrufen
Um ein Dokument anhand seinerid abzurufen, verwenden wir dieget-Methode:
JsonDocument retrieved = bucket.get(id);Wenn mit den angegebenenid kein Dokument vorhanden ist, gibt die Methodenull zurück.
4.4. Aktualisieren oder Ersetzen eines Dokuments
Wir können ein vorhandenes Dokument mit der Methodeupsertaktualisieren:
JsonObject content = document.content();
content.put("homeTown", "Kansas City");
JsonDocument upserted = bucket.upsert(document);Wie in Abschnitt 4.2 erwähnt, istupsert erfolgreich, unabhängig davon, ob ein Dokument mit den angegebenenid gefunden wurde oder nicht.
Wenn zwischen dem ursprünglichen Abrufen des Dokuments und dem Versuch, das überarbeitete Dokument erneut einzufügen, genügend Zeit vergangen ist, besteht die Möglichkeit, dass das ursprüngliche Dokument von einem anderen Prozess oder Benutzer aus dem Bucket gelöscht wurde.
Wenn wir uns in unserer Anwendung vor diesem Szenario schützen müssen, können wir stattdessen die Methodereplace verwenden, die mitDocumentDoesNotExistException fehlschlägt, wenn in Couchbase kein Dokument mit den angegebenenid gefunden wird:
JsonDocument replaced = bucket.replace(document);4.5. Ein Dokument löschen
Um ein Couchbase-Dokument zu löschen, verwenden wir die Methoderemove:
JsonDocument removed = bucket.remove(document);Sie können auch umid entfernen:
JsonDocument removed = bucket.remove(id);Für das zurückgegebene ObjektJsonDocument sind nur die Eigenschaftenid undCASfestgelegt. Alle anderen Eigenschaften (einschließlich des JSON-Inhalts) werden aus dem zurückgegebenen Objekt entfernt.
Wenn mit den angegebenenid kein Dokument vorhanden ist, gibt Couchbase einDocumentDoesNotExistException aus.
5. Arbeiten mit Replikaten
In diesem Abschnitt wird die virtuelle Bucket- und Replikatarchitektur von Couchbase erläutert und ein Mechanismus zum Abrufen eines Replikats eines Dokuments für den Fall vorgestellt, dass der primäre Knoten eines Dokuments nicht verfügbar ist.
5.1. Virtuelle Buckets und Replikate
Couchbase verteilt die Dokumente eines Buckets auf eine Sammlung von 1024 virtuellen Buckets odervbuckets, wobei ein Hashing-Algorithmus für das Dokumentidverwendet wird, um dievbucketzu bestimmen, in denen jedes Dokument gespeichert werden soll.
Jeder Couchbase-Bucket kann auch so konfiguriert werden, dass ein oder mehrerereplicas von jedemvbucket verwaltet werden. Immer wenn ein Dokument eingefügt oder aktualisiert und in seinevbucket geschrieben wird, initiiert Couchbase einen Prozess, um das neue oder aktualisierte Dokument in seinereplica vbucket zu replizieren.
In einem Cluster mit mehreren Knoten verteilt Couchbasevbuckets undreplica vbuckets auf alle Datenknoten im Cluster. Avbucket undreplica vbucket werden auf getrennten Datenknoten gespeichert, um ein bestimmtes Maß an Hochverfügbarkeit zu erreichen.
5.2. Abrufen eines Dokuments von einem Replikat
Wenn beim Abrufen eines Dokuments umid der primäre Knoten des Dokuments aufgrund eines Netzwerkfehlers ausgefallen oder auf andere Weise nicht erreichbar ist, löst Couchbase eine Ausnahme aus.
Sie können Ihre Anwendung die Ausnahme abfangen lassen und versuchen, eine oder mehrere Replikate des Dokuments mit der MethodegetFromReplicaabzurufen.
Der folgende Code würde das erste gefundene Replikat verwenden:
JsonDocument doc;
try{
doc = bucket.get(id);
}
catch(CouchbaseException e) {
List list = bucket.getFromReplica(id, ReplicaMode.FIRST);
if(!list.isEmpty()) {
doc = list.get(0);
}
} Beachten Sie, dass es beim Schreiben Ihrer Anwendung möglich ist, Schreibvorgänge zu blockieren, bis Persistenz und Replikation abgeschlossen sind. Aus Leistungsgründen ist es jedoch üblicher, dass die Anwendung unmittelbar nach dem Schreiben in den Speicher des Primärknotens eines Dokuments von Schreibvorgängen zurückkehrt, da Festplattenschreibvorgänge von Natur aus langsamer sind als Speicherschreibvorgänge.
Wenn bei Verwendung des letzteren Ansatzes der Primärknoten eines kürzlich aktualisierten Dokuments ausfallen oder offline gehen sollte, bevor die Aktualisierungen vollständig repliziert wurden, geben Replikat-Lesevorgänge möglicherweise die neueste Version des Dokuments zurück oder nicht.
Beachten Sie auch, dass Couchbase Replikate (sofern vorhanden) asynchron abruft. Wenn Ihr Bucket für mehrere Replikate konfiguriert ist, gibt es keine Garantie für die Reihenfolge, in der das SDK sie zurückgibt, und Sie möchten möglicherweise alle gefundenen Replikate durchlaufen, um sicherzustellen, dass in Ihrer Anwendung die neueste verfügbare Replikatversion vorhanden ist:
long maxCasValue = -1;
for(JsonDocument replica : bucket.getFromReplica(id, ReplicaMode.ALL)) {
if(replica.cas() > maxCasValue) {
doc = replica;
maxCasValue = replica.cas();
}
}6. Fazit
Wir haben einige grundlegende Verwendungsszenarien vorgestellt, die Sie benötigen, um mit dem Couchbase SDK zu beginnen.
In diesem Tutorial vorgestellte Codefragmente finden Sie inGitHub project.
Weitere Informationen zum SDK finden Sie unterCouchbase SDK developer documentation site.