Persisting documents with MongoRepository

Spring Data MongoDB provides a variety of ways to work with a MongoDB database: low-level MongoReader and MongoWriter APIs, and higher-level MongoTemplate and MongoOperations APIs that make use of Query, Criteria and Update DSLs. It also provides a repository-style programming model through the MongoRepository interface which adds convenient abstractions to work with MongoDB.

In this post, we'll explore how to persist documents with MongoRepository, create custom converters for specific data types and cascade the documents.

Lombok is used to generate boilerplate code (e.g., getters, setters, builders, etc.) by using annotations. You can learn more about it here.

You'd need a mongoDB instance to persist the data. You can install MongoDB Community Server from here or get a free trial instance at MongoDB Atlas. You can also launch MongoDB as a Docker container. Create a docker-compose.yml file somewhere and add the following details in it.

 1version: '3'
 2
 3services:
 4
 5  mongo:
 6    image: mongo:latest
 7    container_name: mongodb_latest
 8    ports:
 9      - 27017:27017
10    environment:
11      MONGO_INITDB_ROOT_USERNAME: gwen
12      MONGO_INITDB_ROOT_PASSWORD: stacy

Open the terminal at the location of docker-compose.yml and execute the following command to launch the container.

docker-compose up -d

Define a domain

Story Consider a fictional social network where a user can create an account. A sign in by a user from a distinct location creates a session associated with that location. Since a user can sign in from different locations, multiple sessions may exist for an account. A user may decide to delete their account; if this happens, the corresponding sessions should also be deleted.

Let's start by defining a domain for the above story. The relationship between the Account, User and Session collections can be represented by the following diagram.

A Many-to-One relationship in MongoDB can be modeled with either embedded documents or document references. You can add the latter behavior through a @DBRef annotation.

Define an Account class as follows -

 1// src/main/java/dev/mflash/guides/mongo/domain/Account.java
 2
 3@Data @Builder
 4public class Account {
 5
 6  private final @Id @Default String key = UUID.randomUUID().toString();
 7  private @DBRef User user;
 8  private @DBRef @Singular Set<Session> sessions;
 9  private ZonedDateTime created;
10}

Similarly, define the User

 1// src/main/java/dev/mflash/guides/mongo/domain/User.java
 2
 3@Data @Builder
 4public class User {
 5
 6  private final @Id @Default String key = UUID.randomUUID().toString();
 7  private String name;
 8  private String email;
 9  private Locale locale;
10  private LocalDate dateOfBirth;
11}

and Session classes.

 1// src/main/java/dev/mflash/guides/mongo/domain/Session.java
 2
 3@Data @Builder
 4public class Session {
 5
 6  private final @Id @Default String key = UUID.randomUUID().toString();
 7  private String city;
 8  private Locale locale;
 9  private LocalDateTime accessed;
10}

Note that we're initializing the key with a random UUID. We'll discuss why this is needed in the cascading section.

Create a Repository

Define a repository for the Account by extending the MongoRepository interface.

1// src/main/java/dev/mflash/guides/mongo/repository/AccountRepository.java
2
3public interface AccountRepository extends MongoRepository<Account, String> {
4
5  Account findDistinctFirstByUser(User user);
6
7  List<Account> findBySessions(Session session);
8}

MongoRepository extends CrudRepository interface and thereby, provides several CRUD methods (e.g., findAll(), save(), etc.) out-of-the-box. For specific queries, you can declare query methods (using the naming conventions described in the docs). Spring will generate their implementations at runtime.

Testing the AccountRepository

Let's write some tests to check the functionality of the AccountRepository. We'll use assertion methods provided by AssertJ, a popular assertion library that comes bundled with Spring.

 1// src/test/java/dev/mflash/guides/mongo/repository/AccountRepositoryTest.java
 2
 3@ExtendWith(SpringExtension.class)
 4@SpringBootTest class AccountRepositoryTest {
 5
 6  private static final List<User> SAMPLE_USERS = List.of(
 7      User.builder().name("Tina Lawrence").email("tina@example.com").locale(Locale.CANADA).dateOfBirth(
 8          LocalDate.of(1989, Month.JANUARY, 11)).build(),
 9      User.builder().name("Adrian Chase").email("adrian@example.com").locale(Locale.UK).dateOfBirth(
10          LocalDate.of(1994, Month.APRIL, 23)).build(),
11      User.builder().name("Mohd Ali").email("mohdali@example.com").locale(Locale.JAPAN).dateOfBirth(
12          LocalDate.of(1999, Month.OCTOBER, 9)).build()
13  );
14
15  private static final List<Session> SAMPLE_SESSIONS = List.of(
16      Session.builder().city("Toronto").locale(Locale.CANADA).build(),
17      Session.builder().city("Los Angeles").locale(Locale.US).build(),
18      Session.builder().city("London").locale(Locale.UK).build(),
19      Session.builder().city("Paris").locale(Locale.FRANCE).build(),
20      Session.builder().city("Tokyo").locale(Locale.JAPAN).build()
21  );
22
23  private static final List<Account> SAMPLE_ACCOUNTS = List.of(
24      Account.builder().user(SAMPLE_USERS.get(0)).session(SAMPLE_SESSIONS.get(0)).session(SAMPLE_SESSIONS.get(1))
25          .created(ZonedDateTime.now()).build(),
26      Account.builder().user(SAMPLE_USERS.get(1)).session(SAMPLE_SESSIONS.get(1)).session(SAMPLE_SESSIONS.get(2))
27          .created(ZonedDateTime.now()).build(),
28      Account.builder().user(SAMPLE_USERS.get(2)).session(SAMPLE_SESSIONS.get(4)).session(SAMPLE_SESSIONS.get(3))
29          .created(ZonedDateTime.now()).build()
30  );
31
32  private @Autowired AccountRepository repository;
33
34  @BeforeEach
35  void setUp() {
36    repository.deleteAll();
37    repository.saveAll(SAMPLE_ACCOUNTS);
38  }
39
40  @Test
41  @DisplayName("Should find some accounts")
42  void shouldFindSomeAccounts() {
43    assertThat(repository.count()).isEqualTo(SAMPLE_ACCOUNTS.size());
44  }
45
46  @Test
47  @DisplayName("Should assign a key on save")
48  void shouldAssignAKeyOnSave() {
49    assertThat(repository.findAll()).extracting("key").isNotNull();
50  }
51
52  @Test
53  @DisplayName("Should get a distinct user by first name")
54  void shouldGetADistinctUserByFirstName() {
55    assertThat(repository.findDistinctFirstByUser(SAMPLE_USERS.get(0)).getUser())
56        .isEqualToIgnoringGivenFields(SAMPLE_USERS.get(0), "key");
57  }
58
59  @Test
60  @DisplayName("Should find some users with a given session")
61  void shouldFindSomeUsersWithAGivenSession() {
62    assertThat(repository.findBySessions(SAMPLE_SESSIONS.get(1))).isNotEmpty();
63  }
64}

In the above test, we begin by creating some test data (SAMPLE_USERS, SAMPLE_SESSIONS and SAMPLE_ACCOUNTS). Using the test data we test several functionalities of the repository.

When you'll run these tests, the following exception may be thrown:

org.bson.codecs.configuration.CodecConfigurationException: Can't find a codec for class java.time.ZonedDateTime

This happens because Account has a field created of type ZonedDateTime which can't be converted to a valid MongoDB representation by the available Spring converters. You'll have to tell Spring how to do this conversion by defining a custom converter.

Converters for ZonedDateTime

Spring provides a Converter interface that you can implement for this purpose. We need two converters here: one to convert ZonedDateTime to Date and the other to convert Date to ZonedDateTime.

 1// src/main/java/dev/mflash/guides/mongo/configuration/ZonedDateTimeConverters.java
 2
 3public class ZonedDateTimeConverters {
 4
 5  public static List<Converter<?, ?>> getConvertersToRegister() {
 6    return List.of(ZonedDateTimeToDateConverter.INSTANCE, DateToZonedDateTimeConverter.INSTANCE);
 7  }
 8
 9  private enum ZonedDateTimeToDateConverter implements Converter<ZonedDateTime, Date> {
10    INSTANCE;
11
12    public @Override Date convert(ZonedDateTime source) {
13      return Date.from(source.toInstant());
14    }
15  }
16
17  private enum DateToZonedDateTimeConverter implements Converter<Date, ZonedDateTime> {
18    INSTANCE;
19
20    public @Override ZonedDateTime convert(Date source) {
21      return source.toInstant().atZone(ZoneOffset.UTC);
22    }
23  }
24}

In the above ZonedDateTimeConverters implementation, we first define the ZonedDateTimeToDateConverter and DateToZonedDateTimeConverter converters by extending the Converter interface. Finally, we return a list of these converters through getConvertersToRegister method.

Also note that we've defined UTC as the ZoneOffset here. MongoDB stores times in UTC by default. You will have to adjust the offset if you need to store times in a custom timezone.

