streamalism.org

1. Introduktion

I denne introduktion til Couchbase SDK til Java demonstrerer vi, hvordan man interagerer med en Couchbase-dokumentdatabase, der dækker grundlæggende begreber såsom at skabe et Couchbase-miljø, oprette forbindelse til en klynge, åbne data-spande, bruge de grundlæggende persistensoperationer og arbejde med dokument replikaer.

2. Maven-afhængigheder

Hvis du bruger Maven, skal du tilføje følgende til din pom.xml-fil:

 com.couchbase.client java-klient 2.2.6 

3. Kom godt i gang

SDK leverer CouchbaseEnvironment interface og en implementeringsklasse StandardCouchbaseEnvironment indeholdende standardindstillinger til styring af adgang til klynger og spande. Standard miljøindstillingerne kan om nødvendigt tilsidesættes, som vi vil se i afsnit 3.2.

Vigtig: Den officielle Couchbase SDK-dokumentation advarer brugere om at sikre, at kun en CouchbaseEnvironment er aktiv i JVM, da brugen af ​​to eller flere kan resultere i uforudsigelig opførsel.

3.1. Oprettelse af forbindelse til en klynge med et standardmiljø

At få SDK automatisk til at oprette en CouchbaseEnvironment med standardindstillinger og knytter det til vores klynge, kan vi oprette forbindelse til klyngen ved blot at angive IP-adressen eller værtsnavnet på en eller flere noder i klyngen.

I dette eksempel opretter vi forbindelse til en enkeltknudeklynge på vores lokale arbejdsstation:

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

For at oprette forbindelse til en klynge med flere knudepunkter, angiver vi mindst to noder, hvis en af ​​dem ikke er tilgængelig, når applikationen forsøger at etablere forbindelsen:

Klyngeklynge = CouchbaseCluster.create ("192.168.4.1", "192.168.4.2");

Bemærk: Det er ikke nødvendigt at specificere hver node i klyngen, når du opretter den oprindelige forbindelse. Det CouchbaseEnvironment vil forespørge klyngen, når forbindelsen er oprettet for at finde de resterende noder (hvis nogen).

3.2. Brug af et brugerdefineret miljø

Hvis din applikation kræver finjustering af nogen af ​​de indstillinger, der leveres af StandardCouchbaseEnvironment, kan du oprette et brugerdefineret miljø og derefter bruge dette miljø, når du opretter forbindelse til din klynge.

Her er et eksempel, der opretter forbindelse til en klynge med en enkelt node ved hjælp af en brugerdefineret CouchbaseEnvironment med en ti sekunders forbindelses timeout og en tre sekunders nøgleværdi-lookout timeout:

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

Og for at oprette forbindelse til en klynge med flere noder med det tilpassede miljø:

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

3.3. Åbning af en spand

Når du har oprettet forbindelse til Couchbase-klyngen, kan du åbne en eller flere spande.

Når du først opretter en Couchbase-klynge, opretter installationspakken automatisk en bucket med navnet "Standard" med et tomt kodeord.

Her er en måde at åbne "Standard" spand, når den har en tom adgangskode:

Spand spand = cluster.openBucket ();

Du kan også angive bucket-navnet, når du åbner det:

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

For enhver anden spand med en tom adgangskode, skal du skal angiv skovlens navn:

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

For at åbne en spand, der har en ikke-blank adgangskode, skal du angive bucket-navnet og adgangskode:

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

4. Persistensoperationer

I dette afsnit viser vi, hvordan du udfører CRUD-operationer i Couchbase. I vores eksempler arbejder vi med enkle JSON-dokumenter, der repræsenterer en person, som i dette eksempeldokument:

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

Det "type" attribut er ikke påkrævet, men det er almindelig praksis at medtage en attribut, der specificerer dokumenttypen, hvis man beslutter at gemme flere typer i samme bucket.

4.1. Dokument-id'er

Hvert dokument, der er gemt i Couchbase, er knyttet til et id det er unikt for den spand, hvor dokumentet opbevares. Dokumentet id er analog med den primære nøglekolonne i en traditionel relationsdatabaserække.

Dokument id værdier skal være UTF-8 strenge på 250 eller færre byte.

Da Couchbase ikke tilvejebringer en mekanisme til automatisk generering af id ved indsættelse skal vi give vores egne.

Fælles strategier for generering id'er inkluderer nøgledivering ved hjælp af en naturlig nøgle, såsom “E-mail” attribut vist i vores eksempeldokument og brugen af UUID strenge.

For vores eksempler genererer vi tilfældige UUID strenge.

4.2. Indsættelse af et dokument

Før vi kan indsætte et nyt dokument i vores spand, skal vi først oprette en forekomst af JSONObjekt indeholdende dokumentets indhold:

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

Dernæst opretter vi en JSONDokument objekt bestående af en id værdi og JSONObjekt:

Streng-id = UUID.randomUUID (). ToString (); JsonDocument-dokument = JsonDocument.create (id, indhold);

For at tilføje et nyt dokument til spanden bruger vi indsæt metode:

JsonDocument indsat = bucket.insert (dokument);

