From ab9eb9a4964a8b099c9af443d7f527de9499d3a5 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Wed, 13 Nov 2024 16:32:50 +0100
Subject: [PATCH] add examples to MutationQuery, SelectionQuery javadoc

---
 .../org/hibernate/query/MutationQuery.java     |  5 +++++
 .../org/hibernate/query/SelectionQuery.java    | 18 ++++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/hibernate-core/src/main/java/org/hibernate/query/MutationQuery.java b/hibernate-core/src/main/java/org/hibernate/query/MutationQuery.java
index e45eeb5d1f..046a9c097e 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/MutationQuery.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/MutationQuery.java
@@ -46,6 +46,11 @@ import jakarta.persistence.TemporalType;
  *     {@link #setParameter(int, Object)} allow arguments to be bound to named
  *     and ordinal parameters defined by the query.
  * </ul>
+ * <pre>
+ * session.createMutationQuery("delete Draft where lastUpdated < local date - ?1 year")
+ *         .setParameter(1, years)
+ *         .executeUpdate();
+ * </pre>
  *
  * @author Steve Ebersole
  */
diff --git a/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java b/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
index 7a403deee2..f630155646 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java
@@ -66,6 +66,24 @@ import org.hibernate.graph.GraphSemantic;
  *     {@link #setParameter(int, Object)} allow arguments to be bound to named
  *     and ordinal parameters defined by the query.
  * </ul>
+ * A query which returns multiple results should be executed via
+ * {@link #getResultList()}:
+ * <pre>
+ * List&lt;Book&gt; books =
+ *         session.createSelectionQuery("from Book left join fetch authors where title like :title")
+ *                 .setParameter("title", title)
+ *                 .setMaxResults(50)
+ *                 .getResultList();
+ * </pre>
+ * A query which is expected to return exactly one on result should be executed
+ * via {@link #getSingleResult()}, or, if it might not return a result,
+ * {@link #getSingleResultOrNull()}:
+ * <pre>
+ * Book book =
+ *         session.createSelectionQuery("from Book where isbn = ?1")
+ *                 .setParameter(1, isbn)
+ *                 .getSingleResultOrNull();
+ * </pre>
  * <p>
  * A query may have explicit <em>fetch joins</em>, specified using the syntax
  * {@code join fetch} in HQL, or via {@link jakarta.persistence.criteria.From#fetch}