Hibernate ORM

Envers

Envers is an extension to Hibernate ORM that provides an easy way to add auditing / versioning for entities.

Features

Envers provides:

  • auditing for all O/R mappings defined by the JPA specification, along with some mappings specific to Hibernate ORM,

  • logged change data for each revision using a revision entity, and

  • querying for historical snapshots of an entity and its associations.

Much like source code version control, Envers uses the concept of revisions. A revision identifies the full set of changes to audited entity fields which occurred within a given transaction.

Overview

In order for Envers to build the necessary historical audit tables and store the change data for audited entities and their associations, you’ll need to:

  • add org.hibernate.orm:hibernate-envers as a dependency, and

  • annotate your entities or their fields with the @Audited annotation.

The @Audited annotation just specifies that a field should be audited:

@Entity
public class Person {
    @Id
    @GeneratedValue
    private Integer id;

    @Audited
    private String name;

    @Audited
    private String surname;

    @Audited
    @ManyToOne
    private Address address;
}

Then the AuditReader interface allows us to:

  • query an entity at a given revision and retrieve a partial view of the state of that entity at that specific revision,

  • access lists of revisions associated with a given entity type or restricted by a given date range, and

  • obtain revision metadata specifying when a change occurred, along with additional custom attributes you have stored on the revision entity based on your application-specific needs.

Getting started

The Getting Started guide for Hibernate ORM includes an example using Envers.

Documentation is available in the Hibernate ORM User Guide.

Back to top