Polishing.

Introduce refined names: EntityQuery, TemplatedQuery, ParametrizedQuery, QueryProvider. Return QueryProvider where possible. Introduce rewrite as concept on DeclaredQuery to retain its nature and track the origin of the query rewriting.

Move methods solely used in tests to TestDefaultEntityQuery.

Remove unused methods, fix naming, group DeclaredQuery implementations in DeclaredQueries. Add documentation.

See #3622
Original pull request: #3527

Author: mp911de

spring-data-jpa/src/jmh/java/org/springframework/data/jpa/repository/query/HqlParserBenchmarks.java

@@ -27,6 +27,8 @@
 import org.openjdk.jmh.annotations.Warmup;
 
 import org.springframework.data.domain.Sort;
+import org.springframework.data.projection.SpelAwareProxyProjectionFactory;
+import org.springframework.data.repository.query.ReturnedType;
 
 /**
  * @author Mark Paluch
@@ -44,6 +46,7 @@ public static class BenchmarkParameters {
 		DeclaredQuery query;
 		Sort sort = Sort.by("foo");
 		QueryEnhancer enhancer;
+		QueryEnhancer.QueryRewriteInformation rewriteInformation;
 
 		@Setup(Level.Iteration)
 		public void doSetup() {
@@ -57,12 +60,14 @@ OR TREAT(p AS SmallProject).name LIKE 'Persist%'
 
 			query = DeclaredQuery.jpqlQuery(s);
 			enhancer = QueryEnhancerFactory.forQuery(query).create(query);
+			rewriteInformation = new DefaultQueryRewriteInformation(sort,
+					ReturnedType.of(Object.class, Object.class, new SpelAwareProxyProjectionFactory()));
 		}
 	}
 
 	@Benchmark
 	public Object measure(BenchmarkParameters parameters) {
-		return parameters.enhancer.applySorting(parameters.sort);
+		return parameters.enhancer.rewrite(parameters.rewriteInformation);
 	}
 
 }

spring-data-jpa/src/jmh/java/org/springframework/data/jpa/repository/query/JSqlParserQueryEnhancerBenchmarks.java

@@ -29,6 +29,8 @@
 import org.openjdk.jmh.annotations.Warmup;
 
 import org.springframework.data.domain.Sort;
+import org.springframework.data.projection.SpelAwareProxyProjectionFactory;
+import org.springframework.data.repository.query.ReturnedType;
 
 /**
  * @author Mark Paluch
@@ -46,6 +48,7 @@ public static class BenchmarkParameters {
 		JSqlParserQueryEnhancer enhancer;
 		Sort sort = Sort.by("foo");
 		private byte[] serialized;
+		private QueryEnhancer.QueryRewriteInformation rewriteInformation;
 
 		@Setup(Level.Iteration)
 		public void doSetup() throws IOException {
@@ -57,12 +60,14 @@ public void doSetup() throws IOException {
 					union select SOME_COLUMN from SOME_OTHER_OTHER_TABLE""";
 
 			enhancer = new JSqlParserQueryEnhancer(DeclaredQuery.nativeQuery(s));
+			rewriteInformation = new DefaultQueryRewriteInformation(sort,
+					ReturnedType.of(Object.class, Object.class, new SpelAwareProxyProjectionFactory()));
 		}
 	}
 
 	@Benchmark
 	public Object applySortWithParsing(BenchmarkParameters p) {
-		return p.enhancer.applySorting(p.sort);
+		return p.enhancer.rewrite(p.rewriteInformation);
 	}
 
 }

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/JpaSpecificationExecutor.java

@@ -15,27 +15,17 @@
  */
 package org.springframework.data.jpa.repository;
 
-import jakarta.persistence.criteria.CriteriaBuilder;
-import jakarta.persistence.criteria.CriteriaQuery;
-import jakarta.persistence.criteria.Root;
-
-import java.util.Arrays;
-import java.util.Collection;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
 import java.util.Optional;
 import java.util.function.Function;
 
-import org.springframework.dao.InvalidDataAccessApiUsageException;
 import org.jspecify.annotations.Nullable;
 
 import org.springframework.dao.InvalidDataAccessApiUsageException;
-
-import org.jspecify.annotations.Nullable;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
-import org.springframework.data.domain.Slice;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.jpa.domain.DeleteSpecification;
 import org.springframework.data.jpa.domain.PredicateSpecification;
