Add support for Scroll API to allow Keyset- and Offset-based scrolling

pom.xml

@@ -5,7 +5,7 @@
 
 	<groupId>org.springframework.data</groupId>
 	<artifactId>spring-data-commons</artifactId>
-	<version>3.1.0-SNAPSHOT</version>
+	<version>3.1.0-GH-2151-SNAPSHOT</version>
 
 	<name>Spring Data Core</name>
 	<description>Core Spring concepts underpinning every Spring Data module.</description>

src/main/asciidoc/index.adoc

@@ -2,6 +2,7 @@
 Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Pollack; Thomas Risberg; Mark Paluch; Jay Bryant
 :revnumber: {version}
 :revdate: {localdate}
+:feature-scroll: true
 ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]]
 
 (C) 2008-2022 The original authors.

src/main/asciidoc/repositories-paging-sorting.adoc

@@ -0,0 +1,136 @@
+[[repositories.special-parameters]]
+=== Special parameter handling
+
+To handle parameters in your query, define method parameters as already seen in the preceding examples.
+Besides that, the infrastructure recognizes certain specific types like `Pageable` and `Sort`, to apply pagination and sorting to your queries dynamically.
+The following example demonstrates these features:
+
+ifdef::feature-scroll[]
+.Using `Pageable`, `Slice`, `ScrollPosition`, and `Sort` in query methods
+====
+[source,java]
+----
+Page<User> findByLastname(String lastname, Pageable pageable);
+
+Slice<User> findByLastname(String lastname, Pageable pageable);
+
+Scroll<User> findTop10ByLastname(String lastname, ScrollPosition position, Sort sort);
+
+List<User> findByLastname(String lastname, Sort sort);
+
+List<User> findByLastname(String lastname, Pageable pageable);
+----
+====
+endif::[]
+
+ifndef::feature-scroll[]
+.Using `Pageable`, `Slice`, and `Sort` in query methods
+====
+[source,java]
+----
+Page<User> findByLastname(String lastname, Pageable pageable);
+
+Slice<User> findByLastname(String lastname, Pageable pageable);
+
+List<User> findByLastname(String lastname, Sort sort);
+
+List<User> findByLastname(String lastname, Pageable pageable);
+----
+====
+endif::[]
+
+IMPORTANT: APIs taking `Sort` and `Pageable` expect non-`null` values to be handed into methods.
+If you do not want to apply any sorting or pagination, use `Sort.unsorted()` and `Pageable.unpaged()`.
+
+The first method lets you pass an `org.springframework.data.domain.Pageable` instance to the query method to dynamically add paging to your statically defined query.
+A `Page` knows about the total number of elements and pages available.
+It does so by the infrastructure triggering a count query to calculate the overall number.
+As this might be expensive (depending on the store used), you can instead return a `Slice`.
+A `Slice` knows only about whether a next `Slice` is available, which might be sufficient when walking through a larger result set.
+
+Sorting options are handled through the `Pageable` instance, too.
+If you need only sorting, add an `org.springframework.data.domain.Sort` parameter to your method.
+As you can see, returning a `List` is also possible.
+In this case, the additional metadata required to build the actual `Page` instance is not created (which, in turn, means that the additional count query that would have been necessary is not issued).
+Rather, it restricts the query to look up only the given range of entities.
+
+NOTE: To find out how many pages you get for an entire query, you have to trigger an additional count query.
+By default, this query is derived from the query you actually trigger.
+
+[[repositories.paging-and-sorting]]
+==== Paging and Sorting
+
+You can define simple sorting expressions by using property names.
+You can concatenate expressions to collect multiple criteria into one expression.
+
+.Defining sort expressions
+====
+[source,java]
+----
+Sort sort = Sort.by("firstname").ascending()
+  .and(Sort.by("lastname").descending());
+----
+====
+
+For a more type-safe way to define sort expressions, start with the type for which to define the sort expression and use method references to define the properties on which to sort.
+
+.Defining sort expressions by using the type-safe API
+====
+[source,java]
+----
+TypedSort<Person> person = Sort.sort(Person.class);
+
+Sort sort = person.by(Person::getFirstname).ascending()
+  .and(person.by(Person::getLastname).descending());
+----
+====
+
+NOTE: `TypedSort.by(…)` makes use of runtime proxies by (typically) using CGlib, which may interfere with native image compilation when using tools such as Graal VM Native.
+
+If your store implementation supports Querydsl, you can also use the generated metamodel types to define sort expressions:
+
+.Defining sort expressions by using the Querydsl API
+====
+[source,java]
+----
+QSort sort = QSort.by(QPerson.firstname.asc())
+  .and(QSort.by(QPerson.lastname.desc()));
+----
+====
+
+ifdef::feature-scroll[]
+include::repositories-scrolling.adoc[]
+endif::[]
+
+[[repositories.limit-query-result]]
+=== Limiting Query Results
+
+You can limit the results of query methods by using the `first` or `top` keywords, which you can use interchangeably.
+You can append an optional numeric value to `top` or `first` to specify the maximum result size to be returned.
+If the number is left out, a result size of 1 is assumed.
+The following example shows how to limit the query size:
+
+.Limiting the result size of a query with `Top` and `First`
+====
+[source,java]
+----
+User findFirstByOrderByLastnameAsc();
+
+User findTopByOrderByAgeDesc();
+
+Page<User> queryFirst10ByLastname(String lastname, Pageable pageable);
+
+Slice<User> findTop3ByLastname(String lastname, Pageable pageable);
+
+List<User> findFirst10ByLastname(String lastname, Sort sort);
+
+List<User> findTop10ByLastname(String lastname, Pageable pageable);
+----
+====
+
+The limiting expressions also support the `Distinct` keyword for datastores that support distinct queries.
+Also, for the queries that limit the result set to one instance, wrapping the result into with the `Optional` keyword is supported.
+
+If pagination or slicing is applied to a limiting query pagination (and the calculation of the number of available pages), it is applied within the limited result.
+
+NOTE: Limiting the results in combination with dynamic sorting by using a `Sort` parameter lets you express query methods for the 'K' smallest as well as for the 'K' biggest elements.

