Community

Otavio Santana

Software Engineer and Java Champion




This tutorial will guide you through creating a Java application using MongoDB and Helidon. Helidon is an open-source framework designed to develop lightweight microservices in the cloud. It features a powerful and fast web core supported by Java virtual threads, providing a solid foundation for modern applications. By following a few simple steps, you will learn how to set up a Java application that seamlessly integrates with MongoDB, enabling you to concentrate on building scalable, high-performance services effortlessly.

You can find all the code presented in this tutorial in the [GitHub repository](https://github.com/soujava/helidon-mongodb-introduction):

```bash
git clone git@github.com:soujava/helidon-mongodb-introduction.git  
```

## Prerequisites

For this tutorial, you’ll need:

* Java 21\.  
* Maven.  
* A MongoDB cluster.  
  * MongoDB Atlas (Option 1\)  
  * Docker (Option 2\)

You can use the following Docker command to start a standalone MongoDB instance:

```
docker run --rm -d --name mongodb-instance -p 27017:27017 mongo
```

You can also use [MongoDB Atlas](https://mongodb.prakticum-team.ru/atlas/database) and try the M0 free tier to deploy your cluster.

## Create a Helidon project.

* Visit the [Helidon Starter](https://helidon.io/starter/).  
* At Flavor, select **Helidon MP** and **Next**.  
* At application type, select **Quickstart**.  
* At Media Support, select **JSON-B**.  
* Define the groupId, artifactId, version, and package name as desired.  
* Configure your project by selecting the desired options, such as the group and artifact ID.  
* Generate the project, download the ZIP file, and extract it to your preferred location. Remember that the file structure may vary with different Helidon versions, but this should be fine for the tutorial. The core focus will be modifying the \`pom.xml\` file and source code, which remains relatively consistent across versions. Any minor structural differences should be good for your progress, and you can refer to version-specific documentation if needed for a seamless learning experience.  
* After generating the project, include the latest version of the [JNoSQL MongoDB driver](https://mvnrepository.com/artifact/org.eclipse.jnosql.databases/jnosql-mongodb):

```
<dependency>
<groupId>org.eclipse.jnosql.databases</groupId>
<artifactId>jnosql-mongodb</artifactId>
<version>1.1.2</version>
</dependency>

```

At this point, your `pom.xml` file should look like this:

```
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>io.helidon.applications</groupId>
        <artifactId>helidon-mp</artifactId>
        <version>4.1.1</version>
        <relativePath/>
    </parent>
    <groupId>expert.os.samples</groupId>
    <artifactId>intro-helidon-mongodb</artifactId>
    <version>0.0.1</version>


    <dependencies>
        <dependency>
            <groupId>org.eclipse.jnosql.databases</groupId>
            <artifactId>jnosql-mongodb</artifactId>
            <version>1.1.2</version>
        </dependency>
        <dependency>
            <groupId>io.helidon.microprofile.bundles</groupId>
            <artifactId>helidon-microprofile-core</artifactId>
        </dependency>
        <dependency>
            <groupId>io.helidon.microprofile.openapi</groupId>
            <artifactId>helidon-microprofile-openapi</artifactId>
        </dependency>
        <dependency>
            <groupId>io.helidon.microprofile.health</groupId>
            <artifactId>helidon-microprofile-health</artifactId>
        </dependency>
        <dependency>
            <groupId>jakarta.json.bind</groupId>
            <artifactId>jakarta.json.bind-api</artifactId>
        </dependency>
        <dependency>
            <groupId>org.glassfish.jersey.media</groupId>
            <artifactId>jersey-media-json-binding</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>io.helidon.logging</groupId>
            <artifactId>helidon-logging-jul</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>io.smallrye</groupId>
            <artifactId>jandex</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.eclipse.microprofile.metrics</groupId>
            <artifactId>microprofile-metrics-api</artifactId>
        </dependency>
        <dependency>
            <groupId>io.helidon.microprofile.metrics</groupId>
            <artifactId>helidon-microprofile-metrics</artifactId>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.helidon.microprofile.testing</groupId>
            <artifactId>helidon-microprofile-testing-junit5</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.hamcrest</groupId>
            <artifactId>hamcrest-all</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <executions>
                    <execution>
                        <id>copy-libs</id>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>io.smallrye</groupId>
                <artifactId>jandex-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <id>make-index</id>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>
```

We will be using the newest version of Helidon with Eclipse JNoSQL. This integration can be done quickly because both are based on the Java Enterprise specification, [Jakarta](https://jakarta.ee/). Helidon uses Eclipse Microprofile, which incorporates several Jakarta Specifications like CDI. Eclipse JNoSQL serves as the foundation, implementing both Jakarta EE specifications for NoSQL and data.

## Database configuration

Before starting the implementation, it's essential to configure your MongoDB database properly. In MongoDB, you must often set up credentials and specific configurations to connect to your database instance. Eclipse JNoSQL offers a flexible configuration mechanism that enables you to manage these settings effectively.

The Eclipse JNoSQL GitHub repository contains detailed configurations and setups for various databases, including MongoDB.

Configure the database name and properties in the src/main/resources/META-INF/microprofile-config.properties file to run your application locally. Open this file and add the following line to specify the database name:

```
# configure the MongoDB client for a replica set of two nodes
quarkus.mongodb.connection-string=mongodb://localhost

# mandatory if you don't specify the name of the database
jnosql.document.database=tools
```

This configuration will enable your application to:

* Use the “tools” database.  
* Connect to the MongoDB cluster available at the provided connection string.

Enable access control and enforce authentication in production. For more details, see the [security checklist](https://mongodb.prakticum-team.ru/docs/manual/administration/security-checklist/).

It's important to note that Eclipse JNoSQL uses Eclipse MicroProfile Configuration to simplify the development of 12-factor applications, particularly in managing configurations. This allows you to override properties using environment variables, seamlessly switching between different configurations for development, testing, and production without modifying your code. This flexibility is a valuable aspect of creating resilient and easily deployable applications.

Now that your database is configured, you can proceed with the tutorial and create your RESTful API with Helidon and Eclipse JNoSQL for MongoDB.

## Create a Tool entity

In this step, we will create a simple \`Tool\`entity which will have four attributes:

* **Name**: The name of the tool (e.g., Hammer, Screwdriver)  
* **Type**: The type or category the tool belongs to (e.g., Hand Tools, Power Tools)  
* **SKU**: A unique identifier for the tool (Stock Keeping Unit)  
* **Quantity**: The number of units of that tool available in the warehouse

Create a new class in the \`src/main/java\` directory named \`Tool\`.

```java
import jakarta.nosql.Column;
import jakarta.nosql.Entity;
import jakarta.nosql.Id;

@Entity(value = "tool")
public record Tool (@Id String sku, @Column String name, @Column String type, @Column int quantity) 
{ }
```

Create a tool repository

After creating the Tool entity, the next step is to define the communication interface to the database; in this sample, we will use the Jakarta Data specification's repository interfaces, which allow a single interface that will enable interactions with a database that supports both relational databases, using Jakarta Persistence, and NoSQL databases, using Jakarta NoSQL. 

This ToolRepository, once extended to the \`BasicRepository\`, allows several database operations, such as save, find, and method by the query. 

```java
import jakarta.data.repository.BasicRepository;
import jakarta.data.repository.Repository;

@Repository
public interface ToolRepository extends BasicRepository<Tool, String> {
}


```

 

## 

## 

## Create a REST API

Now, let’s create a RESTful API to manage developer records. Create a new class in \`src/main/java\` named \`ToolResource\`.

```java


import jakarta.data.Direction;
import jakarta.data.Order;
import jakarta.data.Sort;
import jakarta.data.page.PageRequest;
import jakarta.inject.Inject;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.DELETE;
import jakarta.ws.rs.DefaultValue;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.WebApplicationException;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

import java.util.List;
import java.util.logging.Logger;

@Path("/tools")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ToolResource {

    private static final Logger LOGGER = Logger.getLogger(ToolResource.class.getName());

    private final ToolRepository toolRepository;

    @Inject
    public ToolResource(ToolRepository toolRepository) {
        this.toolRepository = toolRepository;
    }


    @GET
    public List<Tool> findAllTools(@QueryParam("page") @DefaultValue("1") long page,
                                   @QueryParam("size") @DefaultValue("2") int size,
                                   @QueryParam("order") @DefaultValue("sku") String order,
                                   @QueryParam("direction") @DefaultValue("ASC") Direction direction) {

        LOGGER.info("Find all tools, page: " + page + ", size: " + size + ", order: " + order + ", direction: " + direction);
        var pageRequest = PageRequest.ofPage(page).size(size);
        return toolRepository.findAll(pageRequest, Order.by(Sort.of(order, direction, false))).content();
    }

    @POST
    public void save(Tool tool) {
        LOGGER.info("Save tool: " + tool);
        toolRepository.save(tool);
    }

    @GET
    @Path("/{id}")
    public Tool findById(@PathParam("id") String id) {
        LOGGER.info("Find tool by id: " + id);
        return toolRepository.findById(id).orElseThrow(() -> new WebApplicationException("Tool not found", Response.Status.NOT_FOUND));
    }

    @DELETE
    @Path("/{id}")
    public void deleteById(@PathParam("id") String id) {
        LOGGER.info("Delete tool by id: " + id);
        toolRepository.deleteById(id);
    }


}


```

## Test the REST API

Now that we have created our RESTful API for managing developer records, it is time to test it. We will show how to interact with the API using various HTTP requests and command-line tools.

Initiate the project:

```
mvn package
java -jar target/intro-helidon-mongodb.jar
```

### Exploring pagination with offset

We will use \`curl\` to learn more about pagination using the URLs provided. It is a command-line tool that is often used to send HTTP requests. The URLs you have been given are used to access a REST API endpoint fetching fruit pages using offset pagination. Each URL requests a different page, enabling us to observe how pagination functions via the API. Below is how you can interact with these endpoints using the \`curl\` tool:

**Inserting data**  
This command will generate 10 tools in the database:

```
curl -X POST http://localhost:8080/tools -H "Content-Type: application/json" -d '{"sku": "SKU006", "name": "Pliers", "type": "Hand Tools", "quantity": 75}'
curl -X POST http://localhost:8080/tools -H "Content-Type: application/json" -d '{"sku": "SKU007", "name": "Cordless Screwdriver", "type": "Power Tools", "quantity": 50}'
curl -X POST http://localhost:8080/tools -H "Content-Type: application/json" -d '{"sku": "SKU008", "name": "Chisel", "type": "Hand Tools", "quantity": 90}'
curl -X POST http://localhost:8080/tools -H "Content-Type: application/json" -d '{"sku": "SKU009", "name": "Power Drill", "type": "Power Tools", "quantity": 60}'
curl -X POST http://localhost:8080/tools -H "Content-Type: application/json" -d '{"sku": "SKU010", "name": "Tape Measure", "type": "Measuring Tools", "quantity": 120}'
curl -X POST http://localhost:8080/tools -H "Content-Type: application/json" -d '{"sku": "SKU011", "name": "Level", "type": "Measuring Tools", "quantity": 45}'
curl -X POST http://localhost:8080/tools -H "Content-Type: application/json" -d '{"sku": "SKU012", "name": "Wrench Set", "type": "Hand Tools", "quantity": 30}'
curl -X POST http://localhost:8080/tools -H "Content-Type: application/json" -d '{"sku": "SKU013", "name": "Circular Saw", "type": "Power Tools", "quantity": 20}'
curl -X POST http://localhost:8080/tools -H "Content-Type: application/json" -d '{"sku": "SKU014", "name": "Angle Grinder", "type": "Power Tools", "quantity": 35}'
curl -X POST http://localhost:8080/tools -H "Content-Type: application/json" -d '{"sku": "SKU015", "name": "Allen Wrench", "type": "Hand Tools", "quantity": 200}'
```

**Getting an element by ID**  
This command allows you to find a database using the ID:

```
curl --location 'http://localhost:8080/tools/SKU006'
```

**Remove an element by ID**  
This command removes a tool using the ID:

```
curl --location --request DELETE 'http://localhost:8080/tools/SKU005'
```

**Get tools with pagination**

This request allows you to search for tools using pagination, where you can define the page, size, direction, and property:

```
curl --location 'http://localhost:8080/tools/'
curl --location 'http://localhost:8080/tools/?page=2'
curl --location 'http://localhost:8080/tools/?page=3'
curl --location 'http://localhost:8080/tools/?size=10'
curl --location 'http://localhost:8080/tools/?size=10&order=name'
```

## Conclusion

In this tutorial, you learned how to set up a Java application using Helidon and MongoDB, and leveraging the simplicity and power of Jakarta NoSQL. We began by generating a basic project using the Helidon Starter, configuring it to integrate with MongoDB, and building a complete tool management system. You gained practical insight into developing lightweight, scalable microservices that can efficiently interact with NoSQL databases by creating RESTful APIs, handling database entities, and implementing pagination techniques.

Following the steps outlined in this tutorial, you can expand your application to include advanced features like authentication, monitoring, and cloud deployment using MongoDB Atlas. Helidon, combined with MongoDB and Jakarta NoSQL, provides a solid framework for building modern microservices that are high-performance and developer-friendly. You can continue exploring these technologies to exploit their robust capabilities for enterprise-level applications fully.

Ready to explore the benefits of MongoDB Atlas? Get started now by [trying MongoDB Atlas](https://mongodb.prakticum-team.ru/cloud/atlas/lp/try4).

[Access the source code](https://github.com/soujava/helidon-mongodb-introduction) used in this tutorial.

Any questions? Come chat with us in the [MongoDB Community Forum](https://mongodb.prakticum-team.ru/community/forums/).

**References**:

* [Source code](https://github.com/soujava/helidon-mongodb-introduction)

This tutorial introduces building a Java application with MongoDB and Helidon, a framework for lightweight, cloud-native microservices. You'll learn to set up Helidon with MongoDB, create a tool management API, and configure a Docker-based MongoDB instance or connect to MongoDB Atlas. The guide covers creating and using a MongoDB repository with Jakarta Data, building a REST API for CRUD operations, and implementing pagination. Sample code is available on GitHub to help you follow along seamlessly and build scalable, high-performance microservices.

Introduction to MongoDB and Helidon

## Introduction

In modern web development, managing large datasets efficiently through APIs is crucial for enhancing application
performance and user experience. This tutorial explores pagination techniques using Quarkus and MongoDB, a robust
combination for scalable data delivery. Through a live coding session, we'll delve into different pagination methods and
demonstrate how to implement these in a Quarkus-connected MongoDB environment. This guide empowers developers to
optimize REST APIs for effective data handling.

You can find all the code presented in this tutorial in
the [GitHub repository](https://github.com/mongodb-developer/quarkus-pagination-sample):

```bash
git clone git@github.com:mongodb-developer/quarkus-pagination-sample.git
```

## Prerequisites

For this tutorial, you'll need:

- Java 21.
- Maven.
- A MongoDB cluster.
  - MongoDB Atlas (Option 1)
  - Docker (Option 2)

You can use the following Docker command to start a standalone MongoDB instance:

```bash
docker run --rm -d --name mongodb-instance -p 27017:27017 mongo
```

Or you can use MongoDB Atlas and try the M0 free tier to deploy your cluster.

## Create a Quarkus project

- Visit the [Quarkus Code Generator](https://code.quarkus.io/).
- Configure your project by selecting the desired options, such as the group and artifact ID.
- Add the necessary dependencies to your project. For this tutorial, we will add:
  - JNoSQL Document MongoDB [quarkus-jnosql-document-mongodb].
  - RESTEasy Reactive [quarkus-resteasy-reactive].
  - RESTEasy Reactive Jackson [quarkus-resteasy-reactive-jackson].
  - OpenAPI [quarkus-smallrye-openapi].

> Note: If you cannot find some dependencies, you can add them manually in the `pom.xml`. See the file below.

- Generate the project, download the ZIP file, and extract it to your preferred location. Remember that the file
  structure
  may vary with different Quarkus versions, but this should be fine for the tutorial. The core focus will be modifying
  the `pom.xml` file and source code, which remains relatively consistent across versions. Any minor structural
  differences should be good for your progress, and you can refer to version-specific documentation if needed for a
  seamless learning experience.

At this point, your pom.xml file should look like this:

```xml
<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-smallrye-openapi</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.jnosql</groupId>
        <artifactId>quarkus-jnosql-document-mongodb</artifactId>
        <version>3.3.0</version>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-resteasy</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-resteasy-jackson</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-junit5</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

We will work with the latest version of Quarkus alongside Eclipse JNoSQL Lite, a streamlined integration that notably
does not rely on reflection. This approach enhances performance and simplifies the configuration process, making it an
optimal choice for developers looking to maximize efficiency in their applications.

## Database configuration

Before you dive into the implementation, it's essential to configure your MongoDB database properly. In MongoDB, you
must often set up credentials and specific configurations to connect to your database instance. Eclipse JNoSQL provides
a flexible configuration mechanism that allows you to manage these settings efficiently.

You can find detailed configurations and setups for various databases, including MongoDB, in the [Eclipse JNoSQL GitHub
repository](https://github.com/eclipse/jnosql-databases?tab=readme-ov-file#configuration-10).

To run your application locally, you can configure the database name and properties in your application's
`application.properties` file. Open this file and add the following line to set the database name:

```properties
quarkus.mongodb.connection-string = mongodb://localhost
jnosql.document.database = fruits
```

This configuration will enable your application to:
- Use the "fruits" database.
- Connect to the MongoDB cluster available at the provided connection string.

In production, make sure to enable access control and enforce authentication. See the [security checklist](https://mongodb.prakticum-team.ru/docs/manual/administration/security-checklist/) for more
details.

It's worth mentioning that Eclipse JNoSQL leverages Eclipse MicroProfile Configuration, which is designed to facilitate
the implementation of [twelve-factor applications](https://12factor.net/), especially in configuration management. It means you can override
properties through environment variables, allowing you to switch between different configurations for development,
testing, and production without modifying your code. This flexibility is a valuable aspect of building robust and easily
deployable applications.

Now that your database is configured, you can proceed with the tutorial and create your RESTful API with Quarkus and
Eclipse JNoSQL for MongoDB.

## Create a fruit entity

In this step, we will create a simple `Fruit` entity using Java records. Create a new class in the `src/main/java`
directory named `Fruit`.

```java
import jakarta.nosql.Column;
import jakarta.nosql.Convert;
import jakarta.nosql.Entity;
import jakarta.nosql.Id;
import org.eclipse.jnosql.databases.mongodb.mapping.ObjectIdConverter;

@Entity
public class Fruit {

    @Id
    @Convert(ObjectIdConverter.class)
    private String id;

    @Column
    private String name;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @Override
    public String toString() {
        return "Fruit{" +
                "id='" + id + '\'' +
                ", name='" + name + '\'' +
                '}';
    }

    public static Fruit of(String name) {
        Fruit fruit = new Fruit();
        fruit.setName(name);
        return fruit;
    }

}
```

## Create a fruit repository

We will simplify the integration between Java and MongoDB using the Jakarta Data repository by creating an interface
that extends NoSQLRepository. The framework automatically implements this interface, enabling us to define methods for
data retrieval that integrate seamlessly with MongoDB. We will focus on implementing two types of pagination: offset
pagination represented by `Page` and keyset (cursor) pagination represented by `CursoredPage`.

Here's how we define the FruitRepository interface to include methods for both pagination strategies:

```java
import jakarta.data.Sort;
import jakarta.data.page.CursoredPage;
import jakarta.data.page.Page;
import jakarta.data.page.PageRequest;
import jakarta.data.repository.BasicRepository;
import jakarta.data.repository.Find;
import jakarta.data.repository.OrderBy;
import jakarta.data.repository.Repository;

@Repository
public interface FruitRepository extends BasicRepository<Fruit, String> {

    @Find
    CursoredPage<Fruit> cursor(PageRequest pageRequest, Sort<Fruit> order);

    @Find
    @OrderBy("name")
    Page<Fruit> offSet(PageRequest pageRequest);

    long countBy();

}
```

## Create setup

We'll demonstrate how to populate and manage the MongoDB database with a collection of fruit entries at the start of the
application using Quarkus. We'll ensure our database is initialized with predefined data, and we'll also handle cleanup
on application shutdown. Here's how we can structure the SetupDatabase class:

```java
import jakarta.enterprise.context.ApplicationScoped;

import jakarta.enterprise.event.Observes;

import io.quarkus.runtime.ShutdownEvent;
import io.quarkus.runtime.StartupEvent;
import org.jboss.logging.Logger;

import java.util.List;

@ApplicationScoped
public class SetupDatabase {

    private static final Logger LOGGER = Logger.getLogger(SetupDatabase.class.getName());

    private final FruitRepository fruitRepository;

    public SetupDatabase(FruitRepository fruitRepository) {
        this.fruitRepository = fruitRepository;
    }


    void onStart(@Observes StartupEvent ev) {
        LOGGER.info("The application is starting...");
        long count = fruitRepository.countBy();
        if (count > 0) {
            LOGGER.info("Database already populated");
            return;
        }
        List<Fruit> fruits = List.of(
                Fruit.of("apple"),
                Fruit.of("banana"),
                Fruit.of("cherry"),
                Fruit.of("date"),
                Fruit.of("elderberry"),
                Fruit.of("fig"),
                Fruit.of("grape"),
                Fruit.of("honeydew"),
                Fruit.of("kiwi"),
                Fruit.of("lemon")
        );
        fruitRepository.saveAll(fruits);
    }

    void onStop(@Observes ShutdownEvent ev) {
        LOGGER.info("The application is stopping...");
        fruitRepository.deleteAll(fruitRepository.findAll().toList());
    }

}
```

## Create a REST API

Now, let's create a RESTful API to manage developer records. Create a new class in `src/main/java`
named `FruitResource`.

```java
import jakarta.data.Sort;
import jakarta.data.page.PageRequest;
import jakarta.ws.rs.DefaultValue;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.QueryParam;
import jakarta.ws.rs.core.MediaType;

@Path("/fruits")
public class FruitResource {

    private final FruitRepository fruitRepository;

    private static final Sort<Fruit> ASC = Sort.asc("name");
    private static final Sort<Fruit> DESC = Sort.asc("name");

    public FruitResource(FruitRepository fruitRepository) {
        this.fruitRepository = fruitRepository;
    }

    @Path("/offset")
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Iterable<Fruit> hello(@QueryParam("page") @DefaultValue("1") long page,
                                 @QueryParam("size") @DefaultValue("2") int size) {
        var pageRequest = PageRequest.ofPage(page).size(size);
        return fruitRepository.offSet(pageRequest).content();
    }

    @Path("/cursor")
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Iterable<Fruit> cursor(@QueryParam("after") @DefaultValue("") String after,
                                  @QueryParam("before") @DefaultValue("") String before,
                                  @QueryParam("size") @DefaultValue("2") int size) {
        if (!after.isBlank()) {
            var pageRequest = PageRequest.ofSize(size).afterCursor(PageRequest.Cursor.forKey(after));
            return fruitRepository.cursor(pageRequest, ASC).content();
        } else if (!before.isBlank()) {
            var pageRequest = PageRequest.ofSize(size).beforeCursor(PageRequest.Cursor.forKey(before));
            return fruitRepository.cursor(pageRequest, DESC).stream().toList();
        }
        var pageRequest = PageRequest.ofSize(size);
        return fruitRepository.cursor(pageRequest, ASC).content();
    }

}
```

## Test the REST API

Now that we've created our RESTful API for managing developer records, it's time to put it to the test. We'll
demonstrate how to interact with the API using various HTTP requests and command-line tools.

### Start the project

```bash
./mvnw compile quarkus:dev
```

### Exploring pagination with offset

We will use `curl` to learn more about pagination using the URLs provided. It is a command-line tool that is often used
to send HTTP requests. The URLs you have been given are used to access a REST API endpoint fetching fruit pages using
offset pagination. Each URL requests a different page, enabling us to observe how pagination functions via the API.
Below is how you can interact with these endpoints using the `curl` tool.

#### Fetching the first page

This command requests the first page of fruits from the server.

```bash
curl --location http://localhost:8080/fruits/offset?page=1
```

#### Fetching the second page

This command gets the next set of fruits, which is the second page.

```bash
curl --location http://localhost:8080/fruits/offset?page=2
```

#### Fetching the fifth page

By requesting the fifth page, you can see how the API responds when you request a page that might be beyond the range of
existing data.

```bash
curl --location http://localhost:8080/fruits/offset?page=5
```

### Exploring pagination with a cursor

To continue exploring cursor-based pagination with your API, using both `after` and `before` parameters provides a way
to navigate through your dataset forward and backward respectively. This method allows for flexible data retrieval,
which can be particularly useful for interfaces that allow users to move to the next or previous set of results. Here's
how you can structure your `curl` commands to use these parameters effectively:

#### Fetching the initial set of fruits

This command gets the first batch of fruits without specifying a cursor, starting from the beginning.

```bash
curl --location http://localhost:8080/fruits/cursor
```

#### Fetching fruits after "banana"

This command fetches the list of fruits that appear after "banana" in your dataset. This is useful for moving forward in
the list.

```bash
curl --location http://localhost:8080/fruits/cursor?after=banana
```

#### Fetching fruits before "date"

This command is used to go back to the set of fruits that precede "date" in the dataset. This is particularly useful for
implementing "Previous" page functionality.

```bash
curl --location http://localhost:8080/fruits/cursor?before=date
```

## Conclusion

This tutorial explored the fundamentals and implementation of pagination using Quarkus and MongoDB, demonstrating how to
manage large datasets in web applications effectively. By integrating the Jakarta Data repository with Quarkus, we
designed interfaces that streamline the interaction between Java and MongoDB, supporting offset and cursor-based
pagination techniques. We started by setting up a basic Quarkus application and configuring MongoDB connections. Then,
we demonstrated how to populate the database with initial data and ensure clean shutdown behavior.

Throughout this tutorial, we've engaged in live coding sessions, implementing and testing various pagination methods.
We've used the `curl` command to interact with the API, fetching data with no parameters, and using `after` and `before`
parameters to navigate through the dataset forward and backward. The use of cursor-based pagination, in particular,
has showcased its benefits in scenarios where datasets are frequently updated or when precise data retrieval control is
needed. This approach not only boosts performance by avoiding the common issues of offset pagination but also provides a
user-friendly way to navigate through data.

Ready to explore the benefits of MongoDB Atlas? Get started now by [trying MongoDB Atlas](https://mongodb.prakticum-team.ru/atlas/database).

Access the [source code](https://github.com/mongodb-developer/quarkus-pagination-sample) used in this tutorial.

Any questions? Come chat with us in the [MongoDB Community Forum](https://mongodb.prakticum-team.ru/community/forums/).


In this blog post, you'll learn how to create a RESTful API with Quarkus that supports MongoDB queries with pagination.

Introduction to Data Pagination With Quarkus and MongoDB: A Comprehensive Tutorial

## Introduction

In this tutorial, you will learn how to create a RESTful API using Quarkus, a framework for building Java applications,
and integrate it with Eclipse JNoSQL to work with MongoDB. We will create a simple API to manage developer records.

Combining Quarkus with Eclipse JNoSQL allows you to work with NoSQL databases using a unified API, making switching
between different NoSQL database systems easier.

## Prerequisites

For this tutorial, you’ll need:

- Java 17.
- Maven.
- A MongoDB cluster.
    - Docker (Option 1)
    - MongoDB Atlas (Option 2)

You can use the following Docker command to start a standalone MongoDB instance:

```shell
docker run --rm -d --name mongodb-instance -p 27017:27017 mongo
```

Or you can use [MongoDB Atlas](https://mongodb.prakticum-team.ru/atlas/database) and try the M0 free tier to deploy your cluster.

## Create a Quarkus project

- Visit the [Quarkus Code Generator](https://code.quarkus.io/).
- Configure your project by selecting the desired options, such as the group and artifact ID.
- Add the necessary dependencies to your project. For this tutorial, we will add:
    - JNoSQL Document MongoDB [quarkus-jnosql-document-mongodb]
    - RESTEasy Reactive [quarkus-resteasy-reactive]
    - RESTEasy Reactive Jackson [quarkus-resteasy-reactive-jackson]
    - OpenAPI [quarkus-smallrye-openapi]
- Generate the project, download the ZIP file, and extract it to your preferred location. Remember that the file
  structure may vary with different Quarkus versions, but this should be fine for the tutorial. The core focus will be
  modifying the `pom.xml` file and source code, which remains relatively consistent across versions. Any minor
  structural differences should be good for your progress, and you can refer to version-specific documentation if needed
  for a seamless learning experience.

At this point, your `pom.xml` file should look like this:

```xml

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-resteasy-reactive-jackson</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.jnosql</groupId>
        <artifactId>quarkus-jnosql-document-mongodb</artifactId>
        <version>1.0.5</version>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-smallrye-openapi</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-resteasy-reactive</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-junit5</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

By default, [quarkus-jnosql-document-mongodb](https://mvnrepository.com/artifact/io.quarkiverse.jnosql/quarkus-jnosql-document-mongodb)
is in version `1.0.5`, but the latest release is `3.2.2.1`. You should update your `pom.xml` to use the latest version:

```xml
<dependency>
    <groupId>io.quarkiverse.jnosql</groupId>
    <artifactId>quarkus-jnosql-document-mongodb</artifactId>
    <version>3.2.2.1</version>
</dependency>
```

## Database configuration

Before you dive into the implementation, it’s essential to configure your MongoDB database properly. In MongoDB, you
must often set up credentials and specific configurations to connect to your database instance. Eclipse JNoSQL provides
a flexible configuration mechanism that allows you to manage these settings efficiently.

You can find detailed configurations and setups for various databases, including MongoDB, in the [Eclipse JNoSQL GitHub
repository](https://github.com/eclipse/jnosql-databases?tab=readme-ov-file#configuration-10).

To run your application locally, you can configure the database name and properties in your application’s
`application.properties` file. Open this file and add the following line to set the database name:

```properties
quarkus.mongodb.connection-string=mongodb://localhost:27017
jnosql.document.database=school
```

This configuration will enable your application to:
- Use the “school” database.
- Connect to the MongoDB cluster available at the provided connection string.

In production, make sure to enable access control and enforce authentication. See the [security checklist](https://mongodb.prakticum-team.ru/docs/manual/administration/security-checklist/) for more
details.

It’s worth mentioning that Eclipse JNoSQL leverages Eclipse MicroProfile Configuration, which is designed to facilitate
the implementation of [twelve-factor applications](https://12factor.net/), especially in configuration management. It means you can override
properties through environment variables, allowing you to switch between different configurations for development,
testing, and production without modifying your code. This flexibility is a valuable aspect of building robust and easily
deployable applications.

Now that your database is configured, you can proceed with the tutorial and create your RESTful API with Quarkus and
Eclipse JNoSQL for MongoDB.

## Create a developer entity

In this step, we will create a simple `Developer` entity using Java records. Create a new record in the `src/main/java`
directory named `Developer`.

```java
import jakarta.nosql.Column;
import jakarta.nosql.Entity;
import jakarta.nosql.Id;

import java.time.LocalDate;
import java.util.Objects;
import java.util.UUID;

@Entity
public record Developer(
@Id String id,
@Column String name,
@Column LocalDate birthday
) {

    public static Developer newDeveloper(String name, LocalDate birthday) {
        Objects.requireNonNull(name, "name is required");
        Objects.requireNonNull(birthday, "birthday is required");
        return new Developer(
                UUID.randomUUID().toString(),
                name,
                birthday);
    }

    public Developer update(String name, LocalDate birthday) {
        Objects.requireNonNull(name, "name is required");
        Objects.requireNonNull(birthday, "birthday is required");
        return new Developer(
                this.id(),
                name,
                birthday);
    }
}
```

## Create a REST API

Now, let’s create a RESTful API to manage developer records. Create a new class in `src/main/java`
named `DevelopersResource`.

```java
import jakarta.inject.Inject;
import jakarta.nosql.document.DocumentTemplate;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

import java.time.LocalDate;
import java.util.List;

@Path("developers")
@Consumes({MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_JSON})
public class DevelopersResource {

    @Inject
    DocumentTemplate template;

    @GET
    public List<Developer> listAll(@QueryParam("name") String name) {
        if (name == null) {
            return template.select(Developer.class).result();
        }

        return template.select(Developer.class)
                .where("name")
                .like(name)
                .result();
    }

    public record NewDeveloperRequest(String name, LocalDate birthday) {
    }

    @POST
    public Developer add(NewDeveloperRequest request) {
        var newDeveloper = Developer.newDeveloper(request.name(), request.birthday());
        return template.insert(newDeveloper);
    }

    @Path("{id}")
    @GET
    public Developer get(@PathParam("id") String id) {
        return template.find(Developer.class, id)
                .orElseThrow(() -> new WebApplicationException(Response.Status.NOT_FOUND));
    }

    public record UpdateDeveloperRequest(String name, LocalDate birthday) {
    }

    @Path("{id}")
    @PUT
    public Developer update(@PathParam("id") String id, UpdateDeveloperRequest request) {
        var developer = template.find(Developer.class, id)
                .orElseThrow(() -> new WebApplicationException(Response.Status.NOT_FOUND));
        var updatedDeveloper = developer.update(request.name(), request.birthday());
        return template.update(updatedDeveloper);

    }

    @Path("{id}")
    @DELETE
    public void delete(@PathParam("id") String id) {
        template.delete(Developer.class, id);
    }
}
```

## Test the REST API

Now that we've created our RESTful API for managing developer records, it's time to put it to the test. We'll
demonstrate how to interact with the API using various HTTP requests and command-line tools.

### Start the project:

```shell
./mvnw compile quarkus:dev
```

### Create a new developer with POST

You can use the `POST` request to create a new developer record. We'll use `curl` for this demonstration:

```shell
curl -X POST "http://localhost:8080/developers" -H 'Content-Type: application/json' -d '{"name": "Max", "birthday": "
2022-05-01"}'
```

This `POST` request sends a JSON payload with the developer’s name and birthday to the API endpoint. You’ll receive a
response with the details of the newly created developer.

### Read the developers with GET

To retrieve a list of developers, you can use the `GET` request:

```shell
curl http://localhost:8080/developers
```

This `GET` request returns a list of all developers stored in the database.
To fetch details of a specific developer, provide their unique id in the URL:

```shell
curl http://localhost:8080/developers/a6905449-4523-48b6-bcd8-426128014582
```

This request will return the developer’s information associated with the provided id.

### Update a developer with PUT

You can update a developer’s information using the `PUT` request:

```shell
curl -X PUT "http://localhost:8080/developers/a6905449-4523-48b6-bcd8-426128014582" -H 'Content-Type: application/json'
-d '{"name": "Owen", "birthday": "2022-05-01"}'
```

In this example, we update the developer with the given id by providing a new name and birthday in the JSON payload.

### Delete a developer with DELETE

Finally, to delete a developer record, use the DELETE request:

```shell
curl -X DELETE "http://localhost:8080/developers/a6905449-4523-48b6-bcd8-426128014582"
```

This request removes the developer entry associated with the provided `id` from the database.

Following these simple steps, you can interact with your RESTful API to manage developer records effectively. These HTTP
requests allow you to create, read, update, and delete developer entries, providing full control and functionality for
your API.

Explore and adapt these commands to suit your specific use cases and requirements.

## Using OpenAPI to test and explore your API

OpenAPI is a powerful tool that allows you to test and explore your API visually. You can access the OpenAPI
documentation for your Quarkus project at the following URL:

```html
http://localhost:8080/q/swagger-ui/
```

OpenAPI provides a user-friendly interface that displays all the available endpoints and their descriptions and allows
you to make API requests directly from the browser. It’s an essential tool for API development because it:
1. Facilitates API testing: You can send requests and receive responses directly from the OpenAPI interface, making it easy
to verify the functionality of your API.
2. Generates documentation: This is crucial for developers who need to understand how to use your API effectively.
3. Allows for exploration: You can explore all the available endpoints, their input parameters, and expected responses,
which helps you understand the API’s capabilities.
4. Assists in debugging: It shows request and response details, making identifying and resolving issues easier.

In conclusion, using OpenAPI alongside your RESTful API simplifies the testing and exploration process, improves
documentation, and enhances the overall developer experience when working with your API. It’s an essential tool in
modern API development practices.

## Conclusion

In this tutorial, you’ve gained valuable insights into building a REST API using Quarkus and seamlessly integrating it
with Eclipse JNoSQL for MongoDB. You now can efficiently manage developer records through a unified API, streamlining
your NoSQL database operations. However, to take your MongoDB experience even further and leverage the full power of
MongoDB Atlas, consider migrating your application to MongoDB Atlas.

MongoDB Atlas offers a powerful document model, enabling you to store data as JSON-like objects that closely resemble
your application code. With MongoDB Atlas, you can harness your preferred tools and programming languages. Whether you
manage your clusters through the MongoDB CLI for Atlas or embrace infrastructure-as-code (IaC) tools like Terraform or
Cloudformation, MongoDB Atlas provides a seamless and scalable solution for your database needs.

Ready to explore the benefits of MongoDB Atlas? Get started now by [trying MongoDB Atlas](https://mongodb.prakticum-team.ru/cloud/atlas/lp/try4).

[Access the source code](https://github.com/mongodb-developer/demos-ee/tree/main/quarkus-jnosql-mongodb) used in this tutorial.

Any questions? Come chat with us in the [MongoDB Community Forum](https://mongodb.prakticum-team.ru/community/forums/).


Learn to create a REST API with Quarkus and Eclipse JNoSQL for MongoDB

Otavio Santana

Content by Otavio Santana

Introduction to MongoDB and Helidon

Introduction to Data Pagination With Quarkus and MongoDB: A Comprehensive Tutorial

Create a Java REST API with Quarkus and Eclipse JNoSQL for MongoDB