streamalism.org

1. Bemutatkozás

A Java Couchbase SDK ebben a bevezetőjében bemutatjuk, hogyan lehet kölcsönhatásba lépni egy Couchbase dokumentum adatbázissal, amely olyan alapfogalmakra terjed ki, mint például a Couchbase környezet létrehozása, kapcsolódás egy fürthöz, adatcsomagok megnyitása, az alapvető perzisztencia műveletek használata és a dokumentummal való munka másolatok.

2. Maven-függőségek

Ha Maven-t használ, adja hozzá a következőket a pom.xml fájljához:

 com.couchbase.client java-client 2.2.6 

3. Az első lépések

Az SDK biztosítja a CouchbaseEnvironment interfész és egy megvalósítási osztály DefaultCouchbaseEnvironment alapértelmezett beállításokat tartalmaz a fürtökhöz és a csoportokhoz való hozzáférés kezeléséhez. Az alapértelmezett környezeti beállítások szükség esetén felülírhatók, amint azt a 3.2 szakaszban láthatjuk.

Fontos: A Couchbase SDK hivatalos dokumentációja figyelmezteti a felhasználókat, hogy csak egyet biztosítsanak CouchbaseEnvironment aktív a JVM-ben, mivel kettő vagy több használata kiszámíthatatlan viselkedést eredményezhet.

3.1. Csatlakozás alapértelmezett környezettel rendelkező fürthöz

Ha az SDK automatikusan létrehozza a CouchbaseEnvironment alapértelmezett beállításokkal és társítva a fürtünkhöz, egyszerűen csatlakozhatunk a fürthöz azzal, hogy megadjuk a fürt egy vagy több csomópontjának IP-címét vagy hosztnevét.

Ebben a példában egycsomópontos fürthöz csatlakozunk a helyi munkaállomáson:

Fürt fürt = CouchbaseCluster.create ("localhost");

Több csomópontos fürthöz való csatlakozáshoz legalább két csomópontot kell megadnunk, ha az egyik nem érhető el, amikor az alkalmazás megpróbálja létrehozni a kapcsolatot:

Fürt fürt = CouchbaseCluster.create ("192.168.4.1", "192.168.4.2");

Jegyzet: A kezdeti kapcsolat létrehozásakor nem szükséges minden egyes csomópontot megadni. A CouchbaseEnvironment a kapcsolat létrejötte után lekérdezi a fürtöt a fennmaradó csomópontok (ha vannak) felderítése érdekében.

3.2. Egyéni környezet használata

Ha az alkalmazás megköveteli a beállítások bármelyikének finomhangolását DefaultCouchbaseEnvironment, létrehozhat egy egyéni környezetet, majd felhasználhatja azt a fürthöz való csatlakozáskor.

Íme egy példa, amely egy egyedi használatával kapcsolódik az egycsomópontos fürthöz CouchbaseEnvironment tíz másodperces kapcsolási időtúllépés és három másodperces kulcsérték-keresési időtúllépés:

CouchbaseEnvironment env = DefaultCouchbaseEnvironment.builder () .connectTimeout (10000) .kvTimeout (3000) .build (); Fürt fürt = CouchbaseCluster.create (env, "localhost");

És csatlakozás egy több csomópontos fürthöz az egyéni környezettel:

Fürt fürt = CouchbaseCluster.create (env, "192.168.4.1", "192.168.4.2");

3.3. Vödör kinyitása

Miután csatlakozott a Couchbase fürthöz, megnyithat egy vagy több vödröt.

A Couchbase-fürt első beállításakor a telepítőcsomag automatikusan létrehoz egy nevű vödröt „Alapértelmezett” üres jelszóval.

Itt van az egyik módja a „Alapértelmezett” ha üres jelszóval rendelkezik:

Vödör vödör = fürt.openBucket ();

Megadhatja a vödör nevét is, amikor megnyitja:

Vödör vödör = cluster.openBucket ("alapértelmezett");

Bármely más üres jelszóval rendelkező vödör esetén Ön kell adja meg a vödör nevét:

Vödör myBucket = cluster.openBucket ("myBucket");

