streamalism.org

1. Introduksjon

I denne introduksjonen til Couchbase SDK for Java demonstrerer vi hvordan vi kan samhandle med en Couchbase-dokumentdatabase, som dekker grunnleggende konsepter som å lage et Couchbase-miljø, koble til en klynge, åpne dataskuffer, bruke de grunnleggende persistensoperasjonene og jobbe med dokument kopier.

2. Maven-avhengigheter

Hvis du bruker Maven, kan du legge til følgende i pom.xml-filen:

 com.couchbase.client java-klient 2.2.6 

3. Komme i gang

SDK gir CouchbaseEnvironment grensesnitt og en implementeringsklasse DefaultCouchbaseEnvironment som inneholder standardinnstillinger for administrering av tilgang til klynger og bøtter. Standard miljøinnstillinger kan overstyres om nødvendig, som vi vil se i avsnitt 3.2.

Viktig: Den offisielle Couchbase SDK-dokumentasjonen advarer brukerne om å sikre at bare en CouchbaseEnvironment er aktiv i JVM, siden bruk av to eller flere kan føre til uforutsigbar oppførsel.

3.1. Koble til en klynge med standardmiljø

Å ha SDK automatisk til å opprette en CouchbaseEnvironment med standardinnstillinger og knytte den til klyngen vår, kan vi koble til klyngen ganske enkelt ved å oppgi IP-adressen eller vertsnavnet til en eller flere noder i klyngen.

I dette eksemplet kobler vi til en klyngeklynge på vår lokale arbeidsstasjon:

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

For å koble til en gruppe med flere noder, vil vi spesifisere minst to noder i tilfelle en av dem er utilgjengelig når applikasjonen prøver å etablere forbindelsen:

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

Merk: Det er ikke nødvendig å spesifisere hver node i klyngen når du oppretter den første tilkoblingen. De CouchbaseEnvironment vil spørre klyngen når forbindelsen er opprettet for å oppdage de gjenværende nodene (hvis noen).

3.2. Bruke et tilpasset miljø

Hvis søknaden din krever finjustering av noen av innstillingene som tilbys av DefaultCouchbaseEnvironment, kan du opprette et tilpasset miljø og deretter bruke dette miljøet når du kobler til klyngen.

Her er et eksempel som kobles til en klynge med en node ved hjelp av en tilpasset CouchbaseEnvironment med ti sekunders tidsavbrudd for tilkobling og tre sekunders tidsavbrudd for nøkkelverdioppslag:

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

Og for å koble til en gruppe med flere noder med det tilpassede miljøet:

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

3.3. Åpne en bøtte

Når du har koblet deg til Couchbase-klyngen, kan du åpne en eller flere bøtter.

Når du først setter opp en Couchbase-klynge, oppretter installasjonspakken automatisk en bøtte med navnet "misligholde" med et tomt passord.

Her er en måte å åpne "misligholde" bøtte når den har et tomt passord:

Bøttebøtte = cluster.openBucket ();

Du kan også spesifisere skuffenavnet når du åpner det:

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

For alle andre bøtter med et tomt passord, du må oppgi skuffenavnet:

Bøtte myBucket = cluster.openBucket ("myBucket");

For å åpne en bøtte som har et ikke-tomt passord, må du oppgi bøttenavnet og passord:

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

4. Persistensoperasjoner

I denne delen viser vi hvordan du utfører CRUD-operasjoner i Couchbase. I eksemplene våre vil vi jobbe med enkle JSON-dokumenter som representerer en person, som i dette eksempeldokumentet:

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

De "type" attributt er ikke nødvendig, men det er vanlig praksis å inkludere et attributt som spesifiserer dokumenttypen i tilfelle man bestemmer seg for å lagre flere typer i samme bøtte.

4.1. Dokument-ID-er

Hvert dokument som er lagret i Couchbase, er knyttet til et id som er unik for bøtta der dokumentet lagres. Dokumentet id er analog med primærnøkkelkolonnen i en tradisjonell relasjonell databaserad.

Dokument id verdiene må være UTF-8 strenger på 250 eller færre byte.

Siden Couchbase ikke gir en mekanisme for automatisk generering av id ved innsetting må vi sørge for vårt eget.

Vanlige strategier for å generere ID-er inkluderer nøkkel-avledning ved hjelp av en naturlig nøkkel, for eksempel “E-post” attributtet vist i eksemplet vårt, og bruken av UUID strenger.

For eksemplene våre vil vi generere tilfeldige UUID strenger.

4.2. Sette inn et dokument

Før vi kan sette inn et nytt dokument i bøtta vår, må vi først opprette en forekomst av JSONObject som inneholder dokumentets innhold:

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

Deretter lager vi en JSONDocument objekt som består av et id verdi og JSONObject:

Streng-id = UUID.randomUUID (). ToString (); JsonDocument document = JsonDocument.create (id, content);

For å legge til et nytt dokument i bøtta bruker vi sett inn metode:

JsonDocument satt inn = bucket.insert (dokument);

