Criteria
public interface Criteria
extends CriteriaSpecification
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();
Author:
Gavin King
See Also:
Session.createCriteria(java.lang.Class), Restrictions, Projections, Order, Criterion, Projection, a disconnected version of this API
| Fields inherited from interface org.hibernate.criterion.CriteriaSpecification |
| ALIAS_TO_ENTITY_MAP, DISTINCT_ROOT_ENTITY, FULL_JOIN, INNER_JOIN, LEFT_JOIN, PROJECTION, ROOT_ALIAS, ROOT_ENTITY |
| Method Summary | |
| add(Criterion criterion) | |
| createAlias(String associationPath, String alias) | |
| createAlias(String associationPath, String alias, int joinType) | |
| createCriteria(String associationPath) | |
| createCriteria(String associationPath, int joinType) | |
| createCriteria(String associationPath, String alias) | |
| createCriteria(String associationPath, String alias, int joinType) | |
| getAlias() | |
| list() | |
| scroll() | |
| scroll(ScrollMode scrollMode) | |
| setCacheable(boolean cacheable) | |
| setCacheMode(CacheMode cacheMode) | |
| setCacheRegion(String cacheRegion) | |
| setComment(String comment) | |
| setFetchMode(String associationPath, FetchMode mode) | |
| setFetchSize(int fetchSize) | |
| setFirstResult(int firstResult) | |
| setFlushMode(FlushMode flushMode) | |
| setLockMode(LockMode lockMode) | |
| setLockMode(String alias, LockMode lockMode) | |
| setMaxResults(int maxResults) | |
| setProjection(Projection projection) | |
| setResultTransformer(ResultTransformer resultTransformer) | |
| setTimeout(int timeout) | |
| uniqueResult() | |
getAlias
public String getAlias()
Get the alias of the entity encapsulated by this criteria instance.
Returns:
The alias for the encapsulated entity.
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.
Parameters:
projection - The projection representing the overall "shape" of the query results.
Returns:
this (for method chaining)
add
Add a restriction to constrain the results to be retrieved.
Parameters:
criterion - The criterion object representing the restriction to be applied.
Returns:
this (for method chaining)
addOrder
Add an ordering to the result set.
Parameters:
order - The order object representing an ordering to be applied to the results.
Returns:
this (for method chaining)
setFetchMode
Specify an association fetching strategy for an association or a collection of values.
Parameters:
associationPath - a dot seperated property path
mode - The fetch mode for the referenced association
Returns:
this (for method chaining)
Throws:
setLockMode
Set the lock mode of the current entity
Parameters:
lockMode - The lock mode to be applied
Returns:
this (for method chaining)
setLockMode
Set the lock mode of the aliased entity
Parameters:
alias - The previously assigned alias representing the entity to which the given lock mode should apply.
lockMode - The lock mode to be applied
Returns:
this (for method chaining)
createAlias
Join an association, assigning an alias to the joined association.
Functionally equivalent to createAlias(String, String, int) using CriteriaSpecification.INNER_JOIN for the joinType.
Parameters:
associationPath - A dot-seperated property path
alias - The alias to assign to the joined association (for later reference).
Returns:
this (for method chaining)
Throws:
createAlias
public Criteria createAlias(String associationPath,
String alias,
int joinType)
throws HibernateException
Join an association using the specified join-type, assigning an alias to the joined association.
The joinType is expected to be one of CriteriaSpecification.INNER_JOIN (the default), CriteriaSpecification.FULL_JOIN, orCriteriaSpecification.LEFT_JOIN.
Parameters:
associationPath - A dot-seperated property path
alias - The alias to assign to the joined association (for later reference).
joinType - The type of join to use.
Returns:
this (for method chaining)
Throws:
createCriteria
public Criteria createCriteria(String associationPath)
throws HibernateException
Create a new Criteria, "rooted" at the associated entity.
Functionally equivalent to createCriteria(String, int) using CriteriaSpecification.INNER_JOIN for the joinType.
Parameters:
associationPath - A dot-seperated property path
Returns:
the created "sub criteria"
Throws:
createCriteria
Create a new Criteria, "rooted" at the associated entity, using the specified join type.
Parameters:
associationPath - A dot-seperated property path
joinType - The type of join to use.
Returns:
the created "sub criteria"
Throws:
createCriteria
Create a new Criteria, "rooted" at the associated entity, assigning the given alias.
Functionally equivalent to createCriteria(String, String, int) using CriteriaSpecification.INNER_JOIN for the joinType.
Parameters:
associationPath - A dot-seperated property path
alias - The alias to assign to the joined association (for later reference).
Returns:
the created "sub criteria"
Throws:
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.
Parameters:
associationPath - A dot-seperated property path
alias - The alias to assign to the joined association (for later reference).
joinType - The type of join to use.
Returns:
the created "sub criteria"
Throws:
setResultTransformer
public Criteria setResultTransformer(ResultTransformer resultTransformer)
Set a strategy for handling the query results. This determines the "shape" of the query result.
Parameters:
resultTransformer - The transformer to apply
Returns:
this (for method chaining)
See Also:
CriteriaSpecification.ROOT_ENTITY, CriteriaSpecification.DISTINCT_ROOT_ENTITY,CriteriaSpecification.ALIAS_TO_ENTITY_MAP, CriteriaSpecification.PROJECTION
setMaxResults
public Criteria setMaxResults(int maxResults)
Set a limit upon the number of objects to be retrieved.
Parameters:
maxResults - the maximum number of results
Returns:
this (for method chaining)
setFirstResult
public Criteria setFirstResult(int firstResult)
Set the first result to be retrieved.
Parameters:
firstResult - the first result to retrieve, numbered from 0
Returns:
this (for method chaining)
setFetchSize
public Criteria setFetchSize(int fetchSize)
Set a fetch size for the underlying JDBC query.
Parameters:
fetchSize - the fetch size
Returns:
this (for method chaining)
See Also:
setTimeout
public Criteria setTimeout(int timeout)
Set a timeout for the underlying JDBC query.
Parameters:
timeout - The timeout value to apply.
Returns:
this (for method chaining)
See Also:
Statement.setQueryTimeout(int)
setCacheable
public Criteria setCacheable(boolean cacheable)
Enable caching of this query result, provided query caching is enabled for the underlying session factory.
Parameters:
cacheable - Should the result be considered cacheable; default is to not cache (false).
Returns:
this (for method chaining)
setCacheRegion
Set the name of the cache region to use for query result caching.
Parameters:
cacheRegion - the name of a query cache region, or null for the default query cache
Returns:
this (for method chaining)
See Also:
setComment
Add a comment to the generated SQL.
Parameters:
comment - a human-readable string
Returns:
this (for method chaining)
setFlushMode
Override the flush mode for this particular query.
Parameters:
flushMode - The flush mode to use.
Returns:
this (for method chaining)
setCacheMode
Override the cache mode for this particular query.
Parameters:
cacheMode - The cache mode to use.
Returns:
this (for method chaining)
list
public List list()
throws HibernateException
Get the results.
Returns:
The list of matched query results.
Throws:
scroll
public ScrollableResults scroll()
throws HibernateException
Get the results as an instance of ScrollableResults
Returns:
The ScrollableResults representing the matched query results.
Throws:
scroll
public ScrollableResults scroll(ScrollMode scrollMode)
throws HibernateException
Get the results as an instance of ScrollableResults based on the given scroll mode.
Parameters:
scrollMode - Indicates the type of underlying database cursor to request.
Returns:
The ScrollableResults representing the matched query results.
Throws:
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.
Returns:
the single result or null
Throws:
HibernateException - if there is more than one matching result
