21. Envers

21.1. Basics

To audit changes that are performed on an entity, you only need two things:

• the hibernate-envers jar on the classpath,

• an @Audited annotation on the entity.

And that’s all. You can create, modify and delete the entities as always.

If you look at the generated schema for your entities, or at the data persisted by Hibernate, you will notice that there are no changes. However, for each audited entity, a new table is introduced - entity_table_AUD, which stores the historical data, whenever you commit a transaction.

Considering we have a Customer entity, when annotating it with the Audited annotation, Hibernate is going to generate the following tables using the hibernate.hbm2ddl.auto schema tool:

Example 652. Basic Envers entity mapping

@Audited
@Entity(name = "Customer")
public static class Customer {
    @Id
    private Long id;
    private String firstName;
    private String lastName;
    @Temporal( TemporalType.TIMESTAMP )
    @Column(name = "created_on")
    @CreationTimestamp
    private Date createdOn;
    //Getters and setters are omitted for brevity
}

create table Customer (
    id bigint not null,
    created_on timestamp,
    firstName varchar(255),
    lastName varchar(255),
    primary key (id)
)
create table Customer_AUD (
    id bigint not null,
    REV integer not null,
    REVTYPE tinyint,
    created_on timestamp,
    firstName varchar(255),
    lastName varchar(255),
    primary key (id, REV)
)
create table REVINFO (
    REV integer generated by default as identity,
    REVTSTMP bigint,
    primary key (REV)
)
alter table Customer_AUD
   add constraint FK5ecvi1a0ykunrriib7j28vpdj
   foreign key (REV)
   references REVINFO

Instead of annotating the whole class and auditing all properties, you can annotate only some persistent properties with @Audited. This will cause only these properties to be audited.

Now, considering the previous Customer entity, let’s see how Envers auditing works when inserting, updating, and deleting the entity in question.

Example 653. Auditing the entity INSERT operation

Customer customer = new Customer();
customer.setId( 1L );
customer.setFirstName( "John" );
customer.setLastName( "Doe" );
entityManager.persist( customer );

insert
into
    Customer
    (created_on, firstName, lastName, id)
values
    (?, ?, ?, ?)
-- binding parameter [1] as [TIMESTAMP] - [Mon Jul 24 17:21:32 EEST 2017]
-- binding parameter [2] as [VARCHAR]   - [John]
-- binding parameter [3] as [VARCHAR]   - [Doe]
-- binding parameter [4] as [BIGINT]    - [1]
insert
into
    REVINFO
    (REV, REVTSTMP)
values
    (?, ?)
-- binding parameter [1] as [BIGINT]    - [1]
-- binding parameter [2] as [BIGINT]    - [1500906092803]
insert
into
    Customer_AUD
    (REVTYPE, created_on, firstName, lastName, id, REV)
values
    (?, ?, ?, ?, ?, ?)
-- binding parameter [1] as [INTEGER]   - [0]
-- binding parameter [2] as [TIMESTAMP] - [Mon Jul 24 17:21:32 EEST 2017]
-- binding parameter [3] as [VARCHAR]   - [John]
-- binding parameter [4] as [VARCHAR]   - [Doe]
-- binding parameter [5] as [BIGINT]    - [1]
-- binding parameter [6] as [INTEGER]   - [1]

Example 654. Auditing the entity UPDATE operation

Customer customer = entityManager.find( Customer.class, 1L );
customer.setLastName( "Doe Jr." );

update
    Customer
set
    created_on=?,
    firstName=?,
    lastName=?
where
    id=?
-- binding parameter [1] as [TIMESTAMP] - [2017-07-24 17:21:32.757]
-- binding parameter [2] as [VARCHAR]   - [John]
-- binding parameter [3] as [VARCHAR]   - [Doe Jr.]
-- binding parameter [4] as [BIGINT]    - [1]
insert
into
    REVINFO
    (REV, REVTSTMP)
values
    (?, ?)
-- binding parameter [1] as [BIGINT]    - [2]
-- binding parameter [2] as [BIGINT]    - [1500906092853]
insert
into
    Customer_AUD
    (REVTYPE, created_on, firstName, lastName, id, REV)
values
    (?, ?, ?, ?, ?, ?)
-- binding parameter [1] as [INTEGER]   - [1]
-- binding parameter [2] as [TIMESTAMP] - [2017-07-24 17:21:32.757]
-- binding parameter [3] as [VARCHAR]   - [John]
-- binding parameter [4] as [VARCHAR]   - [Doe Jr.]
-- binding parameter [5] as [BIGINT]    - [1]
-- binding parameter [6] as [INTEGER]   - [2]

Example 655. Auditing the entity DELETE operation

Customer customer = entityManager.getReference( Customer.class, 1L );
entityManager.remove( customer );

delete
from
    Customer
where
    id = ?
-- binding parameter [1] as [BIGINT]    - [1]
insert
into
    REVINFO
    (REV, REVTSTMP)
values
    (?, ?)
-- binding parameter [1] as [BIGINT]    - [3]
-- binding parameter [2] as [BIGINT]    - [1500906092876]
insert
into
    Customer_AUD
    (REVTYPE, created_on, firstName, lastName, id, REV)
values
    (?, ?, ?, ?, ?, ?)
-- binding parameter [1] as [INTEGER]   - [2]
-- binding parameter [2] as [TIMESTAMP] - [null]
-- binding parameter [3] as [VARCHAR]   - [null]
-- binding parameter [4] as [VARCHAR]   - [null]
-- binding parameter [5] as [BIGINT]    - [1]
-- binding parameter [6] as [INTEGER]   - [3]

The REVTYPE column value is taken from the RevisionType Enum.

The audit (history) of an entity can be accessed using the AuditReader interface, which can be obtained by having an open EntityManager or Session via the AuditReaderFactory.

Example 656. Getting a list of revisions for the Customer entity

List<Number> revisions = doInJPA( this::entityManagerFactory, entityManager -> {
     return AuditReaderFactory.get( entityManager ).getRevisions(
        Customer.class,
        1L
    );
} );

select
    c.REV as col_0_0_
from
    Customer_AUD c
cross join
    REVINFO r
where
    c.id = ?
    and c.REV = r.REV
order by
    c.REV asc
-- binding parameter [1] as [BIGINT] - [1]

Using the previously fetched revisions, we can now inspect the state of the Customer entity at that particular revision:

