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 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 two-parameter 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. |
| 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-3. |
| 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 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. |
| 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.