B.1 The Expression Factory

     

Hibernate provides the class net.sf.hibernate.expression.Expression as a factory for creating the Criterion instances you use to set up criteria queries. Expression 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. Here is a summary of the available options.

Method	Parameters	Purpose
allEq	Map properties	A shortcut for requiring several properties to have particular values. The keys of the supplied map are the names of the properties you want to constrain, while the values in the map are the target values each property must equal if an entity is to be included in the query results. The returned Criterion ensures that each named property has the corresponding value.
and	Criterion lhs, Criterion rhs	Builds a compound Criterion that requires both halves to be met in order for the whole to succeed.
between	String property, Object low, Object high	Requires the value of the named property to fall between the values of low and high .
conjunction	None	Creates a Conjunction object which can be used to build an "and" criterion with as many pieces as you need. Simply call its add() method with each of the Criterion instances you want to check. The conjunction will be true if and only if all its component criteria are true. This is more convenient than building a tree of and() criteria "by hand." The add() method of the Criteria interface acts as though it contains a Conjunction .
disjunction	None	Creates a Disjunction object that can be used to build an "or" criterion with as many pieces as you need. Simply call its add() method with each of the Criterion instances you want to check. The disjunction will be true if any of its component criteria are true. This is more convenient than building a tree of or() criteria "by hand." See Example 8-10.
eq	String property, Object value	Requires the named property to have the specified value.
eqProperty	String property1, String property2	Requires the two named properties to have the same value.
ge	String property, Object value	Requires the named property to be greater than or equal to the specified value.
gt	String property, Object value	Requires the named property to be greater than the specified value.
ilike	String property, String value	A case-insensitive "like" operator. See like , below.
ilike	String property, String value, MatchMode mode	A case-insensitive "like" operator for people who don't want to mess with "like" syntax and just want to match a substring. MatchMode is a type-safe enumeration with values START , END , ANYWHERE , and EXACT . This method simply adjusts the syntax of value to reflect the kind of matching specified by mode , then calls the twoparameter ilike() .
in	String property, Collection values	A shortcut for allowing the named property to have any of the values contained in the collection. This is more convenient than building up a disjunction() of eq() criteria "by hand."
in	String property, Object[] values	A shortcut for allowing the named property to have any of the values contained in the array. This is more convenient than building up a disjunction() of eq() criteria "by hand."
isNotNull	String property	Requires the named property to have a value other than null .
isNull	String property	Requires the named property to be null .
le	String property, Object value	Requires the named property to be less than or equal to the specified value. See Example 8-3.
leProperty	String property1, String property2	Requires the first named property to be less than or equal to the second.
like	String property, String value	Requires the named property to be "like" the specified value (in the sense of the SQL like operator, which allows simple pattern matching). See Example 8-8 and Example 8-13.
like	String property, String value, MatchMode mode	A "like" operator for people who don't want to mess with "like" syntax and just want to match a substring. MatchMode is a type-safe enumeration with values START, END, ANYWHERE , and EXACT . This method simply adjusts the syntax of value to reflect the kind of matching specified by mode , then calls the two-parameter like() .
lt	String property, Object value	Requires the named property to be less than the specified value.
ltProperty	String property1, String property2	Requires the first named property to be less than the second.
not	Criterion value	Negates the supplied Criterion (if it matched, this one fails, and vice versa).
or	Criterion lhs, Criterion rhs	Builds a compound Criterion that succeeds if either of its halves matches.
sql	String sql	Apply a constraint expressed in the native SQL dialect of the underlying database system. This can be very powerful, but be aware it might lead to loss of portability.
sql	String sql,Object[] values, Type[] types	Apply a constraint expressed in the native SQL of the underlying database, with the supplied JDBC parameters. This can be very powerful, but be aware it might lead to loss of portability.
sql	String sql, Object value, Type type	Apply a constraint expressed in the native SQL of the underlying database, with the supplied JDBC parameters. This can be very powerful, but be aware it might lead to loss of portability.

When specifying query text for the sql() 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 of 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 some kinds of queries that are not yet supported by this API, so you may not always be able to avoid HQL even if you want to.

Despite these caveats, many 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.