Hibernate Envers – Extending Revision Info with Custom Fields

1. Overview

A common requirement for system-of-record applications is keeping track of changes to domain entities. For JPA-based applications, using Hibernate Envers allows us to implement this requirement in an almost transparent way, which makes it a popular choice.

Out-of-the-box, Envers captures only the fields of the modified entity along with the kind of change and a timestamp. In most cases, however, we need to add extra fields to this change event. A common case is to add the user and the remote IP associated with the request that triggered the change.

In this tutorial, we’ll show how to extend Envers to add custom fields to the standard audited data, using a Spring Boot-based pet shelter application as an example.

2. Project Setup

Let’s start our project by adding the required Spring Data JPA and Envers dependencies:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
    <version>3.3.5</version>
</dependency>

<dependency>
    <groupId>org.springframework.data</groupId>
     <artifactId>spring-data-envers</artifactId>
    <version>3.4.0</version>
</dependency>

The latest versions of these dependencies are available on Maven Central:

• spring-boot-starter-data-jpa
• spring-data-envers

Note: when using SpringBoot-managed dependencies, there’s no need to specify versions.

The full project descriptor also includes Lombok, the H2 embedded database, and the standard Spring Boot test starter.

3. Pet Shelter Example

Our simplistic pet shelter domain consists of just three entities:

• Pet: An animal that the shelter will take care of until an Owner decides to adopt it.
• Species: The species of a given Pet
• Owner: A person that adopts one or more Pets

This simplified class diagram shows the relationship between those entities:

Notice that a Pet may not have an Owner. A Pet without an Owner is available for adoption.

When the shelter receives a new Pet, it will be assigned a unique identifier that won’t change throughout its lifetime. Its name, however, can change at any time. For instance, if an Owner decides to return the Pet to the shelter for some reason, the next Owner can choose to give it a new name.

For our shelter, keeping track of those changes is very important, so we’ll use Envers to implement the required audit tables. Now, keeping the old names and Owners for a given Pet is not enough. City regulations require that we also register the name of the shelter’s employee who filed the adoptions and returns.

Moreover, let’s assume that this application runs on a backend and serves requests from a mobile or SPA frontend. In this scenario, it’s important to add some contextual information to the audit record as well. In our case, we’ll assume that the remote address is enough. Those extra fields will be added to the standard REVINFO table that Envers already uses for its versioning control.

4. Domain Layer Implementation

In an earlier tutorial, we’ve already covered the basics of Envers. For most cases, all we need is to add the @Audited annotation to our domain classes:

@Entity
@Audited
@Data
@NoArgsConstructor
public class Species {
    @Id @GeneratedValue
    private Long id;

    @Column(unique = true)
    private String name;

   // ... static methods omitted
}

@Entity
@Audited
@Data
public class Pet {
    @Id @GeneratedValue
    private Long id;

    @Column(unique = true, nullable = false)
    private UUID uuid;

    private String name;

    // A null ownes implies the pet is available for adoption
    @ManyToOne
    @JoinColumn(name = "owner_id", nullable = true)
    private Owner owner;

    @ManyToOne
    @JoinColumn(name = "species_id")
    private Species species;
}

@Entity
@Audited
@Data
public class Owner {
    @Id @GeneratedValue
    private Long id;

    @Column(nullable = false)
    private String name;

    @OneToMany(fetch = FetchType.EAGER)
    private List<Pet> pets;

    // ... static methods omitted
}

Besides those business-related entities, we also need an additional entity as our extended revision entity. Here, we’ll extend Enver’s DefaultRevisionEntity with the required fields:

@Entity
@RevisionEntity
@EqualsAndHashCode(callSuper = true)
@Getter
@Setter
@NoArgsConstructor
@EntityListeners(CustomRevisionListener.class)
public class CustomRevisionEntity extends DefaultRevisionEntity {
    private String remoteHost;
    private String remoteUser;
}

Please notice the @RevisionEntity annotation, which marks this entity as the root for a set of related changes on one or more entities. Moreover, we also need to specify an @EntityListener to it, so we’ll be able to populate our custom fields.

5. Repository Layer Implementation

For the repository layer, we’ll use Spring Data’s standard JpaRepository as a basis, adding extra finder methods as required:

public interface PetRepository extends JpaRepository<Pet,Long>, RevisionRepository<Pet,Long,Long> {
    List<Pet> findPetsByOwnerNullAndSpecies(Species species);
    Optional<Pet> findPetByUuid(UUID uuid);
}

In this example, we’ve added history retrieval support to the Pet entity only. This is done through the RevisionRepository interface that the PetRepository also extends.

At runtime, the Spring Data Envers integration will provide a suitable implementation for the PetRepository. For instance, this is how we’d use the findRevisions() method to list all changes for a given Pet:

return petsRepo.findRevisions(pet.getId()).stream()
  .map(r -> {
     // ... map revision to a suitable DTO
  })
  .toList();

