Introduce Limit type to limit repository query results.

We now accept Limit as type to express dynamic repository query limits.

Closes #2827
Original pull request: #2836

src/main/java/org/springframework/data/domain/Limit.java

@@ -0,0 +1,121 @@
+/*
+ * Copyright 2023 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.domain;
+
+import org.springframework.data.domain.Limit.Limited;
+import org.springframework.data.domain.Limit.Unlimited;
+import org.springframework.util.ClassUtils;
+
+/**
+ * {@link Limit} represents the maximum value up to which an operation should continue processing. It may be used for
+ * defining the {@link #max() maximum} number of results within a repository finder method or if applicable a template
+ * operation.
+ * <p>
+ * A {@link Limit#isUnlimited()} is used to indicate that there is no {@link Limit} defined, which should be favoured
+ * over using {@literal null} or {@link java.util.Optional#empty()} to indicate the absence of an actual {@link Limit}.
+ * </p>
+ * {@link Limit} itself does not make assumptions about the actual {@link #max()} value sign. This means that a negative
+ * value may be valid within a defined context. Implementations should override {@link #isUnlimited()} to fit their
+ * needs and enforce restrictions if needed.
+ * 
+ * @author Christoph Strobl
+ * @since 3.2
+ */
+public sealed interface Limit permits Limited, Unlimited {
+
+	/**
+	 * @return the max number of potential results.
+	 */
+	int max();
+
+	/**
+	 * @return {@literal true} if no limiting (maximum value) should be applied.
+	 */
+	default boolean isUnlimited() {
+		return Unlimited.INSTANCE.equals(this);
+	}
+
+	/**
+	 * @return a {@link Limit} instance that does not define {@link #max()} and answers {@link #isUnlimited()} with
+	 *         {@literal true}.
+	 */
+	static Limit unlimited() {
+		return Unlimited.INSTANCE;
+	}
+
+	/**
+	 * Create a new {@link Limit} from the given {@literal max} value.
+	 *
+	 * @param max the maximum value.
+	 * @return new instance of {@link Limit}.
+	 */
+	static Limit of(int max) {
+		return new Limited(max);
+	}
+
+	final class Limited implements Limit {
+
+		private final int max;
+
+		Limited(int max) {
+			this.max = max;
+		}
+
+		@Override
+		public int max() {
+			return max;
+		}
+
+		@Override
+		public boolean equals(Object obj) {
+
+			if (obj == null) {
+				return false;
+			}
+			if (!ClassUtils.isAssignable(Limit.class, obj.getClass())) {
+				return false;
+			}
+			Limit that = (Limit) obj;
+			if (this.isUnlimited() && that.isUnlimited()) {
+				return true;
+			}
+			return max() == that.max();
+		}
+
+		@Override
+		public int hashCode() {
+			return (int) (max ^ (max >>> 32));
+		}
+	}
+
+	final class Unlimited implements Limit {
+
+		static final Limit INSTANCE = new Unlimited();
+
+		Unlimited() {}
+
+		@Override
+		public int max() {
+			throw new IllegalStateException(
+					"Unlimited does not define 'max'. Please check 'isUnlimited' before attempting to read 'max'");
+		}
+
+		@Override
+		public boolean isUnlimited() {
+			return true;
+		}
+	}
+}

src/main/java/org/springframework/data/domain/Pageable.java

@@ -24,6 +24,7 @@ import org.springframework.util.Assert;
  *
  * @author Oliver Gierke
  * @author Mark Paluch
+ * @author Christoph Strobl
  */
 public interface Pageable {
 
@@ -33,7 +34,18 @@ public interface Pageable {
 	 * @return
 	 */
 	static Pageable unpaged() {
-		return Unpaged.INSTANCE;
+		return unpaged(Sort.unsorted());
+	}
+
+	/**
+	 * Returns a {@link Pageable} instance representing no pagination setup having a defined result {@link Sort order}.
+	 *
+	 * @param sort must not be {@literal null}, use {@link Sort#unsorted()} if needed.
+	 * @return never {@literal null}.
+	 * @since 3.2
+	 */
+	static Pageable unpaged(Sort sort) {
+		return Unpaged.sorted(sort);
 	}
 
 	/**

src/main/java/org/springframework/data/domain/Unpaged.java

@@ -19,10 +19,21 @@ package org.springframework.data.domain;
  * {@link Pageable} implementation to represent the absence of pagination information.
  *
  * @author Oliver Gierke
+ * @author Christoph Strobl
  */
-enum Unpaged implements Pageable {
+final class Unpaged implements Pageable {
 
-	INSTANCE;
+	private static final Pageable UNSORTED = new Unpaged(Sort.unsorted());
+
+	private final Sort sort;
+
+	Unpaged(Sort sort) {
+		this.sort = sort;
+	}
+
+	static Pageable sorted(Sort sort) {
+		return sort.isSorted() ? new Unpaged(sort) : UNSORTED;
+	}
 
 	@Override
 	public boolean isPaged() {
@@ -46,7 +57,7 @@ enum Unpaged implements Pageable {
 
 	@Override
 	public Sort getSort() {
-		return Sort.unsorted();
+		return sort;
 	}
 
 	@Override
@@ -78,5 +89,4 @@ enum Unpaged implements Pageable {
 
 		throw new UnsupportedOperationException();
 	}
-
 }