@@ -115,7 +105,6 @@ default List<T> findAll(PredicateSpecification<T> spec) {
 	 * Returns a {@link Page} of entities matching the given {@link Specification}.
 	 * <p>
 	 * Supports counting the total number of entities matching the {@link Specification}.
-	 * <p>
 	 *
 	 * @param spec can be {@literal null}, if no {@link Specification} is given all entities matching {@code <T>} will be
 	 *          selected.

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/NativeQuery.java

@@ -94,4 +94,5 @@
 	 * Name of the {@link jakarta.persistence.SqlResultSetMapping @SqlResultSetMapping(name)} to apply for this query.
 	 */
 	String sqlResultSetMapping() default "";
+
 }

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/Query.java

@@ -90,4 +90,5 @@
 	 * @since 3.0
 	 */
 	Class<? extends QueryRewriter> queryRewriter() default QueryRewriter.IdentityQueryRewriter.class;
+
 }

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/config/EnableJpaRepositories.java

@@ -178,4 +178,5 @@
 	 * @since 4.0
 	 */
 	Class<? extends QueryEnhancerSelector> queryEnhancerSelector() default QueryEnhancerSelector.DefaultQueryEnhancerSelector.class;
+
 }

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/AbstractStringBasedJpaQuery.java

@@ -20,9 +20,9 @@
 
 import java.util.Objects;
 
-import org.springframework.data.domain.Pageable;
-
 import org.jspecify.annotations.Nullable;
+
+import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.expression.ValueEvaluationContextProvider;
 import org.springframework.data.jpa.repository.QueryRewriter;
@@ -32,7 +32,6 @@
 import org.springframework.data.util.Lazy;
 import org.springframework.util.Assert;
 import org.springframework.util.ConcurrentLruCache;
