Package org.hibernate

Interface Criteria

  • All Superinterfaces:
    CriteriaSpecification
    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

    • Method Detail

      • getAlias

        java.lang.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​(java.lang.String associationPath,
                      FetchMode mode)
               throws HibernateException
        Specify an association fetching strategy for an association or a collection of values.
        Parameters:
        associationPath - a dot separated 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​(java.lang.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​(java.lang.String associationPath,
                     java.lang.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-separated 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​(java.lang.String associationPath,
                     java.lang.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-separated 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​(java.lang.String associationPath,
                     java.lang.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-separated 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​(java.lang.String associationPath,
                        JoinType joinType)
                 throws HibernateException
        Create a new Criteria, "rooted" at the associated entity, using the specified join type.
        Parameters:
        associationPath - A dot-separated 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​(java.lang.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-separated 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​(java.lang.String associationPath,
                        java.lang.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-separated 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​(java.lang.String associationPath,
                        java.lang.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-separated 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​(java.lang.String associationPath,
                        java.lang.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-separated 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​(java.lang.String associationPath,
                        java.lang.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-separated 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

      • 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)

      • 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​(java.lang.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​(java.lang.String comment)
        Add a comment to the generated SQL.
        Parameters:
        comment - a human-readable string
        Returns:
        this (for method chaining)

      • addQueryHint

        Criteria addQueryHint​(java.lang.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.
        Parameters:
        hint - The database specific query hint to add.
        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

        java.util.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.

      • uniqueResult

        java.lang.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