Det JsonDocument returneret indeholder alle egenskaberne i det originale dokument plus en værdi kendt som “CAS” (sammenligne-og-bytte) -værdi, som Couchbase bruger til versionssporing.

Hvis et dokument med det medfølgende id findes allerede i spanden, Couchbase smider en DocumentAlreadyExistsException.

Vi kan også bruge opsving metode, som enten indsætter dokumentet (hvis id ikke findes) eller opdatere dokumentet (hvis id er fundet):

JsonDocument upserted = bucket.upsert (dokument);

4.3. Henter et dokument

At hente et dokument efter dets id, bruger vi få metode:

JsonDocument hentet = bucket.get (id);

Hvis der ikke findes noget dokument med det givne id, metoden vender tilbage nul.

4.4. Opdatering eller udskiftning af et dokument

Vi kan opdatere et eksisterende dokument ved hjælp af opsving metode:

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

Som vi nævnte i afsnit 4.2, opsving vil lykkes, om et dokument med det givne id blev fundet eller ej.

Hvis der er gået nok tid mellem, da vi oprindeligt hentede dokumentet, og vores forsøg på at ophæve det reviderede dokument, er der en mulighed for, at det originale dokument er blevet slettet fra spanden af ​​en anden proces eller bruger.

Hvis vi har brug for at beskytte os mod dette scenario i vores applikation, kan vi i stedet bruge erstatte metode, som mislykkes med en DocumentDoesNotExistException hvis et dokument med det givne id findes ikke i Couchbase:

JsonDocument erstattet = bucket.replace (dokument);

4.5. Sletning af et dokument

For at slette et Couchbase-dokument bruger vi fjerne metode:

JsonDocument fjernet = bucket.remove (dokument);

Du kan også fjerne ved id:

JsonDocument fjernet = bucket.remove (id);

Det JsonDocument returneret objekt har kun id og CAS indstillede egenskaber; alle andre egenskaber (inklusive JSON-indholdet) fjernes fra det returnerede objekt.

Hvis der ikke findes noget dokument med det givne id, Couchbase kaster en DocumentDoesNotExistException.

5. Arbejde med replikaer

Dette afsnit diskuterer Couchbases virtuelle bucket- og replikearkitektur og introducerer en mekanisme til at hente en replika af et dokument i tilfælde af, at et dokuments primære node ikke er tilgængelig.

5.1. Virtuelle spande og replikaer

Couchbase distribuerer en spand dokumenter på tværs af en samling af 1024 virtuelle spande, eller skovle, ved hjælp af en hashingalgoritme på dokumentet id at bestemme vbucket hvor hvert dokument skal gemmes.

Hver Couchbase-skovl kan også konfigureres til at vedligeholde en eller flere replikaer af hver vbucket. Hver gang et dokument indsættes eller opdateres og skrives til dets vbucket, Couchbase starter en proces til at replikere det nye eller opdaterede dokument til dets replika vbucket.

I en klynge med flere knudepunkter distribuerer Couchbase skovle og replika v-skovle blandt alle datanoder i klyngen. EN vbucket ogdet er replika vbucket holdes på separate datanoder for at opnå et bestemt mål for høj tilgængelighed.

5.2. Hentning af et dokument fra en replika

Når du henter et dokument efter dets id, hvis dokumentets primære node er nede eller på anden måde ikke kan nås på grund af en netværksfejl, kaster Couchbase en undtagelse.

Du kan få din applikation til at fange undtagelsen og forsøge at hente en eller flere kopier af dokumentet ved hjælp af getFromReplica metode.

Den følgende kode ville bruge den første replika, der blev fundet:

JsonDocument doc; prøv {doc = bucket.get (id); } fange (CouchbaseException e) {List list = bucket.getFromReplica (id, ReplicaMode.FIRST); hvis (! list.isEmpty ()) {doc = list.get (0); }}

Bemærk, at det er muligt, når du skriver din ansøgning, at have blokering af skriveoperationer, indtil vedholdenhed og replikering er afsluttet. Imidlertid er den mere almindelige praksis af grunde til ydeevne, at applikationen vender tilbage fra skrivning umiddelbart efter skrivning til hukommelsen på et dokuments primære knude, fordi diskskrivninger i sagens natur er langsommere end hukommelseskrivninger.

Når en sidstnævnte metode bruger den sidstnævnte tilgang, hvis en nyligt opdateret dokuments primære node skulle mislykkes eller gå offline, før opdateringerne er blevet fuldstændigt replikeret, kan replika læser måske ikke returnere den nyeste version af dokumentet.

Det er også værd at bemærke, at Couchbase henter replikaer (hvis der findes nogen) asynkront. Derfor, hvis din bucket er konfigureret til flere replikaer, er der ingen garanti for, i hvilken rækkefølge SDK returnerer dem, og du vil muligvis gennemgå alle de replikaer, der findes, for at sikre, at din applikation har den nyeste replikaversion tilgængelig:

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

6. Konklusion

Vi har introduceret nogle grundlæggende brugsscenarier, som du har brug for for at komme i gang med Couchbase SDK.

Kodestykker, der præsenteres i denne vejledning, kan findes i GitHub-projektet.

Du kan lære mere om SDK på det officielle Couchbase SDK-udviklingsdokumentationswebsted.