Example 657. Getting the first revision for the Customer entity

Customer customer = (Customer) AuditReaderFactory
.get( entityManager )
.createQuery()
.forEntitiesAtRevision( Customer.class, revisions.get( 0 ) )
.getSingleResult();
assertEquals("Doe", customer.getLastName());

select
    c.id as id1_1_,
    c.REV as REV2_1_,
    c.REVTYPE as REVTYPE3_1_,
    c.created_on as created_4_1_,
    c.firstName as firstNam5_1_,
    c.lastName as lastName6_1_
from
    Customer_AUD c
where
    c.REV = (
        select
            max( c_max.REV )
        from
            Customer_AUD c_max
        where
            c_max.REV <= ?
            and c.id = c_max.id
    )
    and c.REVTYPE <> ?
-- binding parameter [1] as [INTEGER] - [1]
-- binding parameter [2] as [INTEGER] - [2]

When executing the aforementioned SQL query, there are two parameters:

revision_number

The first parameter marks the revision number we are interested in or the latest one that exists up to this particular revision.

revision_type

The second parameter specifies that we are not interested in DEL RevisionType so that deleted entries are filtered out.

The same goes for the second revision associated with the UPDATE statement.

Example 658. Getting the second revision for the Customer entity

Customer customer = (Customer) AuditReaderFactory
.get( entityManager )
.createQuery()
.forEntitiesAtRevision( Customer.class, revisions.get( 1 ) )
.getSingleResult();
assertEquals("Doe Jr.", customer.getLastName());

For the deleted entity revision, Envers throws a NoResultException since the entity was no longer valid at that revision.

Example 659. Getting the third revision for the Customer entity

try {
    Customer customer = (Customer) AuditReaderFactory
    .get( entityManager )
    .createQuery()
    .forEntitiesAtRevision( Customer.class, revisions.get( 2 ) )
    .getSingleResult();
    fail("The Customer was deleted at this revision: " + revisions.get( 2 ));
}
catch (NoResultException expected) {
}

You can use the forEntitiesAtRevision(Class<T> cls, String entityName, Number revision, boolean includeDeletions) method to get the deleted entity revision so that, instead of a NoResultException, all attributes, except for the entity identifier, are going to be null.

Example 660. Getting the third revision for the Customer entity without getting a NoResultException

Customer customer = (Customer) AuditReaderFactory
.get( entityManager )
.createQuery()
.forEntitiesAtRevision(
    Customer.class,
    Customer.class.getName(),
    revisions.get( 2 ),
    true )
.getSingleResult();
assertEquals( Long.valueOf( 1L ), customer.getId() );
assertNull( customer.getFirstName() );
assertNull( customer.getLastName() );
assertNull( customer.getCreatedOn() );

See the Javadocs for details on other functionality offered.

21.2. Configuration Properties

It is possible to configure various aspects of Hibernate Envers behavior, such as table names, etc.

**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 and that will hold audit information.

**org.hibernate.envers.audit_table_suffix** (default: _AUD)

String that will be appended to the name of an audited entity to create the name of the entity and 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** (default: REV)

Name of a field in the audit entity that will hold the revision number.

