Introduzione a Couchbase SDK per Java

1. Introduzione

In questa introduzione a Couchbase SDK per Java, dimostriamo come interagire con un database di documenti Couchbase, coprendo concetti di base come la creazione di un ambiente Couchbase, la connessione a un cluster, l'apertura di bucket di dati, l'utilizzo delle operazioni di persistenza di base e l'utilizzo del documento repliche.

2. Dipendenze di Maven

Se stai usando Maven, aggiungi quanto segue al tuo file pom.xml:

 com.couchbase.client java-client 2.2.6 

3. Introduzione

L'SDK fornisce l' interfaccia CouchbaseEnvironment e una classe di implementazione DefaultCouchbaseEnvironment contenente le impostazioni predefinite per la gestione dell'accesso a cluster e bucket. Le impostazioni dell'ambiente di default possono essere sovrascritte se necessario, come vedremo nella sezione 3.2.

Importante: la documentazione ufficiale di Couchbase SDK avverte gli utenti di assicurarsi che un solo CouchbaseEnvironment sia attivo nella JVM, poiché l'uso di due o più potrebbe comportare un comportamento imprevedibile.

3.1. Connessione a un cluster con un ambiente predefinito

Per fare in modo che l'SDK crei automaticamente un CouchbaseEnvironment con impostazioni predefinite e lo associ al nostro cluster, possiamo connetterci al cluster semplicemente fornendo l'indirizzo IP o il nome host di uno o più nodi nel cluster.

In questo esempio, ci colleghiamo a un cluster a nodo singolo sulla nostra workstation locale:

Cluster cluster = CouchbaseCluster.create("localhost");

Per connettersi a un cluster multi-nodo, dovremmo specificare almeno due nodi nel caso in cui uno di loro non sia disponibile quando l'applicazione tenta di stabilire la connessione:

Cluster cluster = CouchbaseCluster.create("192.168.4.1", "192.168.4.2");

Nota: non è necessario specificare tutti i nodi del cluster durante la creazione della connessione iniziale. Il CouchbaseEnvironment interrogherà il cluster una volta che la connessione è stabilita al fine di scoprire i nodi rimanenti (se presenti).

3.2. Utilizzo di un ambiente personalizzato

Se l'applicazione richiede l'ottimizzazione di una qualsiasi delle impostazioni fornite da DefaultCouchbaseEnvironment , è possibile creare un ambiente personalizzato e quindi utilizzare quell'ambiente durante la connessione al cluster.

Ecco un esempio che si connette a un cluster a nodo singolo utilizzando un CouchbaseEnvironment personalizzato con un timeout di connessione di dieci secondi e un timeout di ricerca valore-chiave di tre secondi:

CouchbaseEnvironment env = DefaultCouchbaseEnvironment.builder() .connectTimeout(10000) .kvTimeout(3000) .build(); Cluster cluster = CouchbaseCluster.create(env, "localhost");

E per connettersi a un cluster multi-nodo con l'ambiente personalizzato:

Cluster cluster = CouchbaseCluster.create(env, "192.168.4.1", "192.168.4.2");

3.3. Apertura di un secchio

Dopo esserti connesso al cluster Couchbase, puoi aprire uno o più bucket.

Quando si configura per la prima volta un cluster Couchbase, il pacchetto di installazione crea automaticamente un bucket denominato "default" con una password vuota.

Ecco un modo per aprire il bucket "predefinito" quando ha una password vuota:

Bucket bucket = cluster.openBucket();

Puoi anche specificare il nome del bucket quando lo apri:

Bucket bucket = cluster.openBucket("default");

Per qualsiasi altro bucket con una password vuota, devi fornire il nome del bucket:

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

Per aprire un bucket con una password non vuota, devi fornire il nome e la password del bucket :

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

4. Operazioni di persistenza

In questa sezione, mostriamo come eseguire operazioni CRUD in Couchbase. Nei nostri esempi, lavoreremo con semplici documenti JSON che rappresentano una persona, come in questo documento di esempio:

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

L' attributo "tipo" non è richiesto, tuttavia è pratica comune includere un attributo che specifichi il tipo di documento nel caso in cui si decida di memorizzare più tipi nello stesso bucket.

4.1. ID documento

Ogni documento archiviato in Couchbase è associato a un ID univoco per il bucket in cui viene archiviato il documento. L' ID documento è analogo alla colonna della chiave primaria in una riga del database relazionale tradizionale.

I valori dell'ID documento devono essere stringhe UTF-8 di 250 byte o meno.

Poiché Couchbase non fornisce un meccanismo per la generazione automatica dell'ID all'inserimento, dobbiamo fornire il nostro.

