Getting Started Hibernate Envers
In any application, auditing means that we track and log every change in all business objects, i.e, track each insert, update and delete operations.
Basically it involves tracking three things -
- What operation was performed?
- Who did it?
- When was it done?
Auditing helps us in maintaining history records, which can later help us in tracking user activities.
Hibernate Envers is a project that seeks to make auditing persistent classes simple. You only need to annotate your persistent class or a few of its attributes with @Audited if you wish to audit them. A table will be generated that contains the history of the changes made to each audited entity. Then, retrieving and analysing past data won’t take much work.
Process To Get Started off with Envers
- The first and the foremost step is to have the dependency in place for the application
implementation group: 'org.springframework.data', name: 'spring-data-envers', version: '2.6.2
- Following this we will need a set of well defined persistent entities in the application who’s data is crucial and all operations on these entities will need to be verified at any point in time. For example -
@Entity @Table(name = "user") public class User { //list of attributes //getters //setters }
-
In order to enable auditing for this table we need to add the annotation
@Audited
on the table that is required to be tracked. This annotation will generate the audit table in the database that will record all the changes done to this entity. You can either have this annotation at entity level, which means that changes to all the attributes of that entity will be tracked, or you can have it at the attribute level which means that only that attribute changes will be tracked. For attributes that you do not require to be tracked, we can have the@NotAudited
annotation on the attribute. - The
@Audited
has a flag ( withModifiedFlag ) which could be toggled to note the change in values to the attribute in the audit table (all attributes if at entity level, or only specified attribute if at attribute level). This flag is of boolean type which is true for an attribute when the value for that attribute of that entity has changed else false.@Entity @Audited //Entity level Auditing @Table(name = "user") public class User { //list of attributes //getters //setters } // (OR) @Entity @Table(name = "user") public class User { @Audited //Attribute level audting private String name; //list of attributes //getters //setters }
- To capture who created the record and when the record was created we need a set of attributes, for which JPA provides a way to capture these values using custom auditing annotations. In order for the auditing annotations to work we need to enable the entity to listen to events that change the records in the table. The attributes required are as follows -
- createdBy
- createdDate
- modifiedBy
- modifiedDate
- These annotations (
@CreatedBy
,@LastModifiedBy
,@CreatedDate
,@LastModifiedDate
) help to capture the auditor from security context of Spring and the time of change.@Entity @Audited @EntityListeners(AuditingEntityListener.class) // enables the entity to listen to any audits @Table(name = "user") public class User { //list of attributes @CreatedBy private String createdBy; @LastModifiedBy private String lastModifiedBy; @CreatedDate private Date createdDate; @LastModifiedDate private Date lastModifiedDate; //getters //setters }
- We can write custom AuditAwareListeners in order to capture the auditor name using custom logic.
public class CustomAuditAwareListener implements AuditorAware<String> { @Override public Optional<String> getCurrentAuditor() { //logic to retrieve username using custom logic } }
Configuration
Since Envers generates some entities and maps them to tables, it is possible to set the names of the fields that are generated as well as the prefix and suffix that are added to the entity name to construct an audit table for an entity.
The list of properties that could be edited are as follows -
Property Name | Default Value | Description |
---|---|---|
org.hibernate.envers.audit_table_prefix | String that will be prepended to the name of an audited entity to create the name of the entity, that will hold audit information | |
org.hibernate.envers.audit_table_suffix | _AUD | String that will be appended to the name of an audited entity to create the name of the entity, that will hold audit information. If you audit an entity with a table name Person, in the default setting Envers will generate a Person_AUD table to store historical data. |
org.hibernate.envers.revision_field_name | REV | Name of a field in the audit entity that will hold the revision number. |
org.hibernate.envers.revision_type_field_name | REVTYPE | Name of a field in the audit entity that will hold the type of the revision (currently, this can be: add, mod, del). |
org.hibernate.envers.revision_on_collection_change | true | Should a revision be generated when a not-owned relation field changes (this can be either a collection in a one-to-many relation, or the field using “mappedBy” attribute in a one-to-one relation). |
org.hibernate.envers.do_not_audit_optimistic_locking_field | true | When true, properties to be used for optimistic locking, annotated with @Version , will be automatically not audited (their history won’t be stored; it normally doesn’t make sense to store it). |
org.hibernate.envers.store_data_at_delete | false | Should the entity data be stored in the revision when the entity is deleted (instead of only storing the id and all other properties as null). This is not normally needed, as the data is present in the last-but-one revision. Sometimes, however, it is easier and more efficient to access it in the last revision (then the data that the entity contained before deletion is stored twice). |
org.hibernate.envers.default_schema | null (same as normal tables) | The default schema name that should be used for audit tables. Can be overriden using the @AuditTable(schema="...") annotation. If not present, the schema will be the same as the schema of the normal tables. |
org.hibernate.envers.default_catalog | null (same as normal tables) | The default catalog name that should be used for audit tables. Can be overriden using the @AuditTable(catalog="...") annotation. If not present, the catalog will be the same as the catalog of the normal tables. |
The required properties can be set in the application.yml
file and the audit entities generated will be user driven and more meaningful as per the industry standards.
We will need to even enable the application to support envers repository and JPA Auditing fo which we will need to configure as follows:
@SpringBootApplication
@EnableJpaAuditing(auditorAwareRef="auditorAware") //auditorAwareRef points to the name of the bean created for custom auditing listener
@EnableEnversRepositories(repositoryFactoryBeanClass = EnversRevisionRepositoryFactoryBean.class)
public class Application {
public static void main(String[] args) {
SpringApplication.run(FleetAdminApplication.class, args);
}
@Bean //can be defined in a config
public AuditorAware<String> auditorAware() {
return new CustomAuditAwareListener();
}
}
Querying Data
Now that we have the entire history of all types of operations that have taken place on the audited entities, we will need to find a way to query the data in such a way that provides a meaningful information and quickly deduct what changes have been done, what data have been modified and to what was the data modified to.
We will make use of the SQL lag()
function for this purpose that helps provide the above mentioned data to us, making it useful for any business fraction of the company to read and identify the changes.
An example SQL query is as follows:
SELECT id, value, lag(value) over (order by id) as previous_value FROM table_name where id=:id;
We can provide an API that lists the changes that have been made by creating a native query in a similar fashion. We need to create a POJO that contains all the information that we need and create a mapping with the results of the native query and return a meningful response as part of a UI call which would make more sense to a User to understand the auditing done by far on the entity.
@NamedNativeQuery(
name = "user_history_query",
query ="SELECT id, tech, lag(tech) over (order by rev) as previous_tech, name, lag(name) over (order by rev) as previous_name, rev, revtype FROM user_aud where id=:id",
resultSetMapping = "user_history_dto"
)
@SqlResultSetMapping(
name = "user_history_dto",
classes = @ConstructorResult(
targetClass = AuditEntity.class,
columns = {
@ColumnResult(name = "id", type = Long.class),
@ColumnResult(name = "tech", type = String.class),
@ColumnResult(name = "previous_tech", type = String.class),
@ColumnResult(name = "name", type = String.class),
@ColumnResult(name = "previous_name", type = String.class),
@ColumnResult(name = "rev", type = Integer.class),
@ColumnResult(name = "revtype", type = Integer.class)
}
)
)
@Entity
@Audited
@Table(name = "user")
public class User {
//list of attributes
//getters
//setters
}
//(Repository Crud function)
public class Repositoy {
@Query(name = "user_history_query", nativeQuery = true)
List<AuditEntity> findUserHistory(@Param("id") Long id);
}
//(POJO you wish to map the results to)
public class AuditEntity {
private Long id;
private String tech;
private String previousTech;
private String name;
private String previousName;
private int rev;
private int revType;
//constructors
//getters
//setters
}
Screenshots
-
User Table
image: /assets/hibernate-envers/user-table.png -
Revision Info Table
image: /assets/hibernate-envers/rev-info-table.png -
User Audit Table
image: /assets/hibernate-envers/user-audit-table.png -
Query Fetching changes done for a particular user
image: /assets/hibernate-envers/query.png