UUID as Entity ID in MongoDB

1. Overview

By default, the MongoDB Java driver generates IDs of the type ObjectId. Sometimes, we may want to use another type of data as the unique identifier of an object, such as a UUID. However, the MongoDB Java driver can’t generate UUIDs automatically.

In this tutorial, we’ll look at three ways to generate UUIDs with the MongoDB Java driver and Spring Data MongoDB.

2. Common Points

It’s quite rare for an application to manage only one type of data. To simplify the management of the IDs in our MongoDB database, it’s easier to implement an abstract class that will define the ID of all our Document classes.

public abstract class UuidIdentifiedEntity {

    @Id   
    protected UUID id;    

    public void setId(UUID id) {

        if (this.id != null) {
            throw new UnsupportedOperationException("ID is already defined");
        }

        this.id = id;
    }

    // Getter
}

For the examples in this tutorial, we’ll assume that all classes persisted in the MongoDB database inherited from this class.

3. Configuring UUID Support

To allow storage of UUIDs in MongoDB, we must configure the driver. This configuration is very simple and only tells the driver how to store UUIDs in the database. We must handle this carefully if several applications use the same database.

All we have to do is to specify the uuidRepresentation parameter in our MongoDB client at startup:

@Bean
public MongoClient mongo() throws Exception {
    ConnectionString connectionString = new ConnectionString("mongodb://localhost:27017/test");
    MongoClientSettings mongoClientSettings = MongoClientSettings.builder()
      .uuidRepresentation(UuidRepresentation.STANDARD)
      .applyConnectionString(connectionString).build();
    return MongoClients.create(mongoClientSettings);
}

If we use Spring Boot, we can specify this parameter in our application.properties file:

spring.data.mongodb.uuid-representation=standard

4. Using Lifecycle Events

The first method to handle the generation of UUID is by using Spring’s lifecycle events. With MongoDB entities, we can’t use JPA annotations @PrePersist and so on. Therefore, we have to implement event listener classes registered in the ApplicationContext. To do so, our classes must extend the Spring’s AbstractMongoEventListener class:

public class UuidIdentifiedEntityEventListener extends AbstractMongoEventListener<UuidIdentifiedEntity> {
    
    @Override
    public void onBeforeConvert(BeforeConvertEvent<UuidIdentifiedEntity> event) {
        
        super.onBeforeConvert(event);
        UuidIdentifiedEntity entity = event.getSource();
        
        if (entity.getId() == null) {
            entity.setId(UUID.randomUUID());
        } 
    }    
}

In this case, we’re using the OnBeforeConvert event, which is triggered before Spring converts our Java object to a Document object and sends it to the MongoDB driver.

Typing our event to catch UuidIdentifiedEntity class allows handling all subclasses of this abstract supertype. Spring will call our code as soon as an object using a UUID as ID is converted.

We must be aware that, Spring delegates event handling to a TaskExecutor which may be asynchronous. Spring does not guarantee that the event is processed before the object is effectively converted. This method is discouraged in the case your TaskExecutor is asynchronous as the ID may be generated after the object has been converted, leading to an Exception:

InvalidDataAccessApiUsageException: Cannot autogenerate id of type java.util.UUID for entity

We can register the event listener in the ApplicationContext by annotating it with @Component or by generating it in a @Configuration class:

@Bean
public UuidIdentifiedEntityEventListener uuidIdentifiedEntityEventListener() {
    return new UuidIdentifiedEntityEventListener();
}

5. Using Entity Callbacks

Spring infrastructure provides hooks to execute custom code at some points in the lifecycle of an entity. Those are called EntityCallbacks, and we can use them in our case to generate a UUID before the object is persisted in the database.

Unlike the event listener method seen previously, callbacks guarantee that their execution is synchronous and the code will run at the expected point in the object’s lifecycle.

Spring Data MongoDB provides a set of callbacks we can use in our application. In our case, we’ll use the same event as previously. Callbacks can be provided directly in the @Configuration class:

@Bean
public BeforeConvertCallback<UuidIdentifiedEntity> beforeSaveCallback() {
        
    return (entity, collection) -> {
          
        if (entity.getId() == null) {
            entity.setId(UUID.randomUUID());
        }
        return entity;
    };
}

We can also use a Component that implements the BeforeConvertCallback interface.

6. Using Custom Repositories

Spring Data MongoDB provides a third method to achieve our goal: using a custom repository implementation. Usually, we just have to declare an interface inheriting from MongoRepository, and then Spring handles repositories-related code.

If we want to change the way Spring Data handles our objects, we can define custom code that Spring will execute at the repository level. To do so, we must first define an interface extending MongoRepository:

@NoRepositoryBean
public interface CustomMongoRepository<T extends UuidIdentifiedEntity> extends MongoRepository<T, UUID> { }

The @NoRepositoryBean annotation prevents Spring from generating the usual piece of code associated with a MongoRepository. This interface forces the use of UUID as the type of the ID in the objects.

Then, we must create a repository class that will define the required behavior to handle our UUIDs:

public class CustomMongoRepositoryImpl<T extends UuidIdentifiedEntity> 
  extends SimpleMongoRepository<T, UUID> implements CustomMongoRepository<T>

In this repository, we’ll have to catch all methods calls where we need to generate an ID by overriding the relevant methods of SimpleMongoRepository. Those methods are save() and insert() in our case:

@Override
public <S extends T> S save(S entity) {
    generateId(entity);
    return super.save(entity);
}

Finally, we need to tell Spring to use our custom class as the implementation of the repositories instead of the default implementation. We do that in the @Configuration class:

@EnableMongoRepositories(basePackages = "com.baeldung.repository", repositoryBaseClass = CustomMongoRepositoryImpl.class)

Then, we can declare our repositories as usual with no changes:

public interface BookRepository extends MongoRepository<Book, UUID> { }

7. Conclusion

In this article, we have seen three ways to implement UUIDs as MongoDB object’s ID with Spring Data MongoDB.