Hibernate.orgCommunity Documentation
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 Chapter 3, Configuration.
The entry point for this type of queries is:
AuditQuery query = getAuditReader().createQuery().forEntitiesAtRevision(MyEntity.class, revisionNumber);
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":
query.add(AuditEntity.property("name").eq("John"));
And to select only entites that are related to a given entity:
query.add(AuditEntity.property("address").eq(relatedEntityInstance)); // or query.add(AuditEntity.relatedId("address").eq(relatedEntityId));
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:
List personsAtAddress = getAuditReader().createQuery() .forEntitiesAtRevision(Person.class, 12) .addOrder(AuditEntity.property("surname").desc()) .add(AuditEntity.relatedId("address").eq(addressId)) .setFirstResult(4) .setMaxResults(2) .getResultList();
The entry point for this type of queries is:
AuditQuery query = getAuditReader().createQuery() .forRevisionsOfEntity(MyEntity.class, false, true);
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:
Number revision = (Number) getAuditReader().createQuery() .forRevisionsOfEntity(MyEntity.class, false, true) .setProjection(AuditEntity.revisionNumber().min()) .add(AuditEntity.id().eq(entityId)) .add(AuditEntity.revisionNumber().gt(42)) .getSingleResult();
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:
Number revision = (Number) getAuditReader().createQuery() .forRevisionsOfEntity(MyEntity.class, false, true) // We are only interested in the first revision .setProjection(AuditEntity.revisionNumber().min()) .add(AuditEntity.property("actualDate").minimize() .add(AuditEntity.property("actualDate").ge(givenDate)) .add(AuditEntity.id().eq(givenEntityId))) .getSingleResult();
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
.
Copyright © 2004 Red Hat Inc.