HHH-6036: Moving the "query" chapter of Envers docs
This commit is contained in:
adamw
parent
9758c63354
commit
a16177035a
|
|
@ -379,6 +379,197 @@ public class ExampleListener implements RevisionListener {
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
<section id="envers-queries">
|
||||||
|
|
||||||
|
<title>Queries</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The queries in Envers are similar to
|
||||||
|
<ulink url="http://www.hibernate.org/hib_docs/v3/reference/en/html/querycriteria.html">Hibernate Criteria</ulink>,
|
||||||
|
so if you are common with them, using Envers queries will be much easier.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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
|
||||||
|
<xref linkend="configuration"/>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section id="entities-at-revision">
|
||||||
|
|
||||||
|
<title>Querying for entities of a class at a given revision</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The entry point for this type of queries is:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting><![CDATA[AuditQuery query = getAuditReader()
|
||||||
|
.createQuery()
|
||||||
|
.forEntitiesAtRevision(MyEntity.class, revisionNumber);]]></programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You can then specify constraints, which should be met by the entities returned, by
|
||||||
|
adding restrictions, which can be obtained using the <literal>AuditEntity</literal>
|
||||||
|
factory class. For example, to select only entities, where the "name" property
|
||||||
|
is equal to "John":
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting><![CDATA[query.add(AuditEntity.property("name").eq("John"));]]></programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
And to select only entites that are related to a given entity:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting><![CDATA[query.add(AuditEntity.property("address").eq(relatedEntityInstance));
|
||||||
|
// or
|
||||||
|
query.add(AuditEntity.relatedId("address").eq(relatedEntityId));]]></programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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
|
||||||
|
<literal>getSingleResult()</literal> or <literal>getResultList()</literal> methods.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
A full query, can look for example like this:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting><![CDATA[List personsAtAddress = getAuditReader().createQuery()
|
||||||
|
.forEntitiesAtRevision(Person.class, 12)
|
||||||
|
.addOrder(AuditEntity.property("surname").desc())
|
||||||
|
.add(AuditEntity.relatedId("address").eq(addressId))
|
||||||
|
.setFirstResult(4)
|
||||||
|
.setMaxResults(2)
|
||||||
|
.getResultList();]]></programlisting>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="revisions-of-entity">
|
||||||
|
|
||||||
|
<title>Querying for revisions, at which entities of a given class changed</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The entry point for this type of queries is:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting><![CDATA[AuditQuery query = getAuditReader().createQuery()
|
||||||
|
.forRevisionsOfEntity(MyEntity.class, false, true);]]></programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You can add constraints to this query in the same way as to the previous one.
|
||||||
|
There are some additional possibilities:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<orderedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
using <literal>AuditEntity.revisionNumber()</literal> you can specify constraints, projections
|
||||||
|
and order on the revision number, in which the audited entity was modified
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
similarly, using <literal>AuditEntity.revisionProperty(propertyName)</literal> 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
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<literal>AuditEntity.revisionType()</literal> gives you access as above to the type of
|
||||||
|
the revision (ADD, MOD, DEL).
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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
|
||||||
|
<literal>MyEntity</literal> with id <literal>entityId</literal> has changed, after revision
|
||||||
|
number 42:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting><![CDATA[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();]]></programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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 <literal>actualDate</literal> for a given entity
|
||||||
|
was larger then a given value, but as small as possible:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting><![CDATA[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();
|
||||||
|
]]></programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The <literal>minimize()</literal> and <literal>maximize()</literal> methods return a criteria,
|
||||||
|
to which you can add constraints, which must be met by the entities with the
|
||||||
|
maximized/minimized properties.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You probably also noticed that there are two boolean parameters, passed when
|
||||||
|
creating the query. The first one, <literal>selectEntitiesOnly</literal>, 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).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
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 <literal>DefaultRevisionEntity</literal>). The third will be the type of the
|
||||||
|
revision (one of the values of the <literal>RevisionType</literal> enumeration:
|
||||||
|
ADD, MOD, DEL).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The second parameter, <literal>selectDeletedEntities</literal>, 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,
|
||||||
|
<literal>null</literal>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
<section>
|
<section>
|
||||||
<title>Understanding the Envers Schema</title>
|
<title>Understanding the Envers Schema</title>
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue