Top Description Fields Methods
org.hibernate

public Interface Criteria

extends CriteriaSpecification
Known Direct Implementers
org.hibernate.impl.CriteriaImpl, org.hibernate.impl.CriteriaImpl.Subcriteria
Imports
java.util.List, org.hibernate.criterion.CriteriaSpecification, .Criterion, .Order, .Projection, org.hibernate.transform.ResultTransformer
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), org.hibernate.criterion.Restrictions, org.hibernate.criterion.Projections, org.hibernate.criterion.Order, org.hibernate.criterion.Criterion, org.hibernate.criterion.Projection, a disconnected version of this API

Field Summary

Inherited from org.hibernate.criterion.CriteriaSpecification:
ALIAS_TO_ENTITY_MAPDISTINCT_ROOT_ENTITYFULL_JOININNER_JOINLEFT_JOINPROJECTIONROOT_ALIASROOT_ENTITY

Method Summary

Modifier and TypeMethod and Description
public Criteria

Returns:

this (for method chaining)
add(Criterion
The criterion object representing the restriction to be applied.
criterion)

Add a restriction to constrain the results to be retrieved.

public Criteria

Returns:

this (for method chaining)
addOrder(Order
The order object representing an ordering to be applied to the results.
order)

Add an ordering to the result set.

public Criteria

Returns:

this (for method chaining)
createAlias(String
A dot-seperated property path
associationPath, String
The alias to assign to the joined association (for later reference).
alias)

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

public Criteria

Returns:

this (for method chaining)
createAlias(String
A dot-seperated property path
associationPath, String
The alias to assign to the joined association (for later reference).
alias, int
The type of join to use.
joinType)

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

public Criteria

Returns:

this (for method chaining)
createAlias(String
A dot-seperated property path
associationPath, String
The alias to assign to the joined association (for later reference).
alias, int
The type of join to use.
joinType, Criterion
The criteria to be added to the join condition (ON clause)
withClause)

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

public Criteria

Returns:

the created "sub criteria"
createCriteria(String
A dot-seperated property path
associationPath)

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

public Criteria

Returns:

the created "sub criteria"
createCriteria(String
A dot-seperated property path
associationPath, int
The type of join to use.
joinType)

Create a new Criteria, "rooted" at the associated entity, using the specified join type.

public Criteria

Returns:

the created "sub criteria"
createCriteria(String
A dot-seperated property path
associationPath, String
The alias to assign to the joined association (for later reference).
alias)

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

public Criteria

Returns:

the created "sub criteria"
createCriteria(String
A dot-seperated property path
associationPath, String
The alias to assign to the joined association (for later reference).
alias, int
The type of join to use.
joinType)

Create a new Criteria, "rooted" at the associated entity, assigning the given alias and using the specified join type.

public Criteria

Returns:

the created "sub criteria"
createCriteria(String
A dot-seperated property path
associationPath, String
The alias to assign to the joined association (for later reference).
alias, int
The type of join to use.
joinType, Criterion
The criteria to be added to the join condition (ON clause)
withClause)

Create a new Criteria, "rooted" at the associated entity, assigning the given alias and using the specified join type.

public String

Returns:

The alias for the encapsulated entity.
getAlias()

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

public boolean

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

Should entities and proxies loaded by this Criteria be put in read-only mode?

public boolean

Returns:

true, the read-only/modifiable mode was explicitly initialized; false, otherwise.
isReadOnlyInitialized()

Was the read-only/modifiable mode explicitly initialized?

public List<E>

Returns:

The list of matched query results.
list()

Get the results.

public ScrollableResults

Returns:

The ScrollableResults representing the matched query results.
scroll()

Get the results as an instance of ScrollableResults

public ScrollableResults

Returns:

The ScrollableResults representing the matched query results.
scroll(ScrollMode
Indicates the type of underlying database cursor to request.
scrollMode)

Get the results as an instance of ScrollableResults based on the given scroll mode.

public Criteria

Returns:

this (for method chaining)
setCacheable(boolean
Should the result be considered cacheable; default is to not cache (false).
cacheable)

