5. Tutorial Using Envers

Objectives

• Annotate an entity as historical

• Configure Envers

• Use the Envers APIs to view and analyze historical data

5.1. persistence.xml

This file was discussed in the JPA tutorial in persistence.xml, and is essentially the same here.

5.2. The annotated entity Java class

Again, the entity is largely the same as in The annotated entity Java class. The major difference is the addition of the @org.hibernate.envers.Audited annotation, which tells Envers to automatically track changes to this entity.

5.3. Example code

The code saves some entities, makes a change to one of the entities and then uses the Envers API to pull back the initial revision as well as the updated revision. A revision refers to a historical snapshot of an entity.

Example 14. Using the org.hibernate.envers.AuditReader

public void testBasicUsage() {
    ...
    AuditReader reader = AuditReaderFactory.get( entityManager );
    Event firstRevision = reader.find( Event.class, 2L, 1 );
    ...
    Event secondRevision = reader.find( Event.class, 2L, 2 );
    ...
}

We see that an org.hibernate.envers.AuditReader is obtained from the org.hibernate.envers.AuditReaderFactory which wraps the javax.persistence.EntityManager.

Next, the find method retrieves specific revisions of the entity. The first call says to find revision number 1 of Event with id 2. The second call says to find revision number 2 of Event with id 2.

5.4. Take it further!

Practice Exercises

• Provide a custom revision entity to additionally capture who made the changes.

• Write a query to retrieve only historical data which meets some criteria. Use the User Guide to see how Envers queries are constructed.

• Experiment with auditing entities which have various forms of relationships (many-to-one, many-to-many, etc). Try retrieving historical versions (revisions) of such entities and navigating the object tree.