From c0137e7de242d9e561cab9e9b64d6d7a22958865 Mon Sep 17 00:00:00 2001
From: Steve Ebersole <steve@hibernate.org>
Date: Sat, 15 Jan 2022 08:50:14 -0600
Subject: [PATCH] additional clean up of - "massive" cleanout of the
 transformers stuff

---
 .../main/java/org/hibernate/query/Query.java   | 10 ++++++++++
 .../hibernate/query/ResultListTransformer.java | 13 +++++++++----
 .../org/hibernate/query/TupleTransformer.java  | 18 +++++++++++-------
 .../hibernate/transform/ResultTransformer.java |  2 +-
 4 files changed, 31 insertions(+), 12 deletions(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/query/Query.java b/hibernate-core/src/main/java/org/hibernate/query/Query.java
index aff7d90685..9f69e21b85 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/Query.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/Query.java
@@ -131,6 +131,8 @@ public interface Query<R> extends TypedQuery<R>, CommonQueryContract {
 	 * by default each result in the list is packaged in an array of type
 	 * {@code Object[]}.
 	 *
+	 * @implNote Delegates to {@link #list()}
+	 *
 	 * @return the results as a list
 	 */
 	default List<R> getResultList() {
@@ -146,6 +148,10 @@ public interface Query<R> extends TypedQuery<R>, CommonQueryContract {
 	 * The client should call {@link Stream#close()} after processing the
 	 * stream so that resources are freed as soon as possible.
 	 *
+	 * @implNote Delegates to {@link #stream()}, which in turn delegates
+	 * to this method.  Implementors should implement at least one of
+	 * these methods.
+	 *
 	 * @return The results as a {@link Stream}
 	 */
 	default Stream<R> getResultStream() {
@@ -217,6 +223,10 @@ public interface Query<R> extends TypedQuery<R>, CommonQueryContract {
 	 *
 	 * @return The results as a {@link Stream}
 	 *
+	 * @implNote Delegates to {@link #getResultStream()}, which in turn
+	 * delegates to this method.  Implementors should implement at least
+	 * one of these methods.
+	 *
 	 * @since 5.2
 	 */
 	default Stream<R> stream() {
diff --git a/hibernate-core/src/main/java/org/hibernate/query/ResultListTransformer.java b/hibernate-core/src/main/java/org/hibernate/query/ResultListTransformer.java
index a2d2cf3bb0..230f3749fa 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/ResultListTransformer.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/ResultListTransformer.java
@@ -8,16 +8,21 @@ package org.hibernate.query;
 
 import java.util.List;
 
+import org.hibernate.Incubating;
+
 /**
- * Defines some processing performed on the result {@link List} of a
- * {@link org.hibernate.Query} before the result list is returned to
- * the caller of {@link org.hibernate.Query#getResultList()}.
+ * Defines some processing performed on the overall result {@link List}
+ * of a {@link Query} before the result list is returned to the caller.
  *
- * @see org.hibernate.transform.ResultTransformer
+ * @see Query#setResultListTransformer
+ * @see Query#list
+ * @see Query#getResultList
+ * @see TupleTransformer
  *
  * @author Steve Ebersole
  * @author Gavin King
  */
+@Incubating
 @FunctionalInterface
 public interface ResultListTransformer<T> {
 	/**
diff --git a/hibernate-core/src/main/java/org/hibernate/query/TupleTransformer.java b/hibernate-core/src/main/java/org/hibernate/query/TupleTransformer.java
index 60d358fef6..7fbdd8b9aa 100644
--- a/hibernate-core/src/main/java/org/hibernate/query/TupleTransformer.java
+++ b/hibernate-core/src/main/java/org/hibernate/query/TupleTransformer.java
@@ -6,28 +6,32 @@
  */
 package org.hibernate.query;
 
+import org.hibernate.Incubating;
 import org.hibernate.sql.results.internal.RowTransformerTupleTransformerAdapter;
 
 import java.util.List;
 
 /**
- * Defines some transformation applied to each result of a {@link org.hibernate.Query}
- * before the results are packaged as a {@link List} and returned to the caller of
- * {@link org.hibernate.Query#getResultList()}. Each query result is received as a
- * tuple, that is, as an array of type {@code Object[]}, and may be transformed to
+ * Defines some transformation applied to each result of a {@link Query}
+ * before the results are packaged as a {@link List} and returned to the caller.  Each result
+ * is received as a tuple (that is, as an {@code Object[]}), and may be transformed to
  * some other type.
- * <p>
- * Every {@code TupleTransformer} is automatically wrapped in an instance of
+ *
+ * @implNote Every {@code TupleTransformer} is automatically wrapped in an instance of
  * {@link RowTransformerTupleTransformerAdapter}, adapting it to the
  * {@link org.hibernate.sql.results.spi.RowTransformer} contract, which is always
  * used to actually process the results internally.
  *
- * @see org.hibernate.transform.ResultTransformer
+ * @see Query#setTupleTransformer
+ * @see Query#list
+ * @see Query#getResultList
+ * @see ResultListTransformer
  * @see org.hibernate.sql.results.spi.RowTransformer
  *
  * @author Steve Ebersole
  * @author Gavin King
  */
+@Incubating
 @FunctionalInterface
 public interface TupleTransformer<T> {
 	/**
diff --git a/hibernate-core/src/main/java/org/hibernate/transform/ResultTransformer.java b/hibernate-core/src/main/java/org/hibernate/transform/ResultTransformer.java
index 22d28f0e7f..65da3d2c33 100644
--- a/hibernate-core/src/main/java/org/hibernate/transform/ResultTransformer.java
+++ b/hibernate-core/src/main/java/org/hibernate/transform/ResultTransformer.java
@@ -21,7 +21,7 @@ import org.hibernate.query.TupleTransformer;
  *
  * @author Gavin King
  *
- * @deprecated Use {@link TupleTransformer} and/or {@link ResultListTransformer}
+ * @deprecated (since 6.0) Use {@link TupleTransformer} and/or {@link ResultListTransformer} instead
  */
 @Deprecated
 public interface ResultTransformer<T> extends TupleTransformer<T>, ResultListTransformer<T>, Serializable {