public interface

Criteria

implements CriteriaSpecification
org.hibernate.Criteria
Known Indirect Subclasses

Class Overview

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();

See Also

Summary

[Expand]
Inherited Constants
From interface org.hibernate.criterion.CriteriaSpecification
[Expand]
Inherited Fields
From interface org.hibernate.criterion.CriteriaSpecification
Public Methods
abstract Criteria add(Criterion criterion)
Add a restriction to constrain the results to be retrieved.
abstract Criteria addOrder(Order order)
Add an ordering to the result set.
abstract Criteria createAlias(String associationPath, String alias, int joinType)
Join an association using the specified join-type, assigning an alias to the joined association.
abstract Criteria createAlias(String associationPath, String alias)
Join an association, assigning an alias to the joined association.
abstract Criteria createAlias(String associationPath, String alias, int joinType, Criterion withClause)
Join an association using the specified join-type, assigning an alias to the joined association.
abstract Criteria createCriteria(String associationPath)
Create a new Criteria, "rooted" at the associated entity.
abstract Criteria createCriteria(String associationPath, int joinType)
Create a new Criteria, "rooted" at the associated entity, using the specified join type.
abstract Criteria createCriteria(String associationPath, String alias)
Create a new Criteria, "rooted" at the associated entity, assigning the given alias.
abstract Criteria createCriteria(String associationPath, String alias, int joinType)
Create a new Criteria, "rooted" at the associated entity, assigning the given alias and using the specified join type.
abstract Criteria createCriteria(String associationPath, String alias, int joinType, Criterion withClause)
Create a new Criteria, "rooted" at the associated entity, assigning the given alias and using the specified join type.
abstract String getAlias()
Get the alias of the entity encapsulated by this criteria instance.
abstract boolean isReadOnly()
Should entities and proxies loaded by this Criteria be put in read-only mode? If the read-only/modifiable setting was not initialized, then the default read-only/modifiable setting for the persistence context is returned instead.
abstract boolean isReadOnlyInitialized()
Was the read-only/modifiable mode explicitly initialized?
abstract List list()
Get the results.
abstract ScrollableResults scroll(ScrollMode scrollMode)
Get the results as an instance of ScrollableResults based on the given scroll mode.
abstract ScrollableResults scroll()
Get the results as an instance of ScrollableResults
abstract Criteria setCacheMode(CacheMode cacheMode)
Override the cache mode for this particular query.
abstract Criteria setCacheRegion(String cacheRegion)
Set the name of the cache region to use for query result caching.
abstract Criteria setCacheable(boolean cacheable)
Enable caching of this query result, provided query caching is enabled for the underlying session factory.
abstract Criteria setComment(String comment)
Add a comment to the generated SQL.
abstract Criteria setFetchMode(String associationPath, FetchMode mode)
Specify an association fetching strategy for an association or a collection of values.
abstract Criteria setFetchSize(int fetchSize)
Set a fetch size for the underlying JDBC query.
abstract Criteria setFirstResult(int firstResult)
Set the first result to be retrieved.
abstract Criteria setFlushMode(FlushMode flushMode)
Override the flush mode for this particular query.
abstract Criteria setLockMode(String alias, LockMode lockMode)
Set the lock mode of the aliased entity
abstract Criteria setLockMode(LockMode lockMode)
Set the lock mode of the current entity
abstract Criteria setMaxResults(int maxResults)
Set a limit upon the number of objects to be retrieved.
abstract Criteria setProjection(Projection projection)
Used to specify that the query results will be a projection (scalar in nature).
abstract Criteria setReadOnly(boolean readOnly)
Set the read-only/modifiable mode for entities and proxies loaded by this Criteria.
abstract Criteria setResultTransformer(ResultTransformer resultTransformer)
Set a strategy for handling the query results.
abstract Criteria setTimeout(int timeout)
Set a timeout for the underlying JDBC query.
abstract Object uniqueResult()
Convenience method to return a single instance that matches the query, or null if the query returns no results.

Public Methods

public abstract Criteria add (Criterion criterion)

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)

public abstract Criteria addOrder (Order order)

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)

public abstract Criteria createAlias (String associationPath, String alias, int joinType)

Join an association using the specified join-type, assigning an alias to the joined association.

The joinType is expected to be one of INNER_JOIN (the default), FULL_JOIN, or 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
HibernateException Indicates a problem creating the sub criteria

public abstract Criteria createAlias (String associationPath, String alias)

Join an association, assigning an alias to the joined association.

Functionally equivalent to createAlias(String, String, int) using 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
HibernateException Indicates a problem creating the sub criteria

