Uvod u Couchbase SDK za Javu
1. Uvod
U ovom uvodu u Couchbase SDK za Javu demonstriramo kako komunicirati s bazom podataka Couchbase dokumenata, pokrivajući osnovne koncepte poput stvaranja Couchbase okruženja, povezivanja s klasterom, otvaranja segmenata podataka, korištenja osnovnih operacija trajanja i rada s dokumentom replike.
2. Ovisnosti Mavena
Ako koristite Maven, dodajte sljedeće u datoteku pom.xml:
com.couchbase.client java-client 2.2.6
3. Početak rada
SDK pruža CouchbaseEnvironment sučelje i klasa implementacije DefaultCouchbaseEnvironment koji sadrži zadane postavke za upravljanje pristupom klasterima i segmentima. Zadane postavke okruženja mogu se poništiti ako je potrebno, kao što ćemo vidjeti u odjeljku 3.2.
Važno: Službena Couchbase SDK dokumentacija upozorava korisnike da osiguraju samo jedan CouchbaseEnvironment aktivan je u JVM-u, jer upotreba dva ili više može rezultirati nepredvidljivim ponašanjem.
3.1. Povezivanje s klasterom sa zadanim okruženjem
Da bi SDK automatski stvorio a CouchbaseEnvironment sa zadanim postavkama i pridružiti ga našem klasteru, možemo se povezati s klasterom jednostavno davanjem IP adrese ili naziva hosta jednog ili više čvorova u klasteru.
U ovom primjeru povezujemo se s klasterom s jednim čvorom na našoj lokalnoj radnoj stanici:
Klaster klastera = CouchbaseCluster.create ("localhost");
Da bismo se povezali s klasterom s više čvorova, naveli bismo najmanje dva čvora u slučaju da jedan od njih nije dostupan kada aplikacija pokušava uspostaviti vezu:
Klaster klastera = CouchbaseCluster.create ("192.168.4.1", "192.168.4.2");
Bilješka: Nije potrebno navesti svaki čvor u klasteru prilikom kreiranja početne veze. The CouchbaseEnvironment upitat će klaster nakon uspostavljanja veze kako bi se otkrili preostali čvorovi (ako ih ima).
3.2. Korištenje prilagođenog okruženja
Ako vaša aplikacija zahtijeva fino podešavanje bilo koje postavke koju pruža DefaultCouchbaseEnvironment, možete stvoriti prilagođeno okruženje, a zatim ga koristiti prilikom povezivanja s klasterom.
Evo primjera koji se povezuje s klasterom s jednim čvorom pomoću prilagođenog CouchbaseEnvironment s deset sekundi prekida veze i vremenskim ograničenjem pretraživanja ključ / vrijednost od tri sekunde:
CouchbaseEnvironment env = DefaultCouchbaseEnvironment.builder () .connectTimeout (10000) .kvTimeout (3000) .build (); Klaster klastera = CouchbaseCluster.create (env, "localhost");
I za povezivanje s klasterom s više čvorova s prilagođenim okruženjem:
Klaster klastera = CouchbaseCluster.create (env, "192.168.4.1", "192.168.4.2");
3.3. Otvaranje kante
Nakon što se povežete s Couchbase klasterom, možete otvoriti jedan ili više segmenata.
Kada prvi put postavite Couchbase klaster, instalacijski paket automatski kreira segment s imenom "zadano" s praznom lozinkom.
Evo jednog od načina za otvaranje "zadano" kanta kad ima praznu lozinku:
Segment kante = cluster.openBucket ();
Prilikom otvaranja možete navesti i naziv segmenta:
Segment kanta = cluster.openBucket ("zadani");
Za bilo koju drugu kantu s praznom lozinkom, vi mora navedite naziv kante:
Segment myBucket = cluster.openBucket ("myBucket");
Da biste otvorili segment koji ima praznu lozinku, morate unijeti ime segmenta i zaporka:
Segment segmenta = cluster.openBucket ("bucketName", "bucketPassword");
4. Operacije upornosti
U ovom odjeljku prikazujemo kako izvoditi CRUD operacije u Couchbaseu. U našim ćemo primjerima raditi s jednostavnim JSON dokumentima koji predstavljaju osobu, kao u ovom primjeru dokumenta:
{"name": "John Doe", "type": "Person", "email": "[email protected]", "homeTown": "Chicago"}
The "tip" atribut nije potreban, međutim uobičajena je praksa uključivanje atributa koji specificira vrstu dokumenta u slučaju da se netko odluči pohraniti više vrsta u isti segment.
4.1. ID-ovi dokumenata
Svaki dokument pohranjen u Couchbaseu povezan je s iskaznica to je jedinstveno za segment u kojem se dokument čuva. Dokument iskaznica analogan je stupcu primarnog ključa u tradicionalnom retku relacijske baze podataka.
Dokument iskaznica vrijednosti moraju biti UTF-8 nizovi od 250 ili manje bajtova.
Budući da Couchbase ne pruža mehanizam za automatsko generiranje iskaznica pri umetanju moramo pružiti svoje.
Uobičajene strategije generiranja id uključuju izvođenje ključa pomoću prirodnog ključa, kao što je "E-pošta" atribut prikazan u našem uzorku dokumenta i upotreba UUID žice.
Za naše primjere generirat ćemo slučajno UUID žice.
4.2. Umetanje dokumenta
Prije nego što u svoj segment možemo umetnuti novi dokument, prvo moramo stvoriti instancu JSONObject koji sadrži sadržaj dokumenta:
JsonObject content = JsonObject.empty () .put ("name", "John Doe") .put ("type", "Person") .put ("email", "[email protected]") .put ("homeTown "," Chicago ");
Dalje, kreiramo JSONDocument objekt koji se sastoji od iskaznica vrijednost i JSONObject:
ID niza = UUID.randomUUID (). ToString (); JsonDocument dokument = JsonDocument.create (id, sadržaj);
Da bismo dodali novi dokument u skupinu, koristimo umetnuti metoda:
JsonDocument umetnut = bucket.insert (dokument);
The JsonDocument return sadrži sva svojstva izvornog dokumenta, plus vrijednost poznatu kao "CAS" (usporedite i zamijenite) vrijednost koju Couchbase koristi za praćenje verzija.
Ako je dokument s priloženim iskaznica već postoji u segmentu, Couchbase baca a DocumentAlreadyExistsException.
Također možemo koristiti upsert metoda, koja će umetnuti dokument (ako je iskaznica nije pronađen) ili ažurirajte dokument (ako je iskaznica pronađeno je):
JsonDocument upserted = bucket.upsert (dokument);
4.3. Dohvaćanje dokumenta
Da biste dokument preuzeli pomoću iskaznica, koristimo dobiti metoda:
Dobavljen JsonDocument = bucket.get (id);
Ako s danim ne postoji dokument iskaznica, metoda se vraća null.
4.4. Ažuriranje ili zamjena dokumenta
Postojeći dokument možemo ažurirati pomoću upsert metoda:
Sadržaj JsonObject = document.content (); content.put ("homeTown", "Kansas City"); JsonDocument upserted = bucket.upsert (dokument);
Kao što smo spomenuli u odjeljku 4.2, upsert uspjeti hoće li dokument s danim iskaznica pronađeno ili nije.
Ako je prošlo dovoljno vremena između trenutka kada smo izvorno preuzeli dokument i našeg pokušaja postavljanja revidiranog dokumenta, postoji mogućnost da će drugi postupak ili korisnik izvorni dokument izbrisati iz segmenta.
Ako se u našoj aplikaciji moramo zaštititi ovog scenarija, umjesto toga možemo koristiti zamijeniti metoda koja ne uspije s a DocumentDoesNotExistException ako dokument s danim iskaznica nije pronađen u Couchbaseu:
Zamijenjen JsonDocument = bucket.replace (dokument);
4.5. Brisanje dokumenta
Za brisanje Couchbase dokumenta koristimo ukloniti metoda:
JsonDocument uklonjen = bucket.remove (dokument);
Možete i ukloniti do iskaznica:
JsonDocument uklonjen = bucket.remove (id);
The JsonDocument vraćeni objekt ima samo iskaznica i CAS postavljena svojstva; sva ostala svojstva (uključujući JSON sadržaj) uklanjaju se iz vraćenog objekta.
Ako s danim ne postoji dokument iskaznica, Couchbase baca a DocumentDoesNotExistException.
5. Rad s replikama
Ovaj odjeljak raspravlja o arhitekturi virtualnog segmenta i replika Couchbase i uvodi mehanizam za dohvaćanje replike dokumenta u slučaju da primarni čvor dokumenta nije dostupan.
5.1. Virtualne kante i replike
Couchbase distribuira dokumente segmenta kroz zbirku od 1024 virtualna segmenta ili vbuckets, koristeći algoritam raspršivanja na dokumentu iskaznica utvrditi vbucket u koju treba pohraniti svaki dokument.
Svaka sekcija Couchbase također se može konfigurirati da održava jednu ili više njih replike svakog vbucket. Kad god se dokument umetne ili ažurira i napiše u njega vbucket, Couchbase pokreće postupak repliciranja novog ili ažuriranog dokumenta na njegov replika vbucket.
U klasteru s više čvorova, Couchbase distribuira vbuckets i replika vbucket-a među svim podatkovnim čvorovima u klasteru. A vbucket I je replika vbucket čuvaju se na odvojenim čvorovima podataka kako bi se postigla određena mjera visoke dostupnosti.
5.2. Dohvaćanje dokumenta iz replike
Prilikom dohvaćanja dokumenta pomoću iskaznica, ako je primarni čvor dokumenta odbijen ili je na drugi način nedostupan zbog mrežne pogreške, Couchbase donosi iznimku.
Možete zatražiti da vaša aplikacija uhvati iznimku i pokuša dohvatiti jednu ili više replika dokumenta pomoću getFromReplica metoda.
Sljedeći kôd koristi prvu pronađenu repliku:
JsonDocument doc; pokušajte {doc = bucket.get (id); } catch (CouchbaseException e) {List list = bucket.getFromReplica (id, ReplicaMode.FIRST); if (! list.isEmpty ()) {doc = list.get (0); }}
Imajte na umu da je moguće prilikom pisanja aplikacije blokirati operacije pisanja dok se ne završi trajanje i replikacija. Međutim, češća je praksa, zbog performansi, da se aplikacija vraća iz upisa odmah nakon upisivanja u memoriju primarnog čvora dokumenta, jer je zapisivanje na disku u osnovi sporije od upisa u memoriju.
Kada se koristi potonji pristup, ako primarni čvor nedavno ažuriranog dokumenta ne uspije ili se isključi izvan mreže prije nego što se ažuriranja u potpunosti repliciraju, očitavanja replike mogu ili ne moraju vratiti najnoviju verziju dokumenta.
Također je vrijedno napomenuti da Couchbase asinhrono dohvaća replike (ako su pronađene). Stoga, ako je vaš segment konfiguriran za više replika, ne postoji jamstvo za redoslijed kojim ih SDK vraća, a možda ćete htjeti pregledati sve pronađene replike kako biste osigurali da vaša aplikacija ima najnoviju verziju replike:
duga maxCasValue = -1; za (JsonDocument replika: bucket.getFromReplica (id, ReplicaMode.ALL)) {if (replica.cas ()> maxCasValue) {doc = replika; maxCasValue = replica.cas (); }}
6. Zaključak
Uveli smo nekoliko osnovnih scenarija upotrebe koji će vam trebati da biste započeli s Couchbase SDK-om.
Isječci koda predstavljeni u ovom vodiču mogu se naći u projektu GitHub.
Možete saznati više o SDK-u na službenom web mjestu dokumentacije za razvojne programere Couchbase SDK.