Un guide pour JNoSQL d’Eclipse

Un guide pour Eclipse JNoSQL

1. Vue d'ensemble

EclipseJNoSQL est un ensemble d'API et d'implémentations quesimplify the interaction of Java applications with NoSQL databases.

Dans cet article, nous allons apprendre à configurer et configurer JNoSQL pour interagir avec une base de données NoSQL. Nous travaillerons à la fois avec les couches Communication et Mapping.

2. Couche de communication Eclipse JNoSQL

Techniquement parlant, la couche communication se compose de deux modules:Diana API and a driver.

While the API defines an abstraction to NoSQL database types, the driver provides implementations for most known databases.

Nous pouvons comparer cela avec l'API JDBC et le pilote JDBC dans les bases de données relationnelles.

2.1. API Eclipse JNoSQL Diana

En termes simples, il existe quatre types de base de bases de données NoSQL: Key-Value, Column, Document et Graph.

Et l'API Eclipse JNoSQL Diana définit trois modules:

diana-key-value
diana-colonne
diana-document

Le type de graphe NoSQL n'est pas couvert par l'API, car il est déjà couvert parApache ThinkerPop.

L'API est basée sur un module principal, diana-core, et définit une abstraction aux concepts courants, tels que la configuration, la fabrique, le gestionnaire, l'entité et la valeur.

Pour utiliser l'API, nous devons fournir la dépendance du module correspondant à notre type de base de données NoSQL.

Ainsi, pour une base de données orientée document, nous aurons besoin de la dépendancediana-document:


    org.jnosql.diana
    diana-document
    0.0.5

De même, nous devrions utiliser le modulediana-key-value si la base de données NoSQL active est orientée clé-valeur:


    org.jnosql.diana
    diana-key-value
    0.0.5

Et enfin, le modulediana-column s'il s'agit d'un module orienté colonne:


    org.jnosql.diana
    diana-column
    0.0.5

Les versions les plus récentes se trouvent surMaven Central.

2.2. Pilote Eclipse JNoSQL Diana

The driver is a set of implementations of the API for the most common NoSQL databases.

Il existe une implémentation par base de données NoSQL. If the database is multi-model, the driver should implement all supported APIs.

Par exemple,couchbase-driver implémente à la foisdiana-document etdiana-key-value carCouchbase est à la fois orienté document et valeur-clé.

Contrairement aux bases de données relationnelles, où le pilote est généralement fourni par le fournisseur de la base de données, icithe driver is provided by Eclipse JNoSQL. Dans la plupart des cas, ce pilote est une enveloppe de la bibliothèque officielle du fournisseur.

Pour commencer à utiliser le pilote, nous devons inclure l’API et l’implémentation correspondante pour la base de données NoSQL choisie.

Pour MongoDB, par exemple, nous devons inclure les dépendances suivantes:


    org.jnosql.diana
    diana-document
    0.0.5


    org.jnosql.diana
    mongodb-driver
    0.0.5

Le processus de travail avec le pilote est simple.

Tout d'abord, nous avons besoin d'un beanConfiguration. En lisant un fichier de configuration à partir du chemin de classe ou des valeurs en dur, leConfiguration est capable de créer unFactory. Nous l'utilisons ensuite pour créer unManager.

Finally, The Manager is responsible for pushing and retrieving the Entity to and from the NoSQL database.

Dans les sous-sections suivantes, nous expliquerons ce processus pour chaque type de base de données NoSQL.

2.3. Utilisation d'une base de données orientée document

Dans cet exemple,we’ll be using an embedded MongoDB est simple à utiliser et ne nécessite pas d’installation. Il est orienté document et les instructions suivantes s'appliquent à toute autre base de données NoSQL orientée document.

Au tout début, nous devrions fournir tous les paramètres nécessaires à l'application pour interagir correctement avec la base de données. Dans sa forme la plus élémentaire, nous devrions fournir leshost et lesport d'un instance en cours d'exécution de MongoDB.

Nous pouvons fournir ces paramètres soit dans lesmongodb-driver.properties situés sur le chemin de classe:

#Define Host and Port
mongodb-server-host-1=localhost:27017

