Document limitations around nullable properties.

See: #4308
Original Pull Request: #4317

Author: mp911de

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ExecutableFindOperation.java

@@ -20,8 +20,9 @@
 import java.util.stream.Stream;
 
 import org.springframework.dao.DataAccessException;
-import org.springframework.data.domain.Window;
+import org.springframework.data.domain.KeysetScrollPosition;
 import org.springframework.data.domain.ScrollPosition;
+import org.springframework.data.domain.Window;
 import org.springframework.data.geo.GeoResults;
 import org.springframework.data.mongodb.core.query.CriteriaDefinition;
 import org.springframework.data.mongodb.core.query.NearQuery;
@@ -128,10 +129,13 @@ default Optional<T> first() {
 		/**
 		 * Return a window of elements either starting or resuming at
 		 * {@link org.springframework.data.domain.ScrollPosition}.
+		 * <p>
+		 * When using {@link KeysetScrollPosition}, make sure to use non-nullable
+		 * {@link org.springframework.data.domain.Sort sort properties} as MongoDB does not support criteria to reconstruct
+		 * a query result from absent document fields or {@code null} values through {@code $gt/$lt} operators.
 		 *
 		 * @param scrollPosition the scroll position.
 		 * @return a window of the resulting elements.
-		 * @throws IllegalStateException if a potential {@literal KeysetScrollPosition} contains an invalid position.
 		 * @since 4.1
 		 * @see org.springframework.data.domain.OffsetScrollPosition
 		 * @see org.springframework.data.domain.KeysetScrollPosition

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java

@@ -807,19 +807,24 @@ <T> MapReduceResults<T> mapReduce(Query query, String inputCollectionName, Strin
 	<T> List<T> find(Query query, Class<T> entityClass, String collectionName);
 
 	/**
-	 * Query for a window window of objects of type T from the specified collection. <br />
+	 * Query for a window of objects of type T from the specified collection. <br />
 	 * Make sure to either set {@link Query#skip(long)} or {@link Query#with(KeysetScrollPosition)} along with
 	 * {@link Query#limit(int)} to limit large query results for efficient scrolling. <br />
 	 * Result objects are converted from the MongoDB native representation using an instance of {@see MongoConverter}.
 	 * Unless configured otherwise, an instance of {@link MappingMongoConverter} will be used. <br />
 	 * If your collection does not contain a homogeneous collection of types, this operation will not be an efficient way
 	 * to map objects since the test for class type is done in the client and not on the server.
+	 * <p>
+	 * When using {@link KeysetScrollPosition}, make sure to use non-nullable {@link org.springframework.data.domain.Sort
+	 * sort properties} as MongoDB does not support criteria to reconstruct a query result from absent document fields or
+	 * {@code null} values through {@code $gt/$lt} operators.
 	 *
 	 * @param query the query class that specifies the criteria used to find a record and also an optional fields
 	 *          specification. Must not be {@literal null}.
 	 * @param entityType the parametrized type of the returned window.
 	 * @return the converted window.
-	 * @throws IllegalStateException if a potential {@link Query#getKeyset() KeysetScrollPosition} contains an invalid position.
+	 * @throws IllegalStateException if a potential {@link Query#getKeyset() KeysetScrollPosition} contains an invalid
+	 *           position.
 	 * @since 4.1
 	 * @see Query#with(org.springframework.data.domain.OffsetScrollPosition)
 	 * @see Query#with(org.springframework.data.domain.KeysetScrollPosition)
@@ -834,13 +839,18 @@ <T> MapReduceResults<T> mapReduce(Query query, String inputCollectionName, Strin
 	 * Unless configured otherwise, an instance of {@link MappingMongoConverter} will be used. <br />
 	 * If your collection does not contain a homogeneous collection of types, this operation will not be an efficient way
 	 * to map objects since the test for class type is done in the client and not on the server.
+	 * <p>
+	 * When using {@link KeysetScrollPosition}, make sure to use non-nullable {@link org.springframework.data.domain.Sort
+	 * sort properties} as MongoDB does not support criteria to reconstruct a query result from absent document fields or
+	 * {@code null} values through {@code $gt/$lt} operators.
 	 *
 	 * @param query the query class that specifies the criteria used to find a record and also an optional fields
 	 *          specification. Must not be {@literal null}.
 	 * @param entityType the parametrized type of the returned window.
 	 * @param collectionName name of the collection to retrieve the objects from.
 	 * @return the converted window.
-	 * @throws IllegalStateException if a potential {@link Query#getKeyset() KeysetScrollPosition} contains an invalid position.
+	 * @throws IllegalStateException if a potential {@link Query#getKeyset() KeysetScrollPosition} contains an invalid
+	 *           position.
 	 * @since 4.1
 	 * @see Query#with(org.springframework.data.domain.OffsetScrollPosition)
 	 * @see Query#with(org.springframework.data.domain.KeysetScrollPosition)

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveFindOperation.java

@@ -18,8 +18,9 @@
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
-import org.springframework.data.domain.Window;
+import org.springframework.data.domain.KeysetScrollPosition;
 import org.springframework.data.domain.ScrollPosition;
+import org.springframework.data.domain.Window;
 import org.springframework.data.geo.GeoResult;
 import org.springframework.data.mongodb.core.query.CriteriaDefinition;
 import org.springframework.data.mongodb.core.query.NearQuery;
@@ -91,6 +92,10 @@ interface TerminatingFind<T> {
 
 		/**
 		 * Return a scroll of elements either starting or resuming at {@link ScrollPosition}.
+		 * <p>
+		 * When using {@link KeysetScrollPosition}, make sure to use non-nullable
+		 * {@link org.springframework.data.domain.Sort sort properties} as MongoDB does not support criteria to reconstruct
+		 * a query result from absent document fields or {@code null} values through {@code $gt/$lt} operators.
 		 *
 		 * @param scrollPosition the scroll position.
 		 * @return a scroll of the resulting elements.

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoOperations.java

@@ -473,12 +473,17 @@ Mono<MongoCollection<Document>> createView(String name, String source, Aggregati
 	 * Unless configured otherwise, an instance of {@link MappingMongoConverter} will be used. <br />
 	 * If your collection does not contain a homogeneous collection of types, this operation will not be an efficient way
 	 * to map objects since the test for class type is done in the client and not on the server.
+	 * <p>
+	 * When using {@link KeysetScrollPosition}, make sure to use non-nullable {@link org.springframework.data.domain.Sort
+	 * sort properties} as MongoDB does not support criteria to reconstruct a query result from absent document fields or
+	 * {@code null} values through {@code $gt/$lt} operators.
 	 *
 	 * @param query the query class that specifies the criteria used to find a record and also an optional fields
 	 *          specification. Must not be {@literal null}.
 	 * @param entityType the parametrized type of the returned list.
 	 * @return {@link Mono} emitting the converted window.
-	 * @throws IllegalStateException if a potential {@link Query#getKeyset() KeysetScrollPosition} contains an invalid position.
+	 * @throws IllegalStateException if a potential {@link Query#getKeyset() KeysetScrollPosition} contains an invalid
+	 *           position.
 	 * @since 4.1
 	 * @see Query#with(org.springframework.data.domain.OffsetScrollPosition)
 	 * @see Query#with(org.springframework.data.domain.KeysetScrollPosition)
@@ -493,13 +498,18 @@ Mono<MongoCollection<Document>> createView(String name, String source, Aggregati
 	 * Unless configured otherwise, an instance of {@link MappingMongoConverter} will be used. <br />
 	 * If your collection does not contain a homogeneous collection of types, this operation will not be an efficient way
 	 * to map objects since the test for class type is done in the client and not on the server.
+	 * <p>
+	 * When using {@link KeysetScrollPosition}, make sure to use non-nullable {@link org.springframework.data.domain.Sort
+	 * sort properties} as MongoDB does not support criteria to reconstruct a query result from absent document fields or
+	 * {@code null} values through {@code $gt/$lt} operators.
 	 *
 	 * @param query the query class that specifies the criteria used to find a record and also an optional fields
 	 *          specification. Must not be {@literal null}.
 	 * @param entityType the parametrized type of the returned list.
 	 * @param collectionName name of the collection to retrieve the objects from.
 	 * @return {@link Mono} emitting the converted window.
-	 * @throws IllegalStateException if a potential {@link Query#getKeyset() KeysetScrollPosition} contains an invalid position.
+	 * @throws IllegalStateException if a potential {@link Query#getKeyset() KeysetScrollPosition} contains an invalid
+	 *           position.
 	 * @since 4.1
 	 * @see Query#with(org.springframework.data.domain.OffsetScrollPosition)
 	 * @see Query#with(org.springframework.data.domain.KeysetScrollPosition)