org.hibernate
Interface Criteria

All Superinterfaces:
CriteriaSpecification
All Known Implementing Classes:
CriteriaImpl, CriteriaImpl.Subcriteria

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

Field Summary
 
Fields inherited from interface org.hibernate.criterion.CriteriaSpecification
ALIAS_TO_ENTITY_MAP, DISTINCT_ROOT_ENTITY, PROJECTION, ROOT_ALIAS, ROOT_ENTITY
 
Method Summary
 Criteria add(Criterion criterion)
          Add a Criterion to constrain the results to be retrieved.
 Criteria addOrder(Order order)
          Add an Order to the result set.
 Criteria createAlias(String associationPath, String alias)
          Join an association, assigning an alias to the joined entity
 Criteria createCriteria(String associationPath)
          Create a new Criteria, "rooted" at the associated entity
 Criteria createCriteria(String associationPath, String alias)
          Create a new Criteria, "rooted" at the associated entity, assigning the given alias
 String getAlias()
          Get the alias of the entity
 List list()
          Get the results.
 ScrollableResults scroll()
          Get the results as an instance of ScrollableResults.
 ScrollableResults scroll(ScrollMode scrollMode)
          Get the results as an instance of ScrollableResults.
 Criteria setCacheable(boolean cacheable)
          Enable caching of this query result set
 Criteria setCacheMode(CacheMode cacheMode)
          Override the cache mode
 Criteria setCacheRegion(String cacheRegion)
          Set the name of the cache region.
 Criteria setComment(String comment)
          Add a comment to the generated SQL
 Criteria setFetchMode(String associationPath, FetchMode mode)
          Specify an association fetching strategy for a one-to-many, many-to-one or one-to-one association, or for a collection of values.
 Criteria setFetchSize(int fetchSize)
          Set a fetch size for the underlying JDBC query.
 Criteria setFirstResult(int firstResult)
          Set the first result to be retrieved.
 Criteria setFlushMode(FlushMode flushMode)
          Override the flush mode
 Criteria setLockMode(LockMode lockMode)
          Set the lock mode of the current entity
 Criteria setLockMode(String alias, LockMode lockMode)
          Set the lock mode of the aliased entity
 Criteria setMaxResults(int maxResults)
          Set a limit upon the number of objects to be retrieved.
 Criteria setProjection(Projection projection)
          Set a projection of projection list, and select the PROJECTION result transformer
 Criteria setResultTransformer(ResultTransformer resultTransformer)
          Set a strategy for handling the query results.
 Criteria setTimeout(int timeout)
          Set a timeout for the underlying JDBC query.
 Object uniqueResult()
          Convenience method to return a single instance that matches the query, or null if the query returns no results.
 

Method Detail

add

public Criteria add(Criterion criterion)
Add a Criterion to constrain the results to be retrieved.

Parameters:
criterion -
Returns:
Criteria

addOrder

public Criteria addOrder(Order order)
Add an Order to the result set.

Parameters:
order -
Returns:
Criteria

setFetchMode

public Criteria setFetchMode(String associationPath,
                             FetchMode mode)
                      throws HibernateException
Specify an association fetching strategy for a one-to-many, many-to-one or one-to-one association, or for a collection of values.

Parameters:
associationPath - a dot seperated property path
mode - the fetch mode
Returns:
the Criteria object for method chaining
Throws:
HibernateException

createAlias

public Criteria createAlias(String associationPath,
                            String alias)
                     throws HibernateException
Join an association, assigning an alias to the joined entity

Throws:
HibernateException

createCriteria

public Criteria createCriteria(String associationPath)
                        throws HibernateException
Create a new Criteria, "rooted" at the associated entity

Throws:
HibernateException

createCriteria

public Criteria createCriteria(String associationPath,
                               String alias)
                        throws HibernateException
Create a new Criteria, "rooted" at the associated entity, assigning the given alias

Throws:
HibernateException

setProjection

public Criteria setProjection(Projection projection)
Set a projection of projection list, and select the PROJECTION result transformer


getAlias

public String getAlias()
Get the alias of the entity


setResultTransformer

public Criteria setResultTransformer(ResultTransformer resultTransformer)
Set a strategy for handling the query results. This determines the "shape" of the query result set.

Parameters:
resultTransformer -
See Also:
CriteriaSpecification.ROOT_ENTITY, CriteriaSpecification.DISTINCT_ROOT_ENTITY, CriteriaSpecification.ALIAS_TO_ENTITY_MAP

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:
Criteria

setFirstResult

public Criteria setFirstResult(int firstResult)
Set the first result to be retrieved.

Parameters:
firstResult - the first result, numbered from 0
Returns:
Criteria

setFetchSize

public Criteria setFetchSize(int fetchSize)
Set a fetch size for the underlying JDBC query.

Parameters:
fetchSize - the fetch size

setTimeout

public Criteria setTimeout(int timeout)
Set a timeout for the underlying JDBC query.

Parameters:
timeout -
Returns:
Criteria

setCacheable

public Criteria setCacheable(boolean cacheable)
Enable caching of this query result set


setCacheRegion

public Criteria setCacheRegion(String cacheRegion)
Set the name of the cache region.

Parameters:
cacheRegion - the name of a query cache region, or null for the default query cache

list

public List list()
          throws HibernateException
Get the results.

Returns:
List
Throws:
HibernateException

scroll

public ScrollableResults scroll()
                         throws HibernateException
Get the results as an instance of ScrollableResults.

Returns:
ScrollableResults
Throws:
HibernateException

scroll

public ScrollableResults scroll(ScrollMode scrollMode)
                         throws HibernateException
Get the results as an instance of ScrollableResults.

Returns:
ScrollableResults
Throws:
HibernateException

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

setLockMode

public Criteria setLockMode(LockMode lockMode)
Set the lock mode of the current entity

Parameters:
lockMode - the lock mode

setLockMode

public Criteria setLockMode(String alias,
                            LockMode lockMode)
Set the lock mode of the aliased entity

Parameters:
alias - an alias
lockMode - the lock mode

setComment

public Criteria setComment(String comment)
Add a comment to the generated SQL

Parameters:
comment - a human-readable string

setFlushMode

public Criteria setFlushMode(FlushMode flushMode)
Override the flush mode


setCacheMode

public Criteria setCacheMode(CacheMode cacheMode)
Override the cache mode