Add WindowIterator and rename Scroll to Window

The intend of WindowIterator is to support users who need to iterate multiple windows. It keeps track of the position and loads the next window if needed so that the user does not have to interact with the position at all.

Also remove the Window methods to get the frist/last position and enforce the index based variant.

Update the documentation to make use of the newly introduced API.

Author: christophstrobl

src/main/asciidoc/repositories-scrolling.adoc

@@ -6,8 +6,36 @@ Scrolling consists of a stable sort, a scroll type (Offset- or Keyset-based scro
 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 `Scroll<T>` that allows obtaining the scroll position to resume to obtain the next `Scroll<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 next `ScrollPosition`  through `Scroll.lastScrollPosition()`.
+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.isLast());
+----
+
+`WindowIterator` provides a specialized implementation that simplifies consumption of multiple `Window` instances 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()) {
+  users.next().forEach(user -> {
+    // consume the user
+  });
+}
+----
 
 [[repositories.scrolling.offset]]
 ===== Scrolling using Offset
@@ -22,21 +50,13 @@ However, most databases require materializing the full query result before your
 ----
 interface UserRepository extends Repository<User, Long> {
 
-  Scroll<User> findFirst10ByLastnameOrderByFirstname(String lastname, OffsetScrollPosition position);
+  Window<User> findFirst10ByLastnameOrderByFirstname(String lastname, OffsetScrollPosition position);
 }
 
-Scroll<User> users = repository.findFirst10ByLastnameOrderByFirstname("Doe", OffsetScrollPosition.initial());
-
-do {
-
-  for (User u : users) {
-    // consume the user
-  }
-
-  // obtain the next Scroll
-  users = repository.findFirst10ByLastnameOrderByFirstname("Doe", users.lastScrollPosition());
-} while (!users.isEmpty() && !users.isLast());
+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]]
@@ -50,31 +70,30 @@ This approach maintains a set of keys to resume scrolling by passing keys into t
 
 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 `Scroll`.
+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 properties 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> {
 
-  Scroll<User> findFirst10ByLastnameOrderByFirstname(String lastname, KeysetScrollPosition position);
+  Window<User> findFirst10ByLastnameOrderByFirstname(String lastname, KeysetScrollPosition position);
 }
 
-Scroll<User> users = repository.findFirst10ByLastnameOrderByFirstname("Doe", KeysetScrollPosition.initial());
-
-do {
-
-  for (User u : users) {
-    // consume the user
-  }
-
-  // obtain the next Scroll
-  users = repository.findFirst10ByLastnameOrderByFirstname("Doe", users.lastScrollPosition());
-} while (!users.isEmpty() && !users.isLast());
+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.

src/main/java/org/springframework/data/domain/Scroll.java renamed to src/main/java/org/springframework/data/domain/Window.java

@@ -23,65 +23,66 @@
 import org.springframework.data.util.Streamable;
 
 /**
- * A scroll of data consumed from an underlying query result. A scroll is similar to {@link Slice} in the sense that it
- * contains a subset of the actual query results for easier consumption of large result sets. The scroll is less
+ * A set of data consumed from an underlying query result. A {@link Window} is similar to {@link Slice} in the sense
+ * that it contains a subset of the actual query results for easier consumption of large result sets. The window is less
  * opinionated about the actual data retrieval, whether the query has used index/offset, keyset-based pagination or
  * cursor resume tokens.
  *
  * @author Mark Paluch
+ * @author Christoph Strobl
  * @since 3.1
  * @see ScrollPosition
  */
-public interface Scroll<T> extends Streamable<T> {
+public interface Window<T> extends Streamable<T> {
 
 	/**
-	 * Construct a {@link Scroll}.
+	 * Construct a {@link Window}.
 	 *
 	 * @param items the list of data.
 	 * @param positionFunction the list of data.
-	 * @return the {@link Scroll}.
+	 * @return the {@link Window}.
 	 * @param <T>
 	 */
-	static <T> Scroll<T> from(List<T> items, IntFunction<? extends ScrollPosition> positionFunction) {
-		return new ScrollImpl<>(items, positionFunction, false);
+	static <T> Window<T> from(List<T> items, IntFunction<? extends ScrollPosition> positionFunction) {
+		return new WindowImpl<>(items, positionFunction, false);
 	}
 
 	/**
-	 * Construct a {@link Scroll}.
+	 * Construct a {@link Window}.
 	 *
 	 * @param items the list of data.
 	 * @param positionFunction the list of data.
 	 * @param hasNext
-	 * @return the {@link Scroll}.
+	 * @return the {@link Window}.
 	 * @param <T>
 	 */
-	static <T> Scroll<T> from(List<T> items, IntFunction<? extends ScrollPosition> positionFunction, boolean hasNext) {
-		return new ScrollImpl<>(items, positionFunction, hasNext);
+	static <T> Window<T> from(List<T> items, IntFunction<? extends ScrollPosition> positionFunction, boolean hasNext) {
+		return new WindowImpl<>(items, positionFunction, hasNext);
 	}
 
 	/**
-	 * Returns the number of elements in this scroll.
+	 * Returns the number of elements in this window.
 	 *
-	 * @return the number of elements in this scroll.
+	 * @return the number of elements in this window.
 	 */
 	int size();
 
 	/**
-	 * Returns {@code true} if this scroll contains no elements.
+	 * Returns {@code true} if this window contains no elements.
 	 *
-	 * @return {@code true} if this scroll contains no elements
+	 * @return {@code true} if this window contains no elements
 	 */
 	boolean isEmpty();
 
 	/**
-	 * Returns the scroll content as {@link List}.
+	 * Returns the windows content as {@link List}.
 	 *
 	 * @return
 	 */
 	List<T> getContent();
 
 	/**
-	 * Returns whether the current scroll is the last one.
+	 * Returns whether the current window is the last one.
 	 *
 	 * @return
 	 */
@@ -90,9 +91,9 @@ default boolean isLast() {
 	}
 
 	/**
-	 * Returns if there is a next scroll.
+	 * Returns if there is a next window.
 	 *
-	 * @return if there is a next scroll window.
+	 * @return if there is a next window window.
 	 */
 	boolean hasNext();
 
@@ -123,45 +124,12 @@ default ScrollPosition positionAt(T object) {
 		return positionAt(index);
 	}
 
-	// TODO: First and last seem to conflict with first/last scroll or first/last position of elements.
-	// these methods should rather express the position of the first element within this scroll and the scroll position
-	// to be used to get the next Scroll.
 	/**
-	 * Returns the first {@link ScrollPosition} or throw {@link NoSuchElementException} if the list is empty.
-	 *
-	 * @return the first {@link ScrollPosition}.
-	 * @throws NoSuchElementException if this result is empty.
-	 */
-	default ScrollPosition firstPosition() {
-
-		if (size() == 0) {
-			throw new NoSuchElementException();
-		}
-
-		return positionAt(0);
-	}
-
-	/**
-	 * Returns the last {@link ScrollPosition} or throw {@link NoSuchElementException} if the list is empty.
-	 *
-	 * @return the last {@link ScrollPosition}.
-	 * @throws NoSuchElementException if this result is empty.
-	 */
-	default ScrollPosition lastPosition() {
-
-		if (size() == 0) {
-			throw new NoSuchElementException();
-		}
-
-		return positionAt(size() - 1);
-	}
-
-	/**
-	 * Returns a new {@link Scroll} with the content of the current one mapped by the given {@code converter}.
+	 * Returns a new {@link Window} with the content of the current one mapped by the given {@code converter}.
 	 *
 	 * @param converter must not be {@literal null}.
-	 * @return a new {@link Scroll} with the content of the current one mapped by the given {@code converter}.
+	 * @return a new {@link Window} with the content of the current one mapped by the given {@code converter}.
 	 */
-	<U> Scroll<U> map(Function<? super T, ? extends U> converter);
+	<U> Window<U> map(Function<? super T, ? extends U> converter);
 
 }

src/main/java/org/springframework/data/domain/ScrollImpl.java renamed to src/main/java/org/springframework/data/domain/WindowImpl.java

@@ -26,19 +26,19 @@
 import org.springframework.util.ObjectUtils;
 
 /**
- * Default {@link Scroll} implementation.
+ * Default {@link Window} implementation.
  *
  * @author Mark Paluch
  * @since 3.1
  */
-class ScrollImpl<T> implements Scroll<T> {
+class WindowImpl<T> implements Window<T> {
 
 	private final List<T> items;
 	private final IntFunction<? extends ScrollPosition> positionFunction;
 
 	private final boolean hasNext;
 
-	ScrollImpl(List<T> items, IntFunction<? extends ScrollPosition> positionFunction, boolean hasNext) {
+	WindowImpl(List<T> items, IntFunction<? extends ScrollPosition> positionFunction, boolean hasNext) {
 
 		Assert.notNull(items, "List of items must not be null");
 		Assert.notNull(positionFunction, "Position function must not be null");
@@ -79,11 +79,11 @@ public ScrollPosition positionAt(int index) {
 	}
 
 	@Override
-	public <U> Scroll<U> map(Function<? super T, ? extends U> converter) {
+	public <U> Window<U> map(Function<? super T, ? extends U> converter) {
 
 		Assert.notNull(converter, "Function must not be null");
 
-		return new ScrollImpl<>(stream().map(converter).collect(Collectors.toList()), positionFunction, hasNext);
+		return new WindowImpl<>(stream().map(converter).collect(Collectors.toList()), positionFunction, hasNext);
 	}
 
 	@NotNull
@@ -98,7 +98,7 @@ public boolean equals(Object o) {
 			return true;
 		if (o == null || getClass() != o.getClass())
 			return false;
-		ScrollImpl<?> that = (ScrollImpl<?>) o;
+		WindowImpl<?> that = (WindowImpl<?>) o;
 		return ObjectUtils.nullSafeEquals(items, that.items)
 				&& ObjectUtils.nullSafeEquals(positionFunction, that.positionFunction)
 				&& ObjectUtils.nullSafeEquals(hasNext, that.hasNext);