Inject these converters through a MongoCustomConversions bean as follows:

 1// src/main/java/dev/mflash/guides/mongo/configuration/MongoConfiguration.java
 2
 3@EnableMongoRepositories(MongoConfiguration.REPOSITORY_PACKAGE)
 4public @Configuration class MongoConfiguration {
 5
 6  static final String REPOSITORY_PACKAGE = "dev.mflash.guides.mongo.repository";
 7
 8  public @Bean MongoCustomConversions customConversions() {
 9    return new MongoCustomConversions(ZonedDateTimeConverters.getConvertersToRegister());
10  }
11}

You'll be able to run the tests successfully now.

Cascade the document operations

Spring Data MongoDB provides the support for lifecycle events through the MongoMappingEvent class. You can use this to write an event listener that can perform cascading operations for you.

Define a @Cascade annotation

Let's start by defining an annotation to indicate that a field should be cascaded.

1// src/main/java/dev/mflash/guides/mongo/event/Cascade.java
2
3@Retention(RetentionPolicy.RUNTIME)
4@Target(ElementType.FIELD)
5public @interface Cascade {
6
7  CascadeType value() default CascadeType.ALL;
8}

The CascadeType is an enum that denotes different types of cascading supported by our implementation.

1// src/main/java/dev/mflash/guides/mongo/event/CascadeType.java
2
3public enum CascadeType {
4  ALL, SAVE, DELETE
5}

With this, we can pass a CascadeType value to the @Cascade annotation and control the type of cascading we may want. By default, both save and delete operations will be cascaded.

Annotate the desired fields with this annotation.

 1// src/main/java/dev/mflash/guides/mongo/domain/Account.java
 2
 3@Data @Builder
 4public class Account {
 5
 6  // Other properties
 7
 8  private @DBRef @Cascade User user;
 9  private @DBRef @Cascade @Singular Set<Session> sessions;
10
11  // Other properties
12}

Detect the fields to be cascaded

The references of cascaded objects should be associated with a document by checking if such a document exists. You can do this by checking the @Id of the document through a FieldCallback.

 1// src/main/java/dev/mflash/guides/mongo/event/IdentifierCallback.java
 2
 3public class IdentifierCallback implements FieldCallback {
 4
 5  private boolean idFound;
 6
 7  public @Override void doWith(final Field field) throws IllegalArgumentException {
 8    ReflectionUtils.makeAccessible(field);
 9
10    if (field.isAnnotationPresent(Id.class)) {
11      idFound = true;
12    }
13  }
14
15  public boolean isIdFound() {
16    return idFound;
17  }
18}

Since a valid non-null @Id must be present for this to properly work, we need to initialize the key as early as possible. That's why we are initializing the key field of every document with a random UUID.

To detect the fields to be cascaded, we need to check which of them have been annotated with the @Cascade annotation. For a save cascade, define an implementation of the FieldCallback which performs this check and applies a save operation using a MongoOperations bean.

 1// src/main/java/dev/mflash/guides/mongo/event/CascadeSaveCallback.java
 2
 3@RequiredArgsConstructor
 4public class CascadeSaveCallback implements FieldCallback {
 5
 6  private final Object source;
 7  private final MongoOperations mongoOperations;
 8
 9  public @Override void doWith(final Field field) throws IllegalArgumentException, IllegalAccessException {
10    ReflectionUtils.makeAccessible(field);
11
12    if (field.isAnnotationPresent(DBRef.class) && field.isAnnotationPresent(Cascade.class)) {
13      final Object fieldValue = field.get(source);
14
15      if (Objects.nonNull(fieldValue)) {
16        final var callback = new IdentifierCallback();
17        final CascadeType cascadeType = field.getAnnotation(Cascade.class).value();
18
19        if (cascadeType.equals(CascadeType.SAVE) || cascadeType.equals(CascadeType.ALL)) {
20          if (fieldValue instanceof Collection<?>) {
21            ((Collection<?>) fieldValue).forEach(mongoOperations::save);
22          } else {
23            ReflectionUtils.doWithFields(fieldValue.getClass(), callback);
24            mongoOperations.save(fieldValue);
25          }
26        }
27      }
28    }
29  }
30}

