Bevezetés a Java Couchbase SDK-ba
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.