Ou en tant que valeurs codées en dur:

Map map = new HashMap<>();
map.put("mongodb-server-host-1", "localhost:27017");

Ensuite, nous créons le beanConfiguration pour le type de document:

DocumentConfiguration configuration = new MongoDBDocumentConfiguration();

A partir de ce beanConfiguration, nous pouvons créer unManagerFactory:

DocumentCollectionManagerFactory managerFactory = configuration.get();

Implicitement, la méthodeget() du beanConfiguration utilise les paramètres du fichier de propriétés. Nous pouvons également obtenir cette usine à partir de valeurs codées en dur:

DocumentCollectionManagerFactory managerFactory
  = configuration.get(Settings.of(map));

LeManagerFactory a une méthode simpleget(), qui prend le nom de la base de données comme paramètre et crée lesManager:

DocumentCollectionManager manager = managerFactory.get("my-db");

Et enfin, nous sommes prêts. LeManager fournit toutes les méthodes nécessaires pour interagir avec la base de données NoSQL sous-jacente via lesDocumentEntity.

Ainsi, nous pourrions, par exemple, insérer un document:

DocumentEntity documentEntity = DocumentEntity.of("books");
documentEntity.add(Document.of("_id", "100"));
documentEntity.add(Document.of("name", "JNoSQL in Action"));
documentEntity.add(Document.of("pages", "620"));
DocumentEntity saved = manager.insert(documentEntity);

Nous pourrions aussi rechercher des documents:

DocumentQuery query = select().from("books").where("_id").eq(100).build();
List entities = manager.select(query);

Et de manière similaire, nous pourrions mettre à jour un document existant:

saved.add(Document.of("author", "example"));
DocumentEntity updated = manager.update(saved);

Et enfin, nous pouvons supprimer un document stocké:

DocumentDeleteQuery deleteQuery = delete().from("books").where("_id").eq("100").build();
manager.delete(deleteQuery);

Pour exécuter l'exemple, il suffit d'accéder au modulejnosql-diana et d'exécuter l'applicationDocumentApp.

Nous devrions voir la sortie dans la console:

DefaultDocumentEntity{documents={pages=620, name=JNoSQL in Action, _id=100}, name='books'}
DefaultDocumentEntity{documents={pages=620, author=example, name=JNoSQL in Action, _id=100}, name='books'}
[]

2.4. Utilisation d'une base de données orientée colonnes

Pour les besoins de cette section,we’ll use an embedded version of the Cassandra database, donc aucune installation n'est nécessaire.

Le processus d'utilisation d'une base de données orientée colonne est très similaire. Tout d’abord, nous ajoutons le pilote Cassandra et l’API de colonne au pom:


    org.jnosql.diana
    diana-column
    0.0.5


    org.jnosql.diana
    cassandra-driver
    0.0.5

Ensuite, nous avons besoin des paramètres de configuration spécifiés dans le fichier de configuration,diana-cassandra.properties, et le chemin de classe. Alternativement, nous pourrions également utiliser des valeurs de configuration codées en dur.

Ensuite, avec une approche similaire, nous allons créer unColumnFamilyManager et commencer à manipuler lesColumnEntity:

ColumnConfiguration configuration = new CassandraConfiguration();
ColumnFamilyManagerFactory managerFactory = configuration.get();
ColumnFamilyManager entityManager = managerFactory.get("my-keySpace");

Donc, pour créer une nouvelle entité, invoquons la méthodeinsert():

ColumnEntity columnEntity = ColumnEntity.of("books");
Column key = Columns.of("id", 10L);
Column name = Columns.of("name", "JNoSQL in Action");
columnEntity.add(key);
columnEntity.add(name);
ColumnEntity saved = entityManager.insert(columnEntity);

Pour exécuter l'exemple et voir la sortie dans la console, exécutez l'applicationColumnFamilyApp.

2.5. Utilisation d'une base de données orientée valeurs-clés

Dans cette section, nous utiliserons le Hazelcast. Hazelcast is a key-value oriented NoSQL database. Pour plus d'informations sur la base de données Hazelcast, vous pouvez vérifier ceslink.

