How to use Hibernate Envers to audit data including username information

Recently, I have been working in a project which it was required to audit all the database transactions including the username. For this purpose I have been using Hibernate ORM Envers, which aims to enable easy auditing/versioning of persistent classes.

In order to show how to use Hibernate Envers in this post I have built a sample project, based on this Spring boot JPA project. Spring Boot makes it easy to create stand-alone, production-grade Spring based Applications that you can “just run”. In this case it is very handy because it includes: an embedded tomcat,’starter’ POMs to simplify your Maven configuration, and REST web services ready to use.

This post is structure in 5 simple steps, neverthelesss, the last 2 steps are only useful if you would like to add the username (or any other information) to your revisions.

1. Configure Hibernate envers

2. Audit tables

3. Read Revisions

4. Add username information to each revision

5. Read Revision including username

 

1.Configure Hibernate Envers

First of all, you will need to add the Hibernate Envers dependency into your project. As I am using Maven, for managing my dependecies, all I need to do is add the dependency into my pom file:

 

[xml]

org.hibernate
hibernate-envers
4.3.10.Final

[/xml]

2. Audit Tables

In order to be able to audit your entity tables, you only need to have an entity with a primary key and use the annotation @Audited. You can use the annotation @Audited either at the top of the class (that will audit all the fields of the class) or only in the fields that you would like to audit.

Once you add the @Audited annotation you will see that a new table with the suffix “_AUD” will be created for each entity. Also you will find that a new table called REVINFO, which contains all the revisions information, has been created. By default this table will only contain the id of the revision and the timestamp, although on section 4 and 5 I will show you how to add more data to this table, like the username.

Here is an example of an audited java class:

[java]
@Entity
@Audited
public class City implements Serializable {

private static final long serialVersionUID = 1L;

@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Long id;

@Column
private String name;

@Column
private String state;

@Column
private String country;

@Column
private String map;

//getters and setters

}
[/java]

In this case we will automatically have in our database 2 tables, one called City and another one called City_AUD which will include all the city fields plus a revision identifier and a revision type (creation, update, delete).

3. Read Revisions

If you have already configured Hibernate Envers into your project, now every time that you add or update an object into the database you will see that another row will be added to the audited table. Now we would like to get the different revisions for a specific object.

Hibernate Envers includes a class called Audit Reader which makes easier to read any revision. You only need to initialize it with an entity manager. Then you can find any revision using the find method:

AuditReader reader = AuditReaderFactory.get(entityManager);
reader.find(class, object id, revision id);

Here is an example of creating and updating a City object and then check the revisions:

[java]
final static String WRONG_STATE = “Wrong State”;
final static String OXFORDSHIRE_STATE = “Oxfordshire”;

@PersistenceContext
private EntityManager entityManager;

@Autowired
private Transactor transactor;

long cityId;

@Test
public void testSaveAndUpdateCity(){
transactor.perform(() -> {
addCity();
});
transactor.perform(() -> {
updateCity(cityId);
});

transactor.perform(() -> {
checkRevisions(cityId);
});

}

private void addCity(){
City city = new City(“Oxford”, “UK”);
city.setState(WRONG_STATE);
entityManager.persist(city);
entityManager.flush();
cityId = city.getId();
}

private void updateCity(long cityId) {
City updateCity = entityManager.find(City.class, cityId);
updateCity.setState(OXFORDSHIRE_STATE);
entityManager.persist(updateCity);
entityManager.flush();
}

private void checkRevisions(long cityId){
AuditReader reader = AuditReaderFactory.get(entityManager);

City city_rev1 = reader.find(City.class, cityId, 1);
assertThat(city_rev1.getState(), is(WRONG_STATE));

City city_rev2 = reader.find(City.class, cityId, 2);
assertThat(city_rev2.getState(), is(OXFORDSHIRE_STATE));
}

[/java]

Transactor is a custom class for running a piece of code in a single transaction. As you can see in the checkRevisions function, we are using the AuditReader for getting the different revisions for the same city.

The AuditReader has more methods which will make you easier to look for any revision, please have a look to the api for more information.

4. Add username information to each revision

If you have followed the first 3 steps, you should be able to audit and read any revision, and for some projects that’s all you need. Nevertheless, in other cases you will need to audit more information like the username of the person who did the transaction. For this purpose you will need to implement this 2 classes:

• Revision Entity
• Revision Listener

The Revision entity is the class which contains the data that you would like to audit in each transaction. It is mandatory that this class contains a revision number and a revision timestamp, either you can add these 2 fields manually or you can extend the DefaultRevisionEntity class which already contains them.

Here is an example of my revision entity which extends DefaultRevisionEntity and have an attribute for the username:

[java]
@Entity
@RevisionEntity(UserRevisionListener.class)
public class UserRevEntity extends DefaultRevisionEntity {

private String username;

public String getUsername() { return username; }
public void setUsername(String username) { this.username = username; }
}
[/java]

Note that the class contains the @RevisionEntity(UserRevisionListener.class) annotation. The revision listener is the class where you need to specify how to populate the additional data into the revision. This class needs to implement the RevisionListener interface which has only one method called newRevision.

Let’s see an example:

[java]
public class UserRevisionListener implements RevisionListener {

public final static String USERNAME = “Suay”;

@Override
public void newRevision(Object revisionEntity) {
UserRevEntity exampleRevEntity = (UserRevEntity) revisionEntity;
exampleRevEntity.setUsername(USERNAME);
}
}
[/java]

In this example, I am auditing any transaction with the same username (“SUAY”), but in a real environment you should get the username from a User service or any other method that you use to log the users.

5. Read Revision including username

For getting the user information, I run a query using the method “forRevisionsOfEntity” which will return a triplet of objects: the entity, the entity revision information and at last the revision type. Only the second object is the one that I am interested because it containes the username information. Please have a look to the following example:

[java]
@Test
public void testUserRevisions() throws Exception{
transactor.perform(() -> {
addCity();
});
transactor.perform(() -> {
checkUsers();
});
}

private void checkUsers(){
AuditReader reader = AuditReaderFactory.get(entityManager);
AuditQuery query = reader.createQuery()
.forRevisionsOfEntity(City.class, false, false);

//This return a list of array triplets of changes concerning the specified revision.
// The array triplet contains the entity, entity revision information and at last the revision type.
Object[] obj = (Object[]) query.getSingleResult();

//In this case we want the entity revision information object, which is the second object of the array.
UserRevEntity userRevEntity = (UserRevEntity) obj[1];

String user = userRevEntity.getUsername();
assertThat(user, is(UserRevisionListener.USERNAME));

}
[/java]

Running the sample project

All the code used in this post is available in github.

If you would like to run the project, you just need to run the main methon in SampleDataJpaApplication.

The project includes a H2 console so you can see on any browser your database. Try:

1) go to http://localhost:8080/console

2) In the login form, please add the following information:

JDBC URL: jdbc:h2:mem:testdb
username: sa
password:
(empty password)

3) Now you should see the followin database structure: