streamalism.org

1. Úvod

V tomto úvode do Couchbase SDK pre Javu si ukážeme, ako interagovať s databázou dokumentov Couchbase, pokrývajúc základné pojmy, ako je vytvorenie prostredia Couchbase, pripojenie k klastru, otvorenie dátových segmentov, použitie základných operácií vytrvalosti a práca s dokumentom. repliky.

2. Maven závislosti

Ak používate Maven, do súboru pom.xml pridajte toto:

 com.couchbase.client java-client 2.2.6 

3. Začíname

SDK poskytuje CouchbaseEnvironment rozhranie a implementačná trieda DefaultCouchbaseEnvironment obsahujúce predvolené nastavenia pre správu prístupu do klastrov a segmentov. Predvolené nastavenia prostredia je možné v prípade potreby prepísať, ako uvidíme v časti 3.2.

Dôležité: Oficiálna dokumentácia Couchbase SDK upozorňuje používateľov, aby zabezpečili, že bude iba jeden CouchbaseEnvironment je aktívny v JVM, pretože použitie dvoch alebo viacerých môže mať za následok nepredvídateľné správanie.

3.1. Pripojenie ku klastru s predvoleným prostredím

Ak chcete, aby SDK automaticky vytvorilo a CouchbaseEnvironment s predvolenými nastaveniami a priradiť ho k nášmu klastru, môžeme sa k klastru pripojiť jednoducho poskytnutím adresy IP alebo názvu hostiteľa jedného alebo viacerých uzlov v klastri.

V tomto príklade sa pripájame k klastru s jedným uzlom na našej lokálnej pracovnej stanici:

Klastrový klaster = CouchbaseCluster.create ("localhost");

Na pripojenie k viacuzlovému klastru by sme určili najmenej dva uzly pre prípad, že jeden z nich nebude k dispozícii, keď sa aplikácia pokúsi nadviazať spojenie:

Klastrový klaster = CouchbaseCluster.create ("192.168.4.1", "192.168.4.2");

Poznámka: Pri vytváraní počiatočného pripojenia nie je potrebné špecifikovať každý uzol v klastri. The CouchbaseEnvironment po nadviazaní spojenia vyhľadá klaster, aby zistil zostávajúce uzly (ak existujú).

3.2. Používanie vlastného prostredia

Ak vaša aplikácia vyžaduje jemné doladenie ktoréhokoľvek z nastavení poskytovaných serverom DefaultCouchbaseEnvironment, môžete vytvoriť vlastné prostredie a potom ho použiť pri pripájaní k svojmu klastru.

Tu je príklad, ktorý sa pripája k klastru s jedným uzlom pomocou vlastného CouchbaseEnvironment s časovým limitom pripojenia desať sekúnd a časovým limitom vyhľadávania kľúč-hodnota tri sekundy:

CouchbaseEnvironment env = DefaultCouchbaseEnvironment.builder () .connectTimeout (10 000). KvTimeout (3 000). Build (); Klastrový klaster = CouchbaseCluster.create (env, "localhost");

A pripojenie k viacuzlovému klastru s vlastným prostredím:

Klastrový klaster = CouchbaseCluster.create (env, "192.168.4.1", "192.168.4.2");

3.3. Otvorenie vedra

Po pripojení ku klastru Couchbase môžete otvoriť jeden alebo viac segmentov.

Pri prvom nastavení klastra Couchbase inštalačný balík automaticky vytvorí segment s názvom „Predvolené“ s prázdnym heslom.

Existuje jeden spôsob, ako otvoriť „Predvolené“ vedro, ak má prázdne heslo:

Vedro vedro = cluster.openBucket ();

Pri otvorení môžete tiež určiť názov segmentu:

Vedro vedro = cluster.openBucket ("predvolené");

Pre akýkoľvek iný segment s prázdnym heslom vy musieť zadajte názov vedra:

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

Ak chcete otvoriť segment, ktorý má nevyplnené heslo, musíte zadať názov segmentu a heslo:

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

4. Perzistenčné operácie

V tejto časti si ukážeme, ako vykonávať operácie CRUD v Couchbase. V našich príkladoch budeme pracovať s jednoduchými dokumentmi JSON, ktoré predstavujú osobu, ako v tomto vzorovom dokumente:

{"name": "John Doe", "type": "Person", "email": "[chránený e-mailom]", "homeTown": "Chicago"}

The „Typ“ atribút sa nevyžaduje, je však bežnou praxou zahrnúť atribút určujúci typ dokumentu v prípade, že sa niekto rozhodne uložiť viac typov do toho istého segmentu.

4.1. ID dokladov

Každý dokument uložený v Couchbase je priradený k id ktorý je jedinečný pre segment, v ktorom je dokument uložený. Dokument id je analogický k stĺpcu primárneho kľúča v tradičnom riadku relačnej databázy.

Dokument id hodnoty musia byť reťazce UTF-8 s veľkosťou 250 alebo menej bajtov.

Pretože Couchbase neposkytuje mechanizmus na automatické generovanie id pri vložení musíme zabezpečiť svoje vlastné.

Spoločné stratégie pre generovanie ids zahŕňajú odvodenie kľúča pomocou prirodzeného kľúča, napríklad „Email“ atribút uvedený v našom vzorovom dokumente a použitie atribútu UUID struny.

Pre naše príklady vygenerujeme náhodné UUID struny.

4.2. Vkladanie dokumentu

Predtým, ako môžeme vložiť nový dokument do nášho segmentu, musíme najskôr vytvoriť inštanciu JSONObject obsahujúci obsah dokumentu:

