Criteria Queries

HQL Clause	Criteria Equivalent[s]
select	Not available
from	Criteria criteria = session.create Criteria(Student.class);
from joins	Criteria.setFetchMode()for associations.
where	net.sf.hibernate.expression.Expression to obtain built-in net.sf.hibernate.expression.Criterion
group by	Not available
having	Not available
order by	Criteria.addOrder() to add net.sf.hibernate.expression.Order

The Criteria interface, as shown in Figure 8.12, is returned by a simple Session.createCriteria() call.

Figure 8.12. Criteria Interface

[View full size image]

Normally, you will use the Expression factory, as shown in Figure 8.13, to obtain a criterion that you wish to apply.

Figure 8.13. Expression Factory

[View full size image]

Figure 8.14 shows the hierarchy of built-in criteria. Normally, you won't instantiate these directly, and instead will use the built-in Expression factory.

The code shown in Listing 8.3 returns the same result set as the HQL select student.firstName from Student as student where student.firstName like 'B%'.

Listing 8.3. Criteria Query

Criteria myQuery =
       hibernateSession.createCriteria(Student.class);
myQuery.add(Expression.like("firstName", "B%"));

Method Chaining

In addition to the standard method execution shown in Listing 8.3, the Criteria API supports the notion of method chaining. Simply put, most of the methods on the Criteria interface return the calling object (i.e., they conclude with the statement return this). This allows you to rewrite the code shown in Listing 8.3 as shown in Listing 8.4.

Listing 8.4. Chained Criteria Query

Criteria myQuery =
     hibernateSession.createCriteria(Student.class).add(
          Expression.like("firstName", "B%"));

As can be seen, this may lead to different (but equivalent) ways of expressing more complex statements. For example, the code shown in Listing 8.5 is equivalent to the code in Listing 8.6.

Listing 8.5. Complex Criteria

Criteria myQuery =
                hibernateSession.createCriteria(Student.class);
myQuery.add(Expression.like("firstName", "B%"));
myQuery.add(Expression.like("lastName", "S%"));
myQuery.setFetchMode("examresults", FetchMode.EAGER);
myQuery.setMaxResults(10);
myQuery.setTimeout(1000);

Listing 8.6. Complex Criteria with Method Chaining

Criteria myQuery =
     hibernateSession
          .createCriteria(Student.class)
          .add(Expression.like("firstName", "B%"))
          .add(Expression.like("lastName", "S%"))
          .setFetchMode("examresults", FetchMode.EAGER)
          .setMaxResults(10)
          .setTimeout(1000);

In certain instances, the more verbose method shown in Listing 8.5 is easier to understand and debug, but the choice of syntax is largely a matter of style.

Easily Override Lazy Settings

One helpful use of the Criteria API is the ability to easily override a lazy="true" setting in a Hibernate mapping with the use of the setFetchMode() method. For example, as shown in Listing 8.6, the method setFetchMode()overrides the lazy="true" setting in the Student mapping of the examresults collection.

Put another way, the setFetchMode() is a convenient way to express an HQL join statement.