src/main/asciidoc/repositories-scrolling.adoc

@@ -0,0 +1,102 @@
+[[repositories.scrolling]]
+==== Scrolling
+
+Scrolling is a more fine-grained approach to iterate through larger results set chunks.
+Scrolling consists of a stable sort, a scroll type (Offset- or Keyset-based scrolling) and result limiting.
+You can define simple sorting expressions by using property names and define static result limiting using the <<repositories.limit-query-result,`Top` or `First` keyword>> through query derivation.
+You can concatenate expressions to collect multiple criteria into one expression.
+
+Scroll queries return a `Window<T>` that allows obtaining the scroll position to resume to obtain the next `Window<T>` until your application has consumed the entire query result.
+Similar to consuming a Java `Iterator<List<…>>` by obtaining the next batch of results, query result scrolling lets you access the a `ScrollPosition`  through `Window.positionAt(...)`.
+
+[source,java]
+----
+Window<User> users = repository.findFirst10ByLastnameOrderByFirstname("Doe", OffsetScrollPosition.initial());
+do {
+
+  for (User u : users) {
+    // consume the user
+  }
+
+  // obtain the next Scroll
+  users = repository.findFirst10ByLastnameOrderByFirstname("Doe", users.positionAt(users.size() - 1));
+} while (!users.isEmpty() && users.hasNext());
+----
+
+`WindowIterator` provides a utility to simplify scrolling across ``Window``s by removing the need to check for the presence of a next `Window` and applying the `ScrollPosition`.
+
+[source,java]
+----
+WindowIterator<User> users = WindowIterator.of(position -> repository.findFirst10ByLastnameOrderByFirstname("Doe", position))
+  .startingAt(OffsetScrollPosition.initial());
+
+while (users.hasNext()) {
+  User u = users.next();
+  // consume the user
+}
+----
+
+[[repositories.scrolling.offset]]
+===== Scrolling using Offset
+
+Offset scrolling uses similar to pagination, an Offset counter to skip a number of results and let the data source only return results beginning at the given Offset.
+This simple mechanism avoids large results being sent to the client application.
+However, most databases require materializing the full query result before your server can return the results.
+
+.Using `OffsetScrollPosition` with Repository Query Methods
+====
+[source,java]
+----
+interface UserRepository extends Repository<User, Long> {
+
+  Window<User> findFirst10ByLastnameOrderByFirstname(String lastname, OffsetScrollPosition position);
+}
+
+WindowIterator<User> users = WindowIterator.of(position -> repository.findFirst10ByLastnameOrderByFirstname("Doe", position))
+  .startingAt(OffsetScrollPosition.initial()); <1>
+----
+
+<1> Start from the initial offset at position `0`.
+====
+
+[[repositories.scrolling.keyset]]
+===== Scrolling using Keyset-Filtering
+
+Offset-based requires most databases require materializing the entire result before your server can return the results.
+So while the client only sees the portion of the requested results, your server needs to build the full result, which causes additional load.
+
+Keyset-Filtering approaches result subset retrieval by leveraging built-in capabilities of your database aiming to reduce the computation and I/O requirements for individual queries.
+This approach maintains a set of keys to resume scrolling by passing keys into the query, effectively amending your filter criteria.
+
+The core idea of Keyset-Filtering is to start retrieving results using a stable sorting order.
+Once you want to scroll to the next chunk, you obtain a `ScrollPosition` that is used to reconstruct the position within the sorted result.
+The `ScrollPosition` captures the keyset of the last entity within the current `Window`.
+To run the query, reconstruction rewrites the criteria clause to include all sort fields and the primary key so that the database can leverage potential indexes to run the query.
+The database needs only constructing a much smaller result from the given keyset position without the need to fully materialize a large result and then skipping results until reaching a particular offset.
+
+[WARNING]
+====
+Keyset-Filtering requires the keyset properties (those used for sorting) to be non-nullable.
+This limitation applies due to the store specific `null` value handling of comparison operators as well as the need to run queries against an indexed source.
+Keyset-Filtering on nullable properties will lead to unexpected results.
+====
+
+.Using `KeysetScrollPosition` with Repository Query Methods
+====
+[source,java]
+----
+interface UserRepository extends Repository<User, Long> {
+
+  Window<User> findFirst10ByLastnameOrderByFirstname(String lastname, KeysetScrollPosition position);
+}
+
+WindowIterator<User> users = WindowIterator.of(position -> repository.findFirst10ByLastnameOrderByFirstname("Doe", position))
+  .startingAt(KeysetScrollPosition.initial()); <1>
+----
+<1> Start at the very beginning and do not apply additional filtering.
+====
+
+Keyset-Filtering works best when your database contains an index that matches the sort fields, hence a static sort works well.
+Scroll queries applying Keyset-Filtering require to the properties used in the sort order to be returned by the query, and these must be mapped in the returned entity.
+
+You can use interface and DTO projections, however make sure to include all properties that you've sorted by to avoid keyset extraction failures.

