Entity auditing with Hibernate Envers

A common requirement in a business application is to store versioning information when particular data changes; when something changed, who changed it and what changed. In this blog post, we are going to take a look at Hibernate Envers, a component of the Hibernate JPA library, that provides an easy auditing/versioning solution for entity classes. Envers works with Hibernate and JPA, and you can use Envers anywhere Hibernate works.

Envers stores changes in special audit tables and provides several query methods to access historical snapshots.

Setup ¶

To start with Envers, you first need to add the library to your project's classpath. In a Maven managed file, you add this dependency.

      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-envers</artifactId>
      <version>6.4.1.Final</version>
    </dependency>
    <dependency>

pom.xml

Next, annotate the entity classes or entity properties, that Envers should keep track of, with the @Audited annotation. For the following examples, I use two entity classes: Employee and Company. In the Employee class, I added the @Audited to the class, Envers keeps track of all properties in this class.

@Entity
@Audited(withModifiedFlag = true)
public class Employee {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private int id;

  private String lastName;

  private String firstName;

  private String street;

  private String city;

  @ManyToOne
  private Company company;

Employee.java

In the Company class, I added @Audited only to the name property. Envers keeps track of this property and ignores all the others. Envers also provides a @NotAudited annotation for cases where you add @Audited to the class but want to ignore specific properties.

@Entity
public class Company {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private int id;

  @Audited
  private String name;

  private String street;

  private String city;

  @OneToMany(mappedBy = "company", cascade = CascadeType.ALL, orphanRemoval = true)
  private Set<Employee> employees;

Company.java

Make sure your entities using immutable unique identifiers (primary keys).

Tables ¶

In the following example project, I set the Hibernate configuration hibernate.hbm2ddl.auto to update.

      <property name="hibernate.hbm2ddl.auto" value="update" />

persistence.xml

With this configuration in place, Hibernate automatically creates the two tables Employee and Company. For each @Audited entity, it creates an audit table where Envers keeps track of the changes. It also creates the REVINFO table, which keeps track of the revision number and the timestamp when the change happened.

Each time an @Audited entity is going to be inserted, updated or deleted, Envers steps in and creates a new revision by inserting a new row into the REVINFO table and the corresponding AUD table.

Notice that the EMPLOYEE_AUD table contains a field for each field in the EMPLOYEE table, whereas the COMPANY_AUD table only contains the name field, that's because we only annotated the name property in the Company class. The ID field of the AUD tables is the primary key of the corresponding entity table; that's the reason your primary keys have to be immutable.

In the Employee class, we enabled the withModifiedFlag option (@Audited(withModifiedFlag = true)) which is disabled by default. You see the effect of this option in the EMPLOYEE_AUD table. Envers added for each property an additional _MOD boolean property. This modification flag stores information if a property has been changed at the given revision.

In the Company class, we didn't enable this option. Therefore the COMPANY_AUD table does not contain a NAME_MOD field.

For comparison here the EMPLOYEE_AUD table definition if you don't enable the option:
without withModifiedFlag

You should only enable withModifiedFlag if you need this information because the trade-off is that the additional fields increase the size of the audit tables. There is one Envers query (forRevisionsOfEntityWithChange) that depends on this additional information, so if you plan to use this query method, you have to enable the option.

Custom Revision Entity ¶

Notice that Envers, by default, only keeps track of the date and time when a change occurred. However, in a multi-user application, you often also want to know who did the change.

For this purpose, we need to create a custom revision entity class. This class has to extend the DefaultRevisionEntity class and has to be annotated with @Entity and @RevisionEntity. You can add any property you like, and they will be stored in the REVINFO table together with the revision number and the timestamp.

import jakarta.persistence.Entity;
import jakarta.persistence.Table;

import org.hibernate.envers.DefaultRevisionEntity;
import org.hibernate.envers.RevisionEntity;

@Entity
@Table(name = "REVINFO")
@RevisionEntity(CustomRevisionEntityListener.class)
public class CustomRevisionEntity extends DefaultRevisionEntity {

