Do not translate empty collection to null for derived Hibernate query bindings.

Hibernate translates empty collections to disjunctions so we don't have to provide values that would lead to a query yielding no results.

Closes #4112

Author: mp911de

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

@@ -229,16 +229,24 @@ public static class PartTreeParameterBinding extends ParameterBinding {
 		private final boolean ignoreCase;
 		private final boolean noWildcards;
 		private final @Nullable Object value;
+		private final PersistenceProvider persistenceProvider;
 
 		public PartTreeParameterBinding(BindingIdentifier identifier, ParameterOrigin origin, Class<?> parameterType,
 				Part part, @Nullable Object value, JpqlQueryTemplates templates, EscapeCharacter escape) {
+			this(identifier, origin, parameterType, part, value, templates, escape, PersistenceProvider.GENERIC_JPA);
+		}
+
+		PartTreeParameterBinding(BindingIdentifier identifier, ParameterOrigin origin, Class<?> parameterType, Part part,
+				@Nullable Object value, JpqlQueryTemplates templates, EscapeCharacter escape,
+				PersistenceProvider persistenceProvider) {
 
 			super(identifier, origin);
 
 			this.parameterType = parameterType;
 			this.templates = templates;
 			this.escape = escape;
 			this.value = value;
+			this.persistenceProvider = persistenceProvider;
 			this.type = value == null
 					&& (Type.SIMPLE_PROPERTY.equals(part.getType()) || Type.NEGATING_SIMPLE_PROPERTY.equals(part.getType()))
 							? Type.IS_NULL
@@ -285,7 +293,7 @@ public JpqlQueryTemplates getTemplates() {
 			}
 
 			return Collection.class.isAssignableFrom(parameterType) //
-					? potentiallyIgnoreCase(ignoreCase, toCollection(value)) //
+					? potentiallyIgnoreCase(ignoreCase, toCollection(value, persistenceProvider)) //
 					: value;
 		}
 
@@ -307,26 +315,27 @@ public JpqlQueryTemplates getTemplates() {
 
 		/**
 		 * Returns the given argument as {@link Collection} which means it will return it as is if it's a
-		 * {@link Collections}, turn an array into an {@link ArrayList} or simply wrap any other value into a single element
-		 * {@link Collections}.
+		 * {@link Collection}, turn an array into an {@link ArrayList} or simply wrap any other value into a single-element
+		 * {@link Collection} by default. {@link PersistenceProvider#HIBERNATE} translates empty collections to disjunctions
+		 * to avoid syntax errors.
 		 *
 		 * @param value the value to be converted to a {@link Collection}.
+		 * @param provider the persistence provider to use.
 		 * @return the object itself as a {@link Collection} or a {@link Collection} constructed from the value.
 		 */
-		private static @Nullable Collection<?> toCollection(@Nullable Object value) {
+		private static @Nullable Collection<?> toCollection(@Nullable Object value, PersistenceProvider provider) {
 
 			if (value == null) {
 				return null;
 			}
 
 			if (value instanceof Collection<?> collection) {
-				return collection.isEmpty() ? null : collection;
+				return provider == PersistenceProvider.HIBERNATE || !collection.isEmpty() ? collection : null;
 			}
 
 			if (ObjectUtils.isArray(value)) {
-
-				List<Object> collection = Arrays.asList(ObjectUtils.toObjectArray(value));
-				return collection.isEmpty() ? null : collection;
+				Object[] array = ObjectUtils.toObjectArray(value);
+				return provider == PersistenceProvider.HIBERNATE || !ObjectUtils.isEmpty(array) ? Arrays.asList(array) : null;
 			}
 
 			return Collections.singleton(value);

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

@@ -67,6 +67,7 @@ public class ParameterMetadataProvider {
 	private final EscapeCharacter escape;
 	private final JpqlQueryTemplates templates;
 	private final JpaParameters jpaParameters;
+	private final PersistenceProvider persistenceProvider;
 	private int position;
 	private int bindMarker;
 
@@ -80,19 +81,37 @@ public class ParameterMetadataProvider {
 	 */
 	public ParameterMetadataProvider(JpaParametersParameterAccessor accessor, EscapeCharacter escape,
 			JpqlQueryTemplates templates) {
-		this(accessor.iterator(), accessor, accessor.getParameters(), escape, templates);
+		this(accessor.iterator(), accessor, accessor.getParameters(), escape, templates, PersistenceProvider.GENERIC_JPA);
 	}
 
 	/**
-	 * Creates a new {@link ParameterMetadataProvider} from the given {@link CriteriaBuilder} and {@link Parameters} with
+	 * Creates a new {@code ParameterMetadataProvider} from the given {@link CriteriaBuilder},
+	 * {@link ParametersParameterAccessor}, and {@link PersistenceProvider}.
+	 *
+	 * @param accessor must not be {@literal null}.
+	 * @param escape must not be {@literal null}.
+	 * @param templates must not be {@literal null}.
+	 * @param persistenceProvider must not be {@literal null}.
+	 * @since 4.0.1
+	 */
+	ParameterMetadataProvider(JpaParametersParameterAccessor accessor, EscapeCharacter escape,
+			JpqlQueryTemplates templates, PersistenceProvider persistenceProvider) {
+		this(accessor.iterator(), accessor, accessor.getParameters(), escape, templates, persistenceProvider);
+	}
+
+	/**
+	 * Creates a new {@code ParameterMetadataProvider} from the given {@link CriteriaBuilder} and {@link Parameters} with
 	 * support for parameter value customizations via {@link PersistenceProvider}.
+	 * <p>
+	 * Uses {@link PersistenceProvider#HIBERNATE} as provider since this constructor is used in contexts where no special
+	 * handling is required.
 	 *
 	 * @param parameters must not be {@literal null}.
 	 * @param escape must not be {@literal null}.
 	 * @param templates must not be {@literal null}.
 	 */
 	public ParameterMetadataProvider(JpaParameters parameters, EscapeCharacter escape, JpqlQueryTemplates templates) {
-		this(null, null, parameters, escape, templates);
+		this(null, null, parameters, escape, templates, PersistenceProvider.HIBERNATE);
 	}
 
 	/**
@@ -103,10 +122,12 @@ public ParameterMetadataProvider(JpaParameters parameters, EscapeCharacter escap
 	 * @param parameters must not be {@literal null}.
 	 * @param escape must not be {@literal null}.
 	 * @param templates must not be {@literal null}.
+	 * @param persistenceProvider must not be {@literal null}.
 	 */
 	private ParameterMetadataProvider(@Nullable Iterator<Object> bindableParameterValues,
 			@Nullable JpaParametersParameterAccessor accessor, JpaParameters parameters, EscapeCharacter escape,
-			JpqlQueryTemplates templates) {
+			JpqlQueryTemplates templates, PersistenceProvider persistenceProvider) {
+
 		Assert.notNull(parameters, "Parameters must not be null");
 		Assert.notNull(escape, "EscapeCharacter must not be null");
 		Assert.notNull(templates, "JpqlQueryTemplates must not be null");
@@ -118,6 +139,7 @@ private ParameterMetadataProvider(@Nullable Iterator<Object> bindableParameterVa
 		this.bindableParameterValues = bindableParameterValues;
 		this.escape = escape;
 		this.templates = templates;
+		this.persistenceProvider = persistenceProvider;
 	}
 
 	JpaParameters getParameters() {
@@ -204,7 +226,7 @@ private <T> PartTreeParameterBinding next(Part part, Class<T> type, Parameter pa
 		/* identifier refers to bindable parameters, not _all_ parameters index */
 		MethodInvocationArgument methodParameter = ParameterOrigin.ofParameter(origin);
 		PartTreeParameterBinding binding = new PartTreeParameterBinding(bindingIdentifier,
-				methodParameter, reifiedType, part, value, templates, escape);
+				methodParameter, reifiedType, part, value, templates, escape, persistenceProvider);
 
 		// PartTreeParameterBinding is more expressive than a potential ParameterBinding for Vector.
 		bindings.add(binding);

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

@@ -31,6 +31,7 @@
 import org.springframework.data.domain.OffsetScrollPosition;
 import org.springframework.data.domain.ScrollPosition;
 import org.springframework.data.domain.Sort;
+import org.springframework.data.jpa.provider.PersistenceProvider;
 import org.springframework.data.jpa.repository.query.JpaParameters.JpaParameter;
 import org.springframework.data.jpa.repository.query.JpaQueryExecution.DeleteExecution;
 import org.springframework.data.jpa.repository.query.JpaQueryExecution.ExistsExecution;
@@ -71,6 +72,7 @@ public class PartTreeJpaQuery extends AbstractJpaQuery {
 	private final EntityManager em;
 	private final EscapeCharacter escape;
 	private final Lazy<JpaEntityInformation<?, ?>> entityInformation;
+	private final PersistenceProvider persistenceProvider;
 
 	/**
 	 * Creates a new {@link PartTreeJpaQuery}.
@@ -96,6 +98,7 @@ public class PartTreeJpaQuery extends AbstractJpaQuery {
 		this.em = em;
 		this.escape = escape;
 		this.parameters = method.getParameters();
+		this.persistenceProvider = PersistenceProvider.fromEntityManager(em);
 
 		Class<?> domainClass = method.getEntityInformation().getJavaType();
 		this.entityInformation = Lazy.of(() -> JpaEntityInformationSupport.getEntityInformation(domainClass, em));
@@ -293,7 +296,8 @@ protected JpqlQueryCreator createCreator(Sort sort, JpaParametersParameterAccess
 			EntityManager entityManager = getEntityManager();
 			ResultProcessor processor = getQueryMethod().getResultProcessor();
 
-			ParameterMetadataProvider provider = new ParameterMetadataProvider(accessor, escape, templates);
+			ParameterMetadataProvider provider = new ParameterMetadataProvider(accessor, escape, templates,
+					persistenceProvider);
 			ReturnedType returnedType = processor.withDynamicProjection(accessor).getReturnedType();
 
 			if (accessor.getScrollPosition() instanceof KeysetScrollPosition keyset) {
@@ -390,7 +394,8 @@ protected JpqlQueryCreator createCreator(Sort sort, JpaParametersParameterAccess
 				return cached;
 			}
 
-			ParameterMetadataProvider provider = new ParameterMetadataProvider(accessor, escape, templates);
+			ParameterMetadataProvider provider = new ParameterMetadataProvider(accessor, escape, templates,
+					persistenceProvider);
 			JpaCountQueryCreator creator = new JpaCountQueryCreator(tree,
 					getQueryMethod().getResultProcessor().getReturnedType(), provider, templates, entityInformation.get(),
 					em.getMetamodel());

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

@@ -0,0 +1,98 @@
+/*
+ * Copyright 2017-2025 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.repository.query;
+
+import static org.assertj.core.api.Assertions.*;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Set;
+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.provider.PersistenceProvider;
+import org.springframework.data.jpa.repository.query.ParameterBinding.BindingIdentifier;
+import org.springframework.data.jpa.repository.query.ParameterBinding.ParameterOrigin;
+import org.springframework.data.jpa.repository.support.JpqlQueryTemplates;
+import org.springframework.data.repository.query.parser.Part;
+
+/**
+ * Unit tests for {@link ParameterBinding}.
+ *
+ * @author Jens Schauder
+ * @author Diego Krupitza
+ * @author Mark Paluch
+ */
+class ParameterBindingUnitTests {
+
+	static ParameterBinding hibernateCollectionBinding = new ParameterBinding.PartTreeParameterBinding(
+			BindingIdentifier.of("foo"), ParameterOrigin.ofParameter("foo"), Collection.class,
+			new Part("name", TestEntity.class), null, JpqlQueryTemplates.UPPER, EscapeCharacter.DEFAULT,
+			PersistenceProvider.HIBERNATE);
+
+	static ParameterBinding eclipselinkCollectionBinding = new ParameterBinding.PartTreeParameterBinding(
+			BindingIdentifier.of("foo"), ParameterOrigin.ofParameter("foo"), Collection.class,
+			new Part("name", TestEntity.class), null, JpqlQueryTemplates.UPPER, EscapeCharacter.DEFAULT,
+			PersistenceProvider.ECLIPSELINK);
+
+	@Test // GH-4112
+	void shouldPrepareEmptyListForHibernate() {
+
+		assertThat(hibernateCollectionBinding.prepare(List.of())).isEqualTo(List.of());
+		assertThat(hibernateCollectionBinding.prepare(new Integer[0])).isEqualTo(List.of());
+	}
+
+	@Test // GH-4112
+	void shouldPrepareEmptyListToNullForEclipselink() {
+
+		assertThat(eclipselinkCollectionBinding.prepare(List.of())).isNull();
+		assertThat(eclipselinkCollectionBinding.prepare(new Integer[0])).isNull();
+	}
+
+	@ParameterizedTest // GH-4112
+	@MethodSource("bindings")
+	void shouldPrepareListToCollection(ParameterBinding binding) {
+
+		assertThat(binding.prepare(List.of("foo"))).isEqualTo(List.of("foo"));
+		assertThat(binding.prepare(new Integer[] { 1, 2, 3 })).isEqualTo(List.of(1, 2, 3));
+	}
+
+	@ParameterizedTest // GH-4112
+	@MethodSource("bindings")
+	void shouldPrepareValueToSingleElementCollection(ParameterBinding binding) {
+		assertThat(binding.prepare("foo")).isEqualTo(Set.of("foo"));
+	}
+
+	@ParameterizedTest // GH-4112
+	@MethodSource("bindings")
+	void shouldPrepareNull(ParameterBinding binding) {
+		assertThat(binding.prepare(null)).isNull();
+	}
+
+	static Stream<Arguments.ArgumentSet> bindings() {
+		return Stream.of(Arguments.argumentSet("Hibernate", hibernateCollectionBinding),
+				Arguments.argumentSet("EclipseLink", eclipselinkCollectionBinding));
+	}
+
+	private record TestEntity(String name) {
+
+	}
+
+}