Hibernate ORM

Envers

The Envers module is a core Hibernate model that works both with Hibernate and JPA. In fact, you can use Envers anywhere Hibernate works whether that is standalone, inside WildFly or JBoss AS, Spring, Grails, etc.

The Envers module aims to provide an easy auditing / versioning solution for entity classes.

Features

  • Auditing of all mappings defined by the JPA specification

  • Auditing some Hibernate mappings that extend JPA, e.g. custom types and collections/maps of "simple" types like Strings, Integers.

  • Logging data for each revision using a "revision entity"

  • Querying historical snapshots of an entity and its associations

Quick Intro

In order for Envers to build the necessary historical audit tables and store the changes made to audited entities and their associations, the following is all that is required to get started:

  • Add the hibernate-envers dependency to your classpath.

  • Annotate your entity or entity properties with the @Audited annotation.

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

A simple example

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

    @Audited
    private String name;

    @Audited
    private String surname;

    @Audited
    @ManyToOne
    private Address address;
}

You can find a step-by-step Envers tutorial in the Getting started guide.

Comprehensive documentation is available in the User’s guide.

Revisioning

Much like source code version control, Envers uses a concept of revisions.

A revision identifies a collection of changes to entities and their associations for all audited attributes that occured within the boundary of a transaction. These revisions are global and numeric.

The AuditReader API provides numerous ways to query for entities at particular revisions and retrieve a partial view of what that entity looked like at that specific revision. It also allows you to get access to lists of revisions associated with an entity type or restricted by a date range. The API also provides a way to get the revision metadata so you can know when a change occured plus any additional custom attributes you may have stored on the revision entity based on your implementation needs.

Back to top