JsonObject content = JsonObject.empty () .put ("name", "John Doe") .put ("type", "Person") .put ("email", "[chránený e-mailom]") .put ("homeTown" "," Chicago ");

Ďalej vytvoríme a JSONDocument objekt pozostávajúci z id hodnota a JSONObject:

Reťazec id = UUID.randomUUID (). ToString (); JsonDocument document = JsonDocument.create (id, obsah);

Na pridanie nového dokumentu do vedra používame vložiť metóda:

Vložený JsonDocument = bucket.insert (dokument);

The JsonDocument Vrátený obsahuje všetky vlastnosti pôvodného dokumentu plus hodnotu známu ako „CAS“ (porovnať a vymeniť) hodnota, ktorú Couchbase používa na sledovanie verzií.

Ak je dokument s dodaným id už vo vedierku existuje, Couchbase hodí a DocumentAlreadyExistsException.

Môžeme tiež použiť upsert metóda, ktorá buď vloží dokument (ak id sa nenájde) alebo aktualizujte dokument (ak id je nájdený):

JsonDocument upserted = bucket.upsert (dokument);

4.3. Načítanie dokumentu

Ak chcete získať dokument podľa jeho id, používame dostať metóda:

JsonDocument retrieved = bucket.get (id);

Pokiaľ s daným neexistuje žiadny dokument id, metóda sa vráti nulový.

4.4. Aktualizácia alebo výmena dokumentu

Existujúci dokument môžeme aktualizovať pomocou upsert metóda:

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

Ako sme uviedli v časti 4.2, upsert uspeje, či dokument s daným id bol nájdený alebo nie.

Ak medzi pôvodným načítaním dokumentu a našim pokusom o vyvrátenie revidovaného dokumentu uplynulo dosť času, existuje možnosť, že pôvodný dokument bude z vedra vymazaný iným procesom alebo používateľom.

Ak sa potrebujeme v našej aplikácii chrániť pred týmto scenárom, môžeme namiesto toho použiť vymeniť metóda, ktorá zlyháva s a DocumentDoesNotExistException ak doklad s daným id sa nenachádza v Couchbase:

JsonDocument nahradený = bucket.replace (dokument);

4.5. Vymazanie dokumentu

Na vymazanie dokumentu Couchbase používame odstrániť metóda:

JsonDocument odstránený = bucket.remove (dokument);

Môžete tiež odstrániť do id:

JsonDocument odstránený = bucket.remove (id);

The JsonDocument vrátený objekt má iba id a CAS sada vlastností; všetky ostatné vlastnosti (vrátane obsahu JSON) sa odstránia z vráteného objektu.

Pokiaľ s daným neexistuje žiadny dokument id, Couchbase hodí a DocumentDoesNotExistException.

5. Práca s replikami

Táto časť pojednáva o architektúre virtuálnych segmentov a replík Couchbase a zavádza mechanizmus na načítanie replík dokumentu v prípade, že primárny uzol dokumentu nie je k dispozícii.

5.1. Virtuálne vedierka a repliky

Couchbase distribuuje dokumenty vedra do zbierky 1024 virtuálnych vedier alebo vbucketspomocou hashovacieho algoritmu v dokumente id určiť vbucket do ktorého sa má každý dokument uložiť.

Každý segment Couchbase môže byť tiež nakonfigurovaný na údržbu jedného alebo viacerých repliky každého z nich vbucket. Kedykoľvek je dokument vložený alebo aktualizovaný a je do neho zapísaný vbucket, Couchbase iniciuje proces replikácie nového alebo aktualizovaného dokumentu na svoj replika vbucket.

Vo viacuzlovom klastri distribuuje Couchbase vbuckets a replika vbuckets medzi všetkými dátovými uzlami v klastri. A vbucket a jeho replika vbucket sa uchovávajú na samostatných dátových uzloch, aby sa dosiahla určitá miera vysokej dostupnosti.

5.2. Načítanie dokumentu z repliky

Pri načítaní dokumentu podľa jeho id, ak je primárny uzol dokumentu nefunkčný alebo inak nedosiahnuteľný z dôvodu chyby siete, Couchbase hodí výnimku.

Môžete nechať svoju aplikáciu chytiť výnimku a pokúsiť sa získať jednu alebo viac replík dokumentu pomocou súboru getFromReplica metóda.

Nasledujúci kód by použil prvú nájdenú repliku:

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

Upozorňujeme, že pri písaní aplikácie je možné blokovať operácie zápisu, kým nedôjde k úplnému dokončeniu a replikácii. Bežnejšou praxou je však z dôvodu výkonu zabezpečenie návratu aplikácie zo zápisov ihneď po zápise do pamäte primárneho uzla dokumentu, pretože zápisy na disk sú vo svojej podstate pomalšie ako zápisy do pamäte.

Ak pri použití tohto druhého prístupu dôjde k zlyhaniu primárneho uzla naposledy aktualizovaného dokumentu alebo k prepnutiu do režimu offline pred úplnou replikáciou aktualizácií, načítanie replík môže alebo nemusí vrátiť najnovšiu verziu dokumentu.

Za zmienku tiež stojí, že Couchbase načítava repliky (ak sa nejaké nájdu) asynchrónne. Preto ak je váš segment nakonfigurovaný pre viac replík, neexistuje žiadna záruka, pokiaľ ide o poradie, v ktorom ich SDK vracia. Možno budete chcieť prepracovať všetky nájdené repliky, aby ste sa uistili, že vaša aplikácia má k dispozícii najnovšiu verziu repliky:

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

6. Záver

Predstavili sme niekoľko základných scenárov použitia, ktoré budete potrebovať, aby ste mohli začať s Couchbase SDK.

Útržky kódu prezentované v tomto výučbe nájdete v projekte GitHub.

Viac sa o SDK dozviete na oficiálnych stránkach dokumentácie pre vývojárov Couchbase SDK.