Le strategie comuni per la generazione di ID includono la derivazione della chiave utilizzando una chiave naturale, come l' attributo "email" mostrato nel nostro documento di esempio, e l'uso di stringhe UUID .

Per i nostri esempi, genereremo stringhe UUID casuali .

4.2. Inserimento di un documento

Prima di poter inserire un nuovo documento nel nostro bucket, dobbiamo prima creare un'istanza di JSONObject contenente il contenuto del documento:

JsonObject content = JsonObject.empty() .put("name", "John Doe") .put("type", "Person") .put("email", "[email protected]") .put("homeTown", "Chicago");

Successivamente, creiamo un oggetto JSONDocument costituito da un valore id e JSONObject :

String id = UUID.randomUUID().toString(); JsonDocument document = JsonDocument.create(id, content);

Per aggiungere un nuovo documento al bucket, utilizziamo il metodo di inserimento :

JsonDocument inserted = bucket.insert(document);

Il JsonDocument restituito contiene tutte le proprietà del documento originale, più un valore noto come valore "CAS" (compare-and-swap) che Couchbase utilizza per il monitoraggio della versione.

Se un documento con l' ID fornito esiste già nel bucket, Couchbase genera un'eccezione DocumentAlreadyExistsException .

Possiamo anche utilizzare il metodo upsert , che inserirà il documento (se l' id non viene trovato) o aggiornerà il documento (se l' id viene trovato):

JsonDocument upserted = bucket.upsert(document);

4.3. Recupero di un documento

Per recuperare un documento dal suo ID , usiamo il metodo get :

JsonDocument retrieved = bucket.get(id);

If no document exists with the given id, the method returns null.

4.4. Updating or Replacing a Document

We can update an existing document using the upsert method:

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

As we mentioned in section 4.2, upsert will succeed whether a document with the given id was found or not.

If enough time has passed between when we originally retrieved the document and our attempt to upsert the revised document, there is a possibility that the original document will have been deleted from the bucket by another process or user.

If we need to guard against this scenario in our application, we can instead use the replace method, which fails with a DocumentDoesNotExistException if a document with the given id is not found in Couchbase:

JsonDocument replaced = bucket.replace(document);

4.5. Deleting a Document

To delete a Couchbase document, we use the remove method:

JsonDocument removed = bucket.remove(document);

You may also remove by id:

JsonDocument removed = bucket.remove(id);

The JsonDocument object returned has only the id and CAS properties set; all other properties (including the JSON content) are removed from the returned object.

If no document exists with the given id, Couchbase throws a DocumentDoesNotExistException.

5. Working With Replicas

This section discusses Couchbase's virtual bucket and replica architecture and introduces a mechanism for retrieving a replica of a document in the event that a document's primary node is unavailable.

5.1. Virtual Buckets and Replicas

Couchbase distributes a bucket's documents across a collection of 1024 virtual buckets, or vbuckets, using a hashing algorithm on the document id to determine the vbucket in which to store each document.

Each Couchbase bucket can also be configured to maintain one or more replicas of each vbucket. Whenever a document is inserted or updated and written to its vbucket, Couchbase initiates a process to replicate the new or updated document to its replica vbucket.

In a multi-node cluster, Couchbase distributes vbuckets and replica vbuckets among all the data nodes in the cluster. A vbucket and its replica vbucket are kept on separate data nodes in order to achieve a certain measure of high-availability.

5.2. Retrieving a Document From a Replica

When retrieving a document by its id, if the document's primary node is down or otherwise unreachable due to a network error, Couchbase throws an exception.

You can have your application catch the exception and attempt to retrieve one or more replicas of the document using the getFromReplica method.

The following code would use the first replica found:

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

Note that it is possible, when writing your application, to have write operations block until persistence and replication are complete. However the more common practice, for reasons of performance, is to have the application return from writes immediately after writing to memory of a document's primary node, because disk writes are inherently slower than memory writes.

When using the latter approach, if a recently updated document's primary node should fail or go offline before the updates have been fully replicated, replica reads may or may not return the latest version of the document.

It is also worth noting that Couchbase retrieves replicas (if any are found) asynchronously. Therefore if your bucket is configured for multiple replicas, there is no guarantee as to the order in which the SDK returns them, and you may want to loop through all the replicas found in order to ensure that your application has the latest replica version available:

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

6. Conclusion

We have introduced some basic usage scenarios that you will need in order to get started with the Couchbase SDK.

Code snippets presented in this tutorial can be found in the GitHub project.

Puoi saperne di più sull'SDK sul sito ufficiale della documentazione per sviluppatori di Couchbase SDK.