The Criteria API: Appendix B - Harnessing Hibernate

Hibernate provides the class org.hibernate.criterion.Restrictions as a factory for creating the Criterion instances you use to narrow down the objects (rows) you want from criteria queries. Restrictions defines a bunch of static methods you can invoke to conveniently create each of the standard Criterion implementations available in Hibernate, using parameters you supply. These criteria are used to determine which persistent objects from the database are included in the results of your query. The following table provides a summary of the available options.

When specifying query text for the sqlRestriction⁠⁠(⁠ ⁠) methods, any occurrences of the string “{alias}” within the query will be replaced by the actual alias of the table on which the query is being performed.

Many of these methods accept Criterion instances as arguments, allowing you to build compound criteria trees with as much complexity as you need. conjunction⁠⁠(⁠ ⁠) and disjunction⁠⁠(⁠ ⁠) return objects that make it even easier to add criteria, by returning objects with add⁠⁠(⁠ ⁠) methods you can call as many times as you’d like to add criteria. If your query gets sufficiently complex, however, it might be easier to express and understand in HQL. There are also a few remaining kinds of queries that are not yet supported by this API, so you may not always be able to avoid HQL. But that’s becoming increasingly rare—most of the kinds of bread-and-butter queries that come up all the time in application development are expressed very naturally and easily in this API, leading to readable and compact Java code that can be checked for correctness at compile-time.

Hibernate provides the class org.hibernate.criterion.Projections as a factory for creating the Projection instances you use to narrow down the properties (columns) you want from criteria queries, and requesting the calculation of aggregate values. Projections defines static methods you can invoke to conveniently create each of the standard Projection implementations available in Hibernate, using parameters you supply. These projections are used to narrow, group or transform the properties that get included in the results of your query. Here is a summary of the available options.

You can ask Hibernate (and thereby, the underlying database system) to sort your results in a particular order. The class org.hibernate.criterion.Order represents these ordering requests, and offers two static factory methods for creating the instances you need, which can then be added to your query. Once you’ve obtained your Order instance, you can call the nonstatic method ignoreCase⁠⁠(⁠ ⁠) on it if you would like your results sorted in a case-insensitive way.

In the methods we’ve been looking at so far, you start with the criterion, projection, or order you’re interested in creating, and then supply the name of the property with which you want to work as a parameter. The Criteria API also lets you work in the opposite direction, starting with the property and then calling a method to build a criterion or projection based on it. The class org.hibernate.criterion.Property is a factory for creating the Property instances you use when you prefer this approach. Property defines a single static method, forName⁠⁠(⁠ ⁠), which you can invoke to create an instance representing a particular property. Once you’ve got that instance, you can call one of the following methods to create criteria, projections and orderings based on the property it represents. Here is a list of the more commonly useful methods; the ones we omit have to do with detached criteria and subqueries, which are beyond the scope of this book. When you want to learn about them, see the Advanced query options chapter of Java Persistence with Hibernate or Detached queries and subqueries in the online reference.