Provide a more sophisticated QueryEnhancer selection algorithm.

Sometimes the automatically chosen `QueryEnhancer` (e.g. `JSqlParserQueryEnhancer`) isn't the right one. Go through a series of choices, finding the first one that doesn't fail on query creation.

Also provide an override through `@QueryEnhancerOverride` that bypasses the selection process, available at the repository level and on a per-method basis.

Resolves #2564.

Author: DiegoKrupitza

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

@@ -18,9 +18,6 @@
 import jakarta.persistence.EntityManager;
 import jakarta.persistence.Query;
 
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
-
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.jpa.repository.QueryRewriter;
@@ -65,8 +62,8 @@ abstract class AbstractStringBasedJpaQuery extends AbstractJpaQuery {
 	 * @param queryRewriter must not be {@literal null}.
 	 */
 	public AbstractStringBasedJpaQuery(JpaQueryMethod method, EntityManager em, String queryString,
-			@Nullable String countQueryString, QueryRewriter queryRewriter, QueryMethodEvaluationContextProvider evaluationContextProvider,
-			SpelExpressionParser parser) {
+			@Nullable String countQueryString, QueryRewriter queryRewriter,
+			QueryMethodEvaluationContextProvider evaluationContextProvider, SpelExpressionParser parser) {
 
 		super(method, em);
 
@@ -77,7 +74,7 @@ public AbstractStringBasedJpaQuery(JpaQueryMethod method, EntityManager em, Stri
 
 		this.evaluationContextProvider = evaluationContextProvider;
 		this.query = new ExpressionBasedStringQuery(queryString, method.getEntityInformation(), parser,
-				method.isNativeQuery());
+				method.isNativeQuery(), method.getQueryEnhancerOverride());
 
 		DeclaredQuery countQuery = query.deriveCountQuery(countQueryString, method.getCountQueryProjection());
 		this.countQuery = ExpressionBasedStringQuery.from(countQuery, method.getEntityInformation(), parser,

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

@@ -25,9 +25,10 @@
  *
  * @author Jens Schauder
  * @author Diego Krupitza
+ * @author Greg Turnquist
  * @since 2.0.3
  */
-interface DeclaredQuery {
+public interface DeclaredQuery {
 
 	/**
 	 * Creates a {@literal DeclaredQuery} from a query {@literal String}.
@@ -105,10 +106,40 @@ default boolean usesPaging() {
 
 	/**
 	 * Return whether the query is a native query of not.
-	 * 
+	 *
 	 * @return <code>true</code> if native query otherwise <code>false</code>
 	 */
 	default boolean isNativeQuery() {
 		return false;
 	}
+
+	/**
+	 * Gets the {@link QueryEnhancer} used for this Query.
+	 *
+	 * @return the concrete {@link QueryEnhancer} implementation used for this given Query
+	 * @since 3.1
+	 */
+	@Nullable
+	default QueryEnhancer getQueryEnhancer() {
+		return null;
+	}
+
+	/**
+	 * Returns the method's {@link QueryEnhancerOverride} annotation
+	 *
+	 * @since 3.1
+	 */
+	@Nullable
+	default QueryEnhancerOverride getQueryEnhancerOverride() {
+		return null;
+	}
+
+	/**
+	 * Returns whether the method has a {@link QueryEnhancerOverride} or not
+	 *
+	 * @since 3.1
+	 */
+	default boolean hasQueryEnhancerOverride() {
+		return getQueryEnhancerOverride() != null;
+	}
 }

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

@@ -24,43 +24,37 @@
  * The implementation of {@link QueryEnhancer} using {@link QueryUtils}.
  *
  * @author Diego Krupitza
+ * @author Greg Turnquist
  * @since 2.7.0
  */
-public class DefaultQueryEnhancer implements QueryEnhancer {
-
-	private final DeclaredQuery query;
+public class DefaultQueryEnhancer extends QueryEnhancer {
 
 	public DefaultQueryEnhancer(DeclaredQuery query) {
-		this.query = query;
+		super(query);
 	}
 
 	@Override
 	public String applySorting(Sort sort, @Nullable String alias) {
-		return QueryUtils.applySorting(this.query.getQueryString(), sort, alias);
+		return QueryUtils.applySorting(getQuery().getQueryString(), sort, alias);
 	}
 
 	@Override
 	public String detectAlias() {
-		return QueryUtils.detectAlias(this.query.getQueryString());
+		return QueryUtils.detectAlias(getQuery().getQueryString());
 	}
 
 	@Override
 	public String createCountQueryFor(@Nullable String countProjection) {
-		return QueryUtils.createCountQueryFor(this.query.getQueryString(), countProjection);
+		return QueryUtils.createCountQueryFor(getQuery().getQueryString(), countProjection);
 	}
 
 	@Override
 	public String getProjection() {
-		return QueryUtils.getProjection(this.query.getQueryString());
+		return QueryUtils.getProjection(getQuery().getQueryString());
 	}
 
 	@Override
 	public Set<String> getJoinAliases() {
-		return QueryUtils.getOuterJoinAliases(this.query.getQueryString());
-	}
-
-	@Override
-	public DeclaredQuery getQuery() {
-		return this.query;
+		return QueryUtils.getOuterJoinAliases(getQuery().getQueryString());
 	}
 }

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

@@ -25,6 +25,7 @@
  * NULL-Object pattern implementation for {@link DeclaredQuery}.
  *
  * @author Jens Schauder
+ * @author Diego Krupitza
  * @since 2.0.3
  */
 class EmptyDeclaredQuery implements DeclaredQuery {

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

@@ -22,12 +22,13 @@
 import org.springframework.expression.ParserContext;
 import org.springframework.expression.spel.standard.SpelExpressionParser;
 import org.springframework.expression.spel.support.StandardEvaluationContext;
+import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
  * Extension of {@link StringQuery} that evaluates the given query string as a SpEL template-expression.
  * <p>
- * Currently the following template variables are available:
+ * Currently, the following template variables are available:
  * <ol>
  * <li>{@code #entityName} - the simple class name of the given entity</li>
  * <ol>
@@ -60,7 +61,23 @@ class ExpressionBasedStringQuery extends StringQuery {
 	 */
 	public ExpressionBasedStringQuery(String query, JpaEntityMetadata<?> metadata, SpelExpressionParser parser,
 			boolean nativeQuery) {
-		super(renderQueryIfExpressionOrReturnQuery(query, metadata, parser), nativeQuery && !containsExpression(query));
+		super(renderQueryIfExpressionOrReturnQuery(query, metadata, parser), nativeQuery && !containsExpression(query),
+				null);
+	}
+
+	/**
+	 * Creates a new {@link ExpressionBasedStringQuery} for the given query and {@link EntityMetadata}.
+	 *
+	 * @param query must not be {@literal null} or empty.
+	 * @param metadata must not be {@literal null}.
+	 * @param parser must not be {@literal null}.
+	 * @param nativeQuery is a given query is native or not
+	 * @param queryEnhancerOverride may be {@literal null}.
+	 */
+	public ExpressionBasedStringQuery(String query, JpaEntityMetadata<?> metadata, SpelExpressionParser parser,
+			boolean nativeQuery, @Nullable QueryEnhancerOverride queryEnhancerOverride) {
+		super(renderQueryIfExpressionOrReturnQuery(query, metadata, parser), nativeQuery && !containsExpression(query),
+				queryEnhancerOverride);
 	}
 
 	/**
@@ -74,7 +91,8 @@ public ExpressionBasedStringQuery(String query, JpaEntityMetadata<?> metadata, S
 	 */
 	static ExpressionBasedStringQuery from(DeclaredQuery query, JpaEntityMetadata<?> metadata,
 			SpelExpressionParser parser, boolean nativeQuery) {
-		return new ExpressionBasedStringQuery(query.getQueryString(), metadata, parser, nativeQuery);
+		return new ExpressionBasedStringQuery(query.getQueryString(), metadata, parser, nativeQuery,
+				query.getQueryEnhancerOverride());
 	}
 
 	/**

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

@@ -29,11 +29,23 @@
 import net.sf.jsqlparser.statement.delete.Delete;
 import net.sf.jsqlparser.statement.insert.Insert;
 import net.sf.jsqlparser.statement.merge.Merge;
-import net.sf.jsqlparser.statement.select.*;
+import net.sf.jsqlparser.statement.select.OrderByElement;
+import net.sf.jsqlparser.statement.select.PlainSelect;
+import net.sf.jsqlparser.statement.select.Select;
+import net.sf.jsqlparser.statement.select.SelectBody;
+import net.sf.jsqlparser.statement.select.SelectExpressionItem;
+import net.sf.jsqlparser.statement.select.SelectItem;
+import net.sf.jsqlparser.statement.select.SetOperationList;
+import net.sf.jsqlparser.statement.select.WithItem;
 import net.sf.jsqlparser.statement.update.Update;
 import net.sf.jsqlparser.statement.values.ValuesStatement;
 
-import java.util.*;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
 import java.util.stream.Collectors;
 
 import org.springframework.data.domain.Sort;
@@ -50,17 +62,16 @@
  * @author Geoffrey Deremetz
  * @since 2.7.0
  */
-public class JSqlParserQueryEnhancer implements QueryEnhancer {
+public class JSqlParserQueryEnhancer extends QueryEnhancer {
 
-	private final DeclaredQuery query;
 	private final ParsedType parsedType;
 
 	/**
 	 * @param query the query we want to enhance. Must not be {@literal null}.
 	 */
 	public JSqlParserQueryEnhancer(DeclaredQuery query) {
 
-		this.query = query;
+		super(query);
 		this.parsedType = detectParsedType();
 	}
 
@@ -72,7 +83,7 @@ public JSqlParserQueryEnhancer(DeclaredQuery query) {
 	private ParsedType detectParsedType() {
 
 		try {
-			Statement statement = CCJSqlParserUtil.parse(this.query.getQueryString());
+			Statement statement = CCJSqlParserUtil.parse(getQuery().getQueryString());
 
 			if (statement instanceof Insert) {
 				return ParsedType.INSERT;
@@ -95,7 +106,7 @@ private ParsedType detectParsedType() {
 	@Override
 	public String applySorting(Sort sort, @Nullable String alias) {
 
-		String queryString = query.getQueryString();
+		String queryString = getQuery().getQueryString();
 		Assert.hasText(queryString, "Query must not be null or empty");
 
 		if (this.parsedType != ParsedType.SELECT) {
@@ -192,7 +203,7 @@ Set<String> getSelectionAliases() {
 			return new HashSet<>();
 		}
 
-		Select selectStatement = parseSelectStatement(this.query.getQueryString());
+		Select selectStatement = parseSelectStatement(getQuery().getQueryString());
 		PlainSelect selectBody = (PlainSelect) selectStatement.getSelectBody();
 		return this.getSelectionAliases(selectBody);
 	}
@@ -280,7 +291,7 @@ private OrderByElement getOrderClause(final Set<String> joinAliases, final Set<S
 
 	@Override
 	public String detectAlias() {
-		return detectAlias(this.query.getQueryString());
+		return detectAlias(getQuery().getQueryString());
 	}
 
 	/**
@@ -354,18 +365,18 @@ private String detectAlias(Merge mergeStatement) {
 	public String createCountQueryFor(@Nullable String countProjection) {
 
 		if (this.parsedType != ParsedType.SELECT) {
-			return this.query.getQueryString();
+			return getQuery().getQueryString();
 		}
 
-		Assert.hasText(this.query.getQueryString(), "OriginalQuery must not be null or empty");
+		Assert.hasText(getQuery().getQueryString(), "OriginalQuery must not be null or empty");
 
-		Select selectStatement = parseSelectStatement(this.query.getQueryString());
+		Select selectStatement = parseSelectStatement(getQuery().getQueryString());
 
 		/*
 		  We only support count queries for {@link PlainSelect}.
 		 */
 		if (!(selectStatement.getSelectBody() instanceof PlainSelect)) {
-			return this.query.getQueryString();
+			return getQuery().getQueryString();
 		}
 
 		PlainSelect selectBody = (PlainSelect) selectStatement.getSelectBody();
@@ -423,9 +434,9 @@ public String getProjection() {
 			return "";
 		}
 
-		Assert.hasText(query.getQueryString(), "Query must not be null or empty");
+		Assert.hasText(getQuery().getQueryString(), "Query must not be null or empty");
 
-		Select selectStatement = parseSelectStatement(query.getQueryString());
+		Select selectStatement = parseSelectStatement(getQuery().getQueryString());
 
 		if (selectStatement.getSelectBody() instanceof ValuesStatement) {
 			return "";
@@ -451,7 +462,7 @@ public String getProjection() {
 
 	@Override
 	public Set<String> getJoinAliases() {
-		return this.getJoinAliases(this.query.getQueryString());
+		return this.getJoinAliases(getQuery().getQueryString());
 	}
 
 	/**
@@ -492,11 +503,6 @@ private boolean onlyASingleColumnProjection(List<SelectItem> projection) {
 				&& (((SelectExpressionItem) projection.get(0)).getExpression()) instanceof Column;
 	}
 
-	@Override
-	public DeclaredQuery getQuery() {
-		return this.query;
-	}
-
 	/**
 	 * An enum to represent the top level parsed statement of the provided query.
 	 * <ul>

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

@@ -62,6 +62,7 @@
  * @author Сергей Цыпанов
  * @author Réda Housni Alaoui
  * @author Greg Turnquist
+ * @author Diego Krupitza
  */
 public class JpaQueryMethod extends QueryMethod {
 
@@ -98,6 +99,7 @@ public class JpaQueryMethod extends QueryMethod {
 	private final Lazy<Boolean> isProcedureQuery;
 	private final Lazy<JpaEntityMetadata<?>> entityMetadata;
 	private final Map<Class<? extends Annotation>, Optional<Annotation>> annotationCache;
+	private final Lazy<QueryEnhancerOverride> queryEnhancerOverride;
 
 	/**
 	 * Creates a {@link JpaQueryMethod}.
@@ -141,6 +143,13 @@ protected JpaQueryMethod(Method method, RepositoryMetadata metadata, ProjectionF
 		this.entityMetadata = Lazy.of(() -> new DefaultJpaEntityMetadata<>(getDomainClass()));
 		this.annotationCache = new ConcurrentReferenceHashMap<>();
 
+		this.queryEnhancerOverride = Lazy.of(() -> Optional //
+				.ofNullable( // First check the method itself for an override
+						AnnotatedElementUtils.findMergedAnnotation(method, QueryEnhancerOverride.class)) //
+				.orElseGet( // Otherwise, check the enclosing class
+						() -> AnnotatedElementUtils.findMergedAnnotation(method.getDeclaringClass(), QueryEnhancerOverride.class)) //
+		);
+
 		Assert.isTrue(!(isModifyingQuery() && getParameters().hasSpecialParameter()),
 				String.format("Modifying method must not contain %s", Parameters.TYPES));
 		assertParameterNamesInAnnotatedQuery();
@@ -387,6 +396,25 @@ boolean isNativeQuery() {
 		return this.isNativeQuery.get();
 	}
 
+	/**
+	 * Returns the methods {@link QueryEnhancerOverride} annotation
+	 *
+	 * @return
+	 */
+	@Nullable
+	QueryEnhancerOverride getQueryEnhancerOverride() {
+		return this.queryEnhancerOverride.getNullable();
+	}
+
+	/**
+	 * Returns whether the method has a {@link QueryEnhancerOverride} or not
+	 *
+	 * @return
+	 */
+	boolean hasQueryEnhancerOverride() {
+		return this.queryEnhancerOverride.getOptional().isPresent();
+	}
+
 	@Override
 	public String getNamedQueryName() {