TOC

Introduction à Couchbase SDK pour Java

Introduction à Couchbase SDK pour Java

1. introduction

Dans cette introduction au kit de développement Couchbase SDK pour Java, nous expliquons comment interagir avec une base de données de documents Couchbase, en abordant des concepts de base tels que la création d'un environnement Couchbase, la connexion à un cluster, l'ouverture de compartiments de données, l'utilisation des opérations de persistance de base et l'utilisation du document. répliques.

2. Dépendances Maven

Si vous utilisez Maven, ajoutez ce qui suit dans votre fichier pom.xml: 


    com.couchbase.client
    java-client
    2.2.6

3. Commencer

Le SDK fournit l'interfaceCouchbaseEnvironment et une classe d'implémentationDefaultCouchbaseEnvironment contenant les paramètres par défaut pour la gestion de l'accès aux clusters et aux buckets. Les paramètres d'environnement par défaut peuvent être remplacés si nécessaire, comme nous le verrons à la section 3.2.

Important: La documentation officielle du SDK Couchbase avertit les utilisateurs de s'assurer qu'un seulCouchbaseEnvironment est actif dans la JVM, car l'utilisation de deux ou plus peut entraîner un comportement imprévisible.

3.1. Connexion à un cluster avec un environnement par défaut

Pour que le SDK crée automatiquement unCouchbaseEnvironment avec les paramètres par défaut et l'associe à notre cluster, nous pouvons nous connecter au cluster simplement en fournissant l'adresse IP ou le nom d'hôte d'un ou plusieurs nœuds du cluster.

Dans cet exemple, nous nous connectons à un cluster à un seul nœud sur notre poste de travail local: 

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

Pour vous connecter à un cluster à plusieurs noeuds, spécifiez au moins deux noeuds au cas où l'un d'entre eux serait indisponible lorsque l'application tenterait d'établir la connexion: 

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

Note: Il n'est pas nécessaire de spécifier chaque nœud du cluster lors de la création de la connexion initiale. LesCouchbaseEnvironment interrogeront le cluster une fois la connexion établie afin de découvrir les nœuds restants (le cas échéant).

3.2. Utilisation d'un environnement personnalisé

Si votre application nécessite un réglage précis de l'un des paramètres fournis parDefaultCouchbaseEnvironment, vous pouvez créer un environnement personnalisé, puis utiliser cet environnement lors de la connexion à votre cluster.

Voici un exemple de connexion à un cluster à nœud unique à l'aide d'unCouchbaseEnvironment personnalisé avec un délai de connexion de dix secondes et un délai de recherche de valeur-clé de trois secondes: 

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

Et pour vous connecter à un cluster multi-nœuds avec l'environnement personnalisé: 

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

3.3. Ouverture d'un seau

Une fois que vous êtes connecté au cluster Couchbase, vous pouvez ouvrir un ou plusieurs compartiments.

Lorsque vous configurez pour la première fois un cluster Couchbase, le package d'installation crée automatiquement un compartiment nommé“default” avec un mot de passe vide.

Voici une façon d'ouvrir le bucket“default” lorsqu'il a un mot de passe vide: 

Bucket bucket = cluster.openBucket();

Vous pouvez également spécifier le nom du compartiment lors de son ouverture: 

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

Pour tout autre compartiment avec un mot de passe vide, vousmust indiquez le nom du compartiment: 

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

Pour ouvrir un compartiment qui a un mot de passe non vide, vous devez fournir le mot de passe du nom de compartimentand: 

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

4. Opérations de persistance

Dans cette section, nous montrons comment effectuer des opérations CRUD dans Couchbase. Dans nos exemples, nous allons travailler avec de simples documents JSON représentant une personne, comme dans cet exemple de document: 

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

L'attribut“type” n'est pas obligatoire, mais il est courant d'inclure un attribut spécifiant le type de document au cas où l'on déciderait de stocker plusieurs types dans le même compartiment.

4.1. ID de document

Chaque document stocké dans Couchbase est associé à unid qui est unique au bucket dans lequel le document est stocké. Le documentid est analogue à la colonne de clé primaire dans une ligne de base de données relationnelle traditionnelle.

Les valeurs du documentid doivent être des chaînes UTF-8 de 250 octets ou moins.

Puisque Couchbase ne fournit pas de mécanisme pour générer automatiquement lesid lors de l'insertion, nous devons fournir le nôtre.

Les stratégies courantes pour générer desids incluent la dérivation de clé à l'aide d'une clé naturelle, telle que l'attribut“email” montré dans notre exemple de document, et l'utilisation des chaînesUUID.

Pour nos exemples, nous allons générer des chaînesUUID aléatoires.

4.2. Insérer un document

Avant de pouvoir insérer un nouveau document dans notre bucket, nous devons d'abord créer une instance deJSONObject contenant le contenu du document: 

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

Ensuite, nous créons un objetJSONDocument composé d'une valeurid et desJSONObject: 

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

Pour ajouter un nouveau document au bucket, nous utilisons la méthodeinsert: 

JsonDocument inserted = bucket.insert(document);

