add some comments and extract some methods in implicit instantiation stuff

Author: gavinking

hibernate-core/src/main/java/org/hibernate/query/sql/internal/NativeQueryImpl.java

@@ -356,6 +356,15 @@ protected <T> void setTupleTransformerForResultType(Class<T> resultClass) {
 		}
 	}
 
+	/**
+	 * If the result type of the query is {@link Tuple}, {@link Map}, {@link List},
+	 * or any record or class type with an appropriate constructor which is NOT a
+	 * registered basic type, then we attempt to repackage the result tuple as an
+	 * instance of the result type using an appropriate {@link TupleTransformer}.
+	 *
+	 * @param resultClass The requested result type of the query
+	 * @return A {@link TupleTransformer} responsible for repackaging the result type
+	 */
 	protected @Nullable TupleTransformer<?> determineTupleTransformerForResultType(Class<?> resultClass) {
 		if ( Tuple.class.equals( resultClass ) ) {
 			return NativeQueryTupleTransformer.INSTANCE;
@@ -369,7 +378,8 @@ else if ( List.class.equals( resultClass ) ) {
 		else if ( resultClass != Object.class && resultClass != Object[].class ) {
 			// TODO: this is extremely fragile and probably a bug
 			if ( isClass( resultClass ) && !hasJavaTypeDescriptor( resultClass ) ) {
-				// not a basic type
+				// not a basic type, so something we can attempt
+				// to instantiate to repackage the results
 				return new NativeQueryConstructorTransformer<>( resultClass );
 			}
 		}

hibernate-core/src/main/java/org/hibernate/query/sqm/internal/ConcreteSqmSelectQueryPlan.java

@@ -247,7 +247,15 @@ private static List<SqmSelection<?>> selections(SqmSelectStatement<?> sqm) {
 					char.class, Character.class
 			);
 
-	@SuppressWarnings("unchecked")
+	/**
+	 * If the result type of the query is {@link Tuple}, {@link Map}, {@link List},
+	 * or any record or class type with an appropriate constructor, then we attempt
+	 * to repackage the result tuple as an instance of the result type using an
+	 * appropriate {@link RowTransformer}.
+	 *
+	 * @param resultClass The requested result type of the query
+	 * @return A {@link RowTransformer} responsible for repackaging the result type
+	 */
 	protected static <T> RowTransformer<T> determineRowTransformer(
 			SqmSelectStatement<?> sqm,
 			Class<T> resultClass,
@@ -260,73 +268,90 @@ else if ( resultClass == null || resultClass == Object.class ) {
 			return RowTransformerStandardImpl.instance();
 		}
 		else {
-			final Class<T> resultType = (Class<T>)
-					WRAPPERS.getOrDefault( resultClass, resultClass );
-			final List<SqmSelection<?>> selections = selections( sqm );
+			final var selections = selections( sqm );
 			if ( selections == null ) {
-				throw new AssertionFailure("No selections");
+				throw new AssertionFailure( "No selections" );
 			}
-			switch ( selections.size() ) {
-				case 0:
-					throw new AssertionFailure("No selections");
-				case 1:
-					final SqmSelection<?> selection = selections.get(0);
-					if ( isSelectionAssignableToResultType( selection, resultType ) ) {
-						return RowTransformerSingularReturnImpl.instance();
-					}
-					else if ( resultType.isArray() ) {
-						return (RowTransformer<T>) RowTransformerArrayImpl.instance();
-					}
-					else if ( List.class.equals( resultType ) ) {
-						return (RowTransformer<T>) RowTransformerListImpl.instance();
-					}
-					else if ( Tuple.class.equals( resultType ) ) {
-						return (RowTransformer<T>) new RowTransformerJpaTupleImpl( tupleMetadata );
-					}
-					else if ( Map.class.equals( resultType ) ) {
-						return (RowTransformer<T>) new RowTransformerMapImpl( tupleMetadata );
-					}
-					else if ( isClass( resultType ) ) {
-						try {
-							return new RowTransformerConstructorImpl<>(
-									resultType,
-									tupleMetadata,
-									sqm.nodeBuilder().getTypeConfiguration()
-							);
-						}
-						catch (InstantiationException ie) {
-							return new RowTransformerCheckingImpl<>( resultType );
-						}
-					}
-					else {
-						return new RowTransformerCheckingImpl<>( resultType );
-					}
-				default:
-					if ( resultType.isArray() ) {
-						return (RowTransformer<T>) RowTransformerArrayImpl.instance();
-					}
-					else if ( List.class.equals( resultType ) ) {
-						return (RowTransformer<T>) RowTransformerListImpl.instance();
-					}
-					else if ( Tuple.class.equals( resultType ) ) {
-						return (RowTransformer<T>) new RowTransformerJpaTupleImpl( tupleMetadata );
-					}
-					else if ( Map.class.equals( resultType ) ) {
-						return (RowTransformer<T>) new RowTransformerMapImpl( tupleMetadata );
-					}
-					else if ( isClass( resultType ) ) {
-						return new RowTransformerConstructorImpl<>(
-								resultType,
-								tupleMetadata,
-								sqm.nodeBuilder().getTypeConfiguration()
-						);
-					}
-					else {
-						throw new QueryTypeMismatchException( "Result type '" + resultType.getSimpleName()
-								+ "' cannot be used to package the selected expressions" );
-					}
+			else {
+				final Class<T> resultType = primitiveToWrapper( resultClass );
+				return switch ( selections.size() ) {
+					case 0 -> throw new AssertionFailure( "No selections" );
+					case 1 -> singleItemRowTransformer( sqm, tupleMetadata, selections.get( 0 ), resultType );
+					default -> multipleItemRowTransformer( sqm, tupleMetadata, resultType );
+				};
+			}
+		}
+	}
+
+	/**
+	 * We tolerate the use of primitive query result types, for example,
+	 * {@code long.class} instead of {@code Long.class}. Note that this
+	 * has no semantics: we don't attempt to enforce that the query
+	 * result is non-null if it is primitive.
+	 */
+	@SuppressWarnings("unchecked")
+	private static <T> Class<T> primitiveToWrapper(Class<T> resultClass) {
+		// this cast, which looks like complete nonsense, is perfectly correct,
+		// since Java assigns the type Class<Long> to te expression long.class
+		// even though the resulting class object is distinct from Long.class
+		return (Class<T>) WRAPPERS.getOrDefault( resultClass, resultClass );
+	}
+
+	@SuppressWarnings("unchecked")
+	private static <T> RowTransformer<T> multipleItemRowTransformer
+			(SqmSelectStatement<?> sqm, TupleMetadata tupleMetadata, Class<T> resultType) {
+		if ( resultType.isArray() ) {
+			return (RowTransformer<T>) RowTransformerArrayImpl.instance();
+		}
+		else if ( List.class.equals( resultType ) ) {
+			return (RowTransformer<T>) RowTransformerListImpl.instance();
+		}
+		else if ( Tuple.class.equals( resultType ) ) {
+			return (RowTransformer<T>) new RowTransformerJpaTupleImpl( tupleMetadata );
+		}
+		else if ( Map.class.equals( resultType ) ) {
+			return (RowTransformer<T>) new RowTransformerMapImpl( tupleMetadata );
+		}
+		else if ( isClass( resultType ) ) {
+			return new RowTransformerConstructorImpl<>( resultType, tupleMetadata,
+					sqm.nodeBuilder().getTypeConfiguration() );
+		}
+		else {
+			throw new QueryTypeMismatchException( "Result type '" + resultType.getSimpleName()
+												+ "' cannot be used to package the selected expressions" );
+		}
+	}
+
+	@SuppressWarnings("unchecked")
+	private static <T> RowTransformer<T> singleItemRowTransformer
+			(SqmSelectStatement<?> sqm, TupleMetadata tupleMetadata, SqmSelection<?> selection, Class<T> resultType) {
+		if ( isSelectionAssignableToResultType( selection, resultType ) ) {
+			return RowTransformerSingularReturnImpl.instance();
+		}
+		else if ( resultType.isArray() ) {
+			return (RowTransformer<T>) RowTransformerArrayImpl.instance();
+		}
+		else if ( List.class.equals( resultType ) ) {
+			return (RowTransformer<T>) RowTransformerListImpl.instance();
+		}
+		else if ( Tuple.class.equals( resultType ) ) {
+			return (RowTransformer<T>) new RowTransformerJpaTupleImpl( tupleMetadata );
+		}
+		else if ( Map.class.equals( resultType ) ) {
+			return (RowTransformer<T>) new RowTransformerMapImpl( tupleMetadata );
+		}
+		else if ( isClass( resultType ) ) {
+			try {
+				return new RowTransformerConstructorImpl<>( resultType, tupleMetadata,
+						sqm.nodeBuilder().getTypeConfiguration() );
+			}
+			catch (InstantiationException ie) {
+				return new RowTransformerCheckingImpl<>( resultType );
 			}
 		}
+		else {
+			return new RowTransformerCheckingImpl<>( resultType );
+		}
 	}
 
 	private static <T> RowTransformer<T> makeRowTransformerTupleTransformerAdapter(

hibernate-core/src/main/java/org/hibernate/query/sqm/internal/SqmUtil.java

@@ -1222,6 +1222,14 @@ private static <T> void verifySelectionType(
 		}
 	}
 
+	/**
+	 * Any query result can be represented as a {@link Tuple}, {@link List}, or {@link Map},
+	 * simply by repackaging the result tuple. Also, any query result is assignable to
+	 * {@code Object}, or can be returned as an instance of {@code Object[]}.
+	 *
+	 * @see ConcreteSqmSelectQueryPlan#determineRowTransformer
+	 * @see org.hibernate.query.sql.internal.NativeQueryImpl#determineTupleTransformerForResultType
+	 */
 	public static boolean isResultTypeAlwaysAllowed(Class<?> expectedResultClass) {
 		return expectedResultClass == null
 			|| expectedResultClass == Object.class