3. Auditing

3.1 Basics

Spring Data provides sophisticated support to transparently keep track of who created or changed an entity and the point in time this happened. To benefit from that functionality you have to equip your entity classes with auditing metadata that can be defined either using annotations or by implementing an interface.

3.1.1 Annotation based auditing metadata

We provide @CreatedBy, @LastModifiedBy to capture the user who created or modified the entity as well as @CreatedDate and @LastModifiedDate to capture the point in time this happened.

Example 3.1. An audited entity

class Customer {

  private User user;

  private DateTime createdDate;

  // … further properties omitted

As you can see, the annotations can be applied selectively, depending on which information you’d like to capture. For the annotations capturing the points in time can be used on properties of type org.joda.time.DateTime, java.util.Date as well as long/Long.

3.1.2 Interface-based auditing metadata

In case you don’t want to use annotations to define auditing metadata you can let your domain class implement the Auditable interface. It exposes setter methods for all of the auditing properties.

There’s also a convenience base class AbstractAuditable which you can extend to avoid the need to manually implement the interface methods. Be aware that this increases the coupling of your domain classes to Spring Data which might be something you want to avoid. Usually the annotation based way of defining auditing metadata is preferred as it is less invasive and more flexible.

3.1.3 AuditorAware

In case you use either @CreatedBy or @LastModifiedBy, the auditing infrastructure somehow needs to become aware of the current principal. To do so, we provide an AuditorAware<T> SPI interface that you have to implement to tell the infrastructure who the current user or system interacting with the application is. The generic type T defines of what type the properties annotated with @CreatedBy or @LastModifiedBy have to be.

Here’s an example implementation of the interface using Spring Security’s Authentication object:

Example 3.2. Implementation of AuditorAware based on Spring Security

class SpringSecurityAuditorAware implements AuditorAware<User> {

  public User getCurrentAuditor() {

    Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

    if (authentication == null || !authentication.isAuthenticated()) {
      return null;

    return ((MyUserDetails) authentication.getPrincipal()).getUser();

The implementation is accessing the Authentication object provided by Spring Security and looks up the custom UserDetails instance from it that you have created in your UserDetailsService implementation. We’re assuming here that you are exposing the domain user through that UserDetails implementation but you could also look it up from anywhere based on the `Authentication found.

3.2 JPA Auditing

3.2.1 General auditing configuration

Spring Data JPA ships with an entity listener that can be used to trigger capturing auditing information. So first you have to register the AuditingEntityListener inside your orm.xml to be used for all entities in your persistence contexts:

Note that the auditing feature requires spring-aspects.jar to be on the classpath.

Example 3.3. Auditing configuration orm.xml

      <entity-listener class="….data.jpa.domain.support.AuditingEntityListener" />

Now activating auditing functionality is just a matter of adding the Spring Data JPA auditing namespace element to your configuration:

Example 3.4. Activating auditing using XML configuration

<jpa:auditing auditor-aware-ref="yourAuditorAwareBean" />

As of Spring Data JPA 1.5, auditing can be enabled by annotating a configuration class with the @EnableJpaAuditing annotation.

Example 3.5. Activating auditing via Java configuration

class Config {

  public AuditorAware<AuditableUser> auditorProvider() {
    return new AuditorAwareImpl();

If you expose a bean of type AuditorAware to the ApplicationContext, the auditing infrastructure will pick it up automatically and use it to determine the current user to be set on domain types. If you have multiple implementations registered in the ApplicationContext, you can select the one to be used by explicitly setting the auditorAwareRef attribute of @EnableJpaAuditing.