-import org.springframework.util.StringUtils;
 
 /**
  * Base class for {@link String} based JPA queries.
@@ -49,8 +48,8 @@
  */
 abstract class AbstractStringBasedJpaQuery extends AbstractJpaQuery {
 
-	private final StringQuery query;
-	private final Lazy<IntrospectedQuery> countQuery;
+	private final EntityQuery query;
+	private final Lazy<ParametrizedQuery> countQuery;
 	private final ValueExpressionDelegate valueExpressionDelegate;
 	private final QueryRewriter queryRewriter;
 	private final QuerySortRewriter querySortRewriter;
@@ -64,25 +63,42 @@ abstract class AbstractStringBasedJpaQuery extends AbstractJpaQuery {
 	 * @param method must not be {@literal null}.
 	 * @param em must not be {@literal null}.
 	 * @param queryString must not be {@literal null}.
-	 * @param countQueryString must not be {@literal null}.
+	 * @param countQuery can be {@literal null} if not defined.
 	 * @param queryConfiguration must not be {@literal null}.
 	 */
-	public AbstractStringBasedJpaQuery(JpaQueryMethod method, EntityManager em, String queryString,
+	AbstractStringBasedJpaQuery(JpaQueryMethod method, EntityManager em, String queryString,
 			@Nullable String countQueryString, JpaQueryConfiguration queryConfiguration) {
+		this(method, em, method.getDeclaredQuery(queryString),
+				countQueryString != null ? method.getDeclaredQuery(countQueryString) : null, queryConfiguration);
+	}
+
+	/**
+	 * Creates a new {@link AbstractStringBasedJpaQuery} from the given {@link JpaQueryMethod}, {@link EntityManager} and
+	 * query {@link String}.
+	 *
+	 * @param method must not be {@literal null}.
+	 * @param em must not be {@literal null}.
+	 * @param query must not be {@literal null}.
+	 * @param countQuery can be {@literal null}.
+	 * @param queryConfiguration must not be {@literal null}.
+	 */
+	public AbstractStringBasedJpaQuery(JpaQueryMethod method, EntityManager em, DeclaredQuery query,
+			@Nullable DeclaredQuery countQuery, JpaQueryConfiguration queryConfiguration) {
 
 		super(method, em);
 
-		Assert.hasText(queryString, "Query string must not be null or empty");
+		Assert.notNull(query, "Query must not be null");
 		Assert.notNull(queryConfiguration, "JpaQueryConfiguration must not be null");
 
 		this.valueExpressionDelegate = queryConfiguration.getValueExpressionDelegate();
 		this.valueExpressionContextProvider = valueExpressionDelegate.createValueContextProvider(method.getParameters());
-		this.query = ExpressionBasedStringQuery.create(queryString, method, queryConfiguration);
+
+		this.query = TemplatedQuery.create(query, method.getEntityInformation(), queryConfiguration);
 
 		this.countQuery = Lazy.of(() -> {
 
-			if (StringUtils.hasText(countQueryString)) {
-				return ExpressionBasedStringQuery.create(countQueryString, method, queryConfiguration);
+			if (countQuery != null) {
+				return TemplatedQuery.create(countQuery, method.getEntityInformation(), queryConfiguration);
 			}
 
 			return this.query.deriveCountQuery(method.getCountQueryProjection());
@@ -108,21 +124,25 @@ public AbstractStringBasedJpaQuery(JpaQueryMethod method, EntityManager em, Stri
 				"JDBC style parameters (?) are not supported for JPA queries");
 	}
 
+	private DeclaredQuery createQuery(String queryString, boolean nativeQuery) {
+		return nativeQuery ? DeclaredQuery.nativeQuery(queryString) : DeclaredQuery.jpqlQuery(queryString);
+	}
+
 	@Override
 	public Query doCreateQuery(JpaParametersParameterAccessor accessor) {
 
 		Sort sort = accessor.getSort();
 		ResultProcessor processor = getQueryMethod().getResultProcessor().withDynamicProjection(accessor);
 		ReturnedType returnedType = processor.getReturnedType();
-		String sortedQueryString = getSortedQueryString(sort, returnedType);
-		Query query = createJpaQuery(sortedQueryString, sort, accessor.getPageable(), returnedType);
+		QueryProvider sortedQuery = getSortedQuery(sort, returnedType);
+		Query query = createJpaQuery(sortedQuery, sort, accessor.getPageable(), returnedType);
 
 		// it is ok to reuse the binding contained in the ParameterBinder, although we create a new query String because the
 		// parameters in the query do not change.
 		return parameterBinder.get().bindAndPrepare(query, accessor);
 	}
 
-	String getSortedQueryString(Sort sort, ReturnedType returnedType) {
+	QueryProvider getSortedQuery(Sort sort, ReturnedType returnedType) {
 		return querySortRewriter.getSorted(query, sort, returnedType);
 	}
 
@@ -131,7 +151,7 @@ protected ParameterBinder createBinder() {
 		return createBinder(query);
 	}
 
-	protected ParameterBinder createBinder(IntrospectedQuery query) {
+	protected ParameterBinder createBinder(ParametrizedQuery query) {
 		return ParameterBinderFactory.createQueryAwareBinder(getQueryMethod().getParameters(), query,
 				valueExpressionDelegate, valueExpressionContextProvider);
 	}
@@ -162,28 +182,28 @@ public EntityQuery getQuery() {
 	/**
 	 * @return the countQuery
 	 */
-	public IntrospectedQuery getCountQuery() {
+	public ParametrizedQuery getCountQuery() {
 		return countQuery.get();
 	}
 
 	/**
 	 * Creates an appropriate JPA query from an {@link EntityManager} according to the current {@link AbstractJpaQuery}
 	 * type.
 	 */
-	protected Query createJpaQuery(String queryString, Sort sort, @Nullable Pageable pageable,
+	protected Query createJpaQuery(QueryProvider query, Sort sort, @Nullable Pageable pageable,
 			ReturnedType returnedType) {
 
 		EntityManager em = getEntityManager();
 
 		if (this.query.hasConstructorExpression() || this.query.isDefaultProjection()) {
-			return em.createQuery(potentiallyRewriteQuery(queryString, sort, pageable));
+			return em.createQuery(potentiallyRewriteQuery(query.getQueryString(), sort, pageable));
 		}
 
 		Class<?> typeToRead = getTypeToRead(returnedType);
 
 		return typeToRead == null //
-				? em.createQuery(potentiallyRewriteQuery(queryString, sort, pageable)) //
-				: em.createQuery(potentiallyRewriteQuery(queryString, sort, pageable), typeToRead);
+				? em.createQuery(potentiallyRewriteQuery(query.getQueryString(), sort, pageable)) //
+				: em.createQuery(potentiallyRewriteQuery(query.getQueryString(), sort, pageable), typeToRead);
 	}
 
 	/**
@@ -202,16 +222,16 @@ protected String potentiallyRewriteQuery(String originalQuery, Sort sort, @Nulla
 				: queryRewriter.rewrite(originalQuery, sort);
 	}
 
-	String applySorting(CachableQuery cachableQuery) {
-		return cachableQuery.getDeclaredQuery().getQueryEnhancer()
+	QueryProvider applySorting(CachableQuery cachableQuery) {
+		return cachableQuery.getDeclaredQuery()
 				.rewrite(new DefaultQueryRewriteInformation(cachableQuery.getSort(), cachableQuery.getReturnedType()));
 	}
 
 	/**
 	 * Query Sort Rewriter interface.
 	 */
 	interface QuerySortRewriter {
-		String getSorted(StringQuery query, Sort sort, ReturnedType returnedType);
+		QueryProvider getSorted(EntityQuery query, Sort sort, ReturnedType returnedType);
 	}
 
 	/**
@@ -221,28 +241,28 @@ enum SimpleQuerySortRewriter implements QuerySortRewriter {
 
 		INSTANCE;
 
-		public String getSorted(StringQuery query, Sort sort, ReturnedType returnedType) {
-			return query.getQueryEnhancer().rewrite(new DefaultQueryRewriteInformation(sort, returnedType));
+		public QueryProvider getSorted(EntityQuery query, Sort sort, ReturnedType returnedType) {
+			return query.rewrite(new DefaultQueryRewriteInformation(sort, returnedType));
 		}
 	}
 
 	static class UnsortedCachingQuerySortRewriter implements QuerySortRewriter {
 
-		private volatile @Nullable String cachedQueryString;
+		private volatile @Nullable QueryProvider cachedQuery;
 
-		public String getSorted(StringQuery query, Sort sort, ReturnedType returnedType) {
+		public QueryProvider getSorted(EntityQuery query, Sort sort, ReturnedType returnedType) {
 
 			if (sort.isSorted()) {
 				throw new UnsupportedOperationException("NoOpQueryCache does not support sorting");
 			}
 
-			String cachedQueryString = this.cachedQueryString;
-			if (cachedQueryString == null) {
-				this.cachedQueryString = cachedQueryString = query.getQueryEnhancer()
+			QueryProvider cachedQuery = this.cachedQuery;
+			if (cachedQuery == null) {
+				this.cachedQuery = cachedQuery = query
 						.rewrite(new DefaultQueryRewriteInformation(sort, returnedType));
 			}
 
-			return cachedQueryString;
+			return cachedQuery;
 		}
 	}
 
@@ -251,22 +271,22 @@ public String getSorted(StringQuery query, Sort sort, ReturnedType returnedType)
 	 */
 	class CachingQuerySortRewriter implements QuerySortRewriter {
 
-		private final ConcurrentLruCache<CachableQuery, String> queryCache = new ConcurrentLruCache<>(16,
+		private final ConcurrentLruCache<CachableQuery, QueryProvider> queryCache = new ConcurrentLruCache<>(16,
 				AbstractStringBasedJpaQuery.this::applySorting);
 
-		private volatile @Nullable String cachedQueryString;
+		private volatile @Nullable QueryProvider cachedQuery;
 
 		@Override
-		public String getSorted(StringQuery query, Sort sort, ReturnedType returnedType) {
+		public QueryProvider getSorted(EntityQuery query, Sort sort, ReturnedType returnedType) {
 
 			if (sort.isUnsorted()) {
 
-				String cachedQueryString = this.cachedQueryString;
-				if (cachedQueryString == null) {
-					this.cachedQueryString = cachedQueryString = queryCache.get(new CachableQuery(query, sort, returnedType));
+				QueryProvider cachedQuery = this.cachedQuery;
+				if (cachedQuery == null) {
+					this.cachedQuery = cachedQuery = queryCache.get(new CachableQuery(query, sort, returnedType));
 				}
 
-				return cachedQueryString;
+				return cachedQuery;
 			}
 
 			return queryCache.get(new CachableQuery(query, sort, returnedType));
@@ -282,20 +302,20 @@ public String getSorted(StringQuery query, Sort sort, ReturnedType returnedType)
 	 */
 	static class CachableQuery {
 
-		private final StringQuery query;
+		private final EntityQuery query;
 		private final String queryString;
 		private final Sort sort;
 		private final ReturnedType returnedType;
 
-		CachableQuery(StringQuery query, Sort sort, ReturnedType returnedType) {
+		CachableQuery(EntityQuery query, Sort sort, ReturnedType returnedType) {
 
 			this.query = query;
 			this.queryString = query.getQueryString();
 			this.sort = sort;
 			this.returnedType = returnedType;
 		}
 
-		StringQuery getDeclaredQuery() {
+		EntityQuery getDeclaredQuery() {
 			return query;
 		}