Enable caching of this query result, provided query caching is enabled for the underlying session factory.

public Criteria

Returns:

this (for method chaining)
setCacheMode(CacheMode
The cache mode to use.
cacheMode)

Override the cache mode for this particular query.

public Criteria

Returns:

this (for method chaining)
setCacheRegion(String
the name of a query cache region, or null for the default query cache
cacheRegion)

Set the name of the cache region to use for query result caching.

public Criteria

Returns:

this (for method chaining)
setComment(String
a human-readable string
comment)

Add a comment to the generated SQL.

public Criteria

Returns:

this (for method chaining)
setFetchMode(String
a dot seperated property path
associationPath, FetchMode
The fetch mode for the referenced association
mode)

Specify an association fetching strategy for an association or a collection of values.

public Criteria

Returns:

this (for method chaining)
setFetchSize(int
the fetch size
fetchSize)

Set a fetch size for the underlying JDBC query.

public Criteria

Returns:

this (for method chaining)
setFirstResult(int
the first result to retrieve, numbered from 0
firstResult)

Set the first result to be retrieved.

public Criteria

Returns:

this (for method chaining)
setFlushMode(FlushMode
The flush mode to use.
flushMode)

Override the flush mode for this particular query.

public Criteria

Returns:

this (for method chaining)
setLockMode(LockMode
The lock mode to be applied
lockMode)

Set the lock mode of the current entity

public Criteria

Returns:

this (for method chaining)
setLockMode(String
The previously assigned alias representing the entity to which the given lock mode should apply.
alias, LockMode
The lock mode to be applied
lockMode)

Set the lock mode of the aliased entity

public Criteria

Returns:

this (for method chaining)
setMaxResults(int
the maximum number of results
maxResults)

Set a limit upon the number of objects to be retrieved.

public Criteria

Returns:

this (for method chaining)
setProjection(Projection
The projection representing the overall "shape" of the query results.
projection)

Used to specify that the query results will be a projection (scalar in nature).

public Criteria
setReadOnly(boolean
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
readOnly)

Set the read-only/modifiable mode for entities and proxies loaded by this Criteria.

public Criteria

Returns:

this (for method chaining)
setResultTransformer(ResultTransformer
The transformer to apply
resultTransformer)

Set a strategy for handling the query results.

public Criteria

Returns:

this (for method chaining)
setTimeout(int
The timeout value to apply.
timeout)

Set a timeout for the underlying JDBC query.

public Object

Returns:

the single result or null
uniqueResult()

Convenience method to return a single instance that matches the query, or null if the query returns no results.

Method Detail

addback to summary
public Criteria add(Criterion criterion)

Add a restriction to constrain the results to be retrieved.

Parameters
criterion:Criterion

The criterion object representing the restriction to be applied.

Returns:Criteria

this (for method chaining)

addOrderback to summary
public Criteria addOrder(Order order)

Add an ordering to the result set.

Parameters
order:Order

The order object representing an ordering to be applied to the results.

Returns:Criteria

this (for method chaining)

createAliasback to summary
public Criteria createAlias(String associationPath, String alias) throws HibernateException

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

A dot-seperated property path

alias:String

The alias to assign to the joined association (for later reference).

Returns:Criteria

this (for method chaining)

Exceptions
HibernateException:
Indicates a problem creating the sub criteria
createAliasback to summary
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 INNER_JOIN (the default), FULL_JOIN, or LEFT_JOIN.

Parameters
associationPath:String

A dot-seperated property path

alias:String

The alias to assign to the joined association (for later reference).

joinType:int

The type of join to use.

Returns:Criteria

this (for method chaining)

Exceptions
HibernateException:
Indicates a problem creating the sub criteria
createAliasback to summary
public Criteria createAlias(String associationPath, String alias, int joinType, Criterion withClause) 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 INNER_JOIN (the default), FULL_JOIN, or LEFT_JOIN.

Parameters
associationPath:String

A dot-seperated property path

alias:String

The alias to assign to the joined association (for later reference).

joinType:int

The type of join to use.