Similarly, implement a CascadeDeleteCallback that checks the presence of the @Id and @Cascade annotations and applies the remove operation.

 1// src/main/java/dev/mflash/guides/mongo/event/CascadeDeleteCallback.java
 2
 3@RequiredArgsConstructor
 4public class CascadeDeleteCallback implements FieldCallback {
 5
 6  private final Object source;
 7  private final MongoOperations mongoOperations;
 8
 9  public @Override void doWith(final Field field) throws IllegalArgumentException, IllegalAccessException {
10    ReflectionUtils.makeAccessible(field);
11
12    if (field.isAnnotationPresent(DBRef.class) && field.isAnnotationPresent(Cascade.class)) {
13      final Object fieldValue = field.get(source);
14
15      if (Objects.nonNull(fieldValue)) {
16        final var callback = new IdentifierCallback();
17        final CascadeType cascadeType = field.getAnnotation(Cascade.class).value();
18
19        if (cascadeType.equals(CascadeType.DELETE) || cascadeType.equals(CascadeType.ALL)) {
20          if (fieldValue instanceof Collection<?>) {
21            ((Collection<?>) fieldValue).forEach(mongoOperations::remove);
22          } else {
23            ReflectionUtils.doWithFields(fieldValue.getClass(), callback);
24            mongoOperations.remove(fieldValue);
25          }
26        }
27      }
28    }
29  }
30}

These callbacks won't be invoked automatically; you'd need a listener to invoke them.

Invoking the cascade automatically

The AbstractMongoEventListener class provides various callback methods that get invoked during the persistence operations. As mentioned in the docs,

• the onBeforeSave callback method is called before inserting or saving a document in the database; this method captures the BeforeSaveEvent containing the document being saved.
• the onBeforeDelete callback method is called before a document is deleted; this method captures the BeforeDeleteEvent containing the document about to be deleted.
• the onAfterDelete callback method is called after a document or a set of documents have been deleted; this method captures the AfterDeleteEvent containing the document(s) that has/have been deleted. The references of the documents in the AfterDeleteEvent merely contain the values of id and not other fields since they've already been deleted.

Also note that the lifecycle events are emitted only for the parent types. These events won't be emitted for any children until and unless they're annotated with the @DBRef annotation.

Let's use these callback methods to execute the cascade callbacks implemented earlier. Create a AccountCascadeMongoEventListener class that extends AbstractMongoEventListener for the Account class.

 1// src/main/java/dev/mflash/guides/mongo/event/AccountCascadeMongoEventListener.java
 2
 3public class AccountCascadeMongoEventListener extends AbstractMongoEventListener<Account> {
 4
 5  private @Autowired MongoOperations mongoOperations;
 6  private Account deletedAccount;
 7
 8  public @Override void onBeforeSave(BeforeSaveEvent<Account> event) {
 9    final Object source = event.getSource();
10    ReflectionUtils.doWithFields(source.getClass(), new CascadeSaveCallback(source, mongoOperations));
11  }
12
13  public @Override void onBeforeDelete(BeforeDeleteEvent<Account> event) {
14    final Object id = Objects.requireNonNull(event.getDocument()).get("_id");
15    deletedAccount = mongoOperations.findById(id, Account.class);
16  }
17
18  public @Override void onAfterDelete(AfterDeleteEvent<Account> event) {
19    ReflectionUtils.doWithFields(Account.class, new CascadeDeleteCallback(deletedAccount, mongoOperations));
20  }
21}

and inject it as a bean using MongoConfiguration.

 1// src/main/java/dev/mflash/guides/mongo/configuration/MongoConfiguration.java
 2
 3@EnableMongoRepositories(MongoConfiguration.REPOSITORY_PACKAGE)
 4public @Configuration class MongoConfiguration {
 5
 6  static final String REPOSITORY_PACKAGE = "dev.mflash.guides.mongo.repository";
 7
 8  public @Bean AccountCascadeMongoEventListener cascadeMongoEventListener() {
 9    return new AccountCascadeMongoEventListener();
10  }
11
12  public @Bean MongoCustomConversions customConversions() {
13    return new MongoCustomConversions(ZonedDateTimeConverters.getConvertersToRegister());
14  }
15}

Testing the cascading