  private static final long serialVersionUID = 1L;

  private String username;

  public String getUsername() {
    return this.username;
  }

  public void setUsername(String username) {
    this.username = username;
  }
}

CustomRevisionEntity.java

The listener we specify with @RevisionEntity must implement the RevisionListener interface. There is only one method we have to implement: newRevision. In this method, we need to fill in our additional properties, in this case, the username. We don't have to touch the revision number and timestamp, Envers sets them automatically.

import org.hibernate.envers.RevisionListener;

public class CustomRevisionEntityListener implements RevisionListener {

  @Override
  public void newRevision(Object revisionEntity) {
    CustomRevisionEntity customRevisionEntity = (CustomRevisionEntity) revisionEntity;
    customRevisionEntity.setUsername(CurrentUser.INSTANCE.get());
  }
}

CustomRevisionEntityListener.java

For this demo application, we store the logged in user into a ThreadLocal variable. The listener above extracts it with CurrentUser.INSTANCE.get() and we set the username with CurrentUser.INSTANCE.set(....)

public class CurrentUser {

  public static final CurrentUser INSTANCE = new CurrentUser();

  private static final ThreadLocal<String> storage = new ThreadLocal<>();

  public void logIn(String user) {
    storage.set(user);
  }

  public void logOut() {
    storage.remove();
  }

  public String get() {
    return storage.get();
  }
}

CurrentUser.java

With this configuration in place, the REVINFO table now contains a new field: username

custom revision properties

I copied these three classes straight from the Envers documentation. Visit this URL for more information: https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html#envers-revisionlog

Examples ¶

In this section, we are going insert, update, and delete some data and see how Envers stores the changes.

Revision 1: Insert ¶

First, the user "Alice" inserts a company and two employees.

    EntityManager em = JPAUtil.getEntityManagerFactory().createEntityManager();
    CurrentUser.INSTANCE.logIn("Alice");

    em.getTransaction().begin();
    Company company = new Company();
    company.setName("E Corp");
    company.setCity("New York City");
    company.setStreet(null);

    Set<Employee> employees = new HashSet<>();

    Employee employee = new Employee();
    employee.setCompany(company);
    employee.setLastName("Spencer");
    employee.setFirstName("Linda");
    employee.setStreet("High Street 123");
    employee.setCity("Newark");
    employees.add(employee);

    employee = new Employee();
    employee.setCompany(company);
    employee.setLastName("Ralbern");
    employee.setFirstName("Michael");
    employee.setStreet("57th Street");
    employee.setCity("New York City");
    employees.add(employee);

    company.setEmployees(employees);

    em.persist(company);
    em.getTransaction().commit();

Main.java

Notice that you don't have to call any special Envers methods. Just write standard JPA (or Hibernate) code. Behind the scenes, Envers listens for any update and automatically inserts the audit information into the database.

Envers inserted a new row into the REVINFO table with the timestamp and the username. Because we inserted the three entities in one transaction, only one REVINFO row was created.

Envers also inserted a new row into COMPANY_AUD for the new Company, REVTYPE of 0 denotes an INSERT operation. Moreover, Envers inserted two new rows into the EMPLOYEE_AUD table. Because in an insert, all properties changed, all _MOD fields contain the value true.

REVINFO
+----+---------------+----------+
| ID |   TIMESTAMP   | USERNAME |
+----+---------------+----------+
|  1 | 1564997410711 | Alice    |
+----+---------------+----------+

COMPANY_AUD
+----+-----+---------+--------+
| ID | REV | REVTYPE |  NAME  |
+----+-----+---------+--------+
|  1 |   1 |       0 | E Corp |
+----+-----+---------+--------+

EMPLOYEE_AUD
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
| ID | REV | REVTYPE |      CITY      | CITY_MOD | FIRSTNAME | FIRSTNAME_MOD | LASTNAME | LASTNAME_MOD |      STREET      | STREET_MOD | COMPANY_ID | COMPANY_MOD |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  1 |   1 |       0 | New York City  |     TRUE | Michael   |          TRUE | Ralbern  |         TRUE | 57th Street      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   1 |       0 | Newark         |     TRUE | Linda     |          TRUE | Spencer  |         TRUE | High Street 123  |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+

Revision 2: Update Company ¶

In the next transaction, "Bob" changes the name of the company from "E Corp" to "EEE Corp".

