Inleiding tot Couchbase SDK voor Java
1. Inleiding
In deze inleiding tot de Couchbase SDK voor Java laten we zien hoe u omgaat met een Couchbase-documentdatabase, waarbij we basisconcepten behandelen zoals het creëren van een Couchbase-omgeving, verbinding maken met een cluster, gegevensbuckets openen, de basisbewerkingen voor persistentie gebruiken en werken met documentgegevens. replica's.
2. Maven afhankelijkheden
Als u Maven gebruikt, voegt u het volgende toe aan uw pom.xml-bestand:
com.couchbase.client java-client 2.2.6 3. Aan de slag
De SDK biedt het Couchbase-omgeving interface en een implementatieklasse DefaultCouchbaseEnvironment met standaardinstellingen voor het beheren van toegang tot clusters en buckets. De standaard omgevingsinstellingen kunnen indien nodig worden overschreven, zoals we zullen zien in paragraaf 3.2.
Belangrijk: De officiële Couchbase SDK-documentatie waarschuwt gebruikers om ervoor te zorgen dat er slechts één Couchbase-omgeving is actief in de JVM, aangezien het gebruik van twee of meer kan leiden tot onvoorspelbaar gedrag.
3.1. Verbinding maken met een cluster met een standaardomgeving
Om de SDK automatisch een Couchbase-omgeving met standaardinstellingen en deze aan ons cluster koppelen, kunnen we verbinding maken met het cluster door simpelweg het IP-adres of de hostnaam van een of meer knooppunten in het cluster op te geven.
In dit voorbeeld maken we verbinding met een cluster met één knooppunt op ons lokale werkstation:
Clustercluster = CouchbaseCluster.create ("localhost");Om verbinding te maken met een cluster met meerdere knooppunten, specificeren we ten minste twee knooppunten voor het geval een ervan niet beschikbaar is wanneer de toepassing probeert de verbinding tot stand te brengen:
Clustercluster = CouchbaseCluster.create ("192.168.4.1", "192.168.4.2");Opmerking: Het is niet nodig om elk knooppunt in het cluster op te geven bij het maken van de eerste verbinding. De Couchbase-omgeving zal het cluster opvragen zodra de verbinding tot stand is gebracht om de resterende knooppunten (indien aanwezig) te ontdekken.
3.2. Met behulp van een aangepaste omgeving
Als uw toepassing een fijnafstemming van een van de instellingen van DefaultCouchbaseEnvironment, kunt u een aangepaste omgeving maken en die omgeving vervolgens gebruiken wanneer u verbinding maakt met uw cluster.
Hier is een voorbeeld dat verbinding maakt met een cluster met één knooppunt met behulp van een aangepast Couchbase-omgeving met een time-out voor een verbinding van tien seconden en een time-out voor het opzoeken van sleutelwaarden van drie seconden:
CouchbaseEnvironment env = DefaultCouchbaseEnvironment.builder () .connectTimeout (10000) .kvTimeout (3000) .build (); Clustercluster = CouchbaseCluster.create (env, "localhost");En om verbinding te maken met een cluster met meerdere knooppunten met de aangepaste omgeving:
Clustercluster = CouchbaseCluster.create (env, "192.168.4.1", "192.168.4.2");3.3. Een emmer openen
Nadat u verbinding heeft gemaakt met het Couchbase-cluster, kunt u één of meerdere buckets openen.
Wanneer u voor het eerst een Couchbase-cluster opzet, maakt het installatiepakket automatisch een bucket aan met de naam "standaard" met een blanco wachtwoord.
Hier is een manier om het "standaard" bucket als het een leeg wachtwoord heeft:
Bucket bucket = cluster.openBucket ();U kunt ook de bucketnaam opgeven wanneer u deze opent:
Bucket bucket = cluster.openBucket ("standaard");Voor elke andere bucket met een leeg wachtwoord, jij moet geef de naam van de bucket:
Bucket myBucket = cluster.openBucket ("myBucket");Om een bucket te openen die een niet-leeg wachtwoord heeft, moet u de bucketnaam opgeven en wachtwoord:
Bucket bucket = cluster.openBucket ("bucketName", "bucketPassword");4. Persistentieoperaties
In dit gedeelte laten we zien hoe u CRUD-bewerkingen kunt uitvoeren in Couchbase. In onze voorbeelden werken we met eenvoudige JSON-documenten die een persoon vertegenwoordigen, zoals in dit voorbeelddocument:
{"name": "John Doe", "type": "Person", "email": "[email protected]", "homeTown": "Chicago"}De "type" attribuut is niet vereist, maar het is gebruikelijk om een attribuut op te nemen dat het documenttype specificeert voor het geval men besluit om meerdere typen in dezelfde bucket op te slaan.
4.1. Document-ID's
Elk document dat in Couchbase is opgeslagen, is gekoppeld aan een ID kaart dat is uniek voor de bucket waarin het document wordt opgeslagen. Het document ID kaart is analoog aan de primaire sleutelkolom in een traditionele relationele databaserij.
Document ID kaart waarden moeten UTF-8-reeksen van 250 of minder bytes zijn.
Aangezien Couchbase geen mechanisme biedt voor het automatisch genereren van de ID kaart bij het inbrengen moeten we die van onszelf voorzien.
Gemeenschappelijke strategieën voor het genereren van id's omvatten sleutelafleiding met behulp van een natuurlijke sleutel, zoals de "E-mail" attribuut getoond in ons voorbeelddocument, en het gebruik van UUID snaren.
Voor onze voorbeelden zullen we random genereren UUID snaren.
4.2. Een document invoegen
Voordat we een nieuw document in onze bucket kunnen invoegen, moeten we eerst een instantie van JSONObject met de inhoud van het document:
JsonObject content = JsonObject.empty () .put ("name", "John Doe") .put ("type", "Person") .put ("email", "[email protected]") .put ("homeTown "," Chicago ");Vervolgens maken we een JSONDocument object bestaande uit een ID kaart waarde en de JSONObject:
String id = UUID.randomUUID (). ToString (); JsonDocument document = JsonDocument.create (id, inhoud);Om een nieuw document aan de bucket toe te voegen, gebruiken we de invoegen methode:
JsonDocument ingevoegd = bucket.insert (document);De JsonDocument geretourneerd bevat alle eigenschappen van het originele document, plus een waarde die bekend staat als de "CAS" (vergelijk-en-ruil) waarde die Couchbase gebruikt voor het bijhouden van versies.
Als een document met de meegeleverde ID kaart bestaat al in de bucket, gooit Couchbase een DocumentAlreadyExistsException.
We kunnen ook de upsert methode, die ofwel het document zal invoegen (als de ID kaart wordt niet gevonden) of werk het document bij (als het ID kaart is gevonden):
JsonDocument upserted = bucket.upsert (document);4.3. Een document ophalen
Om een document op te halen met zijn ID kaart, wij gebruiken de krijgen methode:
JsonDocument opgehaald = bucket.get (id);Als er geen document bestaat met het opgegeven ID kaart, retourneert de methode nul.
4.4. Een document bijwerken of vervangen
We kunnen een bestaand document bijwerken met de upsert methode:
JsonObject-inhoud = document.content (); content.put ("homeTown", "Kansas City"); JsonDocument upserted = bucket.upsert (document);Zoals we al zeiden in paragraaf 4.2, upsert zal slagen of een document met het gegeven ID kaart werd gevonden of niet.
Als er genoeg tijd is verstreken tussen het moment waarop we het document oorspronkelijk hebben opgehaald en onze poging om het herziene document op te slaan, is er een mogelijkheid dat het originele document door een ander proces of een andere gebruiker uit de bucket is verwijderd.
Als we ons in onze applicatie tegen dit scenario moeten beschermen, kunnen we in plaats daarvan de vervangen methode, die mislukt met een DocumentDoesNotExistException als een document met het gegeven ID kaart is niet gevonden in Couchbase:
JsonDocument vervangen = bucket.replace (document);4.5. Een document verwijderen
Om een Couchbase-document te verwijderen, gebruiken we de verwijderen methode:
JsonDocument verwijderd = bucket.remove (document);U kunt ook verwijderen door ID kaart:
JsonDocument verwijderd = bucket.remove (id);De JsonDocument object geretourneerd heeft alleen de ID kaart en CAS eigenschappen set; alle andere eigenschappen (inclusief de JSON-inhoud) worden verwijderd uit het geretourneerde object.
Als er geen document bestaat met het opgegeven ID kaart, Couchbase gooit een DocumentDoesNotExistException.
5. Werken met replica's
Deze sectie bespreekt de virtuele bucket en replica-architectuur van Couchbase en introduceert een mechanisme voor het ophalen van een replica van een document in het geval dat het primaire knooppunt van een document niet beschikbaar is.
5.1. Virtuele emmers en replica's
Couchbase verdeelt de documenten van een bucket over een verzameling van 1024 virtuele buckets, of vbuckets, met behulp van een hash-algoritme op het document ID kaart het bepalen van vbucket waarin elk document moet worden opgeslagen.
Elke Couchbase-bucket kan ook worden geconfigureerd om een of meer te onderhouden replica's van elke vbucket. Telkens wanneer een document wordt ingevoegd of bijgewerkt en naar zijn vbucketStart Couchbase een proces om het nieuwe of bijgewerkte document naar zijn replica vbucket.
In een cluster met meerdere knooppunten distribueert Couchbase vbuckets en replica vbuckets tussen alle gegevensknooppunten in het cluster. EEN vbucket en zijn replica vbucket worden op aparte dataknooppunten bewaard om een bepaalde mate van hoge beschikbaarheid te bereiken.
5.2. Een document ophalen uit een replica
Bij het ophalen van een document met zijn ID kaart, als het primaire knooppunt van het document niet beschikbaar is of anderszins onbereikbaar is vanwege een netwerkfout, genereert Couchbase een uitzondering.
U kunt uw toepassing de uitzondering laten onderscheppen en proberen een of meer replica's van het document op te halen met behulp van de extensie getFromReplica methode.
De volgende code zou de eerste replica gebruiken die werd gevonden:
JsonDocument doc; probeer {doc = bucket.get (id); } catch (CouchbaseException e) {List list = bucket.getFromReplica (id, ReplicaMode.FIRST); if (! list.isEmpty ()) {doc = list.get (0); }}Houd er rekening mee dat het mogelijk is om tijdens het schrijven van uw toepassing schrijfbewerkingen te blokkeren totdat de persistentie en replicatie zijn voltooid. Om prestatieredenen is het echter gebruikelijk om de toepassing terug te laten keren van schrijfbewerkingen onmiddellijk na het schrijven naar het geheugen van het primaire knooppunt van een document, omdat schrijven naar een schijf inherent langzamer is dan schrijven vanuit het geheugen.
Bij gebruik van de laatste benadering, als het primaire knooppunt van een recent bijgewerkt document zou falen of offline zou gaan voordat de updates volledig zijn gerepliceerd, kan het zijn dat replica-leesbewerkingen de nieuwste versie van het document retourneren.
Het is ook vermeldenswaard dat Couchbase replica's (indien aanwezig) asynchroon ophaalt. Als uw bucket dus is geconfigureerd voor meerdere replica's, is er geen garantie met betrekking tot de volgorde waarin de SDK ze retourneert, en wilt u misschien alle gevonden replica's doorlopen om ervoor te zorgen dat uw toepassing de nieuwste beschikbare replicaversie heeft:
lang maxCasValue = -1; voor (JsonDocument-replica: bucket.getFromReplica (id, ReplicaMode.ALL)) {if (replica.cas ()> maxCasValue) {doc = replica; maxCasValue = replica.cas (); }}6. Conclusie
We hebben enkele basisgebruiksscenario's geïntroduceerd die u nodig heeft om aan de slag te gaan met de Couchbase SDK.
Codefragmenten die in deze zelfstudie worden gepresenteerd, zijn te vinden in het GitHub-project.
U kunt meer te weten komen over de SDK op de officiële Couchbase SDK-documentatie voor ontwikkelaars.
