mirror of
https://github.com/hibernate/hibernate-orm
synced 2025-02-28 23:09:13 +00:00
80baaa797b
git-svn-id: https://svn.jboss.org/repos/hibernate/trunk/Hibernate3/doc@5443 1b8cb986-b30d-0410-93ca-fae66ebed9b2
278 lines
10 KiB
XML
278 lines
10 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>
|
|
|
|
</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>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-associations">
|
|
<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 <literal>returnMaps()</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.createCriteria("kittens", "kt")
|
|
.add( Restrictions.eq("name", "F%") )
|
|
.returnMaps()
|
|
.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 to optionally be assigned to a projection, so that it may be
|
|
referred to in restrictions or orderings.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.alias( Projections.groupProperty("color"), "colr" ) )
|
|
.add( Restrictions.ne("colr", Color.BLACK) )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.projectionList()
|
|
.add( Projections.rowCount(), "catCountByColor" )
|
|
.add( Projections.avg("weight"), "avgWeight" )
|
|
.add( Projections.max("weight") )
|
|
.add( Projections.groupProperty("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>
|
|
|
|
</sect1>
|
|
|
|
<!--TODO: Projection API + ResultSetTransformer + aliasing. AliasToBeanTransformer allow returning arbitrary user objects - similar to setResultClass in JDO2. General use of
|
|
ResultTransformer could also be explained.-->
|
|
</chapter> |