From aea72cccd5b77d8fff854c5f8320dad94be12be9 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Sat, 28 Dec 2024 13:55:33 +0100
Subject: [PATCH] HHH-18979 add Order/Restriction to jdoc for @Find and @HQL

---
 .../annotations/processing/Find.java          | 26 ++++++++++++++++++-
 .../hibernate/annotations/processing/HQL.java | 11 ++++++++
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/processing/Find.java b/hibernate-core/src/main/java/org/hibernate/annotations/processing/Find.java
index 9cf80e8a6a..bff8e145b2 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/processing/Find.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/processing/Find.java
@@ -39,12 +39,25 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  * Notice that:
  * <ul>
  * <li>the types and names of the method parameters exactly match the
- *     types and names of the corresponding fields of the entity.
+ *     types and names of the corresponding fields of the entity, and
  * <li>there's no special naming convention for the {@code @Find}
  *     methods&mdash;they may be named arbitrarily, and their names
  *     encode no semantics.
  * </ul>
  * <p>
+ * Alternatively, a method parameter may have the type
+ * {@link org.hibernate.query.range.Range Range&lt;T&gt;} where
+ * {@code T} is the type of the corresponding field in the entity.
+ * <pre>
+ * &#064;Find
+ * Book getBookForIsbn(Range&lt;String&gt; isbn);
+ *
+ * &#064;Find
+ * List&lt;Book&gt; getBooksWithTitle(Range&lt;String&gt; title);
+ * </pre>
+ * This allows the matching field to be restricted based on a variety
+ * of criteria expressed via the static factory methods of {@code Range}.
+ * <p>
  * It's even possible to query by a field of an embedded object:
  * <pre>
  * &#064;Find
@@ -154,6 +167,17 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  * <li>return type {@link org.hibernate.query.KeyedResultList}, and
  * <li>a parameter of type {@link org.hibernate.query.KeyedPage}.
  * </ul>
+ * <p>
+ * Finally, a method might have a parameter of type
+ * {@link org.hibernate.query.Restriction Restriction<? super E>},
+ * allowing the caller to apply an arbitrary filtering criterion to
+ * the query results.
+ * <p>
+ * For example:
+ * <pre>
+ * &#064;Find
+ * List&lt;Book&gt; getBooks(Restriction&lt;Book&gt; filter, List&lt;Order&lt;Book&gt;&gt; order);
+ * </pre>
  *
  * @see HQL
  * @see SQL
diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/processing/HQL.java b/hibernate-core/src/main/java/org/hibernate/annotations/processing/HQL.java
index 112f215c95..31ffa23587 100644
--- a/hibernate-core/src/main/java/org/hibernate/annotations/processing/HQL.java
+++ b/hibernate-core/src/main/java/org/hibernate/annotations/processing/HQL.java
@@ -134,6 +134,17 @@ import static java.lang.annotation.RetentionPolicy.CLASS;
  * <li>a parameter of type {@link org.hibernate.query.KeyedPage}.
  * </ul>
  * <p>
+ * Finally, a method might have a parameter of type
+ * {@link org.hibernate.query.Restriction Restriction<? super E>},
+ * allowing the caller to apply an arbitrary filtering criterion to
+ * the query results.
+ * <p>
+ * For example:
+ * <pre>
+ * &#064;HQL("from Book")
+ * List&lt;Book&gt; findBooks(Restriction&lt;Book&gt; filter, List&lt;Order&lt;Book&gt;&gt; order);
+ * </pre>
+ * <p>
  * Queries specified using this annotation are always validated by
  * the Metamodel Generator, and so it isn't necessary to specify the
  * {@link CheckHQL} annotation.