A Guide to Eclipse JNoSQL

1. Overview

Eclipse JNoSQL is a set of APIs and implementations that simplify the interaction of Java applications with NoSQL databases.

In this article, we’ll learn how to set up and configure JNoSQL to interact with a NoSQL database. We’ll work with both the Communication and Mapping layer.

2. Eclipse JNoSQL Communication Layer

Technically speaking, the communication layer consists of two modules: Diana API and a driver.

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

We can compare this with the JDBC API and JDBC driver in relational databases.

2.1. Eclipse JNoSQL Diana API

Simply put, there are four basic types of NoSQL databases: Key-Value, Column, Document, and Graph.

And the Eclipse JNoSQL Diana API defines three modules:

1. diana-key-value
2. diana-column
3. diana-document

The NoSQL graph type isn’t covered by the API, because it is already covered by Apache ThinkerPop.

The API is based on a core module, diana-core, and defines an abstraction to common concepts, such as Configuration, Factory, Manager, Entity, and Value.

To work with the API, we need to provide the dependency of the corresponding module to our NoSQL database type.

Thus, for a document-oriented database, we’ll need the diana-document dependency:

<dependency>
    <groupId>org.jnosql.diana</groupId>
    <artifactId>diana-document</artifactId>
    <version>0.0.6</version>
</dependency>

Similarly, we should use the diana-key-value module if the working NoSQL database is key-value oriented:

<dependency>
    <groupId>org.jnosql.diana</groupId>
    <artifactId>diana-key-value</artifactId>
    <version>0.0.6</version>
</dependency>

And finally, the diana-column module if it’s a column-oriented:

<dependency>
    <groupId>org.jnosql.diana</groupId>
    <artifactId>diana-column</artifactId>
    <version>0.0.6</version>
</dependency>

The most recent versions can be found on Maven Central.

2.2. Eclipse JNoSQL Diana Driver

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

There’s one implementation per NoSQL database. If the database is multi-model, the driver should implement all supported APIs.

For example, the couchbase-driver implements both diana-document and diana-key-value because Couchbase is both document and key-value oriented.

Unlike with relational databases, where the driver is typically provided by the database vendor, here the driver is provided by Eclipse JNoSQL. In most cases, this driver is a wrapper around the official vendor library.

To get started with the driver, we should include the API and the corresponding implementation for the chosen NoSQL database.

For MongoDB, for example, we need to include the following dependencies:

<dependency>
    <groupId>org.jnosql.diana</groupId>
    <artifactId>diana-document</artifactId>
    <version>0.0.6</version>
</dependency>
<dependency>
    <groupId>org.jnosql.diana</groupId>
    <artifactId>mongodb-driver</artifactId>
    <version>0.0.6</version>
</dependency>

The process behind working with the Driver is simple.

First, we need a Configuration bean. By reading a configuration file from the classpath or hardcoding values, the Configuration is able to create a Factory. We then use it then to create a Manager.

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

In the next subsections, we’ll explain this process for each NoSQL database type.

2.3. Working With a Document-Oriented Database

In this example, we’ll be using an embedded MongoDB as it’s simple to get started with and doesn’t require installation. It’s document-oriented and the following instructions are applicable to any other document-oriented NoSQL database.

At the very beginning, we should provide all necessary settings needed by the application to properly interact with the database. In its most elementary form, we should provide the host and the port of a running instance of the MongoDB.

We can provide these settings either in the mongodb-driver.properties located on the classpath:

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

Or as a hardcoded values:

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

Next, we create the Configuration bean for the document type:

DocumentConfiguration configuration = new MongoDBDocumentConfiguration();

From this Configuration bean, we are able to create a ManagerFactory:

DocumentCollectionManagerFactory managerFactory = configuration.get();

Implicitly, the get() method of the Configuration bean uses settings from the properties file. We can also obtain this factory from hardcoded values:

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

The ManagerFactory has a simple method get(), that takes the database name as a parameter, and creates the Manager:

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

And finally, we’re ready. The Manager provides all the necessary methods to interact with the underlying NoSQL database through the DocumentEntity.

So, we could, for example, insert a 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);

We could also search for documents:

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

And in a similar manner, we could update an existing document:

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

And finally, we can delete a stored document:

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

To run the sample, we just need to access the jnosql-diana module and run the DocumentApp application.

We should see the output in the console:

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

2.4. Working With a Column-Oriented Database

For the purpose of this section, we’ll use an embedded version of the Cassandra database, so no installation is needed.

The process for working with a Column-oriented database is very similar. First of all, we add the Cassandra driver and the column API to the pom:

<dependency>
    <groupId>org.jnosql.diana</groupId>
    <artifactId>diana-column</artifactId>
    <version>0.0.6</version>
</dependency>
<dependency>
    <groupId>org.jnosql.diana</groupId>
    <artifactId>cassandra-driver</artifactId>
    <version>0.0.6</version>
</dependency>

Next, we need the configuration settings specified in the configuration file, diana-cassandra.properties, on the classpath. Alternatively, we could also use hardcoded configuration values.

Then, with a similar approach, we’ll create a ColumnFamilyManager and start manipulating the ColumnEntity:

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

So to create a new entity, let’s invoke the insert() method:

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);