public abstract Criteria createAlias (String associationPath, String alias, int joinType, Criterion withClause)

Join an association using the specified join-type, assigning an alias to the joined association.

The joinType is expected to be one of INNER_JOIN (the default), FULL_JOIN, or 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.
withClause The criteria to be added to the join condition (ON clause)
Returns
  • this (for method chaining)
Throws
HibernateException Indicates a problem creating the sub criteria

public abstract Criteria createCriteria (String associationPath)

Create a new Criteria, "rooted" at the associated entity.

Functionally equivalent to createCriteria(String, int) using INNER_JOIN for the joinType.

Parameters
associationPath A dot-seperated property path
Returns
  • the created "sub criteria"
Throws
HibernateException Indicates a problem creating the sub criteria

public abstract Criteria createCriteria (String associationPath, int joinType)

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
HibernateException Indicates a problem creating the sub criteria

public abstract Criteria createCriteria (String associationPath, String alias)

Create a new Criteria, "rooted" at the associated entity, assigning the given alias.

Functionally equivalent to createCriteria(String, String, int) using 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
HibernateException Indicates a problem creating the sub criteria

public abstract Criteria createCriteria (String associationPath, String alias, int joinType)

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
HibernateException Indicates a problem creating the sub criteria

public abstract Criteria createCriteria (String associationPath, String alias, int joinType, Criterion withClause)

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.
withClause The criteria to be added to the join condition (ON clause)
Returns
  • the created "sub criteria"
Throws
HibernateException Indicates a problem creating the sub criteria

public abstract String getAlias ()

Get the alias of the entity encapsulated by this criteria instance.

Returns
  • The alias for the encapsulated entity.

public abstract boolean isReadOnly ()

Should entities and proxies loaded by this Criteria be put in read-only mode? If the read-only/modifiable setting was not initialized, then the default read-only/modifiable setting for the persistence context is returned instead.

Returns
  • true, entities and proxies loaded by the criteria will be put in read-only mode false, entities and proxies loaded by the criteria will be put in modifiable mode
Throws
IllegalStateException if isReadOnlyInitialized() returns false and this Criteria is not associated with a session.
See Also

public abstract boolean isReadOnlyInitialized ()

Was the read-only/modifiable mode explicitly initialized?

Returns
  • true, the read-only/modifiable mode was explicitly initialized; false, otherwise.
See Also

public abstract List list ()

Get the results.

Returns
  • The list of matched query results.
Throws
HibernateException Indicates a problem either translating the criteria to SQL, exeucting the SQL or processing the SQL results.

public abstract ScrollableResults scroll (ScrollMode scrollMode)

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
Throws
HibernateException Indicates a problem either translating the criteria to SQL, exeucting the SQL or processing the SQL results.

public abstract ScrollableResults scroll ()

Get the results as an instance of ScrollableResults

Returns
Throws
HibernateException Indicates a problem either translating the criteria to SQL, exeucting the SQL or processing the SQL results.

public abstract Criteria setCacheMode (CacheMode cacheMode)

Override the cache mode for this particular query.

Parameters
cacheMode The cache mode to use.
Returns
  • this (for method chaining)

public abstract Criteria setCacheRegion (String cacheRegion)

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

public abstract 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)

public abstract Criteria setComment (String comment)

Add a comment to the generated SQL.

Parameters
comment a human-readable string
Returns
  • this (for method chaining)

public abstract Criteria setFetchMode (String associationPath, FetchMode mode)

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
HibernateException Indicates a problem applying the given fetch mode

public abstract 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

public abstract 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)

public abstract Criteria setFlushMode (FlushMode flushMode)

Override the flush mode for this particular query.

Parameters
flushMode The flush mode to use.
Returns
  • this (for method chaining)

public abstract Criteria setLockMode (String alias, LockMode lockMode)

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)

public abstract Criteria setLockMode (LockMode lockMode)

Set the lock mode of the current entity

Parameters
lockMode The lock mode to be applied
Returns
  • this (for method chaining)

public abstract 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)

public abstract Criteria setProjection (Projection projection)

Used to specify that the query results will be a projection (scalar in nature). Implicitly specifies the 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)

public abstract Criteria setReadOnly (boolean readOnly)

Set the read-only/modifiable mode for entities and proxies loaded by this Criteria. This setting overrides the default setting for the persistence context.

Parameters
readOnly true, entities and proxies loaded by the criteria will be put in read-only mode false, entities and proxies loaded by the criteria will be put in modifiable mode
See Also

public abstract 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

public abstract 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

public abstract Object uniqueResult ()

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