withClause:Criterion

The criteria to be added to the join condition (ON clause)

Returns:Criteria

this (for method chaining)

Exceptions
HibernateException:
Indicates a problem creating the sub criteria
createCriteriaback to summary
public Criteria createCriteria(String associationPath) throws HibernateException

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

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

Parameters
associationPath:String

A dot-seperated property path

Returns:Criteria

the created "sub criteria"

Exceptions
HibernateException:
Indicates a problem creating the sub criteria
createCriteriaback to summary
public Criteria createCriteria(String associationPath, int joinType) throws HibernateException

Create a new Criteria, "rooted" at the associated entity, using the specified join type.

Parameters
associationPath:String

A dot-seperated property path

joinType:int

The type of join to use.

Returns:Criteria

the created "sub criteria"

Exceptions
HibernateException:
Indicates a problem creating the sub criteria
createCriteriaback to summary
public Criteria createCriteria(String associationPath, String alias) throws HibernateException

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

A dot-seperated property path

alias:String

The alias to assign to the joined association (for later reference).

Returns:Criteria

the created "sub criteria"

Exceptions
HibernateException:
Indicates a problem creating the sub criteria
createCriteriaback to summary
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:String

A dot-seperated property path

alias:String

The alias to assign to the joined association (for later reference).

joinType:int

The type of join to use.

Returns:Criteria

the created "sub criteria"

Exceptions
HibernateException:
Indicates a problem creating the sub criteria
createCriteriaback to summary
public Criteria createCriteria(String associationPath, String alias, int joinType, Criterion withClause) throws HibernateException

Create a new Criteria, "rooted" at the associated entity, assigning the given alias and using the specified join type.

Parameters
associationPath:String

A dot-seperated property path

alias:String

The alias to assign to the joined association (for later reference).

joinType:int

The type of join to use.

withClause:Criterion

The criteria to be added to the join condition (ON clause)

Returns:Criteria

the created "sub criteria"

Exceptions
HibernateException:
Indicates a problem creating the sub criteria
getAliasback to summary
public String getAlias()

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

Returns:String

The alias for the encapsulated entity.

isReadOnlyback to summary
public 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:boolean

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

Exceptions
IllegalStateException:
if isReadOnlyInitialized() returns false and this Criteria is not associated with a session.
See Also
Criteria#setReadOnly(boolean), The read-only/modifiable setting has no impact on entities/proxies returned by the Criteria that existed in the session before the Criteria was executed., Criteria#isReadOnlyInitialized()
isReadOnlyInitializedback to summary
public boolean isReadOnlyInitialized()

Was the read-only/modifiable mode explicitly initialized?

Returns:boolean

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

See Also
Criteria#setReadOnly(boolean)
listback to summary
public List<E> list() throws HibernateException

Get the results.

Returns:List<E>

The list of matched query results.

Exceptions
HibernateException:
Indicates a problem either translating the criteria to SQL, exeucting the SQL or processing the SQL results.
scrollback to summary
public ScrollableResults scroll() throws HibernateException

Get the results as an instance of ScrollableResults

Returns:ScrollableResults

The ScrollableResults representing the matched query results.

Exceptions
HibernateException:
Indicates a problem either translating the criteria to SQL, exeucting the SQL or processing the SQL results.
scrollback to summary
public ScrollableResults scroll(ScrollMode scrollMode) throws HibernateException

Get the results as an instance of ScrollableResults based on the given scroll mode.

Parameters
scrollMode:ScrollMode

Indicates the type of underlying database cursor to request.

Returns:ScrollableResults

The ScrollableResults representing the matched query results.

Exceptions
HibernateException:
Indicates a problem either translating the criteria to SQL, exeucting the SQL or processing the SQL results.
setCacheableback to summary
public Criteria setCacheable(boolean cacheable)

Enable caching of this query result, provided query caching is enabled for the underlying session factory.

Parameters
cacheable:boolean

Should the result be considered cacheable; default is to not cache (false).

Returns:Criteria

this (for method chaining)

setCacheModeback to summary
public Criteria setCacheMode(CacheMode cacheMode)

