Criteria (Hibernate JavaDocs)
Date: 2012-04-05

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
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 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();

See Also:
  `SharedSessionContract.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)` Deprecated. use `createAlias(String, String, org.hibernate.sql.JoinType)`
`Criteria` | `createAlias(String associationPath, String alias, int joinType, Criterion withClause)` Deprecated. use `createAlias(String, String, JoinType, Criterion)`
`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 `Criteria`, "rooted" at the associated entity.
`Criteria` | `createCriteria(String associationPath, int joinType)` Deprecated. use `createAlias(String, String, org.hibernate.sql.JoinType)`
`Criteria` | `createCriteria(String associationPath, JoinType 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)` Deprecated. use `createCriteria(String, org.hibernate.sql.JoinType)`
`Criteria` | `createCriteria(String associationPath, String alias, int joinType, Criterion withClause)` Deprecated. use `createCriteria(String, String, org.hibernate.sql.JoinType, org.hibernate.criterion.Criterion)`
`Criteria` | `createCriteria(String associationPath, String alias, JoinType 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, JoinType 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` - The `criterion` 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` - The `order` 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, JoinType )` using `JoinType.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,
                         JoinType 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 `JoinType.INNER_JOIN` (the default), `JoinType.FULL_JOIN`, or `JoinType.LEFT_OUTER_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

    @Deprecated
    Criteria createAlias(String associationPath,
                                    String alias,
                                    int joinType)
                         throws HibernateException

  Deprecated. use `createAlias(String, String, org.hibernate.sql.JoinType)`

  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`, or `CriteriaSpecification.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,
                         JoinType 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 `JoinType.INNER_JOIN` (the default), `JoinType.FULL_JOIN`, or `JoinType.LEFT_OUTER_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

### createAlias

    @Deprecated
    Criteria createAlias(String associationPath,
                                    String alias,
                                    int joinType,
                                    Criterion withClause)
                         throws HibernateException

  Deprecated. use `createAlias(String, String, JoinType, Criterion)`

  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`, or `CriteriaSpecification.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, org.hibernate.sql.JoinType)` using `JoinType.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,
                            JoinType 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

    @Deprecated
    Criteria createCriteria(String associationPath,
                                       int joinType)
                            throws HibernateException

  Deprecated. use `createAlias(String, String, org.hibernate.sql.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

### 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, org.hibernate.sql.JoinType)` using `JoinType.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,
                            JoinType 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

    @Deprecated
    Criteria createCriteria(String associationPath,
                                       String alias,
                                       int joinType)
                            throws HibernateException

  Deprecated. use `createCriteria(String, org.hibernate.sql.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

### createCriteria

    Criteria createCriteria(String associationPath,
                            String alias,
                            JoinType 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

### createCriteria

    @Deprecated
    Criteria createCriteria(String associationPath,
                                       String alias,
                                       int joinType,
                                       Criterion withClause)
                            throws HibernateException

  Deprecated. use `createCriteria(String, String, org.hibernate.sql.JoinType, org.hibernate.criterion.Criterion)`

  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` - if `isReadOnlyInitialized()` returns `false` 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
  Returns:
    `this`, for method chaining
  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.

### 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2012 Red Hat, Inc. All Rights Reserved.