De JsonDocument returnert inneholder alle egenskapene til originaldokumentet, pluss en verdi kjent som “CAS” (sammenlign og bytt) -verdi som Couchbase bruker for versjonssporing.

Hvis et dokument med den medfølgende id eksisterer allerede i bøtta, kaster Couchbase en DocumentAlreadyExistsException.

Vi kan også bruke oppover metoden, som enten setter inn dokumentet (hvis id ikke blir funnet) eller oppdater dokumentet (hvis id er funnet):

JsonDocument upserted = bucket.upsert (dokument);

4.3. Henter et dokument

Å hente et dokument etter id, bruker vi få metode:

JsonDocument hentet = bucket.get (id);

Hvis det ikke finnes noe dokument med det gitte id, returnerer metoden null.

4.4. Oppdatere eller erstatte et dokument

Vi kan oppdatere et eksisterende dokument ved hjelp av oppover metode:

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

Som vi nevnte i avsnitt 4.2, oppover vil lykkes om et dokument med det gitte id ble funnet eller ikke.

Hvis det har gått nok tid mellom da vi opprinnelig hentet dokumentet og vårt forsøk på å oppheve det reviderte dokumentet, er det en mulighet for at originaldokumentet vil ha blitt slettet fra bøtta av en annen prosess eller bruker.

Hvis vi trenger å beskytte oss mot dette scenariet i applikasjonen vår, kan vi i stedet bruke erstatte metoden, som mislykkes med en DocumentDoesNotExistException hvis et dokument med det gitte id finnes ikke i Couchbase:

JsonDocument erstattet = bucket.replace (dokument);

4.5. Slette et dokument

For å slette et Couchbase-dokument bruker vi fjerne metode:

JsonDocument fjernet = bucket.remove (dokument);

Du kan også fjerne ved id:

JsonDocument fjernet = bucket.remove (id);

De JsonDocument gjenstand returnert har bare id og CAS egenskaper satt; alle andre egenskaper (inkludert JSON-innholdet) fjernes fra det returnerte objektet.

Hvis det ikke finnes noe dokument med det gitte id, Couchbase kaster en DocumentDoesNotExistException.

5. Arbeide med kopier

Denne delen diskuterer Couchbases virtuelle bøtte- og replikaarkitektur og introduserer en mekanisme for å hente en kopi av et dokument i tilfelle et dokuments primære node er utilgjengelig.

5.1. Virtuelle bøtter og kopier

Couchbase distribuerer dokumenter fra en bøtte over en samling av 1024 virtuelle bøtter, eller skuffer, ved hjelp av en hashingalgoritme på dokumentet id for å bestemme vbucket hvor hvert dokument skal lagres.

Hver Couchbase-bøtte kan også konfigureres til å vedlikeholde en eller flere kopier av hver vbucket. Hver gang et dokument settes inn eller oppdateres og skrives til det vbucket, Couchbase setter i gang en prosess for å replikere det nye eller oppdaterte dokumentet til det replika vbucket.

I en gruppe med flere noder distribuerer Couchbase skuffer og replika vbuckets blant alle datanodene i klyngen. EN vbucket og dets replika vbucket holdes på separate datanoder for å oppnå et visst mål på høy tilgjengelighet.

5.2. Henter et dokument fra en kopi

Når du henter et dokument etter id, hvis dokumentets primære node er nede eller ellers ikke kan nås på grunn av en nettverksfeil, kaster Couchbase et unntak.

Du kan la applikasjonen fange unntaket og prøve å hente en eller flere kopier av dokumentet ved hjelp av getFromReplica metode.

Følgende kode vil bruke den første kopien som ble funnet:

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

Vær oppmerksom på at det er mulig når du skriver søknaden din, å ha skriveoperasjoner blokkert til utholdenhet og replikering er fullført. Imidlertid er den vanligste fremgangsmåten, av hensyn til ytelse, å få applikasjonen til å returnere fra skriv umiddelbart etter skriving til minnet til et dokuments primære node, fordi diskskrivninger iboende er tregere enn minneskrivinger.

Når du bruker den sistnevnte tilnærmingen, kan replikaavlesninger kanskje ikke returnere den nyeste versjonen av dokumentet hvis den primære noden til et nylig oppdatert dokument skulle mislykkes eller gå offline før oppdateringene er fullstendig replikert.

Det er også verdt å merke seg at Couchbase henter kopier (hvis noen blir funnet) asynkront. Derfor, hvis bøtta er konfigurert for flere kopier, er det ingen garanti for i hvilken rekkefølge SDK returnerer dem, og det kan være lurt å gå gjennom alle replikaene som er funnet for å sikre at applikasjonen din har den nyeste tilgjengelige replikaversjonen:

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

6. Konklusjon

Vi har introdusert noen grunnleggende bruksscenarier du trenger for å komme i gang med Couchbase SDK.

Kodebiter presentert i denne veiledningen finner du i GitHub-prosjektet.

Du kan lære mer om SDK på det offisielle Couchbase SDK-utviklerdokumentasjonsstedet.