diff --git a/documentation/src/main/docbook/devguide/en-US/Envers.xml b/documentation/src/main/docbook/devguide/en-US/Envers.xml
index cb7f31a17b..5a434f26f8 100644
--- a/documentation/src/main/docbook/devguide/en-US/Envers.xml
+++ b/documentation/src/main/docbook/devguide/en-US/Envers.xml
@@ -253,10 +253,12 @@
Should entity types, that have been modified during each revision, be tracked. The default
implementation creates REVENTITY table that stores fully qualified names
- of Java classes changed in a specified revision. Each record encapsulates the revision
- identifier (foreign key to REVINFO table) and a string value. For more
- information refer to and
- .
+ of Java classes changed in a specified revision. Single record encapsulates the revision
+ identifier (foreign key to REVINFO table) and a string value. This
+ feature shall be used when entity name can be clearly identified by Java class type. Otherwise
+ extend org.hibernate.envers.EntityTrackingRevisionListener
+ interface. For more information refer to
+ and .
@@ -463,14 +465,16 @@ public class ExampleListener implements RevisionListener {
- Tracking entity types modified in revision
+ Tracking entity classes modified in revision
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
specified revision. Envers provides a simple mechanism that creates REVENTITY
table which stores fully qualified names of Java classes changed in each revision.
Single record encapsulates the revision identifier (foreign key to REVINFO table)
- and a string value.
+ and a string value. Note that this mechanism shall be used when entity name can be clearly identified
+ by Java class type. Otherwise extend org.hibernate.envers.EntityTrackingRevisionListener
+ interface (described further).
Tracking of modified entity types can be enabled in three different ways:
@@ -513,34 +517,28 @@ public class AnnotatedTrackingRevisionEntity {
- Users utilizing one of the approaches listed above can retrieve all entities modified in each revision
- by using API described in .
+ Users, that have chosen one of the approaches listed above, can retrieve all entities modified in
+ specified revision by utilizing API described in .
Users are also allowed to implement custom mechanism 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.
- org.hibernate.envers.EntityTrackingRevisionListener interface exposes two
- methods that notify user whenever tracking of each audited entity instance is started
- (addEntityToRevision) or stopped (removeEntityFromRevision)
- within the current revision boundaries.
+ EntityTrackingRevisionListener interface exposes one method that notifies
+ whenever audited entity instance has been added, modified or removed within current revision boundaries.
- Custom implementation of tracking entity types modified in revision
+ Custom implementation of tracking entity classes modified in revision
CustomEntityTrackingRevisionListener.java
- Querying for entities modified at a given revision
+ Querying for entities modified in a given revision
The basic query allows retrieving entity classes modified in a specified revision:
@@ -801,23 +799,27 @@ query.add(AuditEntity.relatedId("address").eq(relatedEntityId));]]>
- List findEntitiesChangedInRevision(Number)
+ List]]> findEntitiesChangedInRevision(Number)
- Returns snapshots of all audited entities changed (added, updated and removed) in a given revision.
+ Executes n+1 SQL queries, where n is a number of different entity
+ classes modified within specified revision.
- List findEntitiesChangedInRevision(Number, RevisionType)
+ List]]> findEntitiesChangedInRevision(Number, RevisionType)
- Returns snapshots of all audited entities changed (added, updated or removed) in a given revision
- filtered by modification type.
+ filtered by modification type. Executes n+1 SQL queries, where n
+ is a number of different entity classes modified within specified revision.
]]> findEntitiesChangedInRevisionGroupByRevisionType(Number)
- Returns a map containing lists of entity snapshots grouped by modification operation (e.g.
- addition, update and removal).
+ addition, update and removal). Executes 3n+1 SQL queries, where n
+ is a number of different entity classes modified within specified revision.
Note that methods described above can be legally used only when default mechanism of
- tracking changed entity names is enabled (see ).
+ tracking changed entity classes is enabled (see ).
diff --git a/hibernate-envers/src/main/java/org/hibernate/envers/AuditReader.java b/hibernate-envers/src/main/java/org/hibernate/envers/AuditReader.java
index 92c6d6e15a..06de968297 100644
--- a/hibernate-envers/src/main/java/org/hibernate/envers/AuditReader.java
+++ b/hibernate-envers/src/main/java/org/hibernate/envers/AuditReader.java
@@ -210,8 +210,8 @@ public interface AuditReader {
throws HibernateException;
/**
- * Find all entities changed (added, updated and removed) in a given revision. Executes n+1 queries,
- * where n is a number of entity classes modified within specified revision.
+ * Find all entities changed (added, updated and removed) in a given revision. Executes n+1 SQL queries,
+ * where n is a number of different entity classes modified within specified revision.
* @param revision Revision number.
* @return Snapshots of all audited entities changed in a given revision.
* @throws IllegalStateException If the associated entity manager is closed.
@@ -230,8 +230,8 @@ public interface AuditReader {
throws IllegalStateException, IllegalArgumentException, AuditException;
/**
- * Find all entities changed (added, updated or removed) in a given revision. Executes n+1 queries,
- * where n is a number of entity classes modified within specified revision.
+ * Find all entities changed (added, updated or removed) in a given revision. Executes n+1 SQL queries,
+ * where n is a number of different entity classes modified within specified revision.
* @param revision Revision number.
* @param revisionType Type of modification.
* @return Snapshots of all audited entities changed in a given revision filtered by modification type.
@@ -252,9 +252,9 @@ public interface AuditReader {
/**
* Find all entities changed (added, updated and removed) in a given revision grouped by modification type.
- * Executes mn+1 queries, where:
+ * Executes mn+1 SQL queries, where:
*
- * - n - number of entity classes modified within specified revision.
+ *
- n - number of different entity classes modified within specified revision.
*
- m - number of different revision types. See {@link RevisionType} enum.
*
* @param revision Revision number.