I usually post about Persistence on Twitter - you can follow me there:

1. Overview

In the context of ORM, database auditing means tracking and logging events related to persistent entities, or simply entity versioning. Inspired by SQL triggers, the events are insert, update and delete operations on entities. The benefits of database auditing are analogous to those provided by source version control.

We will demonstrate three approaches to introducing auditing into an application. First, we will implement it using standard JPA. Next, we will look at two JPA extensions that provide their own auditing functionality: one provided by Hibernate, another by Spring Data.

Here are the sample related entities, Bar and Foo, that will be used in this example:

2. Auditing with JPA

JPA doesn’t explicitly contain an auditing API, but the functionality can be achieved using entity lifecycle events.

2.1. @PrePersist, @PreUpdate and @PreRemove

In JPA Entity class, a method can be specified as a callback which will be invoked during a particular entity lifecycle event. As we’re interested in callbacks that are executed before the corresponding DML operations, there are @PrePersist, @PreUpdate and @PreRemove callback annotations available for our purposes:

@Entity
public class Bar {
      
    @PrePersist
    public void onPrePersist() { ... }
      
    @PreUpdate
    public void onPreUpdate() { ... }
      
    @PreRemove
    public void onPreRemove() { ... }
      
}

Internal callback methods should always return void and take no arguments. They can have any name and any access level but should not be static.

Be aware that the @Version annotation in JPA is not strictly related to our topic – it has to do with optimistic locking more than with audit data.

2.2. Implementing the Callback Methods

There is a significant restriction with this approach, though. As stated in JPA 2 specification (JSR 317):

In general, the lifecycle method of a portable application should not invoke EntityManager or Query operations, access other entity instances, or modify relationships within the same persistence context. A lifecycle callback method may modify the non-relationship state of the entity on which it is invoked.

In the absence of an auditing framework, we must maintain the database schema and domain model manually. For our simple use case, let’s add two new properties to the entity, as we can manage only the “non-relationship state of the entity”. An operation property will store the name of an operation performed and a timestamp property is for the timestamp of the operation:

@Entity
public class Bar {
     
    //...
     
    @Column(name = "operation")
    private String operation;
     
    @Column(name = "timestamp")
    private long timestamp;
     
    //...
     
    // standard setters and getters for the new properties
     
    //...
     
    @PrePersist
    public void onPrePersist() {
        audit("INSERT");
    }
     
    @PreUpdate
    public void onPreUpdate() {
        audit("UPDATE");
    }
     
    @PreRemove
    public void onPreRemove() {
        audit("DELETE");
    }
     
    private void audit(String operation) {
        setOperation(operation);
        setTimestamp((new Date()).getTime());
    }
     
}

If you need to add such auditing to multiple classes, you can use @EntityListeners to centralize the code. For example:

@EntityListeners(AuditListener.class)
@Entity
public class Bar { ... }
public class AuditListener {
    
    @PrePersist
    @PreUpdate
    @PreRemove
    private void beforeAnyOperation(Object object) { ... }
    
}

3. Hibernate Envers

With Hibernate, we could make use of Interceptors and EventListeners as well as database triggers to accomplish auditing. But the ORM framework offers Envers, a module implementing auditing and versioning of persistent classes.

3.1. Get Started with Envers

To set up Envers, you need to add the hibernate-envers JAR into your classpath:

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-envers</artifactId>
    <version>${hibernate.version}</version>
</dependency>

Then just add the @Audited annotation either on an @Entity (to audit the whole entity) or on specific @Columns (if you need to audit specific properties only):

@Entity
@Audited
public class Bar { ... }

Note that Bar has a one-to-many relationship with Foo. In this case, we either need to audit Foo as well by adding @Audited on Foo or set @NotAudited on the relationship’s property in Bar:

@OneToMany(mappedBy = "bar")
@NotAudited
private Set<Foo> fooSet;

3.2. Creating Audit Log Tables

There are several ways to create audit tables:

  • set hibernate.hbm2ddl.auto to create, create-drop or update, so Envers can create them automatically
  • use org.hibernate.tool.EnversSchemaGenerator to export the complete database schema programmatically
  • use an Ant task to generate appropriate DDL statements
  • use a Maven plugin for generating a database schema from your mappings (such as Juplo) to export Envers schema (works with Hibernate 4 and higher)

