Chapter 11. Migration from Envers standalone

11.1. Changes to code
11.2. Changes to configuration
11.3. Changes to the revision entity

With the inclusion of Envers as a Hibernate module, some of the public API and configuration defaults changed. In general, "versioning" is renamed to "auditing" (to avoid confusion with the annotation used for indicating an optimistic locking field - @Version).

Because of changing some configuration defaults, there should be no more problems using Envers out-of-the-box with Oracle and other databases, which don't allow tables and field names to start with "_".

11.1. Changes to code

Public API changes involve changing "versioning" to "auditing". So, @Versioned became @Audited; @VersionsTable became @AuditTable and so on.

Also, the query interface has changed slightly, mainly in the part for specifying restrictions, projections and order. Please refer to the Javadoc for further details.

11.2. Changes to configuration

First of all, the name of the event listener changed. It is now named org.hibernate.envers.event.AuditEventListener, instead of org.jboss.envers.event.VersionsEventListener. So to make Envers work, you will have to change these settings in your persistence.xml or Hibernate configuration.

Secondly, the names of the audit (versions) tables and additional auditing (versioning) fields changed. The default suffix added to the table name is now _AUD, instead of _versions. The name of the field that holds the revision number, and which is added to each audit (versions) table, is now REV, instead of _revision. Finally, the name of the field that holds the type of the revision, is now REVTYPE, instead of _rev_type.

If you have a schema generated with the old version of Envers, you will have to set those properties, to use the new version of Envers without problems:

<persistence-unit ...>
<provider>org.hibernate.ejb.HibernatePersistence</provider>
<class>...</class>
<properties>
   <property name="hibernate.dialect" ... />
   <!-- other hibernate properties -->

   <!-- Envers listeners -->

   <property name="org.hibernate.envers.auditTableSuffix" value="_versions" />
   <property name="org.hibernate.envers.revisionFieldName" value="_revision" />
   <property name="org.hibernate.envers.revisionTypeFieldName" value="_rev_type" />
   <!-- other envers properties -->
</properties>
</persistence-unit>

The org.hibernate.envers.doNotAuditOptimisticLockingField property is now by default true, instead of false. You probably never would want to audit the optimistic locking field. Also, the org.hibernate.envers.warnOnUnsupportedTypes configuraiton option was removed. In case you are using some unsupported types, use the @NotAudited annotation.

See Chapter 3, Configuration for details on the configuration and a description of the configuration options.

11.3. Changes to the revision entity

This section applies only if you don't have a custom revision entity. The name of the revision entity generated by default changed, so if you used the default one, you'll have to add a custom revision entity, and map it to the old table. Here's the class that you have to create:

package org.hibernate.envers.example;

import org.hibernate.envers.RevisionNumber;
import org.hibernate.envers.RevisionTimestamp;
import org.hibernate.envers.RevisionEntity;

import javax.persistence.Id;
import javax.persistence.GeneratedValue;
import javax.persistence.Entity;
import javax.persistence.Column;
import javax.persistence.Table;

@Entity
@RevisionEntity
@Table(name="_revisions_info")
public class ExampleRevEntity {
    @Id
    @GeneratedValue
    @RevisionNumber
    @Column(name="revision_id")
    private int id;

    @RevisionTimestamp
    @Column(name="revision_timestamp")
    private long timestamp;

    // Getters, setters, equals, hashCode ...
}