The Revision entries returned by this method allow us to directly query the timestamp, operation, and the original entity values. To reach the actual revision entity we need to use getMetadata().getDelegate().

This delegate, thanks to the @RevisionEntity annotation, will be an instance of our extended revision entity. We can then use it directly to retrieve the extra fields:

return petsRepo.findRevisions(pet.getId()).stream()
  .map(r -> {
      CustomRevisionEntity rev = r.getMetadata().getDelegate();
      // ... map revision info as needed
  })
  .toList();

6. CustomRevisionListener Implementation

Now that we know how to extend the default revision and access it from repositories, we need to implement the entity listener that will populate those extra fields.

Here, it’s worth mentioning that, even though we’ve used our listener class name in the @EntityListeners annotation, in practice, we could also use an interface. As long as there’s a Spring-managed bean available in the context that is compatible with the declared type, Envers will be able to use it.

In any case, there’s a requirement that this type has a void method with one of the lifecycle-related annotations: @Pre/PostPersist, @Pre/PostDelete, etc. For our purpose, we just need a @PrePersist-annotated method:

@Component
@RequiredArgsConstructor
public class CustomRevisionListener {
    private final Supplier<Optional<RequestInfo>> requestInfoSupplier;

    @PrePersist
    private void onPersist(CustomRevisionEntity entity) {
        var info = requestInfoSupplier.get();
        if (info.isEmpty()) {
            return;
        }

        entity.setRemoteHost(info.get().remoteHost());
        entity.setRemoteUser(info.get().remoteUser());
    }
}

This class is a regular Spring @Component, so we can use all the standard injection patterns. Here, we’re using a constructor-injected Supplier that, at runtime, will provide the contextual information we need. Using this approach creates a nice decoupling from the actual source of the contextual information and enforces a clear separation of concerns. It also makes testing the service/repository/domain easier, since we can provide a mock supplier instead of a a real one.

7. Service Layer

Now, let’s take a look at a couple of methods available in the AdoptionService (available online). The first one is registerForAdoption() :

public UUID registerForAdoption( String speciesName) {
    var species = speciesRepo.findByName(speciesName)
      .orElseThrow(() -> new IllegalArgumentException("Unknown Species: " + speciesName));

    var pet = new Pet();
    pet.setSpecies(species);
    pet.setUuid(UUID.randomUUID());
    petsRepo.save(pet);
    return pet.getUuid();
}

Nothing special here, and this is good news! Envers integration is, for the most part, non-intrusive and just works. Next, this the listPetStory() implementation:

public List<PetHistoryEntry> listPetHistory(UUID petUuid) {
    var pet = petsRepo.findPetByUuid(petUuid)
      .orElseThrow(() -> new IllegalArgumentException("No pet with UUID '" + petUuid + "' found"));

    return petsRepo.findRevisions(pet.getId()).stream()
      .map(r -> {
          CustomRevisionEntity rev = r.getMetadata().getDelegate();
          return new PetHistoryEntry(r.getRequiredRevisionInstant(),
            r.getMetadata().getRevisionType(),
            r.getEntity().getUuid(),
            r.getEntity().getSpecies().getName(),
            r.getEntity().getName(),
            r.getEntity().getOwner() != null ? r.getEntity().getOwner().getName() : null,
            rev.getRemoteHost(),
            rev.getRemoteUser());
      })
      .toList();
}

The implementation uses one of the revision-related methods available in the PetRepository to retrieve a list of Revision entries. We then map those entries to PetHistoryEntry records which will be exposed to clients.

8. Testing

To complete our tutorial, let’s create a test that simulates the life of a cat as the shelter receives him and then goes through a couple of adoptions:

@Test
void whenAdoptPet_thenSuccess() {
    var petUuid = adoptionService.registerForAdoption("cat");
    var kitty = adoptionService.adoptPet(petUuid, "adam", "kitty");

    List<PetHistoryEntry> kittyHistory = adoptionService.listPetHistory(kitty.getUuid());
    assertNotNull(kittyHistory);
    assertTrue(kittyHistory.size() > 0 , "kitty should have a history");
    for (PetHistoryEntry e : kittyHistory) {
        log.info("Entry: {}", e);
    }
}

@TestConfiguration
static class TestConfig {
    @Bean
    Supplier<Optional<RequestInfo>> requestInfoSupplier() {
        return () -> Optional.of(new RequestInfo("example.com", "thomas"));        
    }
	
    // ... other test beans omitted
}

Besides the test case itself, the key point here is the use of a @TestConfiguration inner class to provide a bean that implements the required Supplier of RequestInfo. Here, we simply provide fixed data, but we could also simulate a more complex scenario.

9. Conclusion

In this article, we’ve shown how to extend the default Envers revision entity with custom fields and integrate it into a Spring Boot-based application.