From f27e5e8be10ba2a92c3c6ff916723dbfe69f41c5 Mon Sep 17 00:00:00 2001 From: Gavin King Date: Sat, 28 Dec 2024 13:31:17 +0100 Subject: [PATCH] HHH-18979 make Order/Restriction more prominent in jdoc for SelectionQuery --- .../main/java/org/hibernate/query/Restriction.java | 4 ++-- .../java/org/hibernate/query/SelectionQuery.java | 12 ++++++++++++ 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/hibernate-core/src/main/java/org/hibernate/query/Restriction.java b/hibernate-core/src/main/java/org/hibernate/query/Restriction.java index 4facf74bbd..eec3daaa99 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/Restriction.java +++ b/hibernate-core/src/main/java/org/hibernate/query/Restriction.java @@ -17,14 +17,14 @@ import java.util.List; /** * A rule for restricting query results. *

- * This allows restrictions to be added to a {@link Query} by calling + * This allows restrictions to be added to a {@link SelectionQuery} by calling * {@link SelectionQuery#addRestriction(Restriction)}. *

  * session.createSelectionQuery("from Book", Book.class)
  *         .addRestriction(Restriction.like(Book_.title, "%Hibernate%", false))
  *         .addRestriction(Restriction.greaterThan(Book_.pages, 100))
  *         .setOrder(Order.desc(Book_.title))
- * 		   .getResultList() );
+ *         .getResultList() );
  * 
*

* Each restriction pairs an {@linkplain SingularAttribute attribute} of the diff --git a/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java b/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java index f186e6d4b4..09f12663f1 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java +++ b/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java @@ -99,6 +99,11 @@ import org.hibernate.graph.GraphSemantic; * every {@link jakarta.persistence.FetchType#EAGER eager} {@code @ManyToOne} or * {@code @OneToOne} association belonging to an entity returned by the query. *

+ * The method {@link #addRestriction(Restriction)} allows application of additional + * {@linkplain Restriction filtering} to the query results. The static factory + * methods of {@code Restriction} are used to express filtering criteria of various + * kinds. + *

* Finally, two alternative approaches to pagination are available: *

    *
  1. @@ -106,6 +111,13 @@ import org.hibernate.graph.GraphSemantic; * with {@link Order} and {@link Page}, provide a streamlined API for offset-based * pagination, at a slightly higher semantic level than the ancient but dependable * {@link #setFirstResult(int)} and {@link #setMaxResults(int)}. + *
    + * session.createSelectionQuery("from Book", Book.class)
    + *         .addRestriction(Restriction.contains(Book_.title, "hibernate", false))
    + *         .setOrder(Order.desc(Book_.title))
    + *         .setPage(Page.first(50))
    + *         .getResultList() );
    + * 
    *
  2. * On the other hand, {@link KeyedPage} and {@link KeyedResultList}, along with * {@link #getKeyedResultList(KeyedPage)}, provide for key-based pagination,