437 lines
16 KiB
XML
437 lines
16 KiB
XML
<chapter id="querycriteria">
|
|
<title>Criteria Queries</title>
|
|
|
|
<para>
|
|
Hibernate features an intuitive, extensible criteria query API.
|
|
</para>
|
|
|
|
<sect1 id="querycriteria-creating">
|
|
<title>Creating a <literal>Criteria</literal> instance</title>
|
|
|
|
<para>
|
|
The interface <literal>org.hibernate.Criteria</literal> represents a query against
|
|
a particular persistent class. The <literal>Session</literal> is a factory for
|
|
<literal>Criteria</literal> instances.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Criteria crit = sess.createCriteria(Cat.class);
|
|
crit.setMaxResults(50);
|
|
List cats = crit.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-narrowing">
|
|
<title>Narrowing the result set</title>
|
|
|
|
<para>
|
|
An individual query criterion is an instance of the interface
|
|
<literal>org.hibernate.criterion.Criterion</literal>. The class
|
|
<literal>org.hibernate.criterion.Restrictions</literal> defines
|
|
factory methods for obtaining certain built-in
|
|
<literal>Criterion</literal> types.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.like("name", "Fritz%") )
|
|
.add( Restrictions.between("weight", minWeight, maxWeight) )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Restrictions may be grouped logically.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.like("name", "Fritz%") )
|
|
.add( Restrictions.or(
|
|
Restrictions.eq( "age", new Integer(0) ),
|
|
Restrictions.isNull("age")
|
|
) )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.in( "name", new String[] { "Fritz", "Izi", "Pk" } ) )
|
|
.add( Restrictions.disjunction()
|
|
.add( Restrictions.isNull("age") )
|
|
.add( Restrictions.eq("age", new Integer(0) ) )
|
|
.add( Restrictions.eq("age", new Integer(1) ) )
|
|
.add( Restrictions.eq("age", new Integer(2) ) )
|
|
) )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
There are quite a range of built-in criterion types (<literal>Restrictions</literal>
|
|
subclasses), but one that is especially useful lets you specify SQL directly.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.sql("lower({alias}.name) like lower(?)", "Fritz%", Hibernate.STRING) )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
The <literal>{alias}</literal> placeholder with be replaced by the row alias
|
|
of the queried entity.
|
|
</para>
|
|
|
|
<para>
|
|
An alternative approach to obtaining a criterion is to get it from a
|
|
<literal>Property</literal> instance. You can create a <literal>Property</literal>
|
|
by calling <literal>Property.forName()</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[
|
|
Property age = Property.forName("age");
|
|
List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.disjunction()
|
|
.add( age.isNull() )
|
|
.add( age.eq( new Integer(0) ) )
|
|
.add( age.eq( new Integer(1) ) )
|
|
.add( age.eq( new Integer(2) ) )
|
|
) )
|
|
.add( Property.forName("name").in( new String[] { "Fritz", "Izi", "Pk" } ) )
|
|
.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-ordering">
|
|
<title>Ordering the results</title>
|
|
|
|
<para>
|
|
You may order the results using <literal>org.hibernate.criterion.Order</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.like("name", "F%")
|
|
.addOrder( Order.asc("name") )
|
|
.addOrder( Order.desc("age") )
|
|
.setMaxResults(50)
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Property.forName("name").like("F%") )
|
|
.addOrder( Property.forName("name").asc() )
|
|
.addOrder( Property.forName("age").desc() )
|
|
.setMaxResults(50)
|
|
.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-associations" revision="2">
|
|
<title>Associations</title>
|
|
|
|
<para>
|
|
You may easily specify constraints upon related entities by navigating
|
|
associations using <literal>createCriteria()</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.like("name", "F%")
|
|
.createCriteria("kittens")
|
|
.add( Restrictions.like("name", "F%")
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
note that the second <literal>createCriteria()</literal> returns a new
|
|
instance of <literal>Criteria</literal>, which refers to the elements of
|
|
the <literal>kittens</literal> collection.
|
|
</para>
|
|
|
|
<para>
|
|
The following, alternate form is useful in certain circumstances.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.createAlias("kittens", "kt")
|
|
.createAlias("mate", "mt")
|
|
.add( Restrictions.eqProperty("kt.name", "mt.name") )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
(<literal>createAlias()</literal> does not create a new instance of
|
|
<literal>Criteria</literal>.)
|
|
</para>
|
|
|
|
<para>
|
|
Note that the kittens collections held by the <literal>Cat</literal> instances
|
|
returned by the previous two queries are <emphasis>not</emphasis> pre-filtered
|
|
by the criteria! If you wish to retrieve just the kittens that match the
|
|
criteria, you must use a <literal>ResultTransformer</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.createCriteria("kittens", "kt")
|
|
.add( Restrictions.eq("name", "F%") )
|
|
.setResultTransformer(Criteria.ALIAS_TO_ENTITY_MAP)
|
|
.list();
|
|
Iterator iter = cats.iterator();
|
|
while ( iter.hasNext() ) {
|
|
Map map = (Map) iter.next();
|
|
Cat cat = (Cat) map.get(Criteria.ROOT_ALIAS);
|
|
Cat kitten = (Cat) map.get("kt");
|
|
}]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-dynamicfetching" revision="1">
|
|
<title>Dynamic association fetching</title>
|
|
|
|
<para>
|
|
You may specify association fetching semantics at runtime using
|
|
<literal>setFetchMode()</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.like("name", "Fritz%") )
|
|
.setFetchMode("mate", FetchMode.EAGER)
|
|
.setFetchMode("kittens", FetchMode.EAGER)
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
This query will fetch both <literal>mate</literal> and <literal>kittens</literal>
|
|
by outer join. See <xref linkend="performance-fetching"/> for more information.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-examples">
|
|
<title>Example queries</title>
|
|
|
|
<para>
|
|
The class <literal>org.hibernate.criterion.Example</literal> allows
|
|
you to construct a query criterion from a given instance.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Cat cat = new Cat();
|
|
cat.setSex('F');
|
|
cat.setColor(Color.BLACK);
|
|
List results = session.createCriteria(Cat.class)
|
|
.add( Example.create(cat) )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Version properties, identifiers and associations are ignored. By default,
|
|
null valued properties are excluded.
|
|
</para>
|
|
|
|
<para>
|
|
You can adjust how the <literal>Example</literal> is applied.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Example example = Example.create(cat)
|
|
.excludeZeroes() //exclude zero valued properties
|
|
.excludeProperty("color") //exclude the property named "color"
|
|
.ignoreCase() //perform case insensitive string comparisons
|
|
.enableLike(); //use like for string comparisons
|
|
List results = session.createCriteria(Cat.class)
|
|
.add(example)
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
You can even use examples to place criteria upon associated objects.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.add( Example.create(cat) )
|
|
.createCriteria("mate")
|
|
.add( Example.create( cat.getMate() ) )
|
|
.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-projection">
|
|
<title>Projections, aggregation and grouping</title>
|
|
<para>
|
|
The class <literal>org.hibernate.criterion.Projections</literal> is a
|
|
factory for <literal>Projection</literal> instances. We apply a
|
|
projection to a query by calling <literal>setProjection()</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.rowCount() )
|
|
.add( Restrictions.eq("color", Color.BLACK) )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.projectionList()
|
|
.add( Projections.rowCount() )
|
|
.add( Projections.avg("weight") )
|
|
.add( Projections.max("weight") )
|
|
.add( Projections.groupProperty("color") )
|
|
)
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
There is no explicit "group by" necessary in a criteria query. Certain
|
|
projection types are defined to be <emphasis>grouping projections</emphasis>,
|
|
which also appear in the SQL <literal>group by</literal> clause.
|
|
</para>
|
|
|
|
<para>
|
|
An alias may optionally be assigned to a projection, so that the projected value
|
|
may be referred to in restrictions or orderings. Here are two different ways to
|
|
do this:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.alias( Projections.groupProperty("color"), "colr" ) )
|
|
.addOrder( Order.asc("colr") )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.groupProperty("color").as("colr") )
|
|
.addOrder( Order.asc("colr") )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
The <literal>alias()</literal> and <literal>as()</literal> methods simply wrap a
|
|
projection instance in another, aliased, instance of <literal>Projection</literal>.
|
|
As a shortcut, you can assign an alias when you add the projection to a
|
|
projection list:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.projectionList()
|
|
.add( Projections.rowCount(), "catCountByColor" )
|
|
.add( Projections.avg("weight"), "avgWeight" )
|
|
.add( Projections.max("weight"), "maxWeight" )
|
|
.add( Projections.groupProperty("color"), "color" )
|
|
)
|
|
.addOrder( Order.desc("catCountByColor") )
|
|
.addOrder( Order.desc("avgWeight") )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Domestic.class, "cat")
|
|
.createAlias("kittens", "kit")
|
|
.setProjection( Projections.projectionList()
|
|
.add( Projections.property("cat.name"), "catName" )
|
|
.add( Projections.property("kit.name"), "kitName" )
|
|
)
|
|
.addOrder( Order.asc("catName") )
|
|
.addOrder( Order.asc("kitName") )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
You can also use <literal>Property.forName()</literal> to express projections:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Property.forName("name") )
|
|
.add( Property.forName("color").eq(Color.BLACK) )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.projectionList()
|
|
.add( Projections.rowCount().as("catCountByColor") )
|
|
.add( Property.forName("weight").avg().as("avgWeight") )
|
|
.add( Property.forName("weight").max().as("maxWeight") )
|
|
.add( Property.forName("color").group().as("color" )
|
|
)
|
|
.addOrder( Order.desc("catCountByColor") )
|
|
.addOrder( Order.desc("avgWeight") )
|
|
.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-detachedqueries">
|
|
<title>Detached queries and subqueries</title>
|
|
<para>
|
|
The <literal>DetachedCriteria</literal> class lets you create a query outside the scope
|
|
of a session, and then later execute it using some arbitrary <literal>Session</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[DetachedCriteria query = DetachedCriteria.forClass(Cat.class)
|
|
.add( Property.forName("sex").eq('F') );
|
|
|
|
Session session = ....;
|
|
Transaction txn = session.beginTransaction();
|
|
List results = query.getExecutableCriteria(session).setMaxResults(100).list();
|
|
txn.commit();
|
|
session.close();]]></programlisting>
|
|
|
|
<para>
|
|
A <literal>DetachedCriteria</literal> may also be used to express a subquery. Criterion
|
|
instances involving subqueries may be obtained via <literal>Subqueries</literal> or
|
|
<literal>Property</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[DetachedCriteria avgWeight = DetachedCriteria.forClass(Cat.class)
|
|
.setProjection( Property.forName("weight").avg() );
|
|
session.createCriteria(Cat.class)
|
|
.add( Property.forName("weight).gt(avgWeight) )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[DetachedCriteria weights = DetachedCriteria.forClass(Cat.class)
|
|
.setProjection( Property.forName("weight") );
|
|
session.createCriteria(Cat.class)
|
|
.add( Subqueries.geAll("weight", weights) )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Even correlated subqueries are possible:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[DetachedCriteria avgWeightForSex = DetachedCriteria.forClass(Cat.class, "cat2")
|
|
.setProjection( Property.forName("weight").avg() )
|
|
.add( Property.forName("cat2.sex").eqProperty("cat.sex") );
|
|
session.createCriteria(Cat.class, "cat")
|
|
.add( Property.forName("weight).gt(avgWeightForSex) )
|
|
.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<!--TODO: ResultSetTransformer + aliasing. AliasToBeanTransformer allow returning arbitrary
|
|
user objects - similar to setResultClass in JDO2. General use of ResultTransformer
|
|
could also be explained. -->
|
|
|
|
<sect1 id="query-criteria-naturalid">
|
|
<title>Queries by natural identifier</title>
|
|
|
|
<para>
|
|
For most queries, including criteria queries, the query cache is not very efficient,
|
|
because query cache invalidation occurs too frequently. However, there is one special
|
|
kind of query where we can optimize the cache invalidation algorithm: lookups by a
|
|
constant natural key. In some applications, this kind of query occurs frequently.
|
|
The criteria API provides special provision for this use case.
|
|
</para>
|
|
|
|
<para>
|
|
First, you should map the natural key of your entity using
|
|
<literal><natural-id></literal>, and enable use of the second-level cache.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[<class name="User">
|
|
<cache usage="read-write"/>
|
|
<id name="id">
|
|
<generator class="increment"/>
|
|
</id>
|
|
<natural-id>
|
|
<property name="name"/>
|
|
<property name="org"/>
|
|
</natural-id>
|
|
<property name="password"/>
|
|
</class>]]></programlisting>
|
|
|
|
<para>
|
|
Note that this functionality is not intended for use with entities with
|
|
<emphasis>mutable</emphasis> natural keys.
|
|
</para>
|
|
|
|
<para>
|
|
Next, enable the Hibernate query cache.
|
|
</para>
|
|
|
|
<para>
|
|
Now, <literal>Restrictions.naturalId()</literal> allows us to make use of
|
|
the more efficient cache algorithm.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[session.createCriteria(User.class)
|
|
.add( Restrictions.naturalId()
|
|
.set("name", "gavin")
|
|
.set("org", "hb")
|
|
).setCacheable(true)
|
|
.uniqueResult();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|