HHH-19364 documentation updates

documentation/src/main/asciidoc/userguide/chapters/query/programmatic/QuerySpecification.adoc

@@ -20,9 +20,9 @@ A `SelectionSpecification` allows to iteratively build a query from a "base", ad
 ====
 [source, java, indent=0]
 ----
-SelectionSpecification<Book> spec = session.createSelectionSpecification(
-    "from Book",
-    Book.class
+SelectionSpecification<Book> spec = SelectionSpecification.create(
+    Book.class,
+    "from Book"
 );
 ----
 ====
@@ -33,7 +33,7 @@ or a root entity as the base -
 ====
 [source, java, indent=0]
 ----
-SelectionSpecification<Book> spec = session.createSelectionSpecification(Book.class);
+SelectionSpecification<Book> spec = SelectionSpecification.create(Book.class);
 ----
 ====
 
@@ -45,15 +45,15 @@ Once we have the `SelectionSpecification` we can adjust the query adding restric
 ----
 // from here we can augment the base query "from Book",
 // with either restrictions
-spec.restriction(
+spec.restrict(
     Restriction.restrict(
         Book_.suggestedCost,
         Range.closed(10.00, 19.99)
     )
 );
 
 // or here with some sorting
-spec.order(
+spec.sort(
     Order.asc(Book_.suggestedCost)
 )
 ----
@@ -70,7 +70,7 @@ After adjusting the query, we can obtain the executable `SelectionQuery`:
 ====
 [source, java, indent=0]
 ----
-SelectionQuery<Book> qry = ds.createQuery();
+SelectionQuery<Book> qry = ds.createQuery(session);
 List<Book> books = qry.getResultList();
 ----
 ====
@@ -81,17 +81,17 @@ These calls can even be chained, e.g.
 ====
 [source, java, indent=0]
 ----
-SelectionQuery<Book> qry = session.createSelectionSpecification(
-    "from Book",
-    Book.class
-).restriction(
+SelectionQuery<Book> qry = SelectionSpecification.create(
+    Book.class,
+    "from Book"
+).restrict(
     Restriction.restrict(
         Book_.suggestedCost,
         Range.closed(10.00, 19.99)
     )
-).order(
+).sort(
     Order.asc(Book_.suggestedCost)
-).createQuery();
+).createQuery(session);
 ----
 ====
 
@@ -112,14 +112,14 @@ At the moment, only update and delete queries are supported.  E.g.
 ====
 [source, java, indent=0]
 ----
-MutationQuery<Book> qry = session.createMutationSpecification(
-    "delete Book",
-    Book.class
-).restriction(
+MutationQuery<Book> qry = MutationSpecification.create(
+    Book.class,
+    "delete Book"
+).restrict(
     Restriction.restrict(
         Book_.suggestedCost,
         Range.closed(10.00, 19.99)
     )
-).createQuery();
+).createQuery(session);
 ----
 ====

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

@@ -18,22 +18,25 @@
 /**
  * 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 SelectionQuery#setOrder(Order)}.
+ * 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.programmatic.SelectionSpecification#sort(Order)}.
  * <pre>
- * session.createSelectionQuery("from Book b join b.authors a where a.name = :name", Book.class)
+ * SelectionSpecification.create(Book.class,
+ *             "from Book b join b.authors a where a.name = :name")
+ *         .sort(asc(Book_.publicationDate))
+ *         .createQuery(session)
  *         .setParameter("name", authorName)
- *         .setOrder(asc(Book_.publicationDate))
  *         .getResultList();
  * </pre>
  * <p>
  * {@code Order}s may be stacked using {@link List#of} and
- * {@link SelectionQuery#setOrder(List)}.
+ * {@link org.hibernate.query.programmatic.SelectionSpecification#resort(List)}.
  * <pre>
- * session.createSelectionQuery("from Book b join b.authors a where a.name = :name", Book.class)
+ * SelectionSpecification.create(Book.class,
+ *             "from Book b join b.authors a where a.name = :name")
+ *         .sort(List.of(asc(Book_.publicationDate), desc(Book_.ssn)))
  *         .setParameter("name", authorName)
- *         .setOrder(List.of(asc(Book_.publicationDate), desc(Book_.ssn)))
  *         .getResultList();
  * </pre>
  * <p>
@@ -49,8 +52,8 @@
  *          used by Hibernate Data Repositories to implement Jakarta Data
  *          query methods.
  *
- * @see SelectionQuery#setOrder(Order)
- * @see SelectionQuery#setOrder(java.util.List)
+ * @see org.hibernate.query.programmatic.SelectionSpecification#sort(Order)
+ * @see org.hibernate.query.programmatic.SelectionSpecification#resort(List)
  * @see org.hibernate.query.restriction.Restriction
  *
  * @author Gavin King

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

@@ -14,7 +14,6 @@
 import org.hibernate.StatelessSession;
 import org.hibernate.query.IllegalMutationQueryException;
 import org.hibernate.query.MutationQuery;
-import org.hibernate.query.SelectionQuery;
 import org.hibernate.query.programmatic.internal.MutationSpecificationImpl;
 import org.hibernate.query.restriction.Restriction;
 
@@ -28,7 +27,7 @@
  * kinds.
  * <p>
  * Once all {@linkplain #restrict restrictions} are specified, call
- * {@link #createQuery createQuery()} to obtain an {@linkplain SelectionQuery
+ * {@link #createQuery createQuery()} to obtain an {@linkplain MutationQuery
  * executable mutation query object}.
  *
  * @param <T> The entity type which is the target of the mutation.

whats-new.adoc

@@ -129,17 +129,17 @@ A new API has been added for incremental definition of a query, with support for
 ====
 [source, java, indent=0]
 ----
-SelectionQuery<Book> qry = session.createSelectionSpecification(
-    "from Book",
-    Book.class
-).restriction(
+SelectionQuery<Book> qry = SelectionSpecification.create(
+    Book.class,
+    "from Book"
+).restrict(
     Restriction.restrict(
         Book_.suggestedCost,
         Range.closed(10.00, 19.99)
     )
-).order(
+).sort(
     Order.asc(Book_.suggestedCost)
-).createQuery();
+).createQuery(session);
 ----
 ====
 
@@ -148,15 +148,15 @@ as well as mutations -
 ====
 [source, java, indent=0]
 ----
-MutationQuery<Book> qry = session.createMutationSpecification(
-    "delete Book",
-    Book.class
-).restriction(
+MutationQuery<Book> qry = MutationSpecification.create(
+    Book.class,
+    "delete Book"
+).restrict(
     Restriction.restrict(
         Book_.suggestedCost,
         Range.closed(10.00, 19.99)
     )
-).createQuery();
+).createQuery(session);
 ----
 ====