**org.hibernate.envers.revision_type_field_name** (default: 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** (default: 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** (default: true )

When true, properties to be used for optimistic locking, annotated with @Version, will not be automatically audited (their history won’t be stored; it normally doesn’t make sense to store it).

**org.hibernate.envers.store_data_at_delete** (default: 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** (default: null - same schema as the table being audited)

The default schema name that should be used for audit tables.

Can be overridden using the @AuditTable( schema = "…​" ) annotation.

If not present, the schema will be the same as the schema of the table being audited.

**org.hibernate.envers.default_catalog** (default: null - same catalog as the table being audited)

The default catalog name that should be used for audit tables.

Can be overridden using the @AuditTable( catalog = "…​" ) annotation.

If not present, the catalog will be the same as the catalog of the normal tables.

**org.hibernate.envers.audit_strategy**(default: org.hibernate.envers.strategy.DefaultAuditStrategy )

The audit strategy that should be used when persisting audit data. The default stores only the revision, at which an entity was modified.

An alternative, the org.hibernate.envers.strategy.ValidityAuditStrategy stores both the start revision and the end revision. Together these define when an audit row was valid, hence the name ValidityAuditStrategy.

**org.hibernate.envers.audit_strategy_validity_end_rev_field_name** (default: REVEND)

The column name that will hold the end revision number in audit entities. This property is only valid if the validity audit strategy is used.

**org.hibernate.envers.audit_strategy_validity_store_revend_timestamp**(default: false )

Should the timestamp of the end revision be stored, until which the data was valid, in addition to the end revision itself. This is useful to be able to purge old Audit records out of a relational database by using table partitioning.

Partitioning requires a column that exists within the table. This property is only evaluated if the ValidityAuditStrategy is used.

**org.hibernate.envers.audit_strategy_validity_revend_timestamp_field_name**(default: REVEND_TSTMP )

Column name of the timestamp of the end revision until which the data was valid. Only used if the ValidityAuditStrategy is used, and org.hibernate.envers.audit_strategy_validity_store_revend_timestamp evaluates to true.

**org.hibernate.envers.use_revision_entity_with_native_id** (default: true )

Boolean flag that determines the strategy of revision number generation. Default implementation of revision entity uses native identifier generator.

If the current database engine does not support identity columns, users are advised to set this property to false.

In this case revision numbers are created by preconfigured org.hibernate.id.enhanced.SequenceStyleGenerator. See: org.hibernate.envers.DefaultRevisionEntity and org.hibernate.envers.enhanced.SequenceIdRevisionEntity.

**org.hibernate.envers.track_entities_changed_in_revision** (default: false )

Should entity types, that have been modified during each revision, be tracked. The default implementation creates REVCHANGES table that stores entity names of modified persistent objects. Single record encapsulates the revision identifier (foreign key to REVINFO table) and a string value. For more information, refer to Tracking entity names modified during revisions and Querying for entity types modified in a given revision.

**org.hibernate.envers.global_with_modified_flag** (default: false, can be individually overridden with @Audited( withModifiedFlag = true ) )

Should property modification flags be stored for all audited entities and all properties.

When set to true, for all properties an additional boolean column in the audit tables will be created, filled with information if the given property changed in the given revision.

When set to false, such column can be added to selected entities or properties using the @Audited annotation.

For more information, refer to Tracking entity changes at the property level and Querying for entity revisions that modified a given property.

**org.hibernate.envers.modified_flag_suffix** (default: _MOD )

The suffix for columns storing “Modified Flags”.

For example, a property called “age”, will by default get modified flag with column name “age_MOD”.

**org.hibernate.envers.modified_column_naming_strategy** (default: org.hibernate.envers.boot.internal.LegacyModifiedColumnNamingStrategy )

The naming strategy to be used for modified flag columns in the audit metadata.

**org.hibernate.envers.embeddable_set_ordinal_field_name** (default: SETORDINAL )

Name of column used for storing ordinal of the change in sets of embeddable elements.

**org.hibernate.envers.cascade_delete_revision** (default: false )

While deleting revision entry, remove data of associated audited entities. Requires database support for cascade row removal.

**org.hibernate.envers.allow_identifier_reuse** (default: false )

Guarantees proper validity audit strategy behavior when application reuses identifiers of deleted entities. Exactly one row with null end date exists for each identifier.

**org.hibernate.envers.original_id_prop_name** (default: originalId )

Specifies the composite-id key property name used by the audit table mappings.

**org.hibernate.envers.find_by_revision_exact_match** (default: false )

Specifies whether or not AuditReader#find methods which accept a revision-number argument are to find results based on fuzzy-match or exact-match behavior.

The old (legacy) behavior has always been to perform a fuzzy-match where these methods would return a match if any revision existed for the primary-key with a revision-number less-than or equal-to the revision method argument. This behavior is great when you want to find the snapshot of a non-related entity based on another entity’s revision number.

The new (optional) behavior when this option is enabled forces the query to perform an exact-match instead. In order for these methods to return a non-null value, a revision entry must exist for the entity with the specified primary key and revision number; otherwise the result will be null.

21.3. Additional mapping annotations

The name of the audit table can be set on a per-entity basis, using the @AuditTable annotation. It may be tedious to add this annotation to every audited entity, so if possible, it’s better to use a prefix/suffix.

If you have a mapping with secondary tables, audit tables for them will be generated in the same way (by adding the prefix and suffix). If you wish to overwrite this behavior, you can use the @SecondaryAuditTable and @SecondaryAuditTables annotations.

If you’d like to override auditing behavior of some fields/properties inherited from @MappedSuperclass or in an embedded component, you can apply the @AuditOverride annotation on the subtype or usage site of the component.

If you want to audit a relation mapped with @OneToMany and @JoinColumn, please see Mapping exceptions for a description of the additional @AuditJoinTable annotation that you’ll probably want to use.

If you want to audit a relation, where the target entity is not audited (that is the case for example with dictionary-like entities, which don’t change and don’t have to be audited), just annotate it with @Audited( targetAuditMode = RelationTargetAuditMode.NOT_AUDITED ). Then, while reading historic versions of your entity, the relation will always point to the “current” related entity. By default Envers throws javax.persistence.EntityNotFoundException when “current” entity does not exist in the database. Apply @NotFound( action = NotFoundAction.IGNORE ) annotation to silence the exception and assign null value instead. The hereby solution causes implicit eager loading of to-one relations.

If you’d like to audit properties of a superclass of an entity, which are not explicitly audited (they don’t have the @Audited annotation on any properties or on the class), you can set the @AuditOverride( forClass = SomeEntity.class, isAudited = true/false ) annotation.

21.4. Choosing an audit strategy

After the basic configuration, it is important to choose the audit strategy that will be used to persist and retrieve audit information. There is a trade-off between the performance of persisting and the performance of querying the audit information. Currently, there are two audit strategies.

1. The default audit strategy persists the audit data together with a start revision. For each row inserted, updated or deleted in an audited table, one or more rows are inserted in the audit tables, together with the start revision of its validity. Rows in the audit tables are never updated after insertion. Queries of audit information use subqueries to select the applicable rows in the audit tables.

   These subqueries are notoriously slow and difficult to index.

2. The alternative is a validity audit strategy. This strategy stores the start-revision and the end-revision of audit information. For each row inserted, updated or deleted in an audited table, one or more rows are inserted in the audit tables, together with the start revision of its validity. But at the same time, the end-revision field of the previous audit rows (if available) is set to this revision. Queries on the audit information can then use ‘between start and end revision’ instead of subqueries as used by the default audit strategy.

   The consequence of this strategy is that persisting audit information will be a bit slower because of the extra updates involved, but retrieving audit information will be a lot faster.

   This can be improved even further by adding extra indexes.

21.4.1. Configuring the ValidityAuditStrategy

To better visualize how the ValidityAuditStrategy works, consider the following exercise where we replay the previous audit logging example for the Customer entity.

First, you need to configure the ValidityAuditStrategy:

Example 661. Configuring the ValidityAuditStrategy

options.put(
    EnversSettings.AUDIT_STRATEGY,
    ValidityAuditStrategy.class.getName()
);

If, you’re using the persistence.xml configuration file, then the mapping will look as follows:

<property
    name="org.hibernate.envers.audit_strategy"
    value="org.hibernate.envers.strategy.ValidityAuditStrategy"
/>

Once you configured the ValidityAuditStrategy, the following schema is going to be automatically generated:

Example 662. Envers schema for the ValidityAuditStrategy

create table Customer (
    id bigint not null,
    created_on timestamp,
    firstName varchar(255),
    lastName varchar(255),
    primary key (id)
)
create table Customer_AUD (
   id bigint not null,
    REV integer not null,
    REVTYPE tinyint,
    REVEND integer,
    created_on timestamp,
    firstName varchar(255),
    lastName varchar(255),
    primary key (id, REV)
)
create table REVINFO (
    REV integer generated by default as identity,
    REVTSTMP bigint,
    primary key (REV)
)
alter table Customer_AUD
    add constraint FK5ecvi1a0ykunrriib7j28vpdj
    foreign key (REV)
    references REVINFO
alter table Customer_AUD
    add constraint FKqd4fy7ww1yy95wi4wtaonre3f
    foreign key (REVEND)
    references REVINFO

As you can see, the REVEND column is added as well as its foreign key to the REVINFO table.

When rerunning the previous Customer audit log queries against the ValidityAuditStrategy, we get the following results:

Example 663. Getting the first revision for the Customer entity

select
    c.id as id1_1_,
    c.REV as REV2_1_,
    c.REVTYPE as REVTYPE3_1_,
    c.REVEND as REVEND4_1_,
    c.created_on as created_5_1_,
    c.firstName as firstNam6_1_,
    c.lastName as lastName7_1_
from
    Customer_AUD c
where
    c.REV <= ?
    and c.REVTYPE <> ?
    and (
        c.REVEND > ?
        or c.REVEND is null
    )
-- binding parameter [1] as [INTEGER] - [1]
-- binding parameter [2] as [INTEGER] - [2]
-- binding parameter [3] as [INTEGER] - [1]

21.5. Revision Log

When Envers starts a new revision, it creates a new revision entity which stores information about the revision.

By default, that includes just:

revision number

An integral value (int/Integer or long/Long). Essentially, the primary key of the revision.

revision timestamp

Either a long/Long or java.util.Date value representing the instant at which the revision was made. When using a java.util.Date, instead of a long/Long for the revision timestamp, take care not to store it to a column data type which will lose precision.

Envers handles this information as an entity. By default it uses its own internal class to act as the entity, mapped to the REVINFO table. You can, however, supply your own approach to collecting this information which might be useful to capture additional details such as who made a change or the IP address from which the request came. There are two things you need to make this work:

1. First, you will need to tell Envers about the entity you wish to use. Your entity must use the @org.hibernate.envers.RevisionEntity annotation. It must define the two attributes described above annotated with @org.hibernate.envers.RevisionNumber and @org.hibernate.envers.RevisionTimestamp, respectively. You can extend from org.hibernate.envers.DefaultRevisionEntity, if you wish, to inherit all these required behaviors.

   Simply add the custom revision entity as you do your normal entities and Envers will find it.

   It is an error for there to be multiple entities marked as @org.hibernate.envers.RevisionEntity.

2. Second, you need to tell Envers how to create instances of your revision entity which is handled by the newRevision( Object revisionEntity ) method of the org.hibernate.envers.RevisionListener interface.

   You tell Envers your custom org.hibernate.envers.RevisionListener implementation to use by specifying it on the @org.hibernate.envers.RevisionEntity annotation, using the value attribute. If your RevisionListener class is inaccessible from @RevisionEntity (e.g. it exists in a different module), set org.hibernate.envers.revision_listener property to its fully qualified class name. Class name defined by the configuration parameter overrides the revision entity’s value attribute.

Considering we have a CurrentUser utility which stores the currently logged user:

Example 664. CurrentUser utility

public static class CurrentUser {
    public static final CurrentUser INSTANCE = new CurrentUser();
    private static final ThreadLocal<String> storage = new ThreadLocal<>();
    public void logIn(String user) {
        storage.set( user );
    }
    public void logOut() {
        storage.remove();
    }
    public String get() {
        return storage.get();
    }
}

Now, we need to provide a custom @RevisionEntity to store the currently logged user

Example 665. Custom @RevisionEntity example

@Entity(name = "CustomRevisionEntity")
@Table(name = "CUSTOM_REV_INFO")
@RevisionEntity( CustomRevisionEntityListener.class )
public static class CustomRevisionEntity extends DefaultRevisionEntity {
    private String username;
    public String getUsername() {
        return username;
    }
    public void setUsername( String username ) {
        this.username = username;
    }
}

With the custom RevisionEntity implementation in place, we only need to provide the RevisionEntity implementation which acts as a factory of RevisionEntity instances.

Example 666. Custom @RevisionListener example

public static class CustomRevisionEntityListener implements RevisionListener {
    public void newRevision( Object revisionEntity ) {
        CustomRevisionEntity customRevisionEntity =
            ( CustomRevisionEntity ) revisionEntity;
        customRevisionEntity.setUsername(
            CurrentUser.INSTANCE.get()
        );
    }
}

When generating the database schema, Envers creates the following RevisionEntity table:

Example 667. Auto-generated RevisionEntity Envers table

create table CUSTOM_REV_INFO (
    id integer not null,
    timestamp bigint not null,
    username varchar(255),
    primary key (id)
)

You can see the username column in place.

Now, when inserting a Customer entity, Envers generates the following statements:

Example 668. Auditing using the custom @RevisionEntity instance

CurrentUser.INSTANCE.logIn( "Vlad Mihalcea" );
doInJPA( this::entityManagerFactory, entityManager -> {
    Customer customer = new Customer();
    customer.setId( 1L );
    customer.setFirstName( "John" );
    customer.setLastName( "Doe" );
    entityManager.persist( customer );
} );
CurrentUser.INSTANCE.logOut();

insert
into
    Customer
    (created_on, firstName, lastName, id)
values
    (?, ?, ?, ?)
-- binding parameter [1] as [TIMESTAMP] - [Thu Jul 27 15:45:00 EEST 2017]
-- binding parameter [2] as [VARCHAR]   - [John]
-- binding parameter [3] as [VARCHAR]   - [Doe]
-- binding parameter [4] as [BIGINT]    - [1]
insert
into
    CUSTOM_REV_INFO
    (timestamp, username, id)
values
    (?, ?, ?)
-- binding parameter [1] as [BIGINT]  - [1501159500888]
-- binding parameter [2] as [VARCHAR] - [Vlad Mihalcea]
-- binding parameter [3] as [INTEGER] - [1]
insert
into
    Customer_AUD
    (REVTYPE, created_on, firstName, lastName, id, REV)
values
    (?, ?, ?, ?, ?, ?)
-- binding parameter [1] as [INTEGER]   - [0]
-- binding parameter [2] as [TIMESTAMP] - [Thu Jul 27 15:45:00 EEST 2017]
-- binding parameter [3] as [VARCHAR]   - [John]
-- binding parameter [4] as [VARCHAR]   - [Doe]
-- binding parameter [5] as [BIGINT]    - [1]
-- binding parameter [6] as [INTEGER]   - [1]

As demonstrated by the example above, the username is properly set and propagated to the CUSTOM_REV_INFO table.

21.6. Tracking entity names modified during revisions

By default, entity types that have been changed in each revision are not being tracked. This implies the necessity to query all tables storing audited data in order to retrieve changes made during the specified revision. Envers provides a simple mechanism that creates REVCHANGES table which stores entity names of modified persistent objects. Single record encapsulates the revision identifier (foreign key to REVINFO table) and a string value.

Tracking of modified entity names can be enabled in three different ways:

1. Set org.hibernate.envers.track_entities_changed_in_revision parameter to true. In this case org.hibernate.envers.DefaultTrackingModifiedEntitiesRevisionEntity will be implicitly used as the revision log entity.

2. Create a custom revision entity that extends org.hibernate.envers.DefaultTrackingModifiedEntitiesRevisionEntity class.

   @Entity(name = "CustomTrackingRevisionEntity")
   @Table(name = "TRACKING_REV_INFO")
   @RevisionEntity
   public static class CustomTrackingRevisionEntity
       extends DefaultTrackingModifiedEntitiesRevisionEntity {
   }

3. Mark an appropriate field of a custom revision entity with @org.hibernate.envers.ModifiedEntityNames annotation. The property is required to be of Set<String> type.

   @Entity(name = "CustomTrackingRevisionEntity")
   @Table(name = "TRACKING_REV_INFO")
   @RevisionEntity
   public static class CustomTrackingRevisionEntity extends DefaultRevisionEntity {
       @ElementCollection
       @JoinTable(
           name = "REVCHANGES",
           joinColumns = @JoinColumn( name = "REV" )
       )
       @Column( name = "ENTITYNAME" )
       @ModifiedEntityNames
       private Set<String> modifiedEntityNames = new HashSet<>();
       public Set<String> getModifiedEntityNames() {
           return modifiedEntityNames;
       }
   }

Considering we have a Customer entity illustrated by the following example:

Example 669. Customer entity before renaming

@Audited
@Entity(name = "Customer")
public static class Customer {
    @Id
    private Long id;
    private String firstName;
    private String lastName;
    @Temporal( TemporalType.TIMESTAMP )
    @Column(name = "created_on")
    @CreationTimestamp
    private Date createdOn;
    //Getters and setters are omitted for brevity
}

If the Customer entity class name is changed to ApplicationCustomer, Envers is going to insert a new record in the REVCHANGES table with the previous entity class name:

Example 670. Customer entity after renaming

@Audited
@Entity(name = "Customer")
public static class ApplicationCustomer {
    @Id
    private Long id;
    private String firstName;
    private String lastName;
    @Temporal( TemporalType.TIMESTAMP )
    @Column(name = "created_on")
    @CreationTimestamp
    private Date createdOn;
    //Getters and setters are omitted for brevity
}

insert
into
    REVCHANGES
    (REV, ENTITYNAME)
values
    (?, ?)
-- binding parameter [1] as [INTEGER] - [1]
-- binding parameter [2] as [VARCHAR] - [org.hibernate.userguide.envers.EntityTypeChangeAuditTest$Customer]

Users, that have chosen one of the approaches listed above, can retrieve all entities modified in a specified revision by utilizing API described in Querying for entity types modified in a given revision.

Users are also allowed to implement custom mechanisms of tracking modified entity types. In this case, they shall pass their own implementation of org.hibernate.envers.EntityTrackingRevisionListener interface as the value of @org.hibernate.envers.RevisionEntity annotation.

EntityTrackingRevisionListener interface exposes one method that notifies whenever audited entity instance has been added, modified or removed within current revision boundaries.

Example 671. The EntityTrackingRevisionListener implementation

public static class CustomTrackingRevisionListener implements EntityTrackingRevisionListener {
    @Override
    public void entityChanged(Class entityClass,
                              String entityName,
                              Serializable entityId,
                              RevisionType revisionType,
                              Object revisionEntity ) {
        String type = entityClass.getName();
        ( (CustomTrackingRevisionEntity) revisionEntity ).addModifiedEntityType( type );
    }
    @Override
    public void newRevision( Object revisionEntity ) {
    }
}

The CustomTrackingRevisionListener adds the fully-qualified class name to the modifiedEntityTypes attribute of the CustomTrackingRevisionEntity.

Example 672. The RevisionEntity using the custom EntityTrackingRevisionListener

@Entity(name = "CustomTrackingRevisionEntity")
@Table(name = "TRACKING_REV_INFO")
@RevisionEntity( CustomTrackingRevisionListener.class )
public static class CustomTrackingRevisionEntity {
    @Id
    @GeneratedValue
    @RevisionNumber
    private int customId;
    @RevisionTimestamp
    private long customTimestamp;
    @OneToMany(
        mappedBy="revision",
        cascade={
            CascadeType.PERSIST,
            CascadeType.REMOVE
        }
    )
    private Set<EntityType> modifiedEntityTypes = new HashSet<>();
    public Set<EntityType> getModifiedEntityTypes() {
        return modifiedEntityTypes;
    }
    public void addModifiedEntityType(String entityClassName ) {
        modifiedEntityTypes.add( new EntityType( this, entityClassName ) );
    }
}

The CustomTrackingRevisionEntity contains a @OneToMany list of ModifiedTypeRevisionEntity

Example 673. The EntityType encapsulates the entity type name before a class name modification

@Entity(name = "EntityType")
public static class EntityType {
    @Id
    @GeneratedValue
    private Integer id;
    @ManyToOne
    private CustomTrackingRevisionEntity revision;
    private String entityClassName;
    private EntityType() {
    }
    public EntityType(CustomTrackingRevisionEntity revision, String entityClassName) {
        this.revision = revision;
        this.entityClassName = entityClassName;
    }
    //Getters and setters are omitted for brevity
}

Now, when fetching the CustomTrackingRevisionEntity, you can get access to the previous entity class name.

Example 674. Getting the EntityType through the CustomTrackingRevisionEntity

AuditReader auditReader = AuditReaderFactory.get( entityManager );
List<Number> revisions = auditReader.getRevisions(
    ApplicationCustomer.class,
    1L
);
CustomTrackingRevisionEntity revEntity = auditReader.findRevision(
    CustomTrackingRevisionEntity.class,
    revisions.get( 0 )
);
Set<EntityType> modifiedEntityTypes = revEntity.getModifiedEntityTypes();
assertEquals( 1, modifiedEntityTypes.size() );
EntityType entityType = modifiedEntityTypes.iterator().next();
assertEquals(
    Customer.class.getName(),
    entityType.getEntityClassName()
);

21.7. Tracking entity changes at the property level

By default, the only information stored by Envers are revisions of modified entities. This approach lets users create audit queries based on historical values of entity properties. Sometimes it is useful to store additional metadata for each revision, when you are interested also in the type of changes, not only about the resulting values.

The feature described in Tracking entity names modified during revisions makes it possible to tell which entities were modified in a given revision.

The feature described here takes it one step further. Modification Flags enable Envers to track which properties of audited entities were modified in a given revision.

Tracking entity changes at the property level can be enabled by:

1. setting org.hibernate.envers.global_with_modified_flag configuration property to true. This global switch will cause adding modification flags to be stored for all audited properties of all audited entities.

2. using @Audited( withModifiedFlag = true ) on a property or on an entity.

The trade-off coming with this functionality is an increased size of audit tables and a very little, almost negligible, performance drop during audit writes. This is due to the fact that every tracked property has to have an accompanying boolean column in the schema that stores information about the property modifications. Of course, it is Enver’s job to fill these columns accordingly - no additional work by the developer is required. Because of costs mentioned, it is recommended to enable the feature selectively, when needed with use of the granular configuration means described above.

Example 675. Mapping for tracking entity changes at the property level

@Audited(withModifiedFlag = true)
@Entity(name = "Customer")
public static class Customer {
    @Id
    private Long id;
    private String firstName;
    private String lastName;
    @Temporal( TemporalType.TIMESTAMP )
    @Column(name = "created_on")
    @CreationTimestamp
    private Date createdOn;
    //Getters and setters are omitted for brevity
}

create table Customer_AUD (
    id bigint not null,
    REV integer not null,
    REVTYPE tinyint,
    created_on timestamp,
    createdOn_MOD boolean,
    firstName varchar(255),
    firstName_MOD boolean,
    lastName varchar(255),
    lastName_MOD boolean,
    primary key (id, REV)
)

As you can see, every property features a _MOD column (e.g. createdOn_MOD) in the audit log.

Example 676. Tracking entity changes at the property level example

Customer customer = entityManager.find( Customer.class, 1L );
customer.setLastName( "Doe Jr." );

update
    Customer
set
    created_on = ?,
    firstName = ?,
    lastName = ?
where
    id = ?
-- binding parameter [1] as [TIMESTAMP] - [2017-07-31 15:58:20.342]
-- binding parameter [2] as [VARCHAR]   - [John]
-- binding parameter [3] as [VARCHAR]   - [Doe Jr.]
-- binding parameter [4] as [BIGINT]    - [1]
insert
into
    REVINFO
    (REV, REVTSTMP)
values
    (null, ?)
-- binding parameter [1] as [BIGINT] - [1501505900439]
insert
into
    Customer_AUD
    (REVTYPE, created_on, createdOn_MOD, firstName, firstName_MOD, lastName, lastName_MOD, id, REV)
values
    (?, ?, ?, ?, ?, ?, ?, ?, ?)
-- binding parameter [1] as [INTEGER]   - [1]
-- binding parameter [2] as [TIMESTAMP] - [2017-07-31 15:58:20.342]
-- binding parameter [3] as [BOOLEAN]   - [false]
-- binding parameter [4] as [VARCHAR]   - [John]
-- binding parameter [5] as [BOOLEAN]   - [false]
-- binding parameter [6] as [VARCHAR]   - [Doe Jr.]
-- binding parameter [7] as [BOOLEAN]   - [true]
-- binding parameter [8] as [BIGINT]    - [1]
-- binding parameter [9] as [INTEGER]   - [2]

To see how “Modified Flags” can be utilized, check out the very simple query API that uses them: Querying for entity revisions that modified a given property.

21.8. Selecting strategy for tracking property level changes

By default, Envers uses the legacy modified column naming strategy. This strategy is designed to add columns based on the following rule-set:

1. If property is annotated with @Audited and the modifiedColumnName attribute is specified, the column will directly be based on the supplied name.

2. If property is not annotated with @Audited or if no modifiedColumnName attribute is given, the column will be named after the java class property, appended with the configured suffix, the default being _MOD.

While this strategy has no performance drawbacks, it does present concerns for users who prefer consistency without verbosity. Lets take the following entity mapping as an example.

@Audited(withModifiedFlags = true)
@Entity
public class Customer {
  @Id
  private Integer id;
  @Column(name = "customer_name")
  private String name;
}

This mapping will actually lead to some inconsistent naming between columns, see below for how the model’s name will be stored in customer_name but the modified column that tracks whether this column changes between revisions is named name_MOD.

CREATE TABLE Customer_AUD (
    id bigint not null,
    REV integer not null,
    REVTYPE tinyint not null,
    customer_name varchar(255),
    name_MOD boolean,
    primary key(id, REV)
)

An additional strategy called improved, aims to address these inconsistent column naming concerns. This strategy uses the following rule-set:

1. Property is a Basic type (Single Column valued property)

   1. Use the modifiedColumnName directly if one is supplied on the property mapping

   2. Otherwise use the resolved ORM column name appended with the modified flag suffix configured value

1. Property is an Association (to-one mapping) with a Foreign Key using a single column

   1. Use the modifiedColumnName directly if one is supplied on the property mapping

   2. Otherwise use the resolved ORM column name appended with the modified flag suffix configured value

1. Property is an Association (to-one mapping) with a Foreign Key using multiple columns

   1. Use the modifiedColumnName directly if one is supplied on the property mapping

   2. Otherwise use the property name appended with the modified flag suffix configured value

1. Property is an Embeddable

   1. Use the modifiedColumnName directly if one is supplied on the property mapping

   2. Otherwise use the property name appended with the modified flag suffix configured value

While using this strategy, the same Customer mapping will generate the following table schema:

CREATE TABLE Customer_AUD (
    id bigint not null,
    REV integer not null,
    REVTYPE tinyint not null,
    customer_name varchar(255),
    customer_name_MOD boolean,
    primary key(id, REV)
)

When already using Envers in conjunction with the modified columns flag feature, it is advised not to enable the new strategy immediately as schema changes would be required. You will need to either migrate your existing schema manually to adhere to the rules above or use the explicit modifiedColumnName attribute on the @Audited annotation for existing columns that use the feature.

To configure a custom strategy implementation or use the improved strategy, the configuration option org.hibernate.envers.modified_column_naming_strategy will need to be set. This option can be the fully qualified class name of a ModifiedColumnNameStrategy implementation or legacy or improved for either of the two provided implementations.

21.9. Queries

You can think of historic data as having two dimensions:

horizontal

The state of the database at a given revision. Thus, you can query for entities as they were at revision N.

vertical

The revisions, at which entities changed. Hence, you can query for revisions, in which a given entity changed.

The queries in Envers are similar to Hibernate Criteria queries, so if you are familiar with them, using Envers queries will be much easier.

The main limitation of the current queries implementation is that you cannot traverse relations. You can only specify constraints on the ids of the related entities, and only on the “owning” side of the relation. This, however, will be changed in future releases.

21.10. Querying for entities of a class at a given revision

The entry point for this type of queries is:

Example 677. Getting the Customer entity at a given revision

Customer customer = (Customer) AuditReaderFactory
.get( entityManager )
.createQuery()
.forEntitiesAtRevision( Customer.class, revisions.get( 0 ) )
.getSingleResult();
assertEquals("Doe", customer.getLastName());

21.11. Querying for entities using filtering criteria

You can then specify constraints, which should be met by the entities returned, by adding restrictions, which can be obtained using the AuditEntity factory class.

For example, to select only entities where the firstName property is equal to “John”:

Example 678. Getting the Customer audit log with a given firstName attribute value

List<Customer> customers = AuditReaderFactory
.get( entityManager )
.createQuery()
.forRevisionsOfEntity( Customer.class, true, true )
.add( AuditEntity.property( "firstName" ).eq( "John" ) )
.getResultList();
assertEquals(2, customers.size());
assertEquals( "Doe", customers.get( 0 ).getLastName() );
assertEquals( "Doe Jr.", customers.get( 1 ).getLastName() );

And, to select only entities whose relationships are related to a given entity, you can use either the target entity or its identifier.

Example 679. Getting the Customer entities whose address attribute matches the given entity reference

Address address = entityManager.getReference( Address.class, 1L );
List<Customer> customers = AuditReaderFactory
.get( entityManager )
.createQuery()
.forRevisionsOfEntity( Customer.class, true, true )
.add( AuditEntity.property( "address" ).eq( address ) )
.getResultList();
assertEquals(2, customers.size());

select
    c.id as id1_3_,
    c.REV as REV2_3_,
    c.REVTYPE as REVTYPE3_3_,
    c.REVEND as REVEND4_3_,
    c.created_on as created_5_3_,
    c.firstName as firstNam6_3_,
    c.lastName as lastName7_3_,
    c.address_id as address_8_3_
from
    Customer_AUD c
where
    c.address_id = ?
order by
    c.REV asc
-- binding parameter [1] as [BIGINT] - [1]

The same SQL is generated even if we provide the identifier instead of the target entity reference.

Example 680. Getting the Customer entities whose address identifier matches the given entity identifier

List<Customer> customers = AuditReaderFactory
.get( entityManager )
.createQuery()
.forRevisionsOfEntity( Customer.class, true, true )
.add( AuditEntity.relatedId( "address" ).eq( 1L ) )
.getResultList();
assertEquals(2, customers.size());

Apart from strict equality matching, you can also use an IN clause to provide multiple entity identifiers:

Example 681. Getting the Customer entities whose address identifier matches one of the given entity identifiers

List<Customer> customers = AuditReaderFactory
.get( entityManager )
.createQuery()
.forRevisionsOfEntity( Customer.class, true, true )
.add( AuditEntity.relatedId( "address" ).in( new Object[] { 1L, 2L } ) )
.getResultList();
assertEquals(2, customers.size());

select
    c.id as id1_3_,
    c.REV as REV2_3_,
    c.REVTYPE as REVTYPE3_3_,
    c.REVEND as REVEND4_3_,
    c.created_on as created_5_3_,
    c.firstName as firstNam6_3_,
    c.lastName as lastName7_3_,
    c.address_id as address_8_3_
from
    Customer_AUD c
where
    c.address_id in (
        ? , ?
    )
order by
    c.REV asc
-- binding parameter [1] as [BIGINT] - [1]
-- binding parameter [2] as [BIGINT] - [2]

You can limit the number of results, order them, and set aggregations and projections (except grouping) in the usual way. When your query is complete, you can obtain the results by calling the getSingleResult() or getResultList() methods.

A full query, can look for example like this:

Example 682. Getting the Customer entities using filtering and pagination

List<Customer> customers = AuditReaderFactory
.get( entityManager )
.createQuery()
.forRevisionsOfEntity( Customer.class, true, true )
.addOrder( AuditEntity.property( "lastName" ).desc() )
.add( AuditEntity.relatedId( "address" ).eq( 1L ) )
.setFirstResult( 1 )
.setMaxResults( 2 )
.getResultList();
assertEquals(1, customers.size());

select
    c.id as id1_3_,
    c.REV as REV2_3_,
    c.REVTYPE as REVTYPE3_3_,
    c.REVEND as REVEND4_3_,
    c.created_on as created_5_3_,
    c.firstName as firstNam6_3_,
    c.lastName as lastName7_3_,
    c.address_id as address_8_3_
from
    Customer_AUD c
where
    c.address_id = ?
order by
    c.lastName desc
limit ?
offset ?

21.12. Querying for revisions, at which entities of a given class changed

The entry point for this type of queries is:

AuditQuery query = AuditReaderFactory.get( entityManager )
    .createQuery()
    .forRevisionsOfEntity( Customer.class, false, true );

You can add constraints to this query in the same way as to the previous one.

There are some additional possibilities:

1. using AuditEntity.revisionNumber() you can specify constraints, projections and order on the revision number, in which the audited entity was modified.

2. similarly, using AuditEntity.revisionProperty( propertyName ) you can specify constraints, projections and order on a property of the revision entity, corresponding to the revision in which the audited entity was modified.

3. AuditEntity.revisionType() gives you access as above to the type of the revision (ADD, MOD, DEL).

Using these methods, you can order the query results by revision number, set projection or constraint the revision number to be greater or less than a specified value, etc. For example, the following query will select the smallest revision number, at which entity of class MyEntity with id entityId has changed, after revision number 2:

Number revision = (Number) AuditReaderFactory
.get( entityManager )
.createQuery()
.forRevisionsOfEntity( Customer.class, false, true )
.addProjection( AuditEntity.revisionNumber().min() )
.add( AuditEntity.id().eq( 1L ) )
.add( AuditEntity.revisionNumber().gt( 2 ) )
.getSingleResult();

The second additional feature you can use in queries for revisions is the ability to maximize/minimize a property.

For example, if you want to select the smallest possible revision at which the value of the createdOn attribute was larger then a given value, you can run the following query:

Number revision = (Number) AuditReaderFactory
.get( entityManager )
.createQuery()
.forRevisionsOfEntity( Customer.class, false, true )
.addProjection( AuditEntity.revisionNumber().min() )
.add( AuditEntity.id().eq( 1L ) )
.add(
    AuditEntity.property( "createdOn" )
    .minimize()
    .add( AuditEntity.property( "createdOn" )
        .ge(
            Timestamp.from(
                LocalDateTime.now()
                    .minusDays( 1 )
                    .toInstant( ZoneOffset.UTC )
                )
        )
    )
)
.getSingleResult();

The minimize() and maximize() methods return a criterion, to which you can add constraints, which must be met by the entities with the maximized/minimized properties.

You probably also noticed that there are two boolean parameters, passed when creating the query.

selectEntitiesOnly

The first parameter is only valid when you don’t set an explicit projection.

If true, the result of the query will be a list of entities (which changed at revisions satisfying the specified constraints).

If false, the result will be a list of three element arrays:

• the first element will be the changed entity instance.

• the second will be an entity containing revision data (if no custom entity is used, this will be an instance of DefaultRevisionEntity).

• the third will be the type of the revision (one of the values of the RevisionType enumeration: ADD, MOD, DEL).

selectDeletedEntities

The second parameter specifies if revisions, in which the entity was deleted should be included in the results.

If yes, such entities will have the revision type DEL and all attributes, except the id, will be set to null.

Another useful feature is AggregatedAuditExpression#computeAggregationInInstanceContext(). This can be used to create an aggregate query based on the entity instance primary key.

For example, if you wanted to locate all customers but only wanted to retrieve the instances with the maximum revision number, you would use the following query:

List<Customer> results = AuditReaderFactory
    .get( entityManager )
    .createQuery()
    .forRevisionsOfEntity( Customer.class, true, false )
    .add( AuditEntity.revisionNumber().maximize().computeAggregationInInstanceContext() )
    .getResultList();

In other words, the result set would contain a list of Customer instances, one per primary key. Each instance would hold the audited property data at the maximum revision number for each Customer primary key.

21.13. Querying for entity revisions that modified a given property

For the two types of queries described above it’s possible to use special Audit criteria called hasChanged() and hasNotChanged() that make use of the functionality described in Tracking entity changes at the property level.

Let’s have a look at various queries that can benefit from these two criteria.

First, you must make sure that your entity can track modification flags:

Example 683. Valid only when audit logging tracks entity attribute modification flags

@Audited( withModifiedFlag = true )

The following query will return all revisions of the Customer entity with the given id, for which the lastName property has changed.

Example 684. Getting all Customer revisions for which the lastName attribute has changed

List<Customer> customers = AuditReaderFactory
.get( entityManager )
.createQuery()
.forRevisionsOfEntity( Customer.class, false, true )
.add( AuditEntity.id().eq( 1L ) )
.add( AuditEntity.property( "lastName" ).hasChanged() )
.getResultList();

select
    c.id as id1_3_0_,
    c.REV as REV2_3_0_,
    defaultrev1_.REV as REV1_4_1_,
    c.REVTYPE as REVTYPE3_3_0_,
    c.REVEND as REVEND4_3_0_,
    c.created_on as created_5_3_0_,
    c.createdOn_MOD as createdO6_3_0_,
    c.firstName as firstNam7_3_0_,
    c.firstName_MOD as firstNam8_3_0_,
    c.lastName as lastName9_3_0_,
    c.lastName_MOD as lastNam10_3_0_,
    c.address_id as address11_3_0_,
    c.address_MOD as address12_3_0_,
    defaultrev1_.REVTSTMP as REVTSTMP2_4_1_
from
    Customer_AUD c cross
join
    REVINFO defaultrev1_
where
    c.id = ?
    and c.lastName_MOD = ?
    and c.REV=defaultrev1_.REV
order by
    c.REV asc
-- binding parameter [1] as [BIGINT]  - [1]
-- binding parameter [2] as [BOOLEAN] - [true]

Using this query we won’t get all other revisions in which lastName wasn’t touched. From the SQL query you can see that the lastName_MOD column is being used in the WHERE clause, hence the aforementioned requirement for tracking modification flags.

Of course, nothing prevents users from combining hasChanged condition with some additional criteria.

Example 685. Getting all Customer revisions for which the lastName attribute has changed and the firstName attribute has not changed

List<Customer> customers = AuditReaderFactory
.get( entityManager )
.createQuery()
.forRevisionsOfEntity( Customer.class, false, true )
.add( AuditEntity.id().eq( 1L ) )
.add( AuditEntity.property( "lastName" ).hasChanged() )
.add( AuditEntity.property( "firstName" ).hasNotChanged() )
.getResultList();

select
    c.id as id1_3_0_,
    c.REV as REV2_3_0_,
    defaultrev1_.REV as REV1_4_1_,
    c.REVTYPE as REVTYPE3_3_0_,
    c.REVEND as REVEND4_3_0_,
    c.created_on as created_5_3_0_,
    c.createdOn_MOD as createdO6_3_0_,
    c.firstName as firstNam7_3_0_,
    c.firstName_MOD as firstNam8_3_0_,
    c.lastName as lastName9_3_0_,
    c.lastName_MOD as lastNam10_3_0_,
    c.address_id as address11_3_0_,
    c.address_MOD as address12_3_0_,
    defaultrev1_.REVTSTMP as REVTSTMP2_4_1_
from
    Customer_AUD c cross
join
    REVINFO defaultrev1_
where
    c.id=?
    and c.lastName_MOD=?
    and c.firstName_MOD=?
    and c.REV=defaultrev1_.REV
order by
    c.REV asc
-- binding parameter [1] as [BIGINT]  - [1]
-- binding parameter [2] as [BOOLEAN] - [true]
-- binding parameter [3] as [BOOLEAN] - [false]

To get the Customer entities changed at a given revisionNumber with lastName modified and firstName untouched, we have to use the forEntitiesModifiedAtRevision query:

Example 686. Getting the Customer entity for a given revision if the lastName attribute has changed and the firstName attribute has not changed

Customer customer = (Customer) AuditReaderFactory
.get( entityManager )
.createQuery()
.forEntitiesModifiedAtRevision( Customer.class, 2 )
.add( AuditEntity.id().eq( 1L ) )
.add( AuditEntity.property( "lastName" ).hasChanged() )
.add( AuditEntity.property( "firstName" ).hasNotChanged() )
.getSingleResult();