Note: Up until JPA 2.2, the JPA acronym was standing for “Java Persistence API” and its interface was specified under the javax.persistence namespace, while from JPA 3.0 onwards, the JPA acronym is now standing for “Jakarta Persistence API” while its namespace has been migrated to javax.jakarta.persistence. This is due to the Java EE specifications, migration and move into the Eclipse Foundation post Java EE 8 and officiallyfrom Jakarta EE 9 onwards. The final JCP/Oracle represented release of Java EE happened on August 31, 2017 with Java EE 8. More details about this move can be found in this Oracle article.

Although JPA does not provide native support for Auditing, we can leverage its lifecycle events capability to receive a callback on pre/post create/update/delete operations and act on them.

How can we employ that in a sustainable/ extensible manner?

It all starts with the definition and understanding of these lifecycle events. At JPA interface level we have 7 annotations that curiously all align alphabetically in the JavaDoc and they all have the same description:

Specifies a callback method for the corresponding lifecycle event.

Reference JavaDoc for JPA 2.2 under javax.persistence namespace

Reference JavaDoc for JPA 3.0 under jakarta.persistence namespace

Out of these 7 annotations capturing lifecycle events we need 3 of them to capture Audit information:

Where shall we define these annotations? At each entity level?

Probably not, if we want to be dynamic and extensible, trying to minimise the changes to the bare minimum, if we want to onboard other entities to these Audit events being captured and persisted.

To that end, let’s invent a dedicated AuditEvent entity responsible for capturing the change in serialised form:

import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
import java.io.Serializable;
import javax.persistence.*;
import org.hibernate.annotations.Cache;
import org.hibernate.annotations.CacheConcurrencyStrategy;
import java.time.Instant;
import java.util.Objects;

@Entity
@Table(name = "audit_event")
@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
public class AuditEvent implements Serializable {

    private static final long serialVersionUID = 1L;

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotNull
    @Column(name = "entity_name", nullable = false)
    private Long entityName;

    @NotNull
    @Size(max = 25)
    @Column(name = "entity_type", length = 25, nullable = false)
    private String entityType;

    @NotNull
    @Size(max=10)
    @Column(name = "action", length = 10, nullable = false)
    private String action;

    @Lob
    @Column(name = "entity_value")
    private String entityValue;

    @Column(name = "commit_version")
    private Integer commitVersion;

    @Size(max = 50)
    @Column(name = "modified_by", length = 50)
    private String modifiedBy;

    @NotNull
    @Column(name = "modified_date", nullable = false)
    private Instant modifiedDate;

    //getters/setters omitted
}

Notice how the entity value is specified as a @Lob to hold the serialized version of the entity. This will give us the flexibility of holding any potential data structure regardless of the entity, sacrificing a bit searching capabilities since we don’t have everything normalised on dedicated columns.

Its corresponding Spring Data JPA Repository would be:

import org.springframework.data.jpa.repository.JpaRepository;
import com.dimitrisli.blog.auditevents.AuditEvent;

public interface AuditEventRepository extends JpaRepository<AuditEvent, Long> {}

At domain model level, the Audit event action can be represented with an enum:

public enum AuditAction { CREATE, UPDATE, DELETE }

We can confine and delegate the responsibility of converting the business entity into our audit entity and persisting it, into a dedicated Service bean:

@Service
public class AuditEventService {

    private final Logger log = LoggerFactory.getLogger(AuditEventService.class);

    private final AuditEventRepository auditEventRepository;
    private final ObjectMapper objectMapper; 

    public AuditEventService(AuditEventRepository auditEventRepository, ObjectMapper objectMapper) {
        this.auditEventRepository = auditEventRepository;
        this.objectMapper = objectMapper;
    }

    @Async
    public void convertAuditEvent(Object target, AuditAction action, String user) {
        try {
            AuditEvent auditedEntity = prepareAuditEntity(target, action, user);
            if (auditedEntity != null) {
                auditEventRepository.save(auditedEntity);
            }
        } catch (Exception e) {
            log.error("Exception on audit entity {} with error: {}", target, e);
        }
    }

    private AuditEvent prepareAuditEntity(final Object entity, AuditAction action, String user) {
        AuditEvent auditedEntity = new AuditEvent();
        Class<?> entityClass = entity.getClass(); 
        auditedEntity.setAction(action.value());
        auditedEntity.setEntityType(entityClass.getName());
        Long entityId;
        String entityData;
        try {
            Field privateLongField = entityClass.getDeclaredField("id");
            privateLongField.setAccessible(true);
            entityId = (Long) privateLongField.get(entity);
            privateLongField.setAccessible(false);
            //serialized version of the entity
            entityData = objectMapper.writeValueAsString(entity);
        } catch (Exception e) {
            log.error("Exception on entity conversion with error {}", e);
            return null;
        }
        auditedEntity.setEntityId(entityId);
        auditedEntity.setEntityValue(entityData);
        if (AuditAction.CREATE.equals(action)) {
            auditedEntity.setModifiedBy(user);
            auditedEntity.setModifiedDate(Instant.now());
            auditedEntity.setCommitVersion(1);
        } else {
            auditedEntity.setModifiedBy(user);
            auditedEntity.setModifiedDate(Instant.now());
            calculateVersion(auditedEntity);
        }
        return auditedEntity;
    }
}

Notice here that the method is @Async and thus not holding back the servlet request thread of execution (assuming a non-reactive webapp exposing this capability). Also notice how we are pulling out certain attributes via reflection and how we JSON-ising the entity content via Jackson’s ObjectMapper.

Now that we have a mechanism to convert from any entity into this Audit-specific persistable entity, let’s move one level higher and connect the JPA event lifecycle callback annotations to this capability.

For that we’ll leverage Spring Data JPA’s AuditingEntityListener capability via a new dedicated listener bean:

public class AuditEventListener extends AuditingEntityListener {

    private final Logger log = LoggerFactory.getLogger(AuditEventListener.class);

    private AuditEventService auditEventService;

    @PostPersist
    public void onPostCreate(Object target) {
        try {
            auditEventService.convertAuditEvent(target, AuditAction.CREATE, SecurityContextHolder.getContext().getAuthentication().getName());
        } catch (Exception e) {
            log.error("Exception on post create {}", e);
        }
    }

    @PostUpdate
    public void onPostUpdate(Object target) {
        try {
            auditEventService.convertAuditEvent(target, AuditAction.UPDATE, SecurityContextHolder.getContext().getAuthentication().getName());
        } catch (Exception e) {
            log.error("Exception on post update {}", e);
        }
    }

    @PostRemove
    public void onPostRemove(Object target) {
        try {
            auditEventService.convertAuditEvent(target, EntityAuditAction.DELETE, SecurityContextHolder.getContext().getAuthentication().getName());
        } catch (Exception e) {
            log.error("Exception on post remove {}", e);
        }

    public void setAuditEventService(AuditEventService auditEventService) {
        this.auditEventService = auditEventService;
    }
}

Notice how we are pulling the name of the principal to be persisted as user (assuming usage of non-reactive webapp with Spring Security configured).

Now that we have confined and delegated the callback handling and persistence of the audit events, all it’s left is to register the listener at entity level. This is all we have to do to onboard any entity to this Audit capturing capability. The registration of the listeners at entity-level is happening via JPA’s EntityListeners annotation.

JPA 2.2 EntityListeners JavaDoc

JPA 3.0 EntityListeners JavaDoc

@Entity
@Table(name = "my_table")
@EntityListeners(AuditEventListener.class)
public class MyEntity implements Serializable {

    private static final long serialVersionUID = 1L;
    //
}