diff --git a/documentation/src/main/docbook/devguide/en-US/Envers.xml b/documentation/src/main/docbook/devguide/en-US/Envers.xml
index ebb4af5418..f226427384 100644
--- a/documentation/src/main/docbook/devguide/en-US/Envers.xml
+++ b/documentation/src/main/docbook/devguide/en-US/Envers.xml
@@ -259,6 +259,33 @@
and .
+
+
+ org.hibernate.envers.using_modified_flag
+
+
+ false, driven by @Audited annotation parameter
+
+
+ Indicates if detailed information about individual properties changes (so-called "Modified Flags") should be stored for all entities.
+ When set to true all audit tables will contain for each property an additional BOOLEAN column
+ saying if the property has changed in the generated revision. When set to false, the feature will be disabled.
+ For more information refer to
+ and .
+
+
+
+
+ org.hibernate.envers.modified_flag_suffix
+
+
+ _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".
+
+
@@ -270,6 +297,12 @@
org.hibernate.envers.track_entities_changed_in_revision
+
+ org.hibernate.envers.using_modified_flag
+
+
+ org.hibernate.envers.modified_flag_suffix
+
@@ -616,6 +649,65 @@ Set modifiedEntityTypes = revEntity.getModifiedEntityT
+
+ Tracking entity changes at property level
+
+ By default the only information stored at commit time by Envers are
+ "snapshots" (new revisions) of modified entities.
+ This approach lets user create audit queries based on historical
+ values of entity's properties.
+ In most cases this is good enough, however there are many scenarios
+ in which auditor is more concerned about types of changes, not
+ resulting values.
+ The feature described in
+
+ makes it possible to tell
+ which entities were modified in given revision.
+ Feature describe here takes it one step further - with so-called
+ "Modified Flags" enabled, Envers can say which parts (properties) of
+ those entities were modified in a given revision.
+
+
+ Tracking entity changes at property level can be enabled by:
+
+
+
+ setting
+ org.hibernate.envers.using_modified_flag
+ parameter to
+ true. This global switch will force tracking
+ changes for all audited properties in all audited entities.
+
+
+ setting
+ usingModifiedFlag
+ parameter of the annotation
+ @org.hibernate.envers.Audited
+ to true. When the parameter is set at class-level, all class
+ properties will be tracked. When it's set for a property, then
+ it affects only that one property.
+ Class-level settings will always be overriden by field-level ones.
+
+
+
+ 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 type, column in the
+ schema that stores information about property's modifications. Of
+ course it's
+ Envers job to fill these columns accordingly - no additional work of
+ 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.
+
+
+ To see how "Modified Flags" can be utilized, check out the very
+ simple API that uses them: .
+
+
+
Queries
@@ -805,6 +897,78 @@ query.add(AuditEntity.relatedId("address").eq(relatedEntityId));]]>
+
+
+ Querying for revisions of entity that modified given property
+
+
+ For the two types of queries described above it's possible to use
+ special Audit criteria called
+ hasChanged()
+ and
+ hasNotChanged()
+ that makes use of the functionality
+ described in .
+ They're best suited for vertical queries,
+ however existing API doesn't restrict their usage for horizontal
+ ones.
+
+ Let's have a look at following examples:
+
+
+
+
+
+
+ This query will return all revisions of MyEntity with given id,
+ that modified property
+ actualDate.
+ Using this query we won't get all other revisions in which
+ actualDate
+ wasn't touched. Of course nothing prevents user from combining
+ hasChanged condition with some additional criteria - add method
+ can be used here in a normal way.
+
+
+
+
+
+
+ This query will return horizontal slice for MyEntity at the time
+ revisionNumber was generated. It will be limited to revisions
+ that modified
+ prop1
+ but not prop2.
+ Note that the result set will usually also contain revisions
+ with numbers lower than the revisionNumber, so we cannot read
+ this query as "Give me all MyEntities changed in revisionNumber
+ with
+ prop1
+ modified and
+ prop2
+ untouched". To get such result we would have to refine the query
+ as follows (or use forRevisionsOfEntity API):
+
+
+
+
+
+
+
+
Querying for entities modified in a given revision