We’ll go the first route, as it is the most straightforward, but be aware that using hibernate.hbm2ddl.auto is not safe in production.

In our case, bar_AUD and foo_AUD (if you’ve set Foo as @Audited as well) tables should be generated automatically. The audit tables copy all audited fields from the entity’s table with two fields, REVTYPE (values are: “0” for adding, “1” for updating, “2” for removing an entity) and REV.

Besides these, an extra table named REVINFO will be generated by default, it includes two important fields, REV and REVTSTMP and records the timestamp of every revision. And as you can guess, bar_AUD.REV and foo_AUD.REV are actually foreign keys to REVINFO.REV.

3.3. Configuring Envers

You can configure Envers properties just like any other Hibernate property.

For example, let’s change the audit table suffix (which defaults to “_AUD“) to “_AUDIT_LOG“. Here is how to set the value of the corresponding property org.hibernate.envers.audit_table_suffix:

Properties hibernateProperties = new Properties(); 
hibernateProperties.setProperty(
  "org.hibernate.envers.audit_table_suffix", "_AUDIT_LOG"); 
sessionFactory.setHibernateProperties(hibernateProperties);

A full listing of available properties can be found in the Envers documentation.

3.4. Accessing Entity History

You can query for historic data in a way similar to querying data via theHibernate criteria API. The audit history of an entity can be accessed using the AuditReader interface, which can be obtained with an open EntityManager or Session via the AuditReaderFactory:

AuditReader reader = AuditReaderFactory.get(session);

Envers provides AuditQueryCreator (returned by AuditReader.createQuery()) in order to create audit-specific queries. The following line will return all Bar instances modified at revision #2 (where bar_AUDIT_LOG.REV = 2):

AuditQuery query = reader.createQuery()
  .forEntitiesAtRevision(Bar.class, 2)

Here is how to query for Bar‘s revisions, i.e. it will result in getting a list of all Bar instances in all their states that were audited:

AuditQuery query = reader.createQuery()
  .forRevisionsOfEntity(Bar.class, true, true);

If the second parameter is false the result is joined with the REVINFO table, otherwise, only entity instances are returned. The last parameter specifies whether to return deleted Bar instances.

Then you can specify constraints using the AuditEntity factory class:

query.addOrder(AuditEntity.revisionNumber().desc());

4. Spring Data JPA

Spring Data JPA is a framework that extends JPA by adding an extra layer of abstraction on the top of the JPA provider. This layer allows for support for creating JPA repositories by extending Spring JPA repository interfaces.

For our purposes, you can extend CrudRepository<T, ID extends Serializable>, the interface for generic CRUD operations. As soon as you’ve created and injected your repository to another component, Spring Data will provide the implementation automatically and you’re ready to add auditing functionality.

4.1. Enabling JPA Auditing

To start, we want to enable auditing via annotation configuration. In order to do that, just add @EnableJpaAuditing on your @Configuration class:

@Configuration
@EnableTransactionManagement
@EnableJpaRepositories
@EnableJpaAuditing
public class PersistenceConfig { ... }

4.2. Adding Spring’s Entity Callback Listener

As we already know, JPA provides the @EntityListeners annotation to specify callback listener classes. Spring Data provides its own JPA entity listener class: AuditingEntityListener. So let’s specify the listener for the Bar entity:

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Bar { ... }

Now auditing information will be captured by the listener on persisting and updating the Bar entity.

4.3. Tracking Created and Last Modified Dates

Next, we will add two new properties for storing the created and last modified dates to our Bar entity. The properties are annotated by the @CreatedDate and @LastModifiedDate annotations accordingly, and their values are set automatically:

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Bar {
    
    //...
    
    @Column(name = "created_date", nullable = false, updatable = false)
    @CreatedDate
    private long createdDate;

    @Column(name = "modified_date")
    @LastModifiedDate
    private long modifiedDate;
    
    //...
    
}

Generally, you would move the properties to a base class (annotated by @MappedSuperClass) which would be extended by all your audited entities. In our example, we add them directly to Bar for the sake of simplicity.

4.4. Auditing the Author of Changes with Spring Security

If your app uses Spring Security, you can not only track when changes were made but also who made them:

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Bar {
    
    //...
    
    @Column(name = "created_by")
    @CreatedBy
    private String createdBy;

    @Column(name = "modified_by")
    @LastModifiedBy
    private String modifiedBy;
    
    //...
    
}