Le processus d'utilisation du type orienté clé-valeur est également similaire. Nous commençons par ajouter ces dépendances au pom:


    org.jnosql.diana
    diana-key-value
    0.0.5


    org.jnosql.diana
    hazelcast-driver
    0.0.5

Ensuite, nous devons fournir les paramètres de configuration. Ensuite, nous pouvons obtenir unBucketManager puis manipuler lesKeyValueEntity:

KeyValueConfiguration configuration = new HazelcastKeyValueConfiguration();
BucketManagerFactory managerFactory = configuration.get();
BucketManager entityManager = managerFactory.getBucketManager("books");

Supposons que nous souhaitons enregistrer le modèleBook suivant:

public class Book implements Serializable {

    private String isbn;
    private String name;
    private String author;
    private int pages;

    // standard constructor
    // standard getters and setters
}

Nous créons donc une instanceBook puis nous la sauvegardons en invoquant la méthodeput();

Book book = new Book(
  "12345", "JNoSQL in Action",
  "example", 420);
KeyValueEntity keyValueEntity = KeyValueEntity.of(
  book.getIsbn(), book);
entityManager.put(keyValueEntity);

Ensuite, pour récupérer l'instanceBook enregistrée:

Optional optionalValue = manager.get("12345");
Value value = optionalValue.get(); // or any other adequate Optional handling
Book savedBook = value.get(Book.class);

Pour exécuter l'exemple et voir la sortie dans la console, exécutez l'applicationKeyValueApp.

3. Couche de mappage Eclipse JNoSQL

The mapping layer, Artemis API, is a set of APIs that help map java annotated Objects to NoSQL databases. Il est basé sur l'API Diana et CDI (Context and Dependency Injection).

We can consider this API as JPA or ORM like for the NoSQL world. Cette couche fournit également une API pour chaque type NoSQL et une API principale pour les fonctionnalités communes.

Dans cette section, nous allons travailler avec la base de données orientée document MongoDB.

3.1. Dépendances requises

Pour activer Artemis dans l'application, nous devons ajouter la dépendanceartemis-configuration. Puisque MongoDB est orienté document, la dépendanceartemis-document est également nécessaire.

Pour les autres types de bases de données NoSQL, nous utiliserionsartemis-column, artemis-key-value etartemis-graph.

Le pilote Diana pour MongoDB est également nécessaire:


    org.jnosql.artemis
    artemis-configuration
    0.0.5


    org.jnosql.artemis
    artemis-document
    0.0.5


    org.jnosql.diana
    mongodb-driver
    0.0.5

Artemis est basé sur CDI, nous devons donc également fournir cette dépendance Maven:


    javax
    javaee-web-api
    8.0
    provided

3.2. Le fichier de configuration du document

Une configuration est un ensemble de propriétés pour une base de données donnée qui nous permet de définir des paramètres en dehors du code. Par défaut, nous devons fournir le fichierjnosql.json sous la ressource META-INF.

Voici un exemple de fichier de configuration:

[
    {
        "description": "The mongodb document configuration",
        "name": "document",
        "provider": "org.jnosql.diana.mongodb.document.MongoDBDocumentConfiguration",
        "settings": {
            "mongodb-server-host-1":"localhost:27019"
        }
    }
]

Nous devrons spécifier le nom de la configuration ci-dessus en définissant l'attributname dans nosConfigurationUnit.. Si la configuration est dans un fichier différent, elle peut être spécifiée en utilisant l'attributfileName.

Étant donné cette configuration, nous créons une usine:

@Inject
@ConfigurationUnit(name = "document")
private DocumentCollectionManagerFactory managerFactory;

Et à partir de cette fabrique, nous pouvons créer unDocumentCollectionManager:

@Produces
public MongoDBDocumentCollectionManager getEntityManager() {
    return managerFactory.get("todos");
}

LeDocumentCollectionManager est un bean compatible CDI et il est utilisé à la fois dans lesTemplate etRepository.

3.3. Cartographie

Le mappage est un processus basé sur les annotations par lequel le modèleEntity est converti en DianaEntityValue.

Commençons par définir un modèleTodo:

