HHH-19364 final touches to jdoc before release

Author: gavinking

hibernate-core/src/main/java/org/hibernate/query/Order.java

@@ -15,11 +15,11 @@
 import static org.hibernate.query.SortDirection.DESCENDING;
 
 /**
- * A rule for sorting a query result set.
- * <p>
- * This is a convenience class which allows query result ordering rules to be
- * passed around the system before being applied to a {@link Query} by calling
- * {@link org.hibernate.query.specification.SelectionSpecification#sort(Order)}.
+ * A rule for sorting a query result set. This allows query result ordering
+ * rules to be passed around the system before being applied to a
+ * {@link org.hibernate.query.specification.QuerySpecification} by calling
+ * {@link org.hibernate.query.specification.SelectionSpecification#sort(Order)
+ * sort()}.
  * <pre>
  * SelectionSpecification.create(Book.class,
  *             "from Book b join b.authors a where a.name = :name")
@@ -30,7 +30,8 @@
  * </pre>
  * <p>
  * {@code Order}s may be stacked using {@link List#of} and
- * {@link org.hibernate.query.specification.SelectionSpecification#resort(List)}.
+ * {@link org.hibernate.query.specification.SelectionSpecification#resort(List)
+ * resort()}.
  * <pre>
  * SelectionSpecification.create(Book.class,
  *             "from Book b join b.authors a where a.name = :name")

hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java

@@ -99,19 +99,16 @@
  * every {@link jakarta.persistence.FetchType#EAGER eager} {@code @ManyToOne} or
  * {@code @OneToOne} association belonging to an entity returned by the query.
  * <p>
- * Finally, two alternative approaches to pagination are available:
+ * Finally, three alternative approaches to pagination are available:
  * <ol>
  * <li>
- * The operations and {@link #setOrder(List)} and {@link #setPage(Page)}, together
- * 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)}.
- * <pre>
- * session.createSelectionQuery("from Book", Book.class)
- *         .setOrder(Order.desc(Book_.title))
- *         .setPage(Page.first(50))
- *         .getResultList();
- * </pre>
+ * The ancient but dependable operations {@link #setFirstResult(int)} and
+ * {@link #setMaxResults(int)} are the standard approach blessed by the JPA
+ * specification.
+ * <li>
+ * {@link org.hibernate.query.specification.SelectionSpecification SelectionSpecification}
+ * and {@link #setPage(Page)}, together with {@link Order} and {@link Page}, provide
+ * a streamlined API for offset-based pagination, at a slightly higher semantic level.
  * <li>
  * On the other hand, {@link KeyedPage} and {@link KeyedResultList}, along with
  * {@link #getKeyedResultList(KeyedPage)}, provide for <em>key-based pagination</em>,

hibernate-core/src/main/java/org/hibernate/query/restriction/Restriction.java

@@ -19,8 +19,9 @@
 
 /**
  * A rule for restricting query results. This allows restrictions to be added to
- * a {@link org.hibernate.query.specification.SelectionSpecification} by calling
- * {@link org.hibernate.query.specification.SelectionSpecification#restrict(Restriction)}.
+ * a {@link org.hibernate.query.specification.QuerySpecification} by calling
+ * {@link org.hibernate.query.specification.QuerySpecification#restrict(Restriction)
+ * restrict()}.
  * <pre>
  * SelectionSpecification.create(Book.class)
  *         .restrict(Restriction.like(Book_.title, "%Hibernate%", false))

hibernate-core/src/main/java/org/hibernate/query/specification/MutationSpecification.java

@@ -27,6 +27,13 @@
  * {@linkplain Restriction filtering} to the mutated entity. The static factory
  * methods of {@link Restriction} are used to express filtering criteria of various
  * kinds.
+ * <pre>
+ * MutationSpecification.create(Book.class, "delete from Book")
+ *         .restrict(Restriction.lessThan(Book_.publicationDate,
+ *                                        LocalDate.ofYearDay(2000,1)))
+ *         .createQuery(session)
+ *         .executeUpdate();
+ * </pre>
  * <p>
  * Once all {@linkplain #restrict restrictions} are specified, call
  * {@link #createQuery createQuery()} to obtain an {@linkplain MutationQuery
@@ -41,9 +48,6 @@
 @Incubating
 public interface MutationSpecification<T> extends QuerySpecification<T> {
 
-	/**
-	 * Covariant override.
-	 */
 	@Override
 	MutationSpecification<T> restrict(Restriction<? super T> restriction);
 

hibernate-core/src/main/java/org/hibernate/query/specification/SelectionSpecification.java

@@ -15,6 +15,7 @@
 import org.hibernate.StatelessSession;
 import org.hibernate.query.IllegalSelectQueryException;
 import org.hibernate.query.Order;
+import org.hibernate.query.Page;
 import org.hibernate.query.SelectionQuery;
 import org.hibernate.query.specification.internal.SelectionSpecificationImpl;
 import org.hibernate.query.restriction.Path;
@@ -40,7 +41,8 @@
  * are specified, call {@link #createQuery createQuery()} to obtain an
  * {@linkplain SelectionQuery executable selection query object}.
  * <pre>
- * SelectionSpecification.create(Book.class, "from Book where discontinued = false")
+ * 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))
@@ -52,6 +54,17 @@
  * A {@code 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.
+ * <p>
+ * This interface, together with {@link Order} and {@link Page}, provides a streamlined
+ * API for offset-based pagination. For example, given a list of {@code Order}s in
+ * {@code orderList}, and the {@code currentPage}, we may write:
+ * <pre>
+ * SelectionSpecification.create(Book.class, "from Book where ... ")
+ *         .resort(orderList)
+ *         .createQuery(session)
+ *                 .setPage(currentPage)
+ *                 .getResultList();
+ * </pre>
  *
  * @param <T> The entity type returned by the query
  *
@@ -93,9 +106,6 @@ public interface SelectionSpecification<T> extends QuerySpecification<T> {
 	 */
 	SelectionSpecification<T> resort(List<Order<? super T>> orders);
 
-	/**
-	 * Covariant override.
-	 */
 	@Override
 	SelectionSpecification<T> restrict(Restriction<? super T> restriction);
 
@@ -155,15 +165,9 @@ interface Augmentation<T> {
 	 */
 	SelectionSpecification<T> augment(Augmentation<T> augmentation);
 
-	/**
-	 * Covariant override.
-	 */
 	@Override
 	SelectionQuery<T> createQuery(Session session);
 
-	/**
-	 * Covariant override.
-	 */
 	@Override
 	SelectionQuery<T> createQuery(StatelessSession session);