src/main/asciidoc/repositories.adoc

@@ -92,6 +92,10 @@ Page<User> users = repository.findAll(PageRequest.of(1, 20));
 ----
 ====
 
+ifdef::feature-scroll[]
+In addition to pagination, scrolling provides a more fine-grained access to iterate through chunks of larger result sets.
+endif::[]
+
 In addition to query methods, query derivation for both count and delete queries is available.
 The following list shows the interface definition for a derived count query:
 
@@ -517,118 +521,7 @@ List<Person> findByAddress_ZipCode(ZipCode zipCode);
 
 Because we treat the underscore character as a reserved character, we strongly advise following standard Java naming conventions (that is, not using underscores in property names but using camel case instead).
 
-[[repositories.special-parameters]]
-=== Special parameter handling
-
-To handle parameters in your query, define method parameters as already seen in the preceding examples.
-Besides that, the infrastructure recognizes certain specific types like `Pageable` and `Sort`, to apply pagination and sorting to your queries dynamically.
-The following example demonstrates these features:
-
-.Using `Pageable`, `Slice`, and `Sort` in query methods
-====
-[source,java]
-----
-Page<User> findByLastname(String lastname, Pageable pageable);
-
-Slice<User> findByLastname(String lastname, Pageable pageable);
-
-List<User> findByLastname(String lastname, Sort sort);
-
-List<User> findByLastname(String lastname, Pageable pageable);
-----
-====
-
-IMPORTANT: APIs taking `Sort` and `Pageable` expect non-`null` values to be handed into methods.
-If you do not want to apply any sorting or pagination, use `Sort.unsorted()` and `Pageable.unpaged()`.
-
-The first method lets you pass an `org.springframework.data.domain.Pageable` instance to the query method to dynamically add paging to your statically defined query.
-A `Page` knows about the total number of elements and pages available.
-It does so by the infrastructure triggering a count query to calculate the overall number.
-As this might be expensive (depending on the store used), you can instead return a `Slice`.
-A `Slice` knows only about whether a next `Slice` is available, which might be sufficient when walking through a larger result set.
-
-Sorting options are handled through the `Pageable` instance, too.
-If you need only sorting, add an `org.springframework.data.domain.Sort` parameter to your method.
-As you can see, returning a `List` is also possible.
-In this case, the additional metadata required to build the actual `Page` instance is not created (which, in turn, means that the additional count query that would have been necessary is not issued).
-Rather, it restricts the query to look up only the given range of entities.
-
-NOTE: To find out how many pages you get for an entire query, you have to trigger an additional count query.
-By default, this query is derived from the query you actually trigger.
-
-[[repositories.paging-and-sorting]]
-==== Paging and Sorting
-
-You can define simple sorting expressions by using property names.
-You can concatenate expressions to collect multiple criteria into one expression.
-
-.Defining sort expressions
-====
-[source,java]
-----
-Sort sort = Sort.by("firstname").ascending()
-  .and(Sort.by("lastname").descending());
-----
-====
-
-For a more type-safe way to define sort expressions, start with the type for which to define the sort expression and use method references to define the properties on which to sort.
-
-.Defining sort expressions by using the type-safe API
-====
-[source,java]
-----
-TypedSort<Person> person = Sort.sort(Person.class);
-
-Sort sort = person.by(Person::getFirstname).ascending()
-  .and(person.by(Person::getLastname).descending());
-----
-====
-
-NOTE: `TypedSort.by(…)` makes use of runtime proxies by (typically) using CGlib, which may interfere with native image compilation when using tools such as Graal VM Native.
-
-If your store implementation supports Querydsl, you can also use the generated metamodel types to define sort expressions:
-
-.Defining sort expressions by using the Querydsl API
-====
-[source,java]
-----
-QSort sort = QSort.by(QPerson.firstname.asc())
-  .and(QSort.by(QPerson.lastname.desc()));
-----
-====
-
-[[repositories.limit-query-result]]
-=== Limiting Query Results
-
-You can limit the results of query methods by using the `first` or `top` keywords, which you can use interchangeably.
-You can append an optional numeric value to `top` or `first` to specify the maximum result size to be returned.
-If the number is left out, a result size of 1 is assumed.
-The following example shows how to limit the query size:
-
-.Limiting the result size of a query with `Top` and `First`
-====
-[source,java]
-----
-User findFirstByOrderByLastnameAsc();
-
-User findTopByOrderByAgeDesc();
-
-Page<User> queryFirst10ByLastname(String lastname, Pageable pageable);
-
-Slice<User> findTop3ByLastname(String lastname, Pageable pageable);
-
-List<User> findFirst10ByLastname(String lastname, Sort sort);
-
-List<User> findTop10ByLastname(String lastname, Pageable pageable);
-----
-====
-
-The limiting expressions also support the `Distinct` keyword for datastores that support distinct queries.
-Also, for the queries that limit the result set to one instance, wrapping the result into with the `Optional` keyword is supported.
-
-If pagination or slicing is applied to a limiting query pagination (and the calculation of the number of available pages), it is applied within the limited result.
-
-NOTE: Limiting the results in combination with dynamic sorting by using a `Sort` parameter lets you express query methods for the 'K' smallest as well as for the 'K' biggest elements.
+include::repositories-paging-sorting.adoc[]
 
 [[repositories.collections-and-iterables]]
 === Repository Methods Returning Collections or Iterables