Package org.hibernate.query.specification

Interface SelectionSpecification<T>

Type Parameters:
T - The entity type returned by the query
All Superinterfaces:
QuerySpecification<T>
All Known Implementing Classes:
SelectionSpecificationImpl
@Incubating public interface SelectionSpecification<T> extends QuerySpecification<T>
Specialization of QuerySpecification for programmatic customization of selection queries with ordering and restriction criteria.
  • The method restrict(Restriction) allows application of additional filtering to the query results. The static factory methods of Restriction are used to express filtering criteria of various kinds.
  • Refinement or replacement of the query sorting criteria is possible via the methods sort(Order) and resort(List), together with the static factory methods of Order.
  • The method fetch(Path) adds the path of an association to be fetched by the query.

Once all sorting and restrictions are specified, call createQuery() to obtain an executable selection query object. 

 SelectionSpecification.create(Book.class,
             "from Book where discontinued = false")
         .restrict(Restriction.contains(Book_.title, "hibernate", false))
         .sort(Order.desc(Book_.title))
         .fetch(Path.from(Book.class).to(Book_publisher))
         .createQuery(session)                       // obtain a SelectionQuery
         .setPage(Page.first(50))
         .getResultList();

A SelectionSpecification always represents a query which returns a singe root entity. The restriction and ordering criteria are interpreted as applying to the field and properties of this root entity.

This interface, together with Order and Page, provides a streamlined API for offset-based pagination. For example, given a list of Orders in orderList, and the currentPage, we may write: 

 SelectionSpecification.create(Book.class, "from Book where ... ")
         .resort(orderList)
         .createQuery(session)
                 .setPage(currentPage)
                 .getResultList();
Since:
7.0

  • Method Details

    • sort

      SelectionSpecification<T> sort(Order<? super T> order)
      Adds an ordering to the selection specification. Appended to any previous ordering.
      Parameters:
      order - The ordering fragment to be added.
      Returns:
      this for method chaining.

    • resort

      SelectionSpecification<T> resort(Order<? super T> order)
      Sets the ordering for this selection specification. If ordering was already defined, this method drops the previous ordering in favor of the passed orders.
      Parameters:
      order - The ordering fragment to be used.
      Returns:
      this for method chaining.

    • resort

      SelectionSpecification<T> resort(List<Order<? super T>> orders)
      Sets the sorting for this selection specification. If sorting was already defined, this method drops the previous sorting in favor of the passed orders.
      Parameters:
      orders - The sorting fragments to be used.
      Returns:
      this for method chaining.

    • restrict

      SelectionSpecification<T> restrict(Restriction<? super T> restriction)
      Description copied from interface: QuerySpecification
      Adds a restriction to the query specification.
      Specified by:
      restrict in interface QuerySpecification<T>
      Parameters:
      restriction - The restriction predicate to be added.
      Returns:
      this for method chaining.

    • fetch

      SelectionSpecification<T> fetch(Path<T,?> fetchPath)
      Add a fetch path to the specification.
      Parameters:
      fetchPath - The path to fetch
      Returns:
      this for method chaining.

    • augment

      SelectionSpecification<T> augment(SelectionSpecification.Augmentation<T> augmentation)
      Add an augmentation to the specification.

      For example: 

       SelectionSpecification.create(Book.class)
       .augment((builder, query, book) ->
               // augment the query via JPA Criteria API
               query.where(builder.like(book.get(Book_.title), titlePattern)),
                           builder.greaterThan(book.get(Book_.pages), minPages))
                   .orderBy(builder.asc(book.get(Book_.isbn)))
       .createQuery(session)
       .getResultList();
      For complicated cases, a CriteriaDefinition may be used within an augmentation to eliminate repetitive explicit references to the CriteriaBuilder. 
       SelectionSpecification.create(Book.class)
       .augment((builder, query, book) ->
           // eliminate explicit references to 'builder'
           new CriteriaDefinition<>(query) {{
               where(like(entity.get(BasicEntity_.title), titlePattern),
                     greaterThan(book.get(Book_.pages), minPages));
               orderBy(asc(book.get(Book_.isbn)));
           }}
       )
       .createQuery(session)
       .getResultList();
      Parameters:
      augmentation - A function capable of modifying or augmenting a criteria query.
      Returns:
      this for method chaining.

    • createQuery

      SelectionQuery<T> createQuery(Session session)
      Description copied from interface: QuerySpecification
      Finalize the building and create executable query instance.
      Specified by:
      createQuery in interface QuerySpecification<T>

    • createQuery

      SelectionQuery<T> createQuery(StatelessSession session)
      Description copied from interface: QuerySpecification
      Finalize the building and create executable query instance.
      Specified by:
      createQuery in interface QuerySpecification<T>

    • createQuery

      SelectionQuery<T> createQuery(EntityManager entityManager)
      Description copied from interface: QuerySpecification
      Finalize the building and create executable query instance.
      Specified by:
      createQuery in interface QuerySpecification<T>

    • buildCriteria

      CriteriaQuery<T> buildCriteria(CriteriaBuilder builder)
      Build a criteria query satisfying this specification, using the given CriteriaBuilder.

      If the returned criteria query is mutated, the mutations will not be not reflected in this specification.

      Specified by:
      buildCriteria in interface QuerySpecification<T>
      Returns:
      a new criteria query

    • validate

      SelectionSpecification<T> validate(CriteriaBuilder builder)
      Description copied from interface: QuerySpecification
      Validate the query.
      Specified by:
      validate in interface QuerySpecification<T>
      Returns:
      this if everything is fine

    • reference

      TypedQueryReference<T> reference()
      Description copied from interface: QuerySpecification
      Obtain a reference to this specification which may be passed along to EntityManager.createQuery(TypedQueryReference).
      Specified by:
      reference in interface QuerySpecification<T>

    • create

      static <T> SelectionSpecification<T> create(Class<T> rootEntityType)
      Returns a specification reference which can be used to programmatically, iteratively build a SelectionQuery for the given entity type, allowing the addition of sorting and restrictions. This is effectively the same as calling create(Class, String) with "from {rootEntityType}" as the HQL.
      Type Parameters:
      T - The entity type which is the root of the query. resultType and <T> are both expected to refer to a singular query root.
      Parameters:
      rootEntityType - The entity type which is the root of the query.

    • create

      static <T> SelectionSpecification<T> create(Class<T> resultType, String hql)
      Returns a specification reference which can be used to programmatically, iteratively build a SelectionQuery based on a base HQL statement, allowing the addition of sorting and restrictions.
      Type Parameters:
      T - The root entity type for the query. resultType and <T> are both expected to refer to a singular query root.
      Parameters:
      hql - The base HQL query.
      resultType - The result type which will ultimately be returned from the SelectionQuery
      Throws:
      IllegalSelectQueryException - The given HQL is expected to be a select query. This method will throw an exception if not.

    • create

      static <T> SelectionSpecification<T> create(CriteriaQuery<T> criteria)
      Returns a specification reference which can be used to programmatically, iteratively build a SelectionQuery for the given criteria query, allowing the addition of sorting and restrictions.
      Type Parameters:
      T - The entity type which is the root of the query.
      Parameters:
      criteria - The criteria query