allow multi-valued parameters to @find & @delete methods

- interpreted as defining an "in" condition
- allows a methods of BasicRepository to be redefined in
  terms of @find & @delete

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

@@ -24,6 +24,8 @@
 import java.util.Optional;
 import java.util.stream.Stream;
 
+import static jakarta.data.repository.By.ID;
+
 /**
  * <p>A built-in repository supertype for performing basic operations on entities.</p>
  *
@@ -140,7 +142,8 @@ public interface BasicRepository<T, K> extends DataRepository<T, K> {
      * @return the entity with the given Id or {@link Optional#empty()} if none is found.
      * @throws NullPointerException when the Id is {@code null}.
      */
-    Optional<T> findById(K id);
+    @Find
+    Optional<T> findById(@By(ID) K id);
 
     /**
      * Returns whether an entity with the given Id exists.
@@ -186,7 +189,8 @@ public interface BasicRepository<T, K> extends DataRepository<T, K> {
      * ids.
      * @throws NullPointerException in case the given {@link Iterable ids} or one of its items is {@code null}.
      */
-    Stream<T> findByIdIn(Iterable<K> ids);
+    @Find
+    Stream<T> findByIdIn(@By(ID) Iterable<K> ids);
 
     /**
      * Deletes the entity with the given Id.
@@ -196,7 +200,8 @@ public interface BasicRepository<T, K> extends DataRepository<T, K> {
      * @param id must not be {@code null}.
      * @throws NullPointerException when the Id is {@code null}.
      */
-    void deleteById(K id);
+    @Delete
+    void deleteById(@By(ID) K id);
 
     /**
      * Deletes a given entity. Deletion is performed by matching the Id, and if the entity is
@@ -219,7 +224,8 @@ public interface BasicRepository<T, K> extends DataRepository<T, K> {
      * @param ids must not be {@code null}. Must not contain {@code null} elements.
      * @throws NullPointerException when the iterable is {@code null} or contains {@code null} elements.
      */
-    void deleteByIdIn(Iterable<K> ids);
+    @Delete
+    void deleteByIdIn(@By(ID) Iterable<K> ids);
 
     /**
      * Deletes the given entities. Deletion of each entity is performed by matching the unique identifier,

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

@@ -63,9 +63,10 @@
  * <p>Alternatively, the {@code Delete} annotation may be used to annotate a repository method with no parameter of
  * entity type. Then the repository method is interpreted as a parameter-based automatic query method. The entity type
  * to be deleted is the primary entity type of the repository. The method return type must be {@code void}, {@code int},
- * or {@code long}. Every parameter of the annotated method must have exactly the same type and name (the parameter name
- * in the Java source, or a name assigned by {@link By @By}) as a persistent field or property of the entity class.
- * Parameters of type {@code Sort}, {@code Order}, {@code Limit}, and {@code PageRequest} are prohibited.
+ * or {@code long}. Every parameter of the annotated method must have exactly the same name (the parameter name in the
+ * Java source, or a name assigned by {@link By @By}) as a persistent field or property of the entity class and be of
+ * type {@code T}, {@code T[]}, or {@code Iterable<T>} where {@code T} is the type of the field or property. Parameters
+ * of type {@code Sort}, {@code Order}, {@code Limit}, and {@code PageRequest} are prohibited.
  * </p>
  * <p>For example, consider an interface representing a garage:</p>
  * <pre>
@@ -76,10 +77,10 @@
  *     void unparkAll();
  *
  *     {@code @Delete}
- *     void unpark(String registration);
+ *     void unpark(String[] registration);
  * }
  * </pre>
- * <p>Here,{@code unparkAll()} deletes every {@code Car}, while {@code unpark(String)} deletes any {@code Car} with a
+ * <p>Here,{@code unparkAll()} deletes every {@code Car}, while {@code unpark(String)} deletes every {@code Car} with a
  * matching value of its {@code registration} field.
  * </p>
  * <p>An automatic query method annotated {@code Delete} removes every record which satisfies the parameter-based

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

@@ -33,8 +33,9 @@
  * type returned by the query. Each parameter of the annotated method must either:
  * </p>
  * <ul>
- * <li>have exactly the same type and name (the parameter name in the Java source, or a name assigned by {@link By @By})
- *     as a persistent field or property of the entity class, or</li>
+ * <li>have exactly the name (the parameter name in the Java source, or a name assigned by {@link By @By}) as a
+ *     persistent field or property of the entity class and be of type {@code T}, {@code T[]}, or {@code Iterable<T>}
+ *     where {@code T} is the type of the field or property, or</li>
  * <li>be of type {@link jakarta.data.Limit}, {@link jakarta.data.Sort}, {@link jakarta.data.Order}, or
  *     {@link jakarta.data.page.PageRequest}.</li>
  * </ul>
@@ -49,10 +50,14 @@
  * interface Garage {
  *     {@code @Find}
  *     {@code List<Car>} getCarsWithModel(@By("model") String model);
+ *
+ *     {@code @Find}
+ *     {@code List<Car>} getCarsWithYearIn(@By("modelYear") int[] years);
  * }
  * </pre>
  * <p>The {@code @Find} annotation indicates that the {@code getCarsWithModel(model)} method retrieves {@code Car}
- * instances with the given value of the {@code model} field.
+ * instances with the given value of the {@code model} field, and that the {@code getCarsWithYearIn(years)} method
+ * retrieves cars with any one of the given values of the {@code modelYear} field.
  * </p>
  *
  * <p>A method annotated with {@code @Find} must return one of the following types:</p>

spec/src/main/asciidoc/repository.asciidoc

@@ -831,7 +831,7 @@ Each automatic query method must be assigned an entity type. The rules for infer
 
 Jakarta Data infers a query based on the parameters of the method. Each parameter must either:
 
-- have exactly the same type and name as a persistent field or property of the entity class, or
+- have exactly the same name as a persistent field or property of the entity class and be of type `T`, `T[]`, or `Iterable<T>` where `T` is the type of the field or property, or
 - be of type `Limit`, `Order`, `PageRequest`, or `Sort`.
 
 Parameter names map parameters to persistent fields. A repository with parameter-based automatic query methods must either:
@@ -851,6 +851,9 @@ For example:
 @Find
 Book bookByIsbn(String isbn);
 
+@Find
+List<Book> booksByIsbn(@By("isbn") String[] isbns);
+
 @Find
 List<Book> booksByYear(Year year, Sort order, Limit limit);