update the javadoc after the addition of QuerySpecification

Author: gavinking

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

@@ -513,6 +513,8 @@ public interface QueryProducer {
 	 *
 	 * @throws IllegalSelectQueryException The given HQL is expected to be a {@code select} query.  This method will
 	 * throw an exception if not.
+	 *
+	 * @since 7.0
 	 */
 	@Incubating
 	<T> SelectionSpecification<T> createSelectionSpecification(String hql, Class<T> resultType)
@@ -530,6 +532,8 @@ <T> SelectionSpecification<T> createSelectionSpecification(String hql, Class<T>
 	 *
 	 * @param <T> The entity type which is the root of the query.
 	 * {@code resultType} and {@code <T>} are both expected to refer to a singular query root.
+	 *
+	 * @since 7.0
 	 */
 	@Incubating
 	<T> SelectionSpecification<T> createSelectionSpecification(Class<T> rootEntityType);
@@ -547,6 +551,8 @@ <T> SelectionSpecification<T> createSelectionSpecification(String hql, Class<T>
 	 *
 	 * @throws IllegalMutationQueryException Only {@code update} and {@code delete} are supported;
 	 * this method will throw an exception if the given HQL query is not an {@code update} or {@code delete}.
+	 *
+	 * @since 7.0
 	 */
 	@Incubating
 	<T> MutationSpecification<T> createMutationSpecification(String hql, Class<T> mutationTarget)

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

@@ -100,11 +100,6 @@
  * every {@link jakarta.persistence.FetchType#EAGER eager} {@code @ManyToOne} or
  * {@code @OneToOne} association belonging to an entity returned by the query.
  * <p>
- * The method {@link #addRestriction(Restriction)} allows application of additional
- * {@linkplain Restriction filtering} to the query results. The static factory
- * methods of {@code Restriction} are used to express filtering criteria of various
- * kinds.
- * <p>
  * Finally, two alternative approaches to pagination are available:
  * <ol>
  * <li>
@@ -114,10 +109,9 @@
  * {@link #setFirstResult(int)} and {@link #setMaxResults(int)}.
  * <pre>
  * session.createSelectionQuery("from Book", Book.class)
- *         .addRestriction(Restriction.contains(Book_.title, "hibernate", false))
  *         .setOrder(Order.desc(Book_.title))
  *         .setPage(Page.first(50))
- *         .getResultList() );
+ *         .getResultList();
  * </pre>
  * <li>
  * On the other hand, {@link KeyedPage} and {@link KeyedResultList}, along with

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

@@ -11,14 +11,23 @@
 import org.hibernate.query.restriction.Restriction;
 
 /**
- * Specialization of QuerySpecification for building
+ * Specialization of {@link QuerySpecification} for programmatic customization of
  * {@linkplain MutationQuery mutation queries}.
- * Once all {@linkplain #addRestriction restrictions} are defined, call
- * {@linkplain #createQuery()} to obtain the executable form.
+ * <p>
+ * The method {@link #addRestriction(Restriction)} allows application of additional
+ * {@linkplain Restriction filtering} to the mutated entity. The static factory
+ * methods of {@link Restriction} are used to express filtering criteria of various
+ * kinds.
+ * <p>
+ * Once all {@linkplain #addRestriction restrictions} are specified, call
+ * {@linkplain #createQuery()} to obtain an {@linkplain SelectionQuery an
+ * executable mutation query object}.
  *
  * @param <T> The entity type which is the target of the mutation.
  *
  * @author Steve Ebersole
+ *
+ * @since 7.0
  */
 @Incubating
 public interface MutationSpecification<T> extends QuerySpecification<T> {
@@ -38,5 +47,6 @@ default Root<T> getMutationTarget() {
 	/**
 	 * Finalize the building and create the {@linkplain SelectionQuery} instance.
 	 */
+	@Override
 	MutationQuery createQuery();
 }

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

@@ -17,6 +17,8 @@
  * @apiNote Query specifications only support a {@linkplain #getRoot() single root}.
  *
  * @author Steve Ebersole
+ *
+ * @since 7.0
  */
 @Incubating
 public interface QuerySpecification<T> {

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

@@ -14,15 +14,40 @@
 import java.util.List;
 
 /**
- * Specialization of QuerySpecification for building
- * {@linkplain SelectionQuery selection queries} supporting ordering
- * in addition to restrictions.
+ * Specialization of {@link QuerySpecification} for programmatic customization of
+ * {@linkplain SelectionQuery selection queries} with ordering and restriction criteria.
+ * <ul>
+ * <li>The method {@link #addRestriction(Restriction)} allows application of additional
+ *     {@linkplain Restriction filtering} to the query results. The static factory methods
+ *     of {@link Restriction} are used to express filtering criteria of various kinds.
+ * <li>Refinement or replacement of the query sorting criteria is possible via the methods
+ *     {@link #addOrdering(Order)} and {@link #setOrdering(List)}, together with the static
+ *     factory methods of {@link Order}.
+ * </ul>
+ * <p>
  * Once all {@linkplain #addOrdering sorting} and {@linkplain #addRestriction restrictions}
- * are defined, call {@linkplain #createQuery()} to obtain the executable form.
+ * are specified, call {@linkplain #createQuery()} to obtain an {@linkplain SelectionQuery
+ * executable selection query object}.
+ * <pre>
+ * session.createSelectionSpecification("from Book", Book.class)
+ *         .addRestriction(Restriction.contains(Book_.title, "hibernate", false))
+ *         .setOrdering(Order.desc(Book_.title))
+ *         .createQuery()                       // obtain a SelectionQuery
+ *         .setPage(Page.first(50))
+ *         .getResultList();
+ * </pre>
+ * <p>
+ * 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.
+ *
+ * @param <T> The entity type returned by the query
  *
  * @see QueryProducer#createSelectionSpecification(String, Class)
  *
  * @author Steve Ebersole
+ *
+ * @since 7.0
  */
 @Incubating
 public interface SelectionSpecification<T> extends QuerySpecification<T> {
@@ -73,5 +98,6 @@ public interface SelectionSpecification<T> extends QuerySpecification<T> {
 	/**
 	 * Covariant override.
 	 */
+	@Override
 	SelectionQuery<T> createQuery();
 }

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

@@ -17,9 +17,10 @@
  * A compound path is a sequence of attribute references rooted at
  * the root entity type of the query.
  * <pre>
- * session.createSelectionQuery("from Book", Book.class)
+ * session.createSelectionSpecification("from Book", Book.class)
  *         .addRestriction(from(Book.class).to(Book_.publisher).to(Publisher_.name)
  *                         .equalTo("Manning"))
+ *         .createQuery()
  *         .getResultList()
  * </pre>
  * A compound path-based restriction has the same semantics as the

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

@@ -19,16 +19,16 @@
 import java.util.List;
 
 /**
- * A rule for restricting query results.
- * <p>
- * This allows restrictions to be added to a {@link SelectionQuery} by calling
+ * A rule for restricting query results. This allows restrictions to be added to
+ * a {@link org.hibernate.query.programmatic.SelectionSpecification} by calling
  * {@link SelectionQuery#addRestriction(Restriction)}.
  * <pre>
- * session.createSelectionQuery("from Book", Book.class)
+ * session.createSelectionSpecification("from Book", Book.class)
  *         .addRestriction(Restriction.like(Book_.title, "%Hibernate%", false))
  *         .addRestriction(Restriction.greaterThan(Book_.pages, 100))
  *         .setOrder(Order.desc(Book_.title))
- *         .getResultList() );
+ *         .createQuery()
+ *         .getResultList();
  * </pre>
  * <p>
  * Each restriction pairs an {@linkplain SingularAttribute attribute} of the
@@ -48,7 +48,10 @@
  *          is used by Hibernate Data Repositories to implement Jakarta Data
  *          query methods.
  *
- * @see SelectionQuery#addRestriction(Restriction)
+ * @see org.hibernate.query.programmatic.SelectionSpecification
+ * @see org.hibernate.query.programmatic.MutationSpecification
+ * @see org.hibernate.query.programmatic.QuerySpecification#addRestriction(Restriction)
+ *
  * @see Path
  * @see Order
  *