Add configuration option to disable usage of JSqlParser for native queries.

pom.xml

@@ -5,7 +5,7 @@
 
 	<groupId>org.springframework.data</groupId>
 	<artifactId>spring-data-jpa-parent</artifactId>
-	<version>3.4.0-SNAPSHOT</version>
+	<version>3.4.x-2989-SNAPSHOT</version>
 	<packaging>pom</packaging>
 
 	<name>Spring Data JPA Parent</name>

spring-data-envers/pom.xml

@@ -5,12 +5,12 @@
 
 	<groupId>org.springframework.data</groupId>
 	<artifactId>spring-data-envers</artifactId>
-	<version>3.4.0-SNAPSHOT</version>
+	<version>3.4.x-2989-SNAPSHOT</version>
 
 	<parent>
 		<groupId>org.springframework.data</groupId>
 		<artifactId>spring-data-jpa-parent</artifactId>
-		<version>3.4.0-SNAPSHOT</version>
+		<version>3.4.x-2989-SNAPSHOT</version>
 		<relativePath>../pom.xml</relativePath>
 	</parent>
 

spring-data-jpa-distribution/pom.xml

@@ -14,7 +14,7 @@
 	<parent>
 		<groupId>org.springframework.data</groupId>
 		<artifactId>spring-data-jpa-parent</artifactId>
-		<version>3.4.0-SNAPSHOT</version>
+		<version>3.4.x-2989-SNAPSHOT</version>
 		<relativePath>../pom.xml</relativePath>
 	</parent>
 

spring-data-jpa-performance/pom.xml

@@ -15,7 +15,7 @@
 	<parent>
 		<groupId>org.springframework.data</groupId>
 		<artifactId>spring-data-jpa-parent</artifactId>
-		<version>3.4.0-SNAPSHOT</version>
+		<version>3.4.x-2989-SNAPSHOT</version>
 		<relativePath>../pom.xml</relativePath>
 	</parent>
 

spring-data-jpa/pom.xml

@@ -6,7 +6,7 @@
 
 	<groupId>org.springframework.data</groupId>
 	<artifactId>spring-data-jpa</artifactId>
-	<version>3.4.0-SNAPSHOT</version>
+	<version>3.4.x-2989-SNAPSHOT</version>
 
 	<name>Spring Data JPA</name>
 	<description>Spring Data module for JPA repositories.</description>
@@ -15,7 +15,7 @@
 	<parent>
 		<groupId>org.springframework.data</groupId>
 		<artifactId>spring-data-jpa-parent</artifactId>
-		<version>3.4.0-SNAPSHOT</version>
+		<version>3.4.x-2989-SNAPSHOT</version>
 		<relativePath>../pom.xml</relativePath>
 	</parent>
 
@@ -86,6 +86,12 @@
 			<optional>true</optional>
 		</dependency>
 
+		<dependency>
+			<groupId>org.junit.platform</groupId>
+			<artifactId>junit-platform-launcher</artifactId>
+			<scope>test</scope>
+		</dependency>
+
 		<dependency>
 			<groupId>org.hsqldb</groupId>
 			<artifactId>hsqldb</artifactId>

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

@@ -17,29 +17,29 @@
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
+import org.springframework.core.SpringProperties;
 import org.springframework.data.jpa.provider.PersistenceProvider;
+import org.springframework.lang.Nullable;
 import org.springframework.util.ClassUtils;
