Criteria is a simplified API for retrieving entities
by composing
Criterion objects. This is a very
convenient approach for functionality like "search" screens
where there is a variable number of conditions to be placed
upon the result set.
The
Session is a factory for
Criteria.
Criterion instances are usually obtained via
the factory methods on
Restrictions. eg.
List cats = session.createCriteria(Cat.class)
.add( Restrictions.like("name", "Iz%") )
.add( Restrictions.gt( "weight", new Float(minWeight) ) )
.addOrder( Order.asc("age") )
.list();
You may navigate associations using
createAlias() or
createCriteria().
List cats = session.createCriteria(Cat.class)
.createCriteria("kittens")
.add( Restrictions.like("name", "Iz%") )
.list();
List cats = session.createCriteria(Cat.class)
.createAlias("kittens", "kit")
.add( Restrictions.like("kit.name", "Iz%") )
.list();
You may specify projection and aggregation using
Projection
instances obtained via the factory methods on
Projections.
List cats = session.createCriteria(Cat.class)
.setProjection( Projections.projectionList()
.add( Projections.rowCount() )
.add( Projections.avg("weight") )
.add( Projections.max("weight") )
.add( Projections.min("weight") )
.add( Projections.groupProperty("color") )
)
.addOrder( Order.asc("color") )
.list();
add
public Criteria add(Criterion criterion)
Add a
restriction
to constrain the results to be
retrieved.
criterion
- The criterion
object representing the
restriction to be applied.
- this (for method chaining)
addOrder
public Criteria addOrder(Order order)
order
- The order
object representing an ordering
to be applied to the results.
- this (for method chaining)
createAlias
public Criteria createAlias(String associationPath,
String alias)
throws HibernateException
associationPath
- A dot-seperated property pathalias
- The alias to assign to the joined association (for later reference).
- this (for method chaining)
createAlias
public Criteria createAlias(String associationPath,
String alias,
int joinType)
throws HibernateException
associationPath
- A dot-seperated property pathalias
- The alias to assign to the joined association (for later reference).joinType
- The type of join to use.
- this (for method chaining)
createCriteria
public Criteria createCriteria(String associationPath)
throws HibernateException
associationPath
- A dot-seperated property path
- the created "sub criteria"
createCriteria
public Criteria createCriteria(String associationPath,
String alias)
throws HibernateException
associationPath
- A dot-seperated property pathalias
- The alias to assign to the joined association (for later reference).
- the created "sub criteria"
createCriteria
public Criteria createCriteria(String associationPath,
String alias,
int joinType)
throws HibernateException
Create a new Criteria, "rooted" at the associated entity,
assigning the given alias and using the specified join type.
associationPath
- A dot-seperated property pathalias
- The alias to assign to the joined association (for later reference).joinType
- The type of join to use.
- the created "sub criteria"
createCriteria
public Criteria createCriteria(String associationPath,
int joinType)
throws HibernateException
Create a new Criteria, "rooted" at the associated entity, using the
specified join type.
associationPath
- A dot-seperated property pathjoinType
- The type of join to use.
- the created "sub criteria"
getAlias
public String getAlias()
Get the alias of the entity encapsulated by this criteria instance.
- The alias for the encapsulated entity.
list
public List list()
throws HibernateException
Get the results.
- The list of matched query results.
setCacheMode
public Criteria setCacheMode(CacheMode cacheMode)
Override the cache mode for this particular query.
cacheMode
- The cache mode to use.
- this (for method chaining)
setCacheRegion
public Criteria setCacheRegion(String cacheRegion)
Set the name of the cache region to use for query result caching.
cacheRegion
- the name of a query cache region, or null
for the default query cache
- this (for method chaining)
setCacheable
public Criteria setCacheable(boolean cacheable)
Enable caching of this query result, provided query caching is enabled
for the underlying session factory.
cacheable
- Should the result be considered cacheable; default is
to not cache (false).
- this (for method chaining)
setComment
public Criteria setComment(String comment)
Add a comment to the generated SQL.
comment
- a human-readable string
- this (for method chaining)
setFetchMode
public Criteria setFetchMode(String associationPath,
FetchMode mode)
throws HibernateException
Specify an association fetching strategy for an association or a
collection of values.
associationPath
- a dot seperated property pathmode
- The fetch mode for the referenced association
- this (for method chaining)
setFetchSize
public Criteria setFetchSize(int fetchSize)
Set a fetch size for the underlying JDBC query.
fetchSize
- the fetch size
- this (for method chaining)
java.sql.Statement.setFetchSize
setFirstResult
public Criteria setFirstResult(int firstResult)
Set the first result to be retrieved.
firstResult
- the first result to retrieve, numbered from 0
- this (for method chaining)
setFlushMode
public Criteria setFlushMode(FlushMode flushMode)
Override the flush mode for this particular query.
flushMode
- The flush mode to use.
- this (for method chaining)
setLockMode
public Criteria setLockMode(String alias,
LockMode lockMode)
Set the lock mode of the aliased entity
alias
- The previously assigned alias representing the entity to
which the given lock mode should apply.lockMode
- The lock mode to be applied
- this (for method chaining)
setLockMode
public Criteria setLockMode(LockMode lockMode)
Set the lock mode of the current entity
lockMode
- The lock mode to be applied
- this (for method chaining)
setMaxResults
public Criteria setMaxResults(int maxResults)
Set a limit upon the number of objects to be retrieved.
maxResults
- the maximum number of results
- this (for method chaining)
setProjection
public Criteria setProjection(Projection projection)
Used to specify that the query results will be a projection (scalar in
nature). Implicitly specifies the
CriteriaSpecification.PROJECTION
result transformer.
The individual components contained within the given
projection
determines the overall "shape" of the
query result.
projection
- The projection representing the overall "shape" of the
query results.
- this (for method chaining)
setResultTransformer
public Criteria setResultTransformer(ResultTransformer resultTransformer)
Set a strategy for handling the query results. This determines the
"shape" of the query result.
resultTransformer
- The transformer to apply
- this (for method chaining)
setTimeout
public Criteria setTimeout(int timeout)
Set a timeout for the underlying JDBC query.
timeout
- The timeout value to apply.
- this (for method chaining)
java.sql.Statement.setQueryTimeout
uniqueResult
public Object uniqueResult()
throws HibernateException
Convenience method to return a single instance that matches
the query, or null if the query returns no results.
- the single result or null