From a16177035a181588c558eff4e54f1a7ae163e210 Mon Sep 17 00:00:00 2001 From: adamw Date: Thu, 31 Mar 2011 14:02:36 +0200 Subject: [PATCH] HHH-6036: Moving the "query" chapter of Envers docs --- .../main/docbook/devguide/en-US/Envers.xml | 191 ++++++++++++++++++ 1 file changed, 191 insertions(+) diff --git a/documentation/src/main/docbook/devguide/en-US/Envers.xml b/documentation/src/main/docbook/devguide/en-US/Envers.xml index a52506eff5..4f03965677 100644 --- a/documentation/src/main/docbook/devguide/en-US/Envers.xml +++ b/documentation/src/main/docbook/devguide/en-US/Envers.xml @@ -379,6 +379,197 @@ public class ExampleListener implements RevisionListener { +
+ + Queries + + + You can think of historic data as having two dimension. The first - horizontal - + is the state of the database at a given revision. Thus, you can + query for entities as they were at revision N. The second - vertical - are 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, + so if you are common 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. + + + + Please note, that queries on the audited data will be in many cases much slower + than corresponding queries on "live" data, as they involve correlated subselects. + + + + In the future, queries will be improved both in terms of speed and possibilities, when using the valid-time + audit strategy, that is when storing both start and end revisions for entities. See + . + + +
+ + Querying for entities of a class at a given revision + + + The entry point for this type of queries is: + + + + + + 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 "name" property + is equal to "John": + + + + + + And to select only entites that are related to a given entity: + + + + + + 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: + + + + +
+ +
+ + Querying for revisions, at which entities of a given class changed + + + The entry point for this type of queries is: + + + + + + You can add constraints to this query in the same way as to the previous one. + There are some additional possibilities: + + + + + + using AuditEntity.revisionNumber() you can specify constraints, projections + and order on the revision number, in which the audited entity was modified + + + + + 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 + + + + + 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 42: + + + + + + The second additional feature you can use in queries for revisions is the ability + to maximalize/minimize a property. For example, if you want to select the + revision, at which the value of the actualDate for a given entity + was larger then a given value, but as small as possible: + + + + + + The minimize() and maximize() methods return a criteria, + 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. The first one, selectEntitiesOnly, 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). + + + + The second parameter, selectDeletedEntities, 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 fields, except the id, + null. + + +
+ +
+
Understanding the Envers Schema