From c020c97d8d4a444d62a2d1334a1155e5c79d223d Mon Sep 17 00:00:00 2001 From: Gavin King Date: Thu, 29 Feb 2024 09:56:38 +0100 Subject: [PATCH] HHH-17779 update Javadoc --- .../java/org/hibernate/annotations/processing/Find.java | 7 +++++++ .../java/org/hibernate/annotations/processing/HQL.java | 7 +++++++ .../src/main/java/org/hibernate/query/KeyedPage.java | 5 +++++ .../src/main/java/org/hibernate/query/Order.java | 3 ++- hibernate-core/src/main/java/org/hibernate/query/Page.java | 3 ++- .../src/main/java/org/hibernate/query/package-info.java | 7 +++++++ 6 files changed, 30 insertions(+), 2 deletions(-) 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 93e4630d52..83a0dfab37 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 @@ -149,6 +149,13 @@ import static java.lang.annotation.RetentionPolicy.CLASS; * @Find * List<Book> getBooksWithTitle(String title, List<Order<Book>> order); * + *

+ * As a further exception, a method might support key-based pagination. + * Then it must have: + *

* * @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 9c31d0c2a0..1d2d564020 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 @@ -129,6 +129,13 @@ import static java.lang.annotation.RetentionPolicy.CLASS; * List<Book> findBooksByTitleWithPagination(String title, Page page, Order<Book> order); * *

+ * As a further exception, a method might support key-based pagination. + * Then it must have: + *

+ *

* Queries specified using this annotation are always validated by * the Metamodel Generator, and so it isn't necessary to specify the * {@link CheckHQL} annotation. diff --git a/hibernate-core/src/main/java/org/hibernate/query/KeyedPage.java b/hibernate-core/src/main/java/org/hibernate/query/KeyedPage.java index 1e1fffdbba..31c3b86ea7 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/KeyedPage.java +++ b/hibernate-core/src/main/java/org/hibernate/query/KeyedPage.java @@ -39,6 +39,11 @@ import static org.hibernate.query.KeyedPage.KeyInterpretation.NO_KEY; * session.createQuery("from Book", Book.class) * .getKeyedResultList(nextPage); * + *

+ * A parameter of a {@linkplain org.hibernate.annotations.processing.Find + * finder method} or {@linkplain org.hibernate.annotations.processing.HQL + * HQL query method} may be declared with type {@code Page}. Then the + * return type of the method should be {@link KeyedResultList}. * * @since 6.5 * diff --git a/hibernate-core/src/main/java/org/hibernate/query/Order.java b/hibernate-core/src/main/java/org/hibernate/query/Order.java index 3f0f60430a..4697af0fe7 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/Order.java +++ b/hibernate-core/src/main/java/org/hibernate/query/Order.java @@ -21,7 +21,8 @@ import static java.util.stream.Collectors.toList; * rules to be passed around the system before being applied to * a {@link Query} by calling {@link SelectionQuery#setOrder}. *

- * A parameter of a {@linkplain org.hibernate.annotations.processing.HQL + * A parameter of a {@linkplain org.hibernate.annotations.processing.Find + * finder method} or {@linkplain org.hibernate.annotations.processing.HQL * HQL query method} may be declared with type {@code Order}, * {@code List>}, or {@code Order...} (varargs) * where {@code E} is the entity type returned by the query. diff --git a/hibernate-core/src/main/java/org/hibernate/query/Page.java b/hibernate-core/src/main/java/org/hibernate/query/Page.java index e3eacb12bb..b594390778 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/Page.java +++ b/hibernate-core/src/main/java/org/hibernate/query/Page.java @@ -18,7 +18,8 @@ import java.util.List; * results to be passed around the system before being applied to * a {@link Query} by calling {@link Query#setPage(Page)}. *

- * A parameter of a {@linkplain org.hibernate.annotations.processing.HQL + * A parameter of a {@linkplain org.hibernate.annotations.processing.Find + * finder method} or {@linkplain org.hibernate.annotations.processing.HQL * HQL query method} may be declared with type {@code Page}. * * @see SelectionQuery#setPage(Page) diff --git a/hibernate-core/src/main/java/org/hibernate/query/package-info.java b/hibernate-core/src/main/java/org/hibernate/query/package-info.java index 3f5abfcadc..15f2fa4ed7 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/package-info.java +++ b/hibernate-core/src/main/java/org/hibernate/query/package-info.java @@ -15,6 +15,13 @@ * {@link org.hibernate.query.QueryProducer}, that is, from any * {@link org.hibernate.Session} or {@link org.hibernate.StatelessSession}. *

+ * The classes {@link org.hibernate.query.Order}, {@link org.hibernate.query.Page}, + * {@link org.hibernate.query.KeyedPage}, and {@link org.hibernate.query.KeyedResultList} + * define an API for dynamic ordering and key-based pagination. These are + * classes are especially useful as parameters of generated + * {@link org.hibernate.annotations.processing.Find @Find} and + * {@link org.hibernate.annotations.processing.HQL @HQL} methods. + *

* Hibernate's extensions to the JPA criteria query API are defined in the * subpackage {@link org.hibernate.query.criteria}, with * {@link org.hibernate.query.criteria.HibernateCriteriaBuilder} as the