+import org.springframework.util.StringUtils;
 
 /**
  * Encapsulates different strategies for the creation of a {@link QueryEnhancer} from a {@link DeclaredQuery}.
  *
  * @author Diego Krupitza
  * @author Greg Turnquist
  * @author Mark Paluch
+ * @author Christoph Strobl
  * @since 2.7.0
  */
 public final class QueryEnhancerFactory {
 
 	private static final Log LOG = LogFactory.getLog(QueryEnhancerFactory.class);
-
-	private static final boolean jSqlParserPresent = ClassUtils.isPresent("net.sf.jsqlparser.parser.JSqlParser",
-			QueryEnhancerFactory.class.getClassLoader());
+	private static final NativeQueryEnhancer NATIVE_QUERY_ENHANCER;
 
 	static {
 
-		if (jSqlParserPresent) {
-			LOG.info("JSqlParser is in classpath; If applicable, JSqlParser will be used");
-		}
+		NATIVE_QUERY_ENHANCER = NativeQueryEnhancer.select(QueryEnhancerFactory.class.getClassLoader());
 
 		if (PersistenceProvider.ECLIPSELINK.isPresent()) {
 			LOG.info("EclipseLink is in classpath; If applicable, EQL parser will be used.");
@@ -48,7 +48,6 @@ public final class QueryEnhancerFactory {
 		if (PersistenceProvider.HIBERNATE.isPresent()) {
 			LOG.info("Hibernate is in classpath; If applicable, HQL parser will be used.");
 		}
-
 	}
 
 	private QueryEnhancerFactory() {}
@@ -62,15 +61,7 @@ private QueryEnhancerFactory() {}
 	public static QueryEnhancer forQuery(DeclaredQuery query) {
 
 		if (query.isNativeQuery()) {
-
-			if (jSqlParserPresent) {
-				/*
-				 * If JSqlParser fails, throw some alert signaling that people should write a custom Impl.
-				 */
-				return new JSqlParserQueryEnhancer(query);
-			}
-
-			return new DefaultQueryEnhancer(query);
+			return getNativeQueryEnhancer(query);
 		}
 
 		if (PersistenceProvider.HIBERNATE.isPresent()) {
@@ -82,4 +73,56 @@ public static QueryEnhancer forQuery(DeclaredQuery query) {
 		}
 	}
 
+	/**
+	 * Get the native query enhancer for the given {@link DeclaredQuery query} based on {@link #NATIVE_QUERY_ENHANCER}.
+	 *
+	 * @param query the declared query.
+	 * @return new instance of {@link QueryEnhancer}.
+	 */
+	private static QueryEnhancer getNativeQueryEnhancer(DeclaredQuery query) {
+
+		if (NATIVE_QUERY_ENHANCER.equals(NativeQueryEnhancer.JSQL)) {
+			return new JSqlParserQueryEnhancer(query);
+		}
+		return new DefaultQueryEnhancer(query);
+	}
+
+	/**
+	 * Possible choices for the {@link #NATIVE_PARSER_PROPERTY}. Read current selection via {@link #select(ClassLoader)}.
+	 */
+	enum NativeQueryEnhancer {
+
+		AUTO, DEFAULT, JSQL;
+
+		static final String NATIVE_PARSER_PROPERTY = "spring.data.jpa.query.native.parser";
+
+		private static NativeQueryEnhancer from(@Nullable String name) {
+			if (!StringUtils.hasText(name)) {
+				return AUTO;
+			}
+			return NativeQueryEnhancer.valueOf(name.toUpperCase());
+		}
+
+		/**
+		 * @param classLoader ClassLoader to look up available libraries.
+		 * @return the current selection considering classpath avialability and user selection via
+		 *         {@link #NATIVE_PARSER_PROPERTY}.
+		 */
+		static NativeQueryEnhancer select(ClassLoader classLoader) {
+
+			if (!ClassUtils.isPresent("net.sf.jsqlparser.parser.JSqlParser", classLoader)) {
+				return NativeQueryEnhancer.DEFAULT;
+			}
+
+			NativeQueryEnhancer selected = NativeQueryEnhancer.from(SpringProperties.getProperty(NATIVE_PARSER_PROPERTY));
+			if (selected.equals(NativeQueryEnhancer.AUTO) || selected.equals(NativeQueryEnhancer.JSQL)) {
+				LOG.info("JSqlParser is in classpath; If applicable, JSqlParser will be used.");
+				return NativeQueryEnhancer.JSQL;
+			}
+
+			LOG.info("JSqlParser is in classpath but won't be used due to user choice.");
+			return selected;
+		}
+	}
+
 }

spring-data-jpa/src/test/java/org/springframework/data/jpa/repository/query/QueryEnhancerFactoryUnitTests.java

@@ -15,15 +15,24 @@
  */
 package org.springframework.data.jpa.repository.query;
 
-import static org.assertj.core.api.Assertions.*;
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.stream.Stream;
 
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+import org.springframework.data.jpa.repository.query.QueryEnhancerFactory.NativeQueryEnhancer;
+import org.springframework.data.jpa.util.ClassPathExclusions;
+import org.springframework.lang.Nullable;
 
 /**
  * Unit tests for {@link QueryEnhancerFactory}.
  *
  * @author Diego Krupitza
  * @author Greg Turnquist
+ * @author Christoph Strobl
  */
 class QueryEnhancerFactoryUnitTests {
 
@@ -52,4 +61,56 @@ void createsJSqlImplementationForNativeQuery() {
 		assertThat(queryEnhancer) //
 				.isInstanceOf(JSqlParserQueryEnhancer.class);
 	}
+
+	@ParameterizedTest // GH-2989
+	@MethodSource("nativeEnhancerSelectionArgs")
+	void createsNativeImplementationAccordingToUserChoice(@Nullable String selection, NativeQueryEnhancer enhancer) {
+
+		withSystemProperty(NativeQueryEnhancer.NATIVE_PARSER_PROPERTY, selection, () -> {
+			assertThat(NativeQueryEnhancer.select(this.getClass().getClassLoader())).isEqualTo(enhancer);
+		});
+	}
+
+	@Test // GH-2989
+	@ClassPathExclusions(packages = { "net.sf.jsqlparser.parser" })
+	void selectedDefaultImplementationIfJsqlNotAvailable() {
+
+		assertThat(assertThat(NativeQueryEnhancer.select(this.getClass().getClassLoader()))
+				.isEqualTo(NativeQueryEnhancer.DEFAULT));
+	}
+
+	@Test // GH-2989
+	@ClassPathExclusions(packages = { "net.sf.jsqlparser.parser" })
+	void selectedDefaultImplementationIfJsqlNotAvailableEvenIfExplicitlyStated/* or should we raise an error? */() {
+
+		withSystemProperty(NativeQueryEnhancer.NATIVE_PARSER_PROPERTY, "jsql", () -> {
+			assertThat(NativeQueryEnhancer.select(this.getClass().getClassLoader())).isEqualTo(NativeQueryEnhancer.DEFAULT);
+		});
+	}
+
+	void withSystemProperty(String property, @Nullable String value, Runnable exeution) {
+
+		String currentValue = System.getProperty(property);
+		if (value != null) {
+			System.setProperty(property, value);
+		} else {
+			System.clearProperty(property);
+		}
+		try {
+			exeution.run();
+		} finally {
+			if (currentValue != null) {
+				System.setProperty(property, currentValue);
+			} else {
+				System.clearProperty(property);
+			}
+		}
+
+	}
+
+	static Stream<Arguments> nativeEnhancerSelectionArgs() {
+		return Stream.of(Arguments.of(null, NativeQueryEnhancer.JSQL), Arguments.of("", NativeQueryEnhancer.JSQL),
+				Arguments.of("auto", NativeQueryEnhancer.JSQL), Arguments.of("default", NativeQueryEnhancer.DEFAULT),
+				Arguments.of("jsql", NativeQueryEnhancer.JSQL));
+	}
 }

spring-data-jpa/src/test/java/org/springframework/data/jpa/util/ClassPathExclusions.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.jpa.util;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.junit.jupiter.api.extension.ExtendWith;
+
+/**
+ * Annotation used to exclude entries from the classpath. Simplified version of <a href=
+ * "https://github.com/spring-projects/spring-boot/blob/main/spring-boot-project/spring-boot-tools/spring-boot-test-support/src/main/java/org/springframework/boot/testsupport/classpath/ClassPathExclusions.java">ClassPathExclusions</a>.
+ *
+ * @author Christoph Strobl
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE, ElementType.METHOD })
+@Documented
+@ExtendWith(ClassPathExclusionsExtension.class)
+public @interface ClassPathExclusions {
+
+	/**
+	 * One or more packages that should be excluded from the classpath.
+	 *
+	 * @return the excluded packages
+	 */
+	String[] packages();
+
+}