Address review comments.

Author: mp911de

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

@@ -27,9 +27,9 @@ class CollectionUtils {
 	/**
 	 * Return the first {@code count} items from the list.
 	 *
-	 * @param count
-	 * @param list
-	 * @return
+	 * @param count the number of first elements to be included in the returned list.
+	 * @param list must not be {@literal null}
+	 * @return the returned sublist if the {@code list} is greater {@code count}.
 	 * @param <T>
 	 */
 	public static <T> List<T> getFirst(int count, List<T> list) {
@@ -44,9 +44,9 @@ public static <T> List<T> getFirst(int count, List<T> list) {
 	/**
 	 * Return the last {@code count} items from the list.
 	 *
-	 * @param count
-	 * @param list
-	 * @return
+	 * @param count the number of last elements to be included in the returned list.
+	 * @param list must not be {@literal null}
+	 * @return the returned sublist if the {@code list} is greater {@code count}.
 	 * @param <T>
 	 */
 	public static <T> List<T> getLast(int count, List<T> list) {

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

@@ -29,6 +29,7 @@
 import org.springframework.data.jpa.repository.support.JpaEntityInformation;
 import org.springframework.data.repository.query.ReturnedType;
 import org.springframework.data.repository.query.parser.PartTree;
+import org.springframework.lang.Nullable;
 
 /**
  * Extension to {@link JpaQueryCreator} to create queries considering {@link KeysetScrollPosition keyset scrolling}.
@@ -50,7 +51,7 @@ public JpaKeysetScrollQueryCreator(PartTree tree, ReturnedType type, CriteriaBui
 	}
 
 	@Override
-	protected CriteriaQuery<? extends Object> complete(Predicate predicate, Sort sort, CriteriaQuery<?> query,
+	protected CriteriaQuery<?> complete(@Nullable Predicate predicate, Sort sort, CriteriaQuery<?> query,
 			CriteriaBuilder builder, Root<?> root) {
 
 		KeysetScrollSpecification<Object> keysetSpec = new KeysetScrollSpecification<>(scrollPosition, sort,

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

@@ -48,7 +48,7 @@ public static KeysetScrollDelegate of(Direction direction) {
 	}
 
 	@Nullable
-	public <E, P> P createPredicate(KeysetScrollPosition keyset, Sort sort, QueryAdapter<E, P> queryAdapter) {
+	public <E, P> P createPredicate(KeysetScrollPosition keyset, Sort sort, QueryStrategy<E, P> strategy) {
 
 		Map<String, Object> keysetValues = keyset.getKeys();
 
@@ -57,39 +57,37 @@ public <E, P> P createPredicate(KeysetScrollPosition keyset, Sort sort, QueryAda
 			return null;
 		}
 
-		// build matrix query for keyset paging that contains sort^2 queries
-		// reflecting a query that follows sort order semantics starting from the last returned keyset
-
 		List<P> or = new ArrayList<>();
-
 		int i = 0;
-		// progressive query building
+
+		// progressive query building to reconstruct a query matching sorting rules
 		for (Order order : sort) {
 
 			if (!keysetValues.containsKey(order.getProperty())) {
-				throw new IllegalStateException("KeysetScrollPosition does not contain all keyset values");
+				throw new IllegalStateException(String
+						.format("KeysetScrollPosition does not contain all keyset values. Missing key: %s", order.getProperty()));
 			}
 
 			List<P> sortConstraint = new ArrayList<>();
 
 			int j = 0;
 			for (Order inner : sort) {
 
-				E propertyExpression = queryAdapter.createExpression(inner.getProperty());
+				E propertyExpression = strategy.createExpression(inner.getProperty());
 				Object o = keysetValues.get(inner.getProperty());
 
 				if (j >= i) { // tail segment
 
-					sortConstraint.add(queryAdapter.compare(inner, propertyExpression, o));
+					sortConstraint.add(strategy.compare(inner, propertyExpression, o));
 					break;
 				}
 
-				sortConstraint.add(queryAdapter.compare(propertyExpression, o));
+				sortConstraint.add(strategy.compare(propertyExpression, o));
 				j++;
 			}
 
 			if (!sortConstraint.isEmpty()) {
-				or.add(queryAdapter.and(sortConstraint));
+				or.add(strategy.and(sortConstraint));
 			}
 
 			i++;
@@ -99,7 +97,7 @@ public <E, P> P createPredicate(KeysetScrollPosition keyset, Sort sort, QueryAda
 			return null;
 		}
 
-		return queryAdapter.or(or);
+		return strategy.or(or);
 	}
 
 	protected Sort getSortOrders(Sort sort) {
@@ -116,9 +114,9 @@ protected <T> List<T> getResultWindow(List<T> list, int limit) {
 	}
 
 	/**
-	 * Reverse scrolling director variant applying {@link Direction#Backward}. In reverse scrolling, we need to flip
-	 * directions for the actual query so that we do not get everything from the top position and apply the limit but
-	 * rather flip the sort direction, apply the limit and then reverse the result to restore the actual sort order.
+	 * Reverse scrolling variant applying {@link Direction#Backward}. In reverse scrolling, we need to flip directions for
+	 * the actual query so that we do not get everything from the top position and apply the limit but rather flip the
+	 * sort direction, apply the limit and then reverse the result to restore the actual sort order.
 	 */
 	private static class ReverseKeysetScrollDelegate extends KeysetScrollDelegate {
 
@@ -150,34 +148,34 @@ protected <T> List<T> getResultWindow(List<T> list, int limit) {
 	 * @param <E> property path expression type.
 	 * @param <P> predicate type.
 	 */
-	public interface QueryAdapter<E, P> {
+	public interface QueryStrategy<E, P> {
 
 		/**
 		 * Create an expression object from the given {@code property} path.
 		 *
-		 * @param property
+		 * @param property must not be {@literal null}.
 		 * @return
 		 */
 		E createExpression(String property);
 
 		/**
 		 * Create a comparison object according to the {@link Order}.
 		 *
-		 * @param order
-		 * @param propertyExpression
-		 * @param o
+		 * @param order must not be {@literal null}.
+		 * @param propertyExpression must not be {@literal null}.
+		 * @param value
 		 * @return
 		 */
-		P compare(Order order, E propertyExpression, Object o);
+		P compare(Order order, E propertyExpression, Object value);
 
 		/**
 		 * Create an equals-comparison object.
 		 *
-		 * @param propertyExpression
-		 * @param o
+		 * @param propertyExpression must not be {@literal null}.
+		 * @param value
 		 * @return
 		 */
-		P compare(E propertyExpression, Object o);
+		P compare(E propertyExpression, @Nullable Object value);
 
 		/**
 		 * AND-combine the {@code intermediate} predicates.

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

@@ -28,7 +28,7 @@
 import org.springframework.data.domain.Sort;
 import org.springframework.data.domain.Sort.Order;
 import org.springframework.data.jpa.domain.Specification;
-import org.springframework.data.jpa.repository.query.KeysetScrollDelegate.QueryAdapter;
+import org.springframework.data.jpa.repository.query.KeysetScrollDelegate.QueryStrategy;
 import org.springframework.data.jpa.repository.support.JpaEntityInformation;
 import org.springframework.data.mapping.PropertyPath;
 import org.springframework.lang.Nullable;
@@ -53,14 +53,14 @@ public KeysetScrollSpecification(KeysetScrollPosition position, Sort sort, JpaEn
 	/**
 	 * Create a {@link Sort} object to be used with the actual query.
 	 *
-	 * @param position
-	 * @param sort
-	 * @param entity
+	 * @param position must not be {@literal null}.
+	 * @param sort must not be {@literal null}.
+	 * @param entity must not be {@literal null}.
 	 * @return
 	 */
 	public static Sort createSort(KeysetScrollPosition position, Sort sort, JpaEntityInformation<?, ?> entity) {
 
-		KeysetScrollDelegate director = KeysetScrollDelegate.of(position.getDirection());
+		KeysetScrollDelegate delegate = KeysetScrollDelegate.of(position.getDirection());
 
 		Sort sortToUse;
 		if (entity.hasCompositeId()) {
@@ -69,7 +69,7 @@ public static Sort createSort(KeysetScrollPosition position, Sort sort, JpaEntit
 			sortToUse = sort.and(Sort.by(entity.getRequiredIdAttribute().getName()));
 		}
 
-		return director.getSortOrders(sortToUse);
+		return delegate.getSortOrders(sortToUse);
 	}
 
 	@Override
@@ -80,36 +80,39 @@ public Predicate toPredicate(Root<T> root, CriteriaQuery<?> query, CriteriaBuild
 	@Nullable
 	public Predicate createPredicate(Root<?> root, CriteriaBuilder criteriaBuilder) {
 
-		KeysetScrollDelegate director = KeysetScrollDelegate.of(position.getDirection());
-		return director.createPredicate(position, sort, new JpaQueryAdapter(root, criteriaBuilder));
+		KeysetScrollDelegate delegate = KeysetScrollDelegate.of(position.getDirection());
+		return delegate.createPredicate(position, sort, new JpaQueryStrategy(root, criteriaBuilder));
 	}
 
 	@SuppressWarnings("rawtypes")
-	private static class JpaQueryAdapter implements QueryAdapter<Expression<Comparable>, Predicate> {
+	private static class JpaQueryStrategy implements QueryStrategy<Expression<Comparable>, Predicate> {
 
 		private final From<?, ?> from;
 		private final CriteriaBuilder cb;
 
-		public JpaQueryAdapter(From<?, ?> from, CriteriaBuilder cb) {
+		public JpaQueryStrategy(From<?, ?> from, CriteriaBuilder cb) {
+
 			this.from = from;
 			this.cb = cb;
 		}
 
 		@Override
 		public Expression<Comparable> createExpression(String property) {
+
 			PropertyPath path = PropertyPath.from(property, from.getJavaType());
 			return QueryUtils.toExpressionRecursively(from, path);
 		}
 
 		@Override
-		public Predicate compare(Order order, Expression<Comparable> propertyExpression, Object o) {
-			return order.isAscending() ? cb.greaterThan(propertyExpression, (Comparable) o)
-					: cb.lessThan(propertyExpression, (Comparable) o);
+		public Predicate compare(Order order, Expression<Comparable> propertyExpression, Object value) {
+
+			return order.isAscending() ? cb.greaterThan(propertyExpression, (Comparable) value)
+					: cb.lessThan(propertyExpression, (Comparable) value);
 		}
 
 		@Override
-		public Predicate compare(Expression<Comparable> propertyExpression, Object o) {
-			return cb.equal(propertyExpression, o);
+		public Predicate compare(Expression<Comparable> propertyExpression, @Nullable Object value) {
+			return value == null ? cb.isNull(propertyExpression) : cb.equal(propertyExpression, value);
 		}
 
 		@Override

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

@@ -41,7 +41,7 @@ public class ScrollDelegate<T> {
 
 	private final JpaEntityInformation<T, ?> entity;
 
-	public ScrollDelegate(JpaEntityInformation<T, ?> entity) {
+	protected ScrollDelegate(JpaEntityInformation<T, ?> entity) {
 		this.entity = entity;
 	}
 
@@ -79,8 +79,8 @@ public Window<T> scroll(Query query, Sort sort, ScrollPosition scrollPosition) {
 	private static <T> Window<T> createWindow(Sort sort, int limit, Direction direction,
 			JpaEntityInformation<T, ?> entity, List<T> result) {
 
-		KeysetScrollDelegate director = KeysetScrollDelegate.of(direction);
-		List<T> resultsToUse = director.postProcessResults(result);
+		KeysetScrollDelegate delegate = KeysetScrollDelegate.of(direction);
+		List<T> resultsToUse = delegate.postProcessResults(result);
 
 		IntFunction<KeysetScrollPosition> positionFunction = value -> {
 
@@ -90,7 +90,7 @@ private static <T> Window<T> createWindow(Sort sort, int limit, Direction direct
 			return KeysetScrollPosition.of(keys);
 		};
 
-		return Window.from(director.getResultWindow(resultsToUse, limit), positionFunction, hasMoreElements(result, limit));
+		return Window.from(delegate.getResultWindow(resultsToUse, limit), positionFunction, hasMoreElements(result, limit));
 	}
 
 	private static <T> Window<T> createWindow(List<T> result, int limit,

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

@@ -60,22 +60,22 @@ class FetchableFluentQueryBySpecification<S, R> extends FluentQuerySupport<S, R>
 	private final EntityManager entityManager;
 
 	public FetchableFluentQueryBySpecification(Specification<S> spec, Class<S> entityType,
-			Function<Sort, TypedQuery<S>> finder, SpecificationScrollDelegate<S> scrollDirector,
+			Function<Sort, TypedQuery<S>> finder, SpecificationScrollDelegate<S> scrollDelegate,
 			Function<Specification<S>, Long> countOperation, Function<Specification<S>, Boolean> existsOperation,
 			EntityManager entityManager) {
-		this(spec, entityType, (Class<R>) entityType, Sort.unsorted(), 0, Collections.emptySet(), finder, scrollDirector,
+		this(spec, entityType, (Class<R>) entityType, Sort.unsorted(), 0, Collections.emptySet(), finder, scrollDelegate,
 				countOperation, existsOperation, entityManager);
 	}
 
 	private FetchableFluentQueryBySpecification(Specification<S> spec, Class<S> entityType, Class<R> resultType,
 			Sort sort, int limit, Collection<String> properties, Function<Sort, TypedQuery<S>> finder,
-			SpecificationScrollDelegate<S> scrollDirector, Function<Specification<S>, Long> countOperation,
+			SpecificationScrollDelegate<S> scrollDelegate, Function<Specification<S>, Long> countOperation,
 			Function<Specification<S>, Boolean> existsOperation, EntityManager entityManager) {
 
 		super(resultType, sort, limit, properties, entityType);
 		this.spec = spec;
 		this.finder = finder;
-		this.scroll = scrollDirector;
+		this.scroll = scrollDelegate;
 		this.countOperation = countOperation;
 		this.existsOperation = existsOperation;
 		this.entityManager = entityManager;

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

@@ -228,7 +228,8 @@ public boolean isNew(T entity) {
 	@Override
 	public Map<String, Object> getKeyset(Iterable<String> propertyPaths, T entity) {
 
-		// TODO: proxy business?
+		// TODO: Proxy handling requires more elaborate refactoring, see
+		// https://github.com/spring-projects/spring-data-jpa/issues/2784
 		BeanWrapper entityWrapper = new DirectFieldAccessFallbackBeanWrapper(entity);
 
 		Map<String, Object> keyset = new LinkedHashMap<>();

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

@@ -32,7 +32,7 @@
 import org.springframework.data.domain.Sort.Order;
 import org.springframework.data.jpa.repository.EntityGraph;
 import org.springframework.data.jpa.repository.query.KeysetScrollDelegate;
-import org.springframework.data.jpa.repository.query.KeysetScrollDelegate.QueryAdapter;
+import org.springframework.data.jpa.repository.query.KeysetScrollDelegate.QueryStrategy;
 import org.springframework.data.jpa.repository.query.KeysetScrollSpecification;
 import org.springframework.data.jpa.repository.support.FetchableFluentQueryByPredicate.PredicateScrollDelegate;
 import org.springframework.data.jpa.repository.support.FluentQuerySupport.ScrollQueryFactory;
@@ -48,6 +48,7 @@
 import com.querydsl.core.types.ConstantImpl;
 import com.querydsl.core.types.EntityPath;
 import com.querydsl.core.types.Expression;
+import com.querydsl.core.types.NullExpression;
 import com.querydsl.core.types.Ops;
 import com.querydsl.core.types.OrderSpecifier;
 import com.querydsl.core.types.Predicate;
@@ -75,7 +76,7 @@ public class QuerydslJpaPredicateExecutor<T> implements QuerydslPredicateExecuto
 	private final JpaEntityInformation<T, ?> entityInformation;
 	private final EntityPath<T> path;
 	private final Querydsl querydsl;
-	private final QuerydslQueryAdapter scrollQueryAdapter;
+	private final QuerydslQueryStrategy scrollQueryAdapter;
 	private final EntityManager entityManager;
 	private final CrudMethodMetadata metadata;
 
@@ -96,7 +97,7 @@ public QuerydslJpaPredicateExecutor(JpaEntityInformation<T, ?> entityInformation
 		this.path = resolver.createPath(entityInformation.getJavaType());
 		this.querydsl = new Querydsl(entityManager, new PathBuilder<T>(path.getType(), path.getMetadata()));
 		this.entityManager = entityManager;
-		this.scrollQueryAdapter = new QuerydslQueryAdapter();
+		this.scrollQueryAdapter = new QuerydslQueryStrategy();
 	}
 
 	@Override
@@ -180,9 +181,9 @@ public <S extends T, R> R findBy(Predicate predicate, Function<FetchableFluentQu
 
 			if (scrollPosition instanceof KeysetScrollPosition keyset) {
 
-				KeysetScrollDelegate director = KeysetScrollDelegate.of(keyset.getDirection());
+				KeysetScrollDelegate delegate = KeysetScrollDelegate.of(keyset.getDirection());
 				sort = KeysetScrollSpecification.createSort(keyset, sort, entityInformation);
-				BooleanExpression keysetPredicate = director.createPredicate(keyset, sort, scrollQueryAdapter);
+				BooleanExpression keysetPredicate = delegate.createPredicate(keyset, sort, scrollQueryAdapter);
 
 				if (keysetPredicate != null) {
 					predicateToUse = predicate instanceof BooleanExpression be ? be.and(keysetPredicate)
@@ -328,22 +329,23 @@ private List<T> executeSorted(JPQLQuery<T> query, Sort sort) {
 		return querydsl.applySorting(sort, query).fetch();
 	}
 
-	class QuerydslQueryAdapter implements QueryAdapter<Expression<?>, BooleanExpression> {
+	class QuerydslQueryStrategy implements QueryStrategy<Expression<?>, BooleanExpression> {
 
 		@Override
 		public Expression<?> createExpression(String property) {
 			return querydsl.createExpression(property);
 		}
 
 		@Override
-		public BooleanExpression compare(Order order, Expression<?> propertyExpression, Object o) {
+		public BooleanExpression compare(Order order, Expression<?> propertyExpression, Object value) {
 			return Expressions.booleanOperation(order.isAscending() ? Ops.GT : Ops.LT, propertyExpression,
-					ConstantImpl.create(o));
+					ConstantImpl.create(value));
 		}
 
 		@Override
-		public BooleanExpression compare(Expression<?> propertyExpression, Object o) {
-			return Expressions.booleanOperation(Ops.EQ, propertyExpression, ConstantImpl.create(o));
+		public BooleanExpression compare(Expression<?> propertyExpression, @Nullable Object value) {
+			return Expressions.booleanOperation(Ops.EQ, propertyExpression,
+					value == null ? NullExpression.DEFAULT : ConstantImpl.create(value));
 		}
 
 		@Override