Override the cache mode for this particular query.

Parameters
cacheMode:CacheMode

The cache mode to use.

Returns:Criteria

this (for method chaining)

setCacheRegionback to summary
public Criteria setCacheRegion(String cacheRegion)

Set the name of the cache region to use for query result caching.

Parameters
cacheRegion:String

the name of a query cache region, or null for the default query cache

Returns:Criteria

this (for method chaining)

See Also
setCacheable
setCommentback to summary
public Criteria setComment(String comment)

Add a comment to the generated SQL.

Parameters
comment:String

a human-readable string

Returns:Criteria

this (for method chaining)

setFetchModeback to summary
public Criteria setFetchMode(String associationPath, FetchMode mode) throws HibernateException

Specify an association fetching strategy for an association or a collection of values.

Parameters
associationPath:String

a dot seperated property path

mode:FetchMode

The fetch mode for the referenced association

Returns:Criteria

this (for method chaining)

Exceptions
HibernateException:
Indicates a problem applying the given fetch mode
setFetchSizeback to summary
public Criteria setFetchSize(int fetchSize)

Set a fetch size for the underlying JDBC query.

Parameters
fetchSize:int

the fetch size

Returns:Criteria

this (for method chaining)

See Also
java.sql.Statement#setFetchSize
setFirstResultback to summary
public Criteria setFirstResult(int firstResult)

Set the first result to be retrieved.

Parameters
firstResult:int

the first result to retrieve, numbered from 0

Returns:Criteria

this (for method chaining)

setFlushModeback to summary
public Criteria setFlushMode(FlushMode flushMode)

Override the flush mode for this particular query.

Parameters
flushMode:FlushMode

The flush mode to use.

Returns:Criteria

this (for method chaining)

setLockModeback to summary
public Criteria setLockMode(LockMode lockMode)

Set the lock mode of the current entity

Parameters
lockMode:LockMode

The lock mode to be applied

Returns:Criteria

this (for method chaining)

setLockModeback to summary
public Criteria setLockMode(String alias, LockMode lockMode)

Set the lock mode of the aliased entity

Parameters
alias:String

The previously assigned alias representing the entity to which the given lock mode should apply.

lockMode:LockMode

The lock mode to be applied

Returns:Criteria

this (for method chaining)

setMaxResultsback to summary
public Criteria setMaxResults(int maxResults)

Set a limit upon the number of objects to be retrieved.

Parameters
maxResults:int

the maximum number of results

Returns:Criteria

this (for method chaining)

setProjectionback to summary
public 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:Projection

The projection representing the overall "shape" of the query results.

Returns:Criteria

this (for method chaining)

setReadOnlyback to summary
public 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:boolean

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
To set the default read-only/modifiable setting used for entities and proxies that are loaded into the session:, org.hibernate.engine.PersistenceContext#setDefaultReadOnly(boolean), Read-only entities are not dirty-checked and snapshots of persistent state are not maintained. Read-only entities can be modified, but changes are not persisted. When a proxy is initialized, the loaded entity will have the same read-only/modifiable setting as the uninitialized proxy has, regardless of the session's current setting. The read-only/modifiable setting has no impact on entities/proxies returned by the criteria that existed in the session before the criteria was executed.
setResultTransformerback to summary
public Criteria setResultTransformer(ResultTransformer resultTransformer)

Set a strategy for handling the query results. This determines the "shape" of the query result.

Parameters
resultTransformer:ResultTransformer

The transformer to apply

Returns:Criteria

this (for method chaining)

See Also
ROOT_ENTITY, DISTINCT_ROOT_ENTITY, ALIAS_TO_ENTITY_MAP, PROJECTION
setTimeoutback to summary
public Criteria setTimeout(int timeout)

Set a timeout for the underlying JDBC query.

Parameters
timeout:int

The timeout value to apply.

Returns:Criteria

this (for method chaining)

See Also
java.sql.Statement#setQueryTimeout
uniqueResultback to summary
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:Object

the single result or null

Exceptions
HibernateException:
if there is more than one matching result