introduce First annotation

api/src/main/java/jakarta/data/Limit.java

@@ -45,7 +45,9 @@
  * <ul>
  * <li>more than one parameter of type {@code Limit},</li>
  * <li>a parameter of type {@code Limit} and a parameter of type
- *     {@link PageRequest}, or</li>
+ *     {@link PageRequest},</li>
+ * <li>a {@link jakarta.data.repository.First @First} annotation
+ *     and a parameter of type {@code Limit}, or</li>
  * <li>a parameter of type {@code Limit} in combination with the
  *     {@code First} keyword.
  * </ul>

api/src/main/java/jakarta/data/repository/Find.java

@@ -84,6 +84,7 @@
  *     <li>{@code Page<E>}, or</li>
  *     <li>{@code CursoredPage<E>} (only allowed when {@code E} is the entity type).</li>
  * </ul>
+ * <p>The number of query results may be limited using the {@link First} annotation.</p>
  *
  * <p>For example, if a {@code Car} entity has attribute names including {@code make},
  * {@code model}, {@code year}, and {@code vin}, a repository can use a Java record
@@ -120,6 +121,8 @@
  *
  * @see By
  * @see OrderBy
+ * @see First
+ * @see Select
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)

api/src/main/java/jakarta/data/repository/First.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2022,2025 Contributors to the Eclipse Foundation
+ *
+ * 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
+ *
+ *     http://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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package jakarta.data.repository;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * <p>Specifies a static limit on the number of results retrieved by a
+ * repository method. The results of a single invocation of a repository
+ * method may be limited to a given {@linkplain #value maximum number of
+ * results}. For example,</p>
+ *
+ * <pre>
+ * &#64;Find &#64;First
+ * &#64;OrderBy(value = _Employee.SALARY, descending = true)
+ * Employee highestPaid(String jobTitle);
+ * </pre>
+ *
+ * <pre>
+ * &#64;First(10)
+ * &#64;Query("order by playCount desc")
+ * List&lt;Song&gt; topTen();
+ * </pre>
+ *
+ * <p>A repository method may not be declared with:
+ * <ul>
+ * <li>a {@code @First} annotation and a parameter of type
+ *     {@link jakarta.data.page.PageRequest} or
+ *     {@link jakarta.data.Limit}, or</li>
+ * <li>a {@code @First} annotation in combination with the
+ *     {@code First} keyword.
+ * </ul>
+ *
+ * @see Find
+ * @see Query
+ *
+ * @since 1.1
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface First {
+    /**
+     * The limit on the number of results returned by the repository
+     * method. Must be strictly positive.
+     */
+    int value() default 1;
+}

api/src/main/java/jakarta/data/repository/Query.java

@@ -131,6 +131,7 @@
  *     <li>{@code Page<R>} or {@code CursoredPage<R>}.</li>
  * </ul>
  * <p>The method returns an object for every query result.</p>
+ * <p>The number of query results may be limited using the {@link First} annotation.</p>
  * <ul>
  * <li>If the return type of the annotated method is {@code R} or {@code Optional<R>} and more than one record satisfies
  *     the query restriction, the method must throw {@link jakarta.data.exceptions.NonUniqueResultException}.</li>
@@ -143,6 +144,8 @@
  * annotation, lifecycle annotation, or query annotation.
  *
  * @see Param
+ * @see First
+ * @see Select
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

api/src/main/java/jakarta/data/repository/Select.java

@@ -46,6 +46,8 @@
  * <p>This annotation must not be used in other locations.</p>
  *
  * @see Find
+ *
+ * @since 1.1
  */
 @Documented
 @Repeatable(Select.List.class)

spec/src/main/asciidoc/repository.asciidoc

@@ -283,7 +283,9 @@ A repository method must throw `UnsupportedOperationException` if it has:
 
 - more than one parameter of type `PageRequest` or `Limit`,
 - a parameter of type `PageRequest` and a parameter of type `Limit`,
-- a parameter of type `PageRequest` or `Limit`, in combination with the keyword `First`, or
+- a `@First` annotation and a parameter of type `PageRequest` or `Limit`,
+- a parameter of type `PageRequest` or `Limit`, in combination with the keyword `First`,
+- a `@First` annotation, in combination with the keyword `First`, or
 - more than one parameter of type `Order`.
 
 Alternatively, a Jakarta Data provider is permitted to reject such a repository method declaration at compile time.