public interface Criteria extends CriteriaSpecification
<tt>Criteria</tt> is a simplified API for retrieving entities by composing <tt>Criterion</tt> 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.<br> <br> The <tt>Session</tt> is a factory for <tt>Criteria</tt>. <tt>Criterion</tt> instances are usually obtained via the factory methods on <tt>Restrictions</tt>. eg. <pre> List cats = session.createCriteria(Cat.class) .add( Restrictions.like("name", "Iz%") ) .add( Restrictions.gt( "weight", new Float(minWeight) ) ) .addOrder( Order.asc("age") ) .list(); </pre> You may navigate associations using <tt>createAlias()</tt> or <tt>createCriteria()</tt>. <pre> List cats = session.createCriteria(Cat.class) .createCriteria("kittens") .add( Restrictions.like("name", "Iz%") ) .list(); </pre> <pre> List cats = session.createCriteria(Cat.class) .createAlias("kittens", "kit") .add( Restrictions.like("kit.name", "Iz%") ) .list(); </pre> You may specify projection and aggregation using <tt>Projection</tt> instances obtained via the factory methods on <tt>Projections</tt>. <pre> 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(); </pre>
ALIAS_TO_ENTITY_MAP, DISTINCT_ROOT_ENTITY, FULL_JOIN, INNER_JOIN, LEFT_JOIN, PROJECTION, ROOT_ALIAS, ROOT_ENTITY
Modifier and Type | Method and Description |
---|---|
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 |
addQueryHint(String hint)
Add a DB query hint to the SQL.
|
Criteria |
createAlias(String associationPath,
String alias)
Join an association, assigning an alias to the joined association.
|
Criteria |
createAlias(String associationPath,
String alias,
int joinType)
Deprecated.
|
Criteria |
createAlias(String associationPath,
String alias,
int joinType,
Criterion withClause)
Deprecated.
|
Criteria |
createAlias(String associationPath,
String alias,
JoinType joinType)
Join an association using the specified join-type, assigning an alias
to the joined association.
|
Criteria |
createAlias(String associationPath,
String alias,
JoinType 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 <tt>Criteria</tt>, "rooted" at the associated entity.
|
Criteria |
createCriteria(String associationPath,
int joinType)
Deprecated.
|
Criteria |
createCriteria(String associationPath,
JoinType joinType)
Create a new <tt>Criteria</tt>, "rooted" at the associated entity, using the
specified join type.
|
Criteria |
createCriteria(String associationPath,
String alias)
Create a new <tt>Criteria</tt>, "rooted" at the associated entity,
assigning the given alias.
|
Criteria |
createCriteria(String associationPath,
String alias,
int joinType)
Deprecated.
|
Criteria |
createCriteria(String associationPath,
String alias,
int joinType,
Criterion withClause)
|
Criteria |
createCriteria(String associationPath,
String alias,
JoinType joinType)
Create a new <tt>Criteria</tt>, "rooted" at the associated entity,
assigning the given alias and using the specified join type.
|
Criteria |
createCriteria(String associationPath,
String alias,
JoinType joinType,
Criterion withClause)
Create a new <tt>Criteria</tt>, "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.
|
String getAlias()
Get the alias of the entity encapsulated by this criteria instance.
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.
<p/>
The individual components contained within the given
projection
determines the overall "shape" of the
query result.
projection
- The projection representing the overall "shape" of the
query results.Criteria add(Criterion criterion)
Add a restriction
to constrain the results to be
retrieved.
criterion
- The criterion
object representing the
restriction to be applied.Criteria addOrder(Order order)
Add an ordering
to the result set.
order
- The order
object representing an ordering
to be applied to the results.Criteria setFetchMode(String associationPath, FetchMode mode) throws HibernateException
Specify an association fetching strategy for an association or a collection of values.
associationPath
- a dot separated property pathmode
- The fetch mode for the referenced associationHibernateException
- Indicates a problem applying the given fetch modeCriteria setLockMode(LockMode lockMode)
Set the lock mode of the current entity.
lockMode
- The lock mode to be appliedCriteria setLockMode(String alias, LockMode lockMode)
Set the lock mode of the aliased entity.
alias
- The previously assigned alias representing the entity to
which the given lock mode should apply.lockMode
- The lock mode to be appliedCriteria createAlias(String associationPath, String alias) throws HibernateException
Join an association, assigning an alias to the joined association.
<p/>
Functionally equivalent to createAlias(String, String, JoinType )
using
JoinType.INNER_JOIN
for the joinType.
associationPath
- A dot-separated property pathalias
- The alias to assign to the joined association (for later reference).HibernateException
- Indicates a problem creating the sub criteriaCriteria createAlias(String associationPath, String alias, JoinType joinType) throws HibernateException
Join an association using the specified join-type, assigning an alias
to the joined association.
<p/>
The joinType is expected to be one of JoinType.INNER_JOIN
(the default),
JoinType.FULL_JOIN
, or JoinType.LEFT_OUTER_JOIN
.
associationPath
- A dot-separated property pathalias
- The alias to assign to the joined association (for later reference).joinType
- The type of join to use.HibernateException
- Indicates a problem creating the sub criteria@Deprecated Criteria createAlias(String associationPath, String alias, int joinType) throws HibernateException
createAlias(String, String, org.hibernate.sql.JoinType)
Join an association using the specified join-type, assigning an alias
to the joined association.
<p/>
The joinType is expected to be one of CriteriaSpecification.INNER_JOIN
(the default),
CriteriaSpecification.FULL_JOIN
, or CriteriaSpecification.LEFT_JOIN
.
associationPath
- A dot-separated property pathalias
- The alias to assign to the joined association (for later reference).joinType
- The type of join to use.HibernateException
- Indicates a problem creating the sub criteriaCriteria createAlias(String associationPath, String alias, JoinType joinType, Criterion withClause) throws HibernateException
Join an association using the specified join-type, assigning an alias
to the joined association.
<p/>
The joinType is expected to be one of JoinType.INNER_JOIN
(the default),
JoinType.FULL_JOIN
, or JoinType.LEFT_OUTER_JOIN
.
associationPath
- A dot-separated property pathalias
- 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 (<tt>ON</tt> clause)HibernateException
- Indicates a problem creating the sub criteria@Deprecated Criteria createAlias(String associationPath, String alias, int joinType, Criterion withClause) throws HibernateException
createAlias(String, String, JoinType, Criterion)
Join an association using the specified join-type, assigning an alias
to the joined association.
<p/>
The joinType is expected to be one of CriteriaSpecification.INNER_JOIN
(the default),
CriteriaSpecification.FULL_JOIN
, or CriteriaSpecification.LEFT_JOIN
.
associationPath
- A dot-separated property pathalias
- 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 (<tt>ON</tt> clause)HibernateException
- Indicates a problem creating the sub criteriaCriteria createCriteria(String associationPath) throws HibernateException
Create a new <tt>Criteria</tt>, "rooted" at the associated entity.
<p/>
Functionally equivalent to createCriteria(String, org.hibernate.sql.JoinType)
using
JoinType.INNER_JOIN
for the joinType.
associationPath
- A dot-separated property pathHibernateException
- Indicates a problem creating the sub criteriaCriteria createCriteria(String associationPath, JoinType joinType) throws HibernateException
Create a new <tt>Criteria</tt>, "rooted" at the associated entity, using the specified join type.
associationPath
- A dot-separated property pathjoinType
- The type of join to use.HibernateException
- Indicates a problem creating the sub criteria@Deprecated Criteria createCriteria(String associationPath, int joinType) throws HibernateException
createAlias(String, String, org.hibernate.sql.JoinType)
Create a new <tt>Criteria</tt>, "rooted" at the associated entity, using the specified join type.
associationPath
- A dot-separated property pathjoinType
- The type of join to use.HibernateException
- Indicates a problem creating the sub criteriaCriteria createCriteria(String associationPath, String alias) throws HibernateException
Create a new <tt>Criteria</tt>, "rooted" at the associated entity,
assigning the given alias.
<p/>
Functionally equivalent to createCriteria(String, String, org.hibernate.sql.JoinType)
using
JoinType.INNER_JOIN
for the joinType.
associationPath
- A dot-separated property pathalias
- The alias to assign to the joined association (for later reference).HibernateException
- Indicates a problem creating the sub criteriaCriteria createCriteria(String associationPath, String alias, JoinType joinType) throws HibernateException
Create a new <tt>Criteria</tt>, "rooted" at the associated entity, assigning the given alias and using the specified join type.
associationPath
- A dot-separated property pathalias
- The alias to assign to the joined association (for later reference).joinType
- The type of join to use.HibernateException
- Indicates a problem creating the sub criteria@Deprecated Criteria createCriteria(String associationPath, String alias, int joinType) throws HibernateException
createCriteria(String, org.hibernate.sql.JoinType)
Create a new <tt>Criteria</tt>, "rooted" at the associated entity, assigning the given alias and using the specified join type.
associationPath
- A dot-separated property pathalias
- The alias to assign to the joined association (for later reference).joinType
- The type of join to use.HibernateException
- Indicates a problem creating the sub criteriaCriteria createCriteria(String associationPath, String alias, JoinType joinType, Criterion withClause) throws HibernateException
Create a new <tt>Criteria</tt>, "rooted" at the associated entity, assigning the given alias and using the specified join type.
associationPath
- A dot-separated property pathalias
- 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 (<tt>ON</tt> clause)HibernateException
- Indicates a problem creating the sub criteria@Deprecated Criteria createCriteria(String associationPath, String alias, int joinType, Criterion withClause) throws HibernateException
createCriteria(String, String, org.hibernate.sql.JoinType, org.hibernate.criterion.Criterion)
Create a new <tt>Criteria</tt>, "rooted" at the associated entity, assigning the given alias and using the specified join type.
associationPath
- A dot-separated property pathalias
- 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 (<tt>ON</tt> clause)HibernateException
- Indicates a problem creating the sub criteriaCriteria setResultTransformer(ResultTransformer resultTransformer)
Set a strategy for handling the query results. This determines the "shape" of the query result.
resultTransformer
- The transformer to applyCriteriaSpecification.ROOT_ENTITY
,
CriteriaSpecification.DISTINCT_ROOT_ENTITY
,
CriteriaSpecification.ALIAS_TO_ENTITY_MAP
,
CriteriaSpecification.PROJECTION
Criteria setMaxResults(int maxResults)
Set a limit upon the number of objects to be retrieved.
maxResults
- the maximum number of resultsCriteria setFirstResult(int firstResult)
Set the first result to be retrieved.
firstResult
- the first result to retrieve, numbered from <tt>0</tt>boolean isReadOnlyInitialized()
Was the read-only/modifiable mode explicitly initialized?
setReadOnly(boolean)
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.
IllegalStateException
- if <code>isReadOnlyInitialized()</code> returns <code>false</code>
and this Criteria is not associated with a session.setReadOnly(boolean)
,
PersistenceContext.isDefaultReadOnly()
,
isReadOnlyInitialized()
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.
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 modethis
, for method chainingPersistenceContext.isDefaultReadOnly()
,
PersistenceContext.setDefaultReadOnly(boolean)
,
Session.setDefaultReadOnly(boolean)
Criteria setFetchSize(int fetchSize)
Set a fetch size for the underlying JDBC query.
fetchSize
- the fetch sizeStatement.setFetchSize(int)
Criteria setTimeout(int timeout)
Set a timeout for the underlying JDBC query.
timeout
- The timeout value to apply.Statement.setQueryTimeout(int)
Criteria setCacheable(boolean cacheable)
Enable caching of this query result, provided query caching is enabled for the underlying session factory.
cacheable
- Should the result be considered cacheable; default is
to not cache (false).Criteria setCacheRegion(String cacheRegion)
Set the name of the cache region to use for query result caching.
cacheRegion
- the name of a query cache region, or <tt>null</tt>
for the default query cachesetCacheable(boolean)
Criteria setComment(String comment)
Add a comment to the generated SQL.
comment
- a human-readable stringCriteria addQueryHint(String hint)
Add a DB query hint to the SQL. These differ from JPA’s QueryHint
, which is specific
to the JPA implementation and ignores DB vendor-specific hints. Instead, these are intended solely for the
vendor-specific hints, such as Oracle’s optimizers. Multiple query hints are supported; the Dialect will
determine concatenation and placement.
hint
- The database specific query hint to add.Criteria setFlushMode(FlushMode flushMode)
Override the flush mode for this particular query.
flushMode
- The flush mode to use.Criteria setCacheMode(CacheMode cacheMode)
Override the cache mode for this particular query.
cacheMode
- The cache mode to use.List list() throws HibernateException
Get the results.
HibernateException
- Indicates a problem either translating the criteria to SQL,
exeucting the SQL or processing the SQL results.ScrollableResults scroll() throws HibernateException
Get the results as an instance of ScrollableResults
.
ScrollableResults
representing the matched
query results.HibernateException
- Indicates a problem either translating the criteria to SQL,
exeucting the SQL or processing the SQL results.ScrollableResults scroll(ScrollMode scrollMode) throws HibernateException
Get the results as an instance of ScrollableResults
based on the
given scroll mode.
scrollMode
- Indicates the type of underlying database cursor to
request.ScrollableResults
representing the matched
query results.HibernateException
- Indicates a problem either translating the criteria to SQL,
exeucting the SQL or processing the SQL results.Object uniqueResult() throws HibernateException
Convenience method to return a single instance that matches the query, or null if the query returns no results.
HibernateException
- if there is more than one matching resultCopyright © 2001-2018 Red Hat, Inc. All Rights Reserved.