LeJsonDocument retourné contient toutes les propriétés du document original, plus une valeur connue sous le nom de valeur“CAS” (comparer et échanger) que Couchbase utilise pour le suivi de version.

Si un document avec lesid fournis existe déjà dans le bucket, Couchbase lance unDocumentAlreadyExistsException.

On peut aussi utiliser la méthodeupsert, qui va soit insérer le document (si leid n'est pas trouvé) soit mettre à jour le document (si leid est trouvé): 

JsonDocument upserted = bucket.upsert(document);

4.3. Récupérer un document

Pour récupérer un document par sesid, nous utilisons la méthodeget: 

JsonDocument retrieved = bucket.get(id);

Si aucun document n'existe avec lesid donnés, la méthode renvoienull.

4.4. Mise à jour ou remplacement d'un document

Nous pouvons mettre à jour un document existant en utilisant la méthodeupsert: 

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

Comme nous l'avons mentionné dans la section 4.2,upsert réussira, qu'un document avec lesid donnés ait été trouvé ou non.

S'il s'est écoulé suffisamment de temps entre la récupération initiale du document et notre tentative de modification du document révisé, il est possible que le document d'origine ait été supprimé du compartiment par un autre processus ou utilisateur.

Si nous devons nous prémunir contre ce scénario dans notre application, nous pouvons à la place utiliser la méthodereplace, qui échoue avec unDocumentDoesNotExistException si un document avec leid donné n'est pas trouvé dans Couchbase: 

JsonDocument replaced = bucket.replace(document);

4.5. Supprimer un document

Pour supprimer un document Couchbase, nous utilisons la méthoderemove: 

JsonDocument removed = bucket.remove(document);

Vous pouvez également supprimer parid: 

JsonDocument removed = bucket.remove(id);

L'objetJsonDocument renvoyé a uniquement les propriétésid etCAS définies; toutes les autres propriétés (y compris le contenu JSON) sont supprimées de l'objet renvoyé.

Si aucun document n'existe avec lesid donnés, Couchbase lance unDocumentDoesNotExistException.

5. Travailler avec des répliques

Cette section traite du bucket virtuel et de l’architecture de réplique de Couchbase et présente un mécanisme de récupération d’une réplique d’un document en cas d’indisponibilité du nœud principal d’un document.

5.1. Buckets virtuels et répliques

Couchbase distribue les documents d'un bucket sur une collection de 1024 buckets virtuels, ouvbuckets, en utilisant un algorithme de hachage sur le documentid pour déterminer lesvbucket dans lesquels stocker chaque document.

Chaque bucket Couchbase peut également être configuré pour conserver un ou plusieursreplicas de chaquevbucket. A chaque fois qu'un document est inséré ou mis à jour et écrit dans sesvbucket, Couchbase lance un processus pour répliquer le document nouveau ou mis à jour dans sesreplica vbucket.

Dans un cluster multi-nœuds, Couchbase distribuevbuckets etreplica vbuckets parmi tous les nœuds de données du cluster. Unvbucket et sesreplica vbucket sont conservés sur des nœuds de données séparés afin d'atteindre une certaine mesure de haute disponibilité.

5.2. Récupération d'un document à partir d'une réplique

Lors de la récupération d'un document par sesid, si le nœud principal du document est en panne ou inaccessible en raison d'une erreur réseau, Couchbase lève une exception.

Vous pouvez demander à votre application d'intercepter l'exception et d'essayer de récupérer une ou plusieurs répliques du document à l'aide de la méthodegetFromReplica.

Le code suivant utiliserait le premier réplica trouvé: 

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

Notez qu'il est possible, lors de l'écriture de votre application, de bloquer des opérations d'écriture jusqu'à ce que la persistance et la réplication soient terminées. Cependant, la pratique la plus courante, pour des raisons de performances, consiste à faire revenir l’application des écritures immédiatement après l’écriture dans la mémoire du nœud principal d’un document, car les écritures sur disque sont par nature plus lentes que les écritures mémoire.

Lors de l’utilisation de cette dernière approche, si le nœud principal d’un document récemment mis à jour échoue ou se met hors ligne avant que les mises à jour n’aient été entièrement répliquées, les lectures de répliques peuvent renvoyer ou non la dernière version du document.

Il est également intéressant de noter que Couchbase récupère les répliques (le cas échéant) de manière asynchrone. Par conséquent, si votre compartiment est configuré pour plusieurs réplicas, il n'y a aucune garantie quant à l'ordre dans lequel le SDK les renvoie, et vous souhaiterez peut-être parcourir toutes les répliques trouvées afin de vous assurer que votre application dispose de la dernière version de réplica disponible: 

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

6. Conclusion

Nous avons présenté quelques scénarios d'utilisation de base dont vous aurez besoin pour commencer à utiliser le kit de développement logiciel (SDK) Couchbase.

Les extraits de code présentés dans ce didacticiel se trouvent dans lesGitHub project.

Vous pouvez en savoir plus sur le SDK sur le site officielCouchbase SDK developer documentation site.

Related