HHH-18979 document Restriction in Short Guide

gavinking · gavinking · commit a18e5ad09953 · 2024-12-28T10:31:19.000+01:00
diff --git a/documentation/src/main/asciidoc/introduction/Interacting.adoc b/documentation/src/main/asciidoc/introduction/Interacting.adoc
@@ -924,6 +924,8 @@ query.where(builder.like(root.get(Book_.title), builder.literal("Hibernate%")));
 query.orderBy(builder.asc(root.get(Book_.title)), builder.desc(root.get(Book_.isbn)));
 List<Book> matchingBooks = session.createSelectionQuery(query).getResultList();
 ----
+This is starting to get a bit messy.
+In Hibernate 7, we can often use <<restrictions-and-ordering,`Restriction`>> instead.
 ====
 
 Do you find some of the code above a bit too verbose?
@@ -1034,8 +1036,59 @@ List<Book> books =
 You can call stored procedures using `createStoredProcedureQuery()` or `createStoredProcedureCall()`.
 ====
 
+[[restrictions-and-ordering]]
+=== Restrictions and ordering
+
+We've already seen how the JPA <<criteria-queries,Criteria Query API>> can be used to construct a query completely programmatically.
+The Criteria API is powerful, but for the most common scenarios it's at least arguably overkill.
+The <<criteria-definition,`CriteriaDefinition`>> class helps a bit, but it doesn't completely eliminate the verbosity of programmatic query definition.
+
+In Hibernate 7, there's a new option, a very ergonomic API for programmatically adding restrictions or ordering to an existing query before executing it.
+(Actually, the ordering part of this was introduced in Hibernate 6.5.)
+This new API:
+
+- isn't part of the Criteria Query API, and so we don't need a `CriteriaQuery` object to make use of it,
+- works with both HQL and Criteria queries, and even with <<named-queries,named HQL queries>>, and
+- is optimized for the case of a query which returns its single root entity.
+
+[source,java]
+----
+var query = session.createSelectionQuery("from Book where year(publicationDate) > 2000", Book.class);
+if (titlePattern != null) {
+    query.addRestriction(Restriction.like(Book_.title, namePattern));
+}
+if (isbns != null && !isbns.isEmpty()) {
+    query.addRestriction(Restriction.in(Book_.isbn, isbns))
+}
+query.setOrder(List.of(Order.asc(Book_.title), Order.asc(Book_.isbn)));
+List<Book> matchingBooks = query.getResultList();
+
+----
+
+Notice that:
+
+- The link:{doc-javadoc-url}org/hibernate/query/Restriction.html[`Restriction`] interface has static methods for constructing a variety of different kinds of restriction in a completely typesafe way.
+- Similarly, the link:{doc-javadoc-url}org/hibernate/query/Order.html[`Order`] class has a variety of static methods for constructing different kinds of ordering criteria.
+
+We need the following methods of `SelectionQuery`:
+
+.Methods for query restriction and ordering
+[%breakable,cols="30,~,^15"]
+|===
+| Method name | Purpose | JPA-standard
+
+| `addRestriction()` | Add a restriction on the query results | &#10006;
+| `setOrder()` | Specify how the query results should be ordered | &#10006;
+|===
+
+Unfortunately, `Restriction` and `Order` can't be used with JPA's `TypedQuery` interface, and JPA has no built-in alternative, so if we're using `EntityManager`, we need to call `unwrap()` to obtain a `SelectionQuery`.
+
+Alternatively, `Restriction` and `Order` can be used with <<paging-and-ordering,generated query or finder methods>>, and even with link:{doc-data-repositories-url}[Jakarta Data repositories].
+
+Programmatic restrictions, and especially programmatic ordering, are often used together with pagination.
+
 [[pagination]]
-=== Limits, pagination, and ordering
+=== Limits and pagination
 
 If a query might return more results than we can handle at one time, we may specify:
 
@@ -1099,10 +1152,21 @@ long pages = results / MAX_RESULTS + (results % MAX_RESULTS == 0 ? 0 : 1);
 List<Book> books = query.setMaxResults(MAX_RESULTS).getResultList();
 ----
 
-A closely-related issue is ordering.
+.Methods for query limits, pagination, and ordering
+[%breakable,cols="30,~,^15"]
+|===
+| Method name | Purpose | JPA-standard
+
+| `setMaxResults()` | Set a limit on the number of results returned by a query | &#10004;
+| `setFirstResult()` | Set an offset on the results returned by a query | &#10004;
+| `setPage()` | Set the limit and offset by specifying a `Page` object | &#10006;
+| `getResultCount()` | Determine how many results the query would return in the absence of any limit or offset | &#10006;
+|===
+
 It's quite common for pagination to be combined with the need to order query results by a field that's determined at runtime.
