[[tutorial_envers]]
== Tutorial Using Envers

NOTE: This tutorial is located within the download bundle under `envers/`.

.Objectives
- [*] Annotate an entity as historical
- [*] Configure Envers
- [*] Use the Envers APIs to view and analyze historical data


[[hibernate-gsg-tutorial-envers-config]]
=== persistence.xml

This file was discussed in the JPA tutorial in <<hibernate-gsg-tutorial-jpa-config>>, and is essentially the same here.


[[hibernate-gsg-tutorial-envers-entity]]
=== The annotated entity Java class

Again, the entity is largely the same as in <<hibernate-gsg-tutorial-jpa-entity>>.  The major difference is the
addition of the `@org.hibernate.envers.Audited` annotation, which tells Envers to automatically track changes to this
entity.


[[hibernate-gsg-tutorial-envers-test]]
=== 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.


[[hibernate-gsg-tutorial-envers-test-api]]
.Using the `org.hibernate.envers.AuditReader`
====
[source, JAVA]
----
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.


[[hibernate-gsg-tutorial-annotations-further]]
=== 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.