| ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
org.hibernate
Interface Criteria
-
All Superinterfaces:
- CriteriaSpecification
-
All Known Implementing Classes:
- CriteriaImpl, CriteriaImpl.Subcriteria
public interface Criteriaextends 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, FULL_JOIN, INNER_JOIN, LEFT_JOIN, PROJECTION, ROOT_ALIAS, ROOT_ENTITY |
Method Summary | |
---|---|
Criteria | add(Criterion criterion) Add a restriction to constrain the results to be retrieved. |
Criteria | addOrder(Order order) Add an ordering to the result set. |
Criteria | createAlias(String associationPath, String alias) Join an association, assigning an alias to the joined association. |
Criteria | createAlias(String associationPath, String alias, int joinType) Join an association using the specified join-type, assigning an alias to the joined association. |
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. |
Criteria | createCriteria(String associationPath) Create a new Criteria, "rooted" at the associated entity. |
Criteria | createCriteria(String associationPath, int joinType) Create a new Criteria, "rooted" at the associated entity, using the specified join type. |
Criteria | createCriteria(String associationPath, String alias) Create a new Criteria, "rooted" at the associated entity, assigning the given alias. |
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. |
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. |
String | getAlias() Get the alias of the entity encapsulated by this criteria instance. |
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. |
boolean | isReadOnlyInitialized() Was the read-only/modifiable mode explicitly initialized? |
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 based on the given scroll mode. |
Criteria | setCacheable(boolean cacheable) Enable caching of this query result, provided query caching is enabled for the underlying session factory. |
Criteria | setCacheMode(CacheMode cacheMode) Override the cache mode for this particular query. |
Criteria | setCacheRegion(String cacheRegion) Set the name of the cache region to use for query result caching. |
Criteria | setComment(String comment) Add a comment to the generated SQL. |
Criteria | setFetchMode(String associationPath, FetchMode mode) Specify an association fetching strategy for an association or 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 for this particular query. |
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) Used to specify that the query results will be a projection (scalar in nature). |
Criteria | setReadOnly(boolean readOnly) Set the read-only/modifiable mode for entities and proxies loaded by this Criteria. |
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 |
---|
getAlias
String getAlias()
-
Get the alias of the entity encapsulated by this criteria instance.
-
-
Returns:
- The alias for the encapsulated entity.
setProjection
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
Criteria add(Criterion criterion)
-
Add a
restriction
to constrain the results to be retrieved. -
-
Parameters:
-
criterion
- Thecriterion
object representing the restriction to be applied.
Returns:
- this (for method chaining)
-
addOrder
Criteria addOrder(Order order)
-
Add an
ordering
to the result set. -
-
Parameters:
-
order
- Theorder
object representing an ordering to be applied to the results.
Returns:
- this (for method chaining)
-
setFetchMode
Criteria setFetchMode(String associationPath, FetchMode mode) throws HibernateException
-
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
-
setLockMode
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)
-
setLockMode
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)
-
createAlias
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)
usingCriteriaSpecification.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
-
createAlias
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:
-
HibernateException
- Indicates a problem creating the sub criteria
-
createAlias
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
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. -
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
-
createCriteria
Criteria createCriteria(String associationPath) throws HibernateException
-
Create a new
Criteria, "rooted" at the associated entity.
Functionally equivalent to
createCriteria(String, int)
usingCriteriaSpecification.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
-
createCriteria
Criteria createCriteria(String associationPath, int joinType) throws HibernateException
-
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
-
createCriteria
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)
usingCriteriaSpecification.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
-
createCriteria
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:
-
HibernateException
- Indicates a problem creating the sub criteria
-
createCriteria
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
- 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
-
setResultTransformer
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
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
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)
-
isReadOnlyInitialized
boolean isReadOnlyInitialized()
-
Was the read-only/modifiable mode explicitly initialized?
-
-
Returns:
- true, the read-only/modifiable mode was explicitly initialized; false, otherwise. See Also:
-
setReadOnly(boolean)
isReadOnly
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
- ifisReadOnlyInitialized()
returnsfalse
and this Criteria is not associated with a session.
See Also:
-
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.
,isReadOnlyInitialized()
setReadOnly
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:
-
To set the default read-only/modifiable setting used for entities and proxies that are loaded into the session:
,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.
-
setFetchSize
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:
-
Statement.setFetchSize(int)
-
setTimeout
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
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
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:
-
setCacheable(boolean)
-
setComment
Criteria setComment(String comment)
-
Add a comment to the generated SQL.
-
-
Parameters:
-
comment
- a human-readable string
Returns:
- this (for method chaining)
-
setFlushMode
Criteria setFlushMode(FlushMode flushMode)
-
Override the flush mode for this particular query.
-
-
Parameters:
-
flushMode
- The flush mode to use.
Returns:
- this (for method chaining)
-
setCacheMode
Criteria setCacheMode(CacheMode cacheMode)
-
Override the cache mode for this particular query.
-
-
Parameters:
-
cacheMode
- The cache mode to use.
Returns:
- this (for method chaining)
-
list
List list() throws HibernateException
-
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.
scroll
ScrollableResults scroll() throws HibernateException
-
Get the results as an instance of
ScrollableResults
-
-
Returns:
-
The
ScrollableResults
representing the matched query results.
Throws:
-
HibernateException
- Indicates a problem either translating the criteria to SQL, exeucting the SQL or processing the SQL results.
-
The
scroll
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:
-
HibernateException
- Indicates a problem either translating the criteria to SQL, exeucting the SQL or processing the SQL results.
-
uniqueResult
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