-So, as an alternative to the HQL `order by` clause, `SelectionQuery` offers the ability to specify that the query results should be ordered by one or more fields of the entity type returned by the query:
+The `Order` class we just met <<restrictions-and-ordering,above>> provides the ability to specify that the query results should be ordered by one or more fields of the entity type returned by the query:
 
+[[query-order-example]]
 [source,java]
 ----
 List<Book> books =
@@ -1113,20 +1177,6 @@ List<Book> books =
             .getResultList();
 ----
 
-Unfortunately, there's no way to do this using JPA's `TypedQuery` interface.
-
-.Methods for query limits, pagination, and ordering
-[%breakable,cols="30,~,^15"]
-|===
-| Method name | Purpose | JPA-standard
-
-| `setMaxResults()` | Set a limit on the number of results returned by a query | &#10004;
-| `setFirstResult()` | Set an offset on the results returned by a query | &#10004;
-| `setPage()` | Set the limit and offset by specifying a `Page` object | &#10006;
-| `setOrder()` | Specify how the query results should be ordered | &#10006;
-| `getResultCount()` | Determine how many results the query would return in the absence of any limit or offset | &#10006;
-|===
-
 The approach to pagination we've just seen is sometimes called _offset-based pagination_.
 Since Hibernate 6.5, there's an alternative approach, which offers some advantages, though it's a little more difficult to use.
 
diff --git a/documentation/src/main/asciidoc/introduction/Processor.adoc b/documentation/src/main/asciidoc/introduction/Processor.adoc
@@ -555,6 +555,24 @@ The `@Pattern` annotation may be applied to a parameter of type `String`, indica
 List<Book> getBooksByTitle(@Pattern String title, Type type);
 ----
 
+Even better, a parameter may be of type `Range<T>`, where `T` is the type of the matching field.
+
+[source,java]
+----
+@Find
+List<Book> getBooksByTitle(Range<String> title, Type type);
+----
+
+The link:{doc-javadoc-url}org/hibernate/query/range/Range.html[`Range`] interface has a variety of `static` methods the caller may use to construct different kinds of ranges.
+For example, `Range.pattern()` constructs a `Range` representing a pattern.
+
+[source,java]
+----
+List<Book> books =
+        // returns books with titles beginning with "hibernate"
+        queries.getBooksByTitle(Range.prefix("hibernate", false), type);
+----
+
 A finder method may specify <<fetch-profiles,fetch profiles>>, for example:
 
 [source,java]
@@ -588,7 +606,7 @@ This lets us declare which associations of `Book` should be pre-fetched by annot
 // ----
 
 [[paging-and-ordering]]
-=== Paging and ordering
+=== Paging, ordering, and restrictions
 
 Optionally, a query method--or a finder method which returns multiple results--may have additional "magic" parameters which do not map to query parameters:
 
@@ -603,6 +621,7 @@ Optionally, a query method--or a finder method which returns multiple results--m
 | `Order<Object[]>` | Specifies a column to order by, if the query returns a projection list | Order.asc(1)
 | `List<Object[]>` +
 (or varargs) | Specifies columns to order by, if the query returns a projection list | List.of(Order.asc(1), Order.desc(2))
+| `Restriction<? super E>` | Specifies a restriction used to filter query results | Restriction.startsWith("Hibernate")
 |===
 
 Thus, if we redefine our earlier query method as follows:
@@ -636,8 +655,28 @@ interface Queries {
 }
 ----
 
-This gives some dynamic control over query execution, but what if we would like direct control over the `Query` object?
-Well, let's talk about the return type.
+Similarly, we may define a query method which accepts an arbitrary ``Restriction``:
+
+[source,java]
+----
+interface Queries {
+    @Find
+    List<Book> findBooks(Restriction<? super Book> restriction, Order<? super Book>... order);
+}
+----
+
+As we <<restrictions-and-ordering,saw earlier>>, the `Restriction` interface has a variety of `static` methods for constructing restrictions.
+
+[source,java]
+----
+List<Book> books =
+        // returns books with titles beginning with "hibernate", sorted by title
+        queries.findBooks(Restriction.startsWith(Book_.title, "hibernate", false),
+                          Order.asc(Book_.title));
+----
+
+This gives some dynamic control over query execution.
+We'll see <<return-query-from-method-example,below>> that it's even possible for the caller to gain direct control over the `Query` object.
 
 [[key-based-paging]]
 === Key-based pagination
@@ -722,6 +761,7 @@ List<IsbnTitle> listIsbnAndTitleForEachBook(Page page);
 
 A query method might even return `TypedQuery` or `SelectionQuery`:
 
+[[return-query-from-method-example]]
 [source,java]
 ----
 @HQL("where title like :title")