A nem üres jelszóval rendelkező tároló megnyitásához meg kell adnia a csoport nevét és Jelszó:

Vödör vödör = cluster.openBucket ("bucketName", "bucketPassword");

4. Perzisztencia műveletek

Ebben a részben bemutatjuk, hogyan kell CRUD műveleteket végrehajtani a Couchbase-ben. Példáinkban egyszerű JSON dokumentumokkal fogunk dolgozni, amelyek egy személyt képviselnek, mint ebben a minta dokumentumban:

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

A "típus" Az attribútum nem szükséges, azonban általános gyakorlat, hogy a dokumentum típusát meghatározó attribútumot is be kell építeni abban az esetben, ha az egyik úgy dönt, hogy több típust tárol ugyanabban a vödörben.

4.1. Dokumentumazonosítók

A Couchbase-ben tárolt minden dokumentum társítva van egy id amely egyedülálló abban a tárolóban, amelyben a dokumentumot tárolják. A dokumentum id analóg a hagyományos relációs adatbázis-sor elsődleges kulcs oszlopával.

Dokumentum id Az értékeknek legfeljebb 250 bájtos UTF-8 karakterláncoknak kell lenniük.

Mivel a Couchbase nem nyújt mechanizmust a id beillesztéskor meg kell adnunk a magunkét.

A generálás közös stratégiái azonosítók tartalmazzon kulcs-levezetést természetes kulcs használatával, például a "email" a mintadokumentumban bemutatott attribútum és a UUID húrok.

Példáinkhoz véletlenszerűt generálunk UUID húrok.

4.2. Dokumentum beszúrása

Mielőtt új dokumentumot illeszthetünk a tárolóba, először létre kell hoznunk egy példányát JSONObject a dokumentum tartalmát tartalmazza:

JsonObject content = JsonObject.empty () .put ("név", "John Doe") .put ("típus", "Személy") .put ("e-mail", "[e-mail védett]") .put ("homeTown") "," Chicago ");

Ezután létrehozunk egy JSONDocument tárgy, amely egy id érték és a JSONObject:

String id = UUID.randomUUID (). ToString (); JsonDocument document = JsonDocument.create (id, tartalom);

Új dokumentum hozzáadásához a csoportba a betét módszer:

JsonDocument insert = vödör.beillesztés (dokumentum);

A JsonDocument A return az eredeti dokumentum összes tulajdonságát tartalmazza, valamint egy értéket, amely a „CAS” (összehasonlítás és csere) érték, amelyet a Couchbase használ a verziókövetéshez.

Ha a mellékelt dokumentum id már létezik a vödörben, Couchbase dob egy DocumentAlreadyExistsException.

Használhatjuk a felfordítani metódus, amely vagy beilleszti a dokumentumot (ha a id nem található), vagy frissítse a dokumentumot (ha a id található):

JsonDocument uperted = bucket.upsert (dokumentum);

4.3. Dokumentum visszakeresése

Dokumentum lekérése annak alapján id, használjuk a kap módszer:

JsonDocument letöltve = bucket.get (id);

Ha a megadottal nincs dokumentum id, a metódus visszatér nulla.

4.4. Dokumentum frissítése vagy cseréje

Frissíthetünk egy meglévő dokumentumot a felfordítani módszer:

JsonObject tartalom = dokumentum.tartalom (); content.put ("homeTown", "Kansas City"); JsonDocument uperted = bucket.upsert (dokumentum);

Amint azt a 4.2. Szakaszban említettük, felfordítani sikerül-e, hogy egy dokumentum a megadottal id találtak vagy sem.

Ha elegendő idő telt el a dokumentum eredeti lekérése és a felülvizsgált dokumentum megdöntésére tett kísérlet között, akkor fennáll annak a lehetősége, hogy az eredeti dokumentumot egy másik folyamat vagy felhasználó törölte a csoportból.

Ha védenünk kell ezt a forgatókönyvet az alkalmazásunkban, akkor ehelyett használhatjuk a cserélje ki módszer, amely a DocumentDoesNotExistException ha egy dokumentum a megadottal id nem található a Couchbase-ben:

