From 18973f9789fd0b535396aa983287d893ef518d7f Mon Sep 17 00:00:00 2001 From: Gavin King Date: Sun, 17 Mar 2024 23:55:56 +0100 Subject: [PATCH 1/3] 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 --- .../java/jakarta/data/repository/BasicRepository.java | 6 ++++-- api/src/main/java/jakarta/data/repository/Delete.java | 11 ++++++----- api/src/main/java/jakarta/data/repository/Find.java | 11 ++++++++--- spec/src/main/asciidoc/repository.asciidoc | 5 ++++- 4 files changed, 22 insertions(+), 11 deletions(-) diff --git a/api/src/main/java/jakarta/data/repository/BasicRepository.java b/api/src/main/java/jakarta/data/repository/BasicRepository.java index d826e7af3..eca018d7c 100644 --- a/api/src/main/java/jakarta/data/repository/BasicRepository.java +++ b/api/src/main/java/jakarta/data/repository/BasicRepository.java @@ -190,7 +190,8 @@ public interface BasicRepository extends DataRepository { * ids. * @throws NullPointerException in case the given {@link Iterable ids} or one of its items is {@code null}. */ - Stream findByIdIn(Iterable ids); + @Find + Stream findByIdIn(@By(ID) Iterable ids); /** * Deletes the entity with the given Id. @@ -224,7 +225,8 @@ public interface BasicRepository extends DataRepository { * @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 ids); + @Delete + void deleteByIdIn(@By(ID) Iterable ids); /** * Deletes the given entities. Deletion of each entity is performed by matching the unique identifier, diff --git a/api/src/main/java/jakarta/data/repository/Delete.java b/api/src/main/java/jakarta/data/repository/Delete.java index d23cc9ed0..9050a8ae3 100644 --- a/api/src/main/java/jakarta/data/repository/Delete.java +++ b/api/src/main/java/jakarta/data/repository/Delete.java @@ -63,9 +63,10 @@ *

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} 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. *

*

For example, consider an interface representing a garage:

* 
@@ -76,10 +77,10 @@
  *     void unparkAll();
  *
  *     {@code @Delete}
- *     void unpark(String registration);
+ *     void unpark(String[] registration);
  * }
  *
- *

Here,{@code unparkAll()} deletes every {@code Car}, while {@code unpark(String)} deletes any {@code Car} with a + *

Here,{@code unparkAll()} deletes every {@code Car}, while {@code unpark(String)} deletes every {@code Car} with a * matching value of its {@code registration} field. *

*

An automatic query method annotated {@code Delete} removes every record which satisfies the parameter-based diff --git a/api/src/main/java/jakarta/data/repository/Find.java b/api/src/main/java/jakarta/data/repository/Find.java index dbc12de80..56f6ec26b 100644 --- a/api/src/main/java/jakarta/data/repository/Find.java +++ b/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: *

*
    - *
  • 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
    • + *
  • 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} + * where {@code T} is the type of the field or property, or
    • *
  • be of type {@link jakarta.data.Limit}, {@link jakarta.data.Sort}, {@link jakarta.data.Order}, or * {@link jakarta.data.page.PageRequest}.
    • *
@@ -49,10 +50,14 @@ * interface Garage { * {@code @Find} * {@code List} getCarsWithModel(@By("model") String model); + * + * {@code @Find} + * {@code List} getCarsWithYearIn(@By("modelYear") int[] years); * } * *

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. *

* *

A method annotated with {@code @Find} must return one of the following types:

diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc index 136ae221b..958a044bb 100644 --- a/spec/src/main/asciidoc/repository.asciidoc +++ b/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` 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 booksByIsbn(@By("isbn") String[] isbns); + @Find List booksByYear(Year year, Sort order, Limit limit); From ef6e8bed323f0020807cab54a28a84e9bef4bc80 Mon Sep 17 00:00:00 2001 From: Gavin King Date: Mon, 18 Mar 2024 11:57:57 +0100 Subject: [PATCH 2/3] go with List rather than Iterable because Iterable is just a PITA to deal with --- api/src/main/java/jakarta/data/repository/Delete.java | 2 +- api/src/main/java/jakarta/data/repository/Find.java | 4 ++-- spec/src/main/asciidoc/repository.asciidoc | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api/src/main/java/jakarta/data/repository/Delete.java b/api/src/main/java/jakarta/data/repository/Delete.java index 9050a8ae3..d37c340fd 100644 --- a/api/src/main/java/jakarta/data/repository/Delete.java +++ b/api/src/main/java/jakarta/data/repository/Delete.java @@ -65,7 +65,7 @@ * 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 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} where {@code T} is the type of the field or property. Parameters + * type {@code T}, {@code T[]}, or {@code List} 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. *

*

For example, consider an interface representing a garage:

diff --git a/api/src/main/java/jakarta/data/repository/Find.java b/api/src/main/java/jakarta/data/repository/Find.java index 56f6ec26b..eb0c95fd1 100644 --- a/api/src/main/java/jakarta/data/repository/Find.java +++ b/api/src/main/java/jakarta/data/repository/Find.java @@ -34,8 +34,8 @@ *

*
    *
  • 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} - * where {@code T} is the type of the field or property, or
    • + * persistent field or property of the entity class and be of type {@code T}, {@code T[]}, or {@code List} where + * {@code T} is the type of the field or property, or *
  • be of type {@link jakarta.data.Limit}, {@link jakarta.data.Sort}, {@link jakarta.data.Order}, or * {@link jakarta.data.page.PageRequest}.
    • *
diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc index 958a044bb..de1c4f385 100644 --- a/spec/src/main/asciidoc/repository.asciidoc +++ b/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 name as a persistent field or property of the entity class and be of type `T`, `T[]`, or `Iterable` where `T` is the type of the field or property, or +- have exactly the same name as a persistent field or property of the entity class and be of type `T`, `T[]`, or `List` 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: From f32d2464d132e1b723ff8c3a51eac9a7b45df965 Mon Sep 17 00:00:00 2001 From: Gavin King Date: Mon, 18 Mar 2024 12:42:47 +0100 Subject: [PATCH 3/3] update BasicRepository to reflect change to List --- .../main/java/jakarta/data/repository/BasicRepository.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/main/java/jakarta/data/repository/BasicRepository.java b/api/src/main/java/jakarta/data/repository/BasicRepository.java index eca018d7c..3b1984431 100644 --- a/api/src/main/java/jakarta/data/repository/BasicRepository.java +++ b/api/src/main/java/jakarta/data/repository/BasicRepository.java @@ -191,7 +191,7 @@ public interface BasicRepository extends DataRepository { * @throws NullPointerException in case the given {@link Iterable ids} or one of its items is {@code null}. */ @Find - Stream findByIdIn(@By(ID) Iterable ids); + Stream findByIdIn(@By(ID) List ids); /** * Deletes the entity with the given Id. @@ -226,7 +226,7 @@ public interface BasicRepository extends DataRepository { * @throws NullPointerException when the iterable is {@code null} or contains {@code null} elements. */ @Delete - void deleteByIdIn(@By(ID) Iterable ids); + void deleteByIdIn(@By(ID) List ids); /** * Deletes the given entities. Deletion of each entity is performed by matching the unique identifier,