From 85826e1fe095bc8996d2903c7a8c0cba6e9a222f Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Thu, 16 Mar 2023 12:02:34 +0100 Subject: [PATCH] Document limitations around nullable properties. See: #4308 Original Pull Request: #4317 --- .../mongodb/core/ExecutableFindOperation.java | 8 ++++++-- .../data/mongodb/core/MongoOperations.java | 16 +++++++++++++--- .../data/mongodb/core/ReactiveFindOperation.java | 7 ++++++- .../mongodb/core/ReactiveMongoOperations.java | 14 ++++++++++++-- 4 files changed, 37 insertions(+), 8 deletions(-) diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ExecutableFindOperation.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ExecutableFindOperation.java index 5ae201093..d5d57e97f 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ExecutableFindOperation.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ExecutableFindOperation.java @@ -20,8 +20,9 @@ import java.util.Optional; 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 @@ public interface ExecutableFindOperation { /** * Return a window of elements either starting or resuming at * {@link org.springframework.data.domain.ScrollPosition}. + *

+ * 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 diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java index 2d51a56c1..2f3c0dd92 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/MongoOperations.java @@ -807,19 +807,24 @@ public interface MongoOperations extends FluentMongoOperations { List find(Query query, Class entityClass, String collectionName); /** - * Query for a window window of objects of type T from the specified collection.
+ * Query for a window of objects of type T from the specified collection.
* 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.
* 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.
* 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. + *

+ * 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 @@ public interface MongoOperations extends FluentMongoOperations { * Unless configured otherwise, an instance of {@link MappingMongoConverter} will be used.
* 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. + *

+ * 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) diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveFindOperation.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveFindOperation.java index 3786cdac0..4456ab6ac 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveFindOperation.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveFindOperation.java @@ -18,8 +18,9 @@ package org.springframework.data.mongodb.core; 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 @@ public interface ReactiveFindOperation { /** * Return a scroll of elements either starting or resuming at {@link ScrollPosition}. + *

+ * 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. diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoOperations.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoOperations.java index 8030fb8a9..af3698965 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoOperations.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/ReactiveMongoOperations.java @@ -473,12 +473,17 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations { * Unless configured otherwise, an instance of {@link MappingMongoConverter} will be used.
* 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. + *

+ * 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 @@ public interface ReactiveMongoOperations extends ReactiveFluentMongoOperations { * Unless configured otherwise, an instance of {@link MappingMongoConverter} will be used.
* 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. + *

+ * 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)