To verify if the cascading works, let's write some tests.

 1// src/test/java/dev/mflash/guides/mongo/repository/AccountCascadeTest.java
 2
 3@ExtendWith(SpringExtension.class)
 4@SpringBootTest class AccountCascadeTest {
 5
 6  private static final User SAMPLE_USER = User.builder().name("Jasmine Beck").email("jasmine@example.com").locale(
 7      Locale.FRANCE).dateOfBirth(LocalDate.of(1995, Month.DECEMBER, 12)).build();
 8  private static final Session SAMPLE_SESSION = Session.builder().city("Paris").locale(Locale.FRANCE).build();
 9  private static final Account SAMPLE_ACCOUNT = Account.builder().user(SAMPLE_USER).session(SAMPLE_SESSION).created(
10      ZonedDateTime.now()).build();
11
12  private @Autowired AccountRepository accountRepository;
13  private @Autowired SessionRepository sessionRepository;
14  private @Autowired UserRepository userRepository;
15
16  private Account savedAccount;
17
18  @BeforeEach
19  void setUp() {
20    accountRepository.deleteAll();
21    sessionRepository.deleteAll();
22    userRepository.deleteAll();
23    savedAccount = accountRepository.save(SAMPLE_ACCOUNT);
24  }
25
26  @Test
27  @DisplayName("Should cascade on save")
28  void shouldCascadeOnSave() {
29    final User savedUser = savedAccount.getUser();
30    final Optional<Session> savedSession = savedAccount.getSessions().stream().findAny();
31
32    final String userId = savedUser.getKey();
33    assertThat(userRepository.findById(userId))
34        .hasValueSatisfying(user -> assertThat(user).isEqualToIgnoringGivenFields(SAMPLE_USER, "key"));
35
36    if (savedSession.isPresent()) {
37      final String sessionId = savedSession.get().getKey();
38      assertThat(sessionRepository.findById(sessionId)).isNotEmpty()
39          .hasValueSatisfying(session -> assertThat(session).isEqualToIgnoringGivenFields(SAMPLE_SESSION, "key"));
40    }
41
42    savedUser.setLocale(Locale.CANADA);
43    savedAccount.setUser(savedUser);
44    accountRepository.save(savedAccount);
45    assertThat(userRepository.findById(userId))
46        .hasValueSatisfying(user -> assertThat(user.getLocale()).isEqualTo(Locale.CANADA));
47
48    if (savedSession.isPresent()) {
49      final Session modifiedSession = savedSession.get();
50      modifiedSession.setCity("Nice");
51      savedAccount.setSessions(Set.of(modifiedSession, Session.builder().city("Lyon").locale(Locale.FRANCE).build()));
52      Account modifiedAccount = accountRepository.save(savedAccount);
53      assertThat(sessionRepository.findById(modifiedSession.getKey())).isNotEmpty()
54          .hasValueSatisfying(session -> assertThat(session.getCity()).isEqualTo("Nice"));
55      assertThat(modifiedAccount.getSessions().stream().filter(s -> s.getCity().equals("Lyon")).findAny())
56          .hasValueSatisfying(session -> assertThat(sessionRepository.findById(session.getKey())).isNotEmpty()
57              .hasValueSatisfying(matchedSession -> assertThat(matchedSession.getCity()).isEqualTo("Lyon")));
58    }
59  }
60
61  @Test
62  @DisplayName("Should not cascade on fetch")
63  void shouldNotCascadeOnFetch() {
64    final String userId = savedAccount.getUser().getKey();
65    final Set<Session> sessions = savedAccount.getSessions();
66    accountRepository.findById(savedAccount.getKey());
67
68    assertThat(userRepository.findById(userId)).isNotEmpty();
69    assertThat(sessions).allSatisfy(session ->
70        assertThat(sessionRepository.findById(session.getKey())).isNotEmpty());
71  }
72
73  @Test
74  @DisplayName("Should cascade on delete")
75  void shouldCascadeOnDelete() {
76    final Optional<Account> fetchedAccount = accountRepository.findById(savedAccount.getKey());
77    accountRepository.deleteById(savedAccount.getKey());
78
79    assertThat(fetchedAccount)
80        .hasValueSatisfying(account -> {
81          assertThat(userRepository.findById(account.getUser().getKey())).isEmpty();
82          assertThat(account.getSessions())
83              .allSatisfy(session -> assertThat(sessionRepository.findById(session.getKey())).isEmpty());
84        });
85  }
86}

In this test class,

• we define some test data - SAMPLE_USER, SAMPLE_SESSION and SAMPLE_ACCOUNT.
• we implement a setup method that removes all the documents from the repositories and saves the SAMPLE_ACCOUNT before each test is run.
• the test shouldCascadeOnSave verifies if the @DBRef annotation correctly persists the SAMPLE_USER and SAMPLE_SESSION documents when the SAMPLE_ACCOUNT is saved. Then it updates the User document in the SAMPLE_ACCOUNT and checks if the same update appears in the document of the User collection for the given id. The same thing is done for the Session document.
• the test shouldNotCascadeOnFetch verifies that the cascade doesn't happen when a document is fetched from the database.
• the test shouldCascadeOnDelete verifies that once the SAMPLE_ACCOUNT has been deleted, the corresponding User and Session documents have also been deleted.

References

Source Code — spring-data-mongo-repository

Updates

• Thanks @CyberpunkPerson for pointing out that onAfterConvert can delete objects not only when the parent is deleted but also when the parent is fetched 🤦‍♀️! I've patched the code and updated the article with a fix.