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-enversas a dependency, and -
annotate your entities or their fields with the
@Auditedannotation.
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.