To run the sample and see the output in the console, run the ColumnFamilyApp application.

2.5. Working With a Key-Value Oriented Database

In this section, we’ll use the Hazelcast. Hazelcast is a key-value oriented NoSQL database. For more information on the Hazelcast database, you can check this link.

The process for working with the key-value oriented type is also similar. We start by adding these dependencies to the pom:

<dependency>
    <groupId>org.jnosql.diana</groupId>
    <artifactId>diana-key-value</artifactId>
    <version>0.0.6</version>
</dependency>
<dependency>
    <groupId>org.jnosql.diana</groupId>
    <artifactId>hazelcast-driver</artifactId>
    <version>0.0.6</version>
</dependency>

Then we need to provide the configuration settings. Next, we can obtain a BucketManager and then manipulate the KeyValueEntity:

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

Let’s say we want to save the following Book model:

public class Book implements Serializable {

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

    // standard constructor
    // standard getters and setters
}

So we create a Book instance and then we save it by invoking the put() method;

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

Then to retrieve the saved Book instance:

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

To run the sample and see the output in the console, run the KeyValueApp application.

3. Eclipse JNoSQL Mapping Layer

The mapping layer, Artemis API, is a set of APIs that help map java annotated Objects to NoSQL databases. It’s based on the Diana API and CDI (Context and Dependency Injection).

We can consider this API as JPA or ORM like for the NoSQL world. This layer also provides an API for each NoSQL type and one core API for common features.

In this section, we’re going to work with the MongoDB document-oriented database.

3.1. Required Dependencies

To enable Artemis in the application, we need to add the artemis-configuration dependency. Since MongoDB is document-oriented, the dependency artemis-document is also needed.

For other types of NoSQL databases, we would use artemis-column, artemis-key-value and artemis-graph.

The Diana driver for MongoDB is also needed:

<dependency>
    <groupId>org.jnosql.artemis</groupId>
    <artifactId>artemis-configuration</artifactId>
    <version>0.0.6</version>
</dependency>
<dependency>
    <groupId>org.jnosql.artemis</groupId>
    <artifactId>artemis-document</artifactId>
    <version>0.0.6</version>
</dependency>
<dependency>
    <groupId>org.jnosql.diana</groupId>
    <artifactId>mongodb-driver</artifactId>
    <version>0.0.6</version>
</dependency>

Artemis is based on CDI, so we need also to provide this Maven dependency:

<dependency>
    <groupId>javax</groupId>
    <artifactId>javaee-web-api</artifactId>
    <version>8.0</version>
    <scope>provided</scope>
</dependency>

3.2. The Document Configuration File

A configuration is a set of properties for a given database that let us provides setting outside the code. By default, we need to supply the jnosql.json file under the META-INF resource.

This is an example of the configuration file:

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

We will need to specify the configuration name above by setting the name attribute in our ConfigurationUnit. If the configuration is in a different file, it can be specified by using the fileName attribute.

Given this configuration, we create a factory:

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

And from this factory, we can create a DocumentCollectionManager:

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

The DocumentCollectionManager is a CDI enabled bean and it is used in both the Template and Repository.

3.3. Mapping

The mapping is an annotation-driven process by which the Entity model is converted to the Diana EntityValue.

Let’s start by defining a Todo model:

@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
}

As shown above, we have the basic mapping annotations: @Entity, @Id, and @Column.

Now to manipulate this model, we need either a Template class or a Repository interface.

3.4. Working With the Template

The template is the bridge between the entity model and the Diana API. For a document-oriented database, we start by injecting the DocumentTemplate bean:

@Inject
DocumentTemplate documentTemplate;

And then, we can manipulate the Todo Entity. For example, we can create a Todo:

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

Or we can retrieve a Todo by id:

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

To select all entities, we build a DocumentQuery and then we invoke the select() method:

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

And finally we can delete a Todo entity by id:

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

3.5. Working With the Repository

In addition to the Template class, we can also manage entities through the Repository interface which has methods for creating, updating, deleting and retrieving information.

To use the Repository interface, we just provide a subinterface of the Repository:

public interface TodoRepository extends Repository<Todo, String> {
    List<Todo> findByName(String name);
    List<Todo> findAll();
}

By the following method and parameter naming conventions, an implementation of this interface is provided at runtime as a CDI bean.

In this example, all Todo entities with a matching name are retrieved by the findByName() method.

We can now use it:

@Inject
TodoRepository todoRepository;

The Database qualifier lets us work with more than one NoSQL database in the same application. It comes with two attributes, the type and the provider.

If the database is multi-model, then we need to specify which model we are working with:

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

Additionally, if we have more than one database of the same model, we need to specify the provider:

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

To run the sample, just access the jnosql-artemis module and invoke this command:

mvn package liberty:run

This command builds, deploy and start the Open Liberty server thanks to the liberty-maven-plugin.

3.6. Testing the Application

As the application exposes a REST endpoint, we can use any REST client for our tests. Here we used the curl tool.

So to save a Todo class:

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

and to get all Todo:

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

Or to get just one Todo:

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

4. Conclusion

In this tutorial, we have explored how JNoSQL is able to abstract the interaction with a NoSQL database.

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.