    CurrentUser.INSTANCE.logIn("Bob");

    em.getTransaction().begin();
    CriteriaBuilder cb = em.getCriteriaBuilder();
    CriteriaQuery<Company> q = cb.createQuery(Company.class);
    Root<Company> c = q.from(Company.class);
    ParameterExpression<String> p = cb.parameter(String.class);
    q.select(c).where(cb.equal(c.get("name"), p));

    TypedQuery<Company> query1 = em.createQuery(q);
    query1.setParameter(p, "E Corp");

    company = query1.getSingleResult();
    company.setName("EEE Corp");

    em.getTransaction().commit();

Main.java

Envers creates a new revision and inserts a new row into the COMPANY_AUD table. REVTYPE = 1 denotes an UPDATE operation.

REVINFO
+----+---------------+----------+
| ID |   TIMESTAMP   | USERNAME |
+----+---------------+----------+
|  1 | 1564997410711 | Alice    |
+----+---------------+----------+
|  2 | 1564997410849 | Bob      |
+----+---------------+----------+

COMPANY_AUD
+----+-----+---------+----------+
| ID | REV | REVTYPE |   NAME   |
+----+-----+---------+----------+
|  1 |   1 |       0 | E Corp   |
+----+-----+---------+----------+
|  1 |   2 |       1 | EEE Corp |
+----+-----+---------+----------+

Revision 3: New Employee ¶

"Bob" inserts a new employee: Janet Robinson

    CurrentUser.INSTANCE.logIn("Bob");

    em.getTransaction().begin();
    employee = new Employee();
    employee.setCompany(company);
    employee.setLastName("Robinson");
    employee.setFirstName("Janet");
    employee.setCity("Greenwich");
    employee.setStreet("Walsh Ln 10");
    company.getEmployees().add(employee);
    em.getTransaction().commit();

Main.java

REVINFO
+----+---------------+----------+
| ID |   TIMESTAMP   | USERNAME |
+----+---------------+----------+
|  1 | 1564997410711 | Alice    |
+----+---------------+----------+
|  2 | 1564997410849 | Bob      |
+----+---------------+----------+
|  3 | 1564997410858 | Bob      |
+----+---------------+----------+


EMPLOYEE_AUD
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
| ID | REV | REVTYPE |      CITY      | CITY_MOD | FIRSTNAME | FIRSTNAME_MOD | LASTNAME | LASTNAME_MOD |      STREET      | STREET_MOD | COMPANY_ID | COMPANY_MOD |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  1 |   1 |       0 | New York City  |     TRUE | Michael   |          TRUE | Ralbern  |         TRUE | 57th Street      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   1 |       0 | Newark         |     TRUE | Linda     |          TRUE | Spencer  |         TRUE | High Street 123  |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  3 |   3 |       0 | Greenwich      |     TRUE | Janet     |          TRUE | Robinson |         TRUE | Walsh Ln 10      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+

Revision 4: Update Employee ¶

"Alice" updates the street and city of the employee Linda Spencer

    CurrentUser.INSTANCE.logIn("Alice");

