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.



Hibernate. A Developer's Notebook
Hibernate: A Developers Notebook
ISBN: 0596006969
EAN: 2147483647
Year: 2003
Pages: 65
Authors: James Elliott

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net