mn create-app example.micronaut.micronautguide \
--features=data-mongodb \
--build=maven \
--lang=java \
--test=junit
Access a MongoDB database with Micronaut Data MongoDB
Learn how to access a MongoDB database with Micronaut Data and the MongoDB Sync driver.
Authors: Tim Yates
Micronaut Version: 4.6.3
1. Getting Started
In this guide, we will create a Micronaut application written in Java.
You will use MongoDB for persistence.
2. What you will need
To complete this guide, you will need the following:
-
Some time on your hands
-
A decent text editor or IDE (e.g. IntelliJ IDEA)
-
JDK 21 or greater installed with
JAVA_HOME
configured appropriately -
Docker installed to run MongoDB and to run tests using Testcontainers.
3. Solution
We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.
-
Download and unzip the source
4. Writing the Application
Create an application using the Micronaut Command Line Interface or with Micronaut Launch.
If you don’t specify the --build argument, Gradle with the Kotlin DSL is used as the build tool. If you don’t specify the --lang argument, Java is used as the language.If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.
|
The previous command creates a Micronaut application with the default package example.micronaut
in a directory named micronautguide
.
If you use Micronaut Launch, select Micronaut Application as application type and add data-mongodb
features.
If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features, and apply those changes to your application. |
4.1. Dependencies
In this guide, we use the MongoDB Sync driver.
The data-mongodb
features adds the following dependencies:
<!-- Add the following to your annotationProcessorPaths element -->
<path>
<groupId>io.micronaut.data</groupId>
<artifactId>micronaut-data-document-processor</artifactId>
</path>
<dependency>
<groupId>io.micronaut.data</groupId>
<artifactId>micronaut-data-mongodb</artifactId>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.mongodb</groupId>
<artifactId>mongodb-driver-sync</artifactId>
<scope>runtime</scope>
</dependency>
4.2. POJO
Create a Fruit
POJO:
package example.micronaut;
import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.annotation.Nullable;
import io.micronaut.data.annotation.GeneratedValue;
import io.micronaut.data.annotation.Id;
import io.micronaut.data.annotation.MappedEntity;
import jakarta.validation.constraints.NotBlank;
@MappedEntity (1)
public class Fruit {
@Id (2)
@GeneratedValue
private String id;
@NonNull
@NotBlank (3)
private final String name;
@Nullable
private String description;
public Fruit(@NonNull String name, @Nullable String description) {
this.name = name;
this.description = description;
}
public String getId() {
return id;
}
public void setId(String id) {
this.id = id;
}
@NonNull
public String getName() {
return name;
}
@Nullable
public String getDescription() {
return description;
}
public void setDescription(@Nullable String description) {
this.description = description;
}
}
1 | Annotate the class with @MappedEntity to map the class to the table defined in the schema. |
2 | Specifies the ID of an entity |
3 | Use jakarta.validation.constraints Constraints to ensure the data matches your expectations. |
4.3. Repository
Create a repository interface to encapsulate the CRUD actions for Fruit
.
package example.micronaut;
import io.micronaut.core.annotation.NonNull;
import io.micronaut.data.mongodb.annotation.MongoRepository;
import io.micronaut.data.repository.CrudRepository;
import java.util.List;
@MongoRepository (1)
public interface FruitRepository extends CrudRepository<Fruit, String> {
@NonNull
Iterable<Fruit> findByNameInList(@NonNull List<String> names); (2)
}
1 | Annotate with @MongoRepository . |
2 | Add a finder for finding fruit by a list of names. |
4.4. Service
Create a service FruitService
as an API to interact with the Fruit
repository.
This will allow you to keep business logic out of the controller, and to test the controller later without interacting with a real database.
package example.micronaut;
import io.micronaut.core.annotation.NonNull;
import java.util.List;
import java.util.Optional;
interface FruitService {
Iterable<Fruit> list();
Fruit save(Fruit fruit);
Optional<Fruit> find(@NonNull String id);
Iterable<Fruit> findByNameInList(List<String> name);
}
And then create a default implementation of this service.
package example.micronaut;
import io.micronaut.core.annotation.NonNull;
import jakarta.inject.Singleton;
import java.util.List;
import java.util.Optional;
@Singleton (1)
class DefaultFruitService implements FruitService {
private final FruitRepository fruitRepository;
public DefaultFruitService(FruitRepository fruitRepository) {
this.fruitRepository = fruitRepository;
}
public Iterable<Fruit> list() {
return fruitRepository.findAll();
}
public Fruit save(Fruit fruit) {
if (fruit.getId() == null) {
return fruitRepository.save(fruit);
} else {
return fruitRepository.update(fruit);
}
}
public Optional<Fruit> find(@NonNull String id) {
return fruitRepository.findById(id);
}
public Iterable<Fruit> findByNameInList(List<String> name) {
return fruitRepository.findByNameInList(name);
}
}
1 | Use jakarta.inject.Singleton to designate a class as a singleton. |
4.5. Controller
Create FruitController
:
package example.micronaut;
import io.micronaut.core.annotation.NonNull;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.PathVariable;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.annotation.Put;
import io.micronaut.http.annotation.QueryValue;
import io.micronaut.http.annotation.Status;
import io.micronaut.scheduling.TaskExecutors;
import io.micronaut.scheduling.annotation.ExecuteOn;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;
import java.util.List;
import java.util.Optional;
@Controller("/fruits") (1)
@ExecuteOn(TaskExecutors.BLOCKING) (2)
class FruitController {
private final FruitService fruitService;
FruitController(FruitService fruitService) { (3)
this.fruitService = fruitService;
}
@Get (4)
Iterable<Fruit> list() {
return fruitService.list();
}
@Post (5)
@Status(HttpStatus.CREATED) (6)
Fruit save(@NonNull @NotNull @Valid Fruit fruit) { (7)
return fruitService.save(fruit);
}
@Put
Fruit update(@NonNull @NotNull @Valid Fruit fruit) {
return fruitService.save(fruit);
}
@Get("/{id}") (8)
Optional<Fruit> find(@PathVariable String id) {
return fruitService.find(id);
}
@Get("/q") (9)
Iterable<Fruit> query(@QueryValue @NotNull List<String> names) { (10)
return fruitService.findByNameInList(names);
}
}
1 | The class is defined as a controller with the @Controller annotation mapped to the path /fruits . |
2 | It is critical that any blocking I/O operations (such as fetching the data from the database) are offloaded to a separate thread pool that does not block the Event loop. |
3 | Use constructor injection to inject a bean of type FruitService . |
4 | The @Get annotation maps the list method to an HTTP GET request on /fruits . |
5 | The @Post annotation maps the save method to an HTTP POST request on /fruits . |
6 | You can specify the HTTP status code via the @Status annotation. |
7 | Add @Valid to any method parameter which requires validation. |
8 | The @Get annotation maps the find method to an HTTP GET request on /fruits/{id} . |
9 | The @Get annotation maps the findByNameInList method to an HTTP GET request on /fruits/q . |
10 | Bind a list of Strings to the query parameter names |
4.6. Test Client
Add a Micronaut declarative HTTP Client to src/test
to ease the testing of the application’s API.
package example.micronaut;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.PathVariable;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.annotation.Put;
import io.micronaut.http.annotation.QueryValue;
import io.micronaut.http.client.annotation.Client;
import jakarta.validation.constraints.NotNull;
import java.util.List;
import java.util.Optional;
@Client("/fruits")
interface FruitClient {
@Get
Iterable<Fruit> list();
@Get("/{id}")
Optional<Fruit> find(@PathVariable String id);
@Get("/q")
Iterable<Fruit> query(@QueryValue @NotNull List<String> names);
@Post
HttpResponse<Fruit> save(Fruit fruit);
@Put
Fruit update(Fruit fruit);
}
Then create a test that verifies the validation of the Fruit
POJO when we create a new entity via POST
:
package example.micronaut;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.http.client.exceptions.HttpClientResponseException;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
@MicronautTest
class FruitValidationControllerTest {
@Inject
@Client("/")
HttpClient httpClient;
@Test
void fruitIsValidated() {
HttpClientResponseException exception = assertThrows(
HttpClientResponseException.class,
() -> httpClient.toBlocking().exchange(HttpRequest.POST("/fruits", new Fruit("", "")))
);
assertEquals(HttpStatus.BAD_REQUEST, exception.getStatus());
}
}
Create a test that checks our controller works against a real MongoDB database:
package example.micronaut;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.HttpStatus;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
@MicronautTest
class FruitControllerTest {
@Inject
FruitClient fruitClient;
@Test
void emptyDatabaseContainsNoFruit() {
assertEquals(0, StreamSupport.stream(fruitClient.list().spliterator(), false).count());
}
@Test
void testInteractionWithTheController() {
HttpResponse<Fruit> response = fruitClient.save(new Fruit("banana", null));
assertEquals(HttpStatus.CREATED, response.getStatus());
Fruit banana = response.getBody().get();
Iterable<Fruit> fruits = fruitClient.list();
List<Fruit> fruitList = StreamSupport.stream(fruits.spliterator(), false).collect(Collectors.toList());
assertEquals(1, fruitList.size());
assertEquals(banana.getName(), fruitList.get(0).getName());
assertNull(fruitList.get(0).getDescription());
response = fruitClient.save(new Fruit("apple", "Keeps the doctor away"));
assertEquals(HttpStatus.CREATED, response.getStatus());
fruits = fruitClient.list();
assertTrue(StreamSupport.stream(fruits.spliterator(), false)
.anyMatch(f -> "Keeps the doctor away".equals(f.getDescription())));
banana.setDescription("Yellow and curved");
fruitClient.update(banana);
fruits = fruitClient.list();
assertEquals(
Stream.of("Keeps the doctor away", "Yellow and curved").collect(Collectors.toSet()),
StreamSupport.stream(fruits.spliterator(), false)
.map(Fruit::getDescription)
.collect(Collectors.toSet())
);
}
@Test
void testSearchWorksAsExpected() {
fruitClient.save(new Fruit("apple", "Keeps the doctor away"));
fruitClient.save(new Fruit("pineapple", "Delicious"));
fruitClient.save(new Fruit("lemon", "Lemonentary my dear Dr Watson"));
Iterable<Fruit> fruit = fruitClient.query(Arrays.asList("apple", "pineapple"));
assertTrue(StreamSupport.stream(fruit.spliterator(), false)
.allMatch(f -> f.getName().equals("apple") || f.getName().equals("pineapple")));
}
}
And finally, create a test which uses a replacement FruitService
to test the controller without touching the database:
package example.micronaut;
import io.micronaut.context.annotation.Property;
import io.micronaut.context.annotation.Replaces;
import io.micronaut.context.annotation.Requires;
import io.micronaut.core.type.Argument;
import io.micronaut.http.HttpHeaders;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.MediaType;
import io.micronaut.http.MutableHttpRequest;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.inject.Inject;
import jakarta.inject.Singleton;
import org.junit.jupiter.api.Test;
import jakarta.validation.constraints.NotNull;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.Optional;
import java.util.stream.Collectors;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
@MicronautTest
@Property(name = "spec.name", value = "controller-isolation")
public class ControllerIsolationTest {
@Inject
@Client("/")
HttpClient httpClient;
@Test
void checkSerialization() {
MutableHttpRequest<Object> get = HttpRequest.GET("/fruits");
HttpResponse<List<Fruit>> response = httpClient.toBlocking().exchange(get, Argument.listOf(Fruit.class));
assertEquals(HttpStatus.OK, response.getStatus());
assertEquals(MediaType.APPLICATION_JSON, response.getHeaders().get(HttpHeaders.CONTENT_TYPE));
assertTrue(response.getBody().isPresent());
String all = response.getBody().get().stream().map(f -> f.getName() + ":" + f.getDescription()).collect(Collectors.joining(","));
assertEquals("apple:red,banana:yellow", all);
}
@Singleton
@Replaces(DefaultFruitService.class)
@Requires(property = "spec.name", value = "controller-isolation")
static class MockService implements FruitService {
@Override
public Iterable<Fruit> list() {
return Arrays.asList(
new Fruit("apple", "red"),
new Fruit("banana", "yellow")
);
}
@Override
public Fruit save(Fruit fruit) {
return fruit;
}
@Override
public Optional<Fruit> find(@NotNull String id) {
return Optional.empty();
}
@Override
public Iterable<Fruit> findByNameInList(List<String> name) {
return Collections.emptyList();
}
}
}
5. Test Resources
When the application is started locally — either under test or by running the application — resolution of the property mongodb.uri
is detected and the Test Resources service will start a local MongoDB docker container, and inject the properties required to use this as the datasource.
When running under production, you should replace this property with the location of your production MongoDB instance via an environment variable.
MONGODB_URI=mongodb://username:password@production-server:27017/databaseName
For more information, see the MongoDB section of the Test Resources documentation.
6. Testing the Application
To run the tests:
./mvnw test
7. Running the Application
To run the application, use the ./mvnw mn:run
command, which starts the application on port 8080.
curl -d '{"name":"Pear"}' \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/fruits
curl -i localhost:8080/fruits
HTTP/1.1 200 OK
date: Wed, 15 Sep 2021 12:40:15 GMT
Content-Type: application/json
content-length: 110
connection: keep-alive
[{"name":"Pear"}]
8. Next steps
Explore more features with Micronaut Guides.
Read more about the integration between the Micronaut Data and MongoDB.
9. Help with the Micronaut Framework
The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.
10. License
All guides are released with an Apache license 2.0 license for the code and a Creative Commons Attribution 4.0 license for the writing and media (images…). |