    em.getTransaction().begin();
    TypedQuery<Employee> query2 = createEmployeeQuery(em, "Linda", "Spencer");
    employee = query2.getSingleResult();
    employee.setStreet("101 W 91st St");
    employee.setCity("New York City");
    em.getTransaction().commit();

Main.java

REVINFO
+----+---------------+----------+
| ID |   TIMESTAMP   | USERNAME |
+----+---------------+----------+
|  1 | 1564997410711 | Alice    |
+----+---------------+----------+
|  2 | 1564997410849 | Bob      |
+----+---------------+----------+
|  3 | 1564997410858 | Bob      |
+----+---------------+----------+
|  4 | 1564997410873 | Alice    |
+----+---------------+----------+

Here we see that only CITY_MOD and STREET_MOD are set to true because these are the only two properties we changed in our code.

EMPLOYEE_AUD
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
| ID | REV | REVTYPE |      CITY      | CITY_MOD | FIRSTNAME | FIRSTNAME_MOD | LASTNAME | LASTNAME_MOD |      STREET      | STREET_MOD | COMPANY_ID | COMPANY_MOD |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  1 |   1 |       0 | New York City  |     TRUE | Michael   |          TRUE | Ralbern  |         TRUE | 57th Street      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   1 |       0 | Newark         |     TRUE | Linda     |          TRUE | Spencer  |         TRUE | High Street 123  |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  3 |   3 |       0 | Greenwich      |     TRUE | Janet     |          TRUE | Robinson |         TRUE | Walsh Ln 10      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   4 |       1 | New York City  |     TRUE | Linda     |         FALSE | Spencer  |        FALSE | 101 W 91st St    |       TRUE |          1 |       FALSE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+

Revision 5: Delete Employee ¶

Alice deletes the employee Michael Ralbern

    CurrentUser.INSTANCE.logIn("Alice");

    em.getTransaction().begin();
    TypedQuery<Employee> query3 = createEmployeeQuery(em, "Michael", "Ralbern");
    employee = query3.getSingleResult();
    employee.getCompany().getEmployees().remove(employee);
    em.remove(employee);
    em.getTransaction().commit();

Main.java

REVINFO
+----+---------------+----------+
| ID |   TIMESTAMP   | USERNAME |
+----+---------------+----------+
|  1 | 1564997410711 | Alice    |
+----+---------------+----------+
|  2 | 1564997410849 | Bob      |
+----+---------------+----------+
|  3 | 1564997410858 | Bob      |
+----+---------------+----------+
|  4 | 1564997410873 | Alice    |
+----+---------------+----------+
|  5 | 1564997410892 | Alice    |
+----+---------------+----------+

Here we see the REVTYPE 2, which denotes a DELETE operation. For delete operations, all properties are set to NULL.

EMPLOYEE_AUD
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
| ID | REV | REVTYPE |      CITY      | CITY_MOD | FIRSTNAME | FIRSTNAME_MOD | LASTNAME | LASTNAME_MOD |      STREET      | STREET_MOD | COMPANY_ID | COMPANY_MOD |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  1 |   1 |       0 | New York City  |     TRUE | Michael   |          TRUE | Ralbern  |         TRUE | 57th Street      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   1 |       0 | Newark         |     TRUE | Linda     |          TRUE | Spencer  |         TRUE | High Street 123  |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  3 |   3 |       0 | Greenwich      |     TRUE | Janet     |          TRUE | Robinson |         TRUE | Walsh Ln 10      |       TRUE |          1 |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  2 |   4 |       1 | New York City  |     TRUE | Linda     |         FALSE | Spencer  |        FALSE | 101 W 91st St    |       TRUE |          1 |       FALSE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+
|  1 |   5 |       2 | NULL           |     TRUE | NULL      |          TRUE | NULL     |         TRUE | NULL             |       TRUE |       NULL |        TRUE |
+----+-----+---------+----------------+----------+-----------+---------------+----------+--------------+------------------+------------+------------+-------------+

Queries ¶

Storing audit/version information is one side of the story, but we also need a way to access this information when we need it. For this purpose, Envers provides several methods to query the audit tables.

The main entry point to the query methods is the class AuditReader. You create an instance with AuditReaderFactory.get and pass the EntityManager instance as the argument.

    EntityManager em = JPAUtil.getEntityManagerFactory().createEntityManager();
    AuditReader reader = AuditReaderFactory.get(em);

Setup ¶

Tables ¶

Custom Revision Entity ¶

Examples ¶

Revision 1: Insert ¶

Revision 2: Update Company ¶

Revision 3: New Employee ¶

Revision 4: Update Employee ¶

Revision 5: Delete Employee ¶

Queries ¶

AuditQuery ¶