@Entity
public class Todo implements Serializable {

    @Id("id")
    public long id;

    @Column
    public String name;

    @Column
    public String description;

    // standard constructor
    // standard getters and setters
}

Comme indiqué ci-dessus, nous avons les annotations de mappage de base:@Entity, @Id, et@Column.

Maintenant, pour manipuler ce modèle, nous avons besoin d'une classeTemplate ou d'une interfaceRepository.

3.4. Travailler avec le modèle

The template is thebridge between the entity model and the Diana API. Pour une base de données orientée document, nous commençons par injecter le beanDocumentTemplate:

@Inject
DocumentTemplate documentTemplate;

Et puis, nous pouvons manipuler l'entitéTodo. Par exemple, nous pouvons créer unTodo:

public Todo add(Todo todo) {
    return documentTemplate.insert(todo);
}

Ou nous pouvons récupérer unTodo parid:

public Todo get(String id) {
    Optional todo = documentTemplate
      .find(Todo.class, id);
    return todo.get(); // or any other proper Optional handling
}

Pour sélectionner toutes les entités, nous construisons unDocumentQuery puis nous invoquons la méthodeselect():

public List getAll() {
    DocumentQuery query = select().from("Todo").build();
    return documentTemplate.select(query);
}

Et enfin nous pouvons supprimer une entitéTodo parid:

public void delete(String id) {
    documentTemplate.delete(Todo.class, id);
}

3.5. Travailler avec le référentiel

En plus de la classeTemplate, nous pouvons également gérer les entités via les informationsthe Repository interface which has methods for creating, updating, deleting and retrieving.

Pour utiliser l'interfaceRepository, nous fournissons simplement une sous-interface desRepository:

public interface TodoRepository extends Repository {
    List findByName(String name);
    List findAll();
}

Conformément aux conventions de dénomination de méthode et de paramètre suivantes, une implémentation de cette interface est fournie au moment de l'exécution en tant que bean CDI.

Dans cet exemple, toutes les entitésTodo avec unname correspondant sont récupérées par la méthodefindByName().

Nous pouvons maintenant l'utiliser:

@Inject
TodoRepository todoRepository;

Le qualificatifDatabase nous permet de travailler avec plus d'une base de données NoSQL dans la même application. Il est livré avec deux attributs, le type et le fournisseur.

Si la base de données est multi-modèle, nous devons spécifier le modèle avec lequel nous travaillons:

@Inject
@Database(value = DatabaseType.DOCUMENT)
TodoRepository todoRepository;

De plus, si nous avons plusieurs bases de données du même modèle, nous devons spécifier le fournisseur:

@Inject
@Database(value = DatabaseType.DOCUMENT, provider="org.jnosql.diana.mongodb.document.MongoDBDocumentConfiguration")
TodoRepository todoRepository;

Pour exécuter l'exemple, accédez simplement au module jnosql-artemis et appelez cette commande:

mvn package liberty:run

Cette commande construit, déploie et démarre le serveurOpen Liberty grâce auxliberty-maven-plugin.

3.6. Test de l'application

Lorsque l'application expose un point de terminaison REST, nous pouvons utiliser n'importe quel client REST pour nos tests. Ici, nous avons utilisé l'outil curl.

Donc, pour sauver un cours Todo:

curl -d '{"id":"120", "name":"task120", "description":"Description 120"}' -H "Content-Type: application/json" -X POST http://localhost:9080/jnosql-artemis/todos

et pour obtenir tous Todo:

curl -H "Accept: application/json" -X GET http://localhost:9080/jnosql-artemis/todos

Ou pour obtenir un seul Todo:

curl -H "Accept: application/json" -X GET http://localhost:9080/jnosql-artemis/todos/120

4. Conclusion

Dans ce didacticiel, nous avons expliqué comment JNoSQL est capable d’abstraire l’interaction avec une base de données NoSQL.

First, we have used JNoSQL Diana API to interact with the database with low-level code. Then, we used the JNoSQL Artemis API to work with friendly Java annotated Models.

Comme d'habitude, on retrouve le code utilisé dans cet articleover on Github.

TOC