JsonDocument cserélve = bucket.replace (dokumentum);

4.5. Dokumentum törlése

A Couchbase dokumentum törléséhez a eltávolítani módszer:

JsonDocument eltávolítva = bucket.remove (dokumentum);

Eltávolíthatja a következőt is: id:

JsonDocument eltávolítva = bucket.remove (id);

A JsonDocument a visszaküldött objektumnak csak a id és CAS beállított tulajdonságok; az összes többi tulajdonság (beleértve a JSON tartalmat is) eltávolításra kerül a visszaküldött objektumból.

Ha a megadottal nincs dokumentum id, Couchbase dob a DocumentDoesNotExistException.

5. Munka a másolatokkal

Ez a szakasz a Couchbase virtuális sávjának és replikájának architektúráját tárgyalja, és bemutatja a dokumentum másolatának lekérésére szolgáló mechanizmust abban az esetben, ha a dokumentum elsődleges csomópontja nem érhető el.

5.1. Virtuális vödrök és replikák

A Couchbase egy vödör dokumentumait 1024 virtuális vödör gyűjteményében terjeszti vödrök, kivonatoló algoritmust használva a dokumentumon id hogy meghatározzuk a vbucket amelyben minden egyes dokumentumot tárolni lehet.

Minden Couchbase vödör konfigurálható egy vagy több karbantartására is másolatok ből vbucket. Amikor egy dokumentumot beillesztenek vagy frissítenek, és arra írnak vbucket, A Couchbase elindít egy eljárást az új vagy frissített dokumentum lemásolására replika vbucket.

Több csomópontos fürtben a Couchbase terjeszt vödrök és replika vödrök a fürt összes adatcsomópontja között. A vbucket és annak replika vbucket külön adatcsomópontokon tartják a magas rendelkezésre állás bizonyos mértékének elérése érdekében.

5.2. Dokumentum lekérése másolatból

Amikor egy dokumentumot annak segítségével szerez be id, ha a dokumentum elsődleges csomópontja nem működik, vagy hálózati hiba miatt más módon nem érhető el, a Couchbase kivételt vet.

Engedélyezheti, hogy az alkalmazás elkapja a kivételt, és megpróbálja lekérni a dokumentum egy vagy több másolatát a getFromReplica módszer.

A következő kód használná az első megtalált replikát:

JsonDocument doc; próbáld ki a {doc = bucket.get (id) parancsot; } catch (CouchbaseException e) {List list = bucket.getFromReplica (id, ReplicaMode.FIRST); if (! list.isEmpty ()) {doc = list.get (0); }}

Ne feledje, hogy az alkalmazás megírásakor lehetséges az írási műveletek blokkolása a kitartás és a replikáció befejezéséig. A teljesítmény okai miatt azonban az általános gyakorlat az, hogy az alkalmazás azonnal visszaáll az írásokról, miután írta a dokumentum elsődleges csomópontjának a memóriájába, mert a lemez írása eleve lassabb, mint a memória írása.

Ez utóbbi megközelítés alkalmazásakor, ha egy nemrégiben frissített dokumentum elsődleges csomópontja meghibásodik vagy offline állapotba kerül, mielőtt a frissítéseket teljesen replikálnák, a replika olvasása visszaadhatja a dokumentum legújabb verzióját, vagy nem.

Érdemes megjegyezni azt is, hogy a Couchbase aszinkron módon kapja le a replikákat (ha vannak ilyenek). Ezért, ha a csoport több replikához van konfigurálva, nincs garancia arra, hogy az SDK milyen sorrendben adja vissza őket, és érdemes végiglapoznia az összes megtalált replikát, hogy megbizonyosodhasson arról, hogy az alkalmazás a rendelkezésre álló legfrissebb verzióval rendelkezik:

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

6. Következtetés

Bevezettünk néhány alapvető használati forgatókönyvet, amelyekre szüksége lesz a Couchbase SDK használatának megkezdéséhez.

Az oktatóanyagban bemutatott kódrészletek a GitHub projektben találhatók.

Az SDK-ról többet megtudhat a hivatalos Couchbase SDK fejlesztői dokumentációs oldalon.