The columns annotated with @CreatedBy and @LastModifiedBy are populated with the name of the principal that created or last modified the entity. The information is pulled from SecurityContext‘s Authentication instance. If you want to customize values that are set to the annotated fields, you can implement AuditorAware<T> interface:

public class AuditorAwareImpl implements AuditorAware<String> {
 
    @Override
    public String getCurrentAuditor() {
        // your custom logic
    }

}

In order to configure the app to use AuditorAwareImpl to look up the current principal, declare a bean of AuditorAware type initialized with an instance of AuditorAwareImpl and specify the bean’s name as the auditorAwareRef parameter’s value in @EnableJpaAuditing:

@EnableJpaAuditing(auditorAwareRef="auditorProvider")
public class PersistenceConfig {
    
    //...
    
    @Bean
    AuditorAware<String> auditorProvider() {
        return new AuditorAwareImpl();
    }
    
    //...
    
}

5. Conclusion

We have considered three approaches to implementing auditing functionality:

  • The pure JPA approach is the most basic and consists of using lifecycle callbacks. However, you are only allowed to modify the non-relationship state of an entity. This makes the @PreRemove callback useless for our purposes, as any settings you’ve made in the method will be deleted then along with the entity.
  • Envers is a mature auditing module provided by Hibernate. It is highly configurable and lacks the flaws of the pure JPA implementation. Thus, it allows us to audit the delete operation, as it logs into tables other than the entity’s table.
  • The Spring Data JPA approach abstracts working with JPA callbacks and provides handy annotations for auditing properties. It’s also ready for integration with Spring Security. The disadvantage is that it inherits the same flaws of the JPA approach, so the delete operation cannot be audited.

The examples for this article are available in a GitHub repository.

I usually post about Persistence on Twitter - you can follow me there:


Sort by:   newest | oldest | most voted
wwwim
Guest

What’s the use of the @PreRemove callback if you can not access other entities or the entitymanager? The entity will be deleted, so updating properties of the entity that will be deleted is useless, no?

Eugen Paraschiv
Guest

You’re definitely right on that particular annotations – the rest of them make sense and do provide (very basic) audit information, but that one doesn’t make a lot of sense.
I’ve added a new version of the article to the content calendar and we’re going to work through a more complete implementation. I’ll follow up here when that’s out.
Thanks for the super useful feedback. Cheers,
Eugen.

Marc Zampetti
Guest

I’m using this same technique, and one issue I’m seeing is that the audit records do not contain any information about who performed the delete operation. I have a column annotated with @LastModified but when the auditing information is created, that field is blank. I have the envers record that records that the delete happened, but I’d like to be able to track who did the delete. Any ideas?

Eugen Paraschiv
Guest

Hey Marc – that’s an interesting usecase that we might explore in the next version of this article. In the meantime, here’s a slightly older but well done writeup on this. Hope it helps. Cheers,
Eugen.

Mark Diskin
Guest

We attempted to use the Spring Data JPA Auditing but run into issues with the @Version annotation which is always generated in the db. If we use the jpa @Version it seems to always bump the number and then the trigger does it again. It does not make sense but we switched it to spring’s data @Version annotation which is not documented well and it seems to work but not really make much sense to us since this for optimistic locking.

Eugen Paraschiv
Guest

That makes sense, thanks for following up. Cheers,
Eugen.

Rob Light
Guest

@baeldung:disqus why do you say “JPA doesn’t explicitly contain an auditing API” when there’s this: http://docs.spring.io/spring-data/jpa/docs/1.5.0.RELEASE/reference/html/jpa.repositories.html#jpa.auditing

Eugen Paraschiv
Guest

Hey Rob – because that’s Spring Data JPA, not JPA. The Java Persistence API standard is a completely separate thing from Spring Data JPA (which is built on top of JPA but not part of it).
Hope that clears things up. Cheers,
Eugen.

Piotr Sobolewski
Guest

Hi. Great article! But there is one thing that you have to know. When you persiste your entity in database via save method then created_date will be generate each time. You should annotate it as not updatable @Column(name = “created_date”, nullable = false, updatable = false).

Grzegorz Piwowarek
Guest

Piotr, great catch. Thanks 🙂 We will update the article

wpDiscuz