From cd840de94579b0b9829e8bad608e5370f0e6b91b Mon Sep 17 00:00:00 2001 From: Jens Schauder Date: Tue, 29 Oct 2019 14:51:21 +0100 Subject: [PATCH 1/3] DATACMNS-1601 - Prepare branch --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 6a81501ac0..9d4710dfa0 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ org.springframework.data spring-data-commons - 2.3.0.BUILD-SNAPSHOT + 2.3.0.DATACMNS-1601-SNAPSHOT Spring Data Core From c92d98bde6cfb4e6672c82a87f58a4ffaea4bb96 Mon Sep 17 00:00:00 2001 From: Jens Schauder Date: Tue, 29 Oct 2019 15:04:05 +0100 Subject: [PATCH 2/3] DATACMNS-1601 - Improving the JavaDoc of the CrudRepository. Clarifying expectations and guarantees or lack thereof. --- .../data/repository/CrudRepository.java | 25 +++++++++++++------ 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/src/main/java/org/springframework/data/repository/CrudRepository.java b/src/main/java/org/springframework/data/repository/CrudRepository.java index 46133b4b84..080986f027 100644 --- a/src/main/java/org/springframework/data/repository/CrudRepository.java +++ b/src/main/java/org/springframework/data/repository/CrudRepository.java @@ -38,9 +38,11 @@ public interface CrudRepository extends Repository { /** * Saves all given entities. * - * @param entities must not be {@literal null}. - * @return the saved entities; will never be {@literal null}. - * @throws IllegalArgumentException in case the given entity is {@literal null}. + * @param entities must not be {@literal null} nor must it contain {@literal null} + * @return the saved entities; will never be {@literal null}. The returned {@literal Iterable} will have the same size + * as the {@literal Iterable} passed as an argument. + * @throws IllegalArgumentException in case the given {@literal Iterable} or one of its contained entities is + * {@literal null}. */ Iterable saveAll(Iterable entities); @@ -71,9 +73,15 @@ public interface CrudRepository extends Repository { /** * Returns all instances of the type with the given IDs. + *

+ * If some or all ids are not found no entities are returned for these IDs. + *

+ * Note that the order of elements in the result is not guaranteed. * - * @param ids - * @return + * @param ids must not be {@literal null} nor contain any {@literal null} values. + * @return guaranteed to be not {@literal null}. The size will be equal or smaller than that of the argument. + * @throws IllegalArgumentException in case the given {@literal Iterable} or one of its contained entities is + * {@literal null}. */ Iterable findAllById(Iterable ids); @@ -95,7 +103,7 @@ public interface CrudRepository extends Repository { /** * Deletes a given entity. * - * @param entity + * @param entity must not be {@literal null}. * @throws IllegalArgumentException in case the given entity is {@literal null}. */ void delete(T entity); @@ -103,8 +111,9 @@ public interface CrudRepository extends Repository { /** * Deletes the given entities. * - * @param entities - * @throws IllegalArgumentException in case the given {@link Iterable} is {@literal null}. + * @param entities must not be {@literal null}. Must not contain {@literal null} elements + * @throws IllegalArgumentException in case the given {@literal Iterable} or one of its contained entities is + * {@literal null}. */ void deleteAll(Iterable entities); From c127d24f11f4bd0e0a848e562b48dc0013d4953d Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Wed, 30 Oct 2019 09:55:18 +0100 Subject: [PATCH 3/3] DATACMNS-1601 - Polishing. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document throws on save(…). Align documentation for reactive repositories. --- .../data/repository/CrudRepository.java | 23 +++--- .../reactive/ReactiveCrudRepository.java | 41 +++++++---- .../reactive/RxJava2CrudRepository.java | 70 ++++++++++++------- 3 files changed, 82 insertions(+), 52 deletions(-) diff --git a/src/main/java/org/springframework/data/repository/CrudRepository.java b/src/main/java/org/springframework/data/repository/CrudRepository.java index 080986f027..0478ea9061 100644 --- a/src/main/java/org/springframework/data/repository/CrudRepository.java +++ b/src/main/java/org/springframework/data/repository/CrudRepository.java @@ -32,16 +32,17 @@ public interface CrudRepository extends Repository { * * @param entity must not be {@literal null}. * @return the saved entity; will never be {@literal null}. + * @throws IllegalArgumentException in case the given {@code entity} is {@literal null}. */ S save(S entity); /** * Saves all given entities. * - * @param entities must not be {@literal null} nor must it contain {@literal null} + * @param entities must not be {@literal null} nor must it contain {@literal null}. * @return the saved entities; will never be {@literal null}. The returned {@literal Iterable} will have the same size * as the {@literal Iterable} passed as an argument. - * @throws IllegalArgumentException in case the given {@literal Iterable} or one of its contained entities is + * @throws IllegalArgumentException in case the given {@link Iterable entities} or one of its entities is * {@literal null}. */ Iterable saveAll(Iterable entities); @@ -50,7 +51,7 @@ public interface CrudRepository extends Repository { * Retrieves an entity by its id. * * @param id must not be {@literal null}. - * @return the entity with the given id or {@literal Optional#empty()} if none found + * @return the entity with the given id or {@literal Optional#empty()} if none found. * @throws IllegalArgumentException if {@code id} is {@literal null}. */ Optional findById(ID id); @@ -72,23 +73,22 @@ public interface CrudRepository extends Repository { Iterable findAll(); /** - * Returns all instances of the type with the given IDs. + * Returns all instances of the type {@code T} with the given IDs. *

- * If some or all ids are not found no entities are returned for these IDs. + * If some or all ids are not found, no entities are returned for these IDs. *

* Note that the order of elements in the result is not guaranteed. * * @param ids must not be {@literal null} nor contain any {@literal null} values. - * @return guaranteed to be not {@literal null}. The size will be equal or smaller than that of the argument. - * @throws IllegalArgumentException in case the given {@literal Iterable} or one of its contained entities is - * {@literal null}. + * @return guaranteed to be not {@literal null}. The size can be equal or less than the number of given {@code ids}. + * @throws IllegalArgumentException in case the given {@link Iterable ids} or one of its items is {@literal null}. */ Iterable findAllById(Iterable ids); /** * Returns the number of entities available. * - * @return the number of entities + * @return the number of entities. */ long count(); @@ -111,9 +111,8 @@ public interface CrudRepository extends Repository { /** * Deletes the given entities. * - * @param entities must not be {@literal null}. Must not contain {@literal null} elements - * @throws IllegalArgumentException in case the given {@literal Iterable} or one of its contained entities is - * {@literal null}. + * @param entities must not be {@literal null}. Must not contain {@literal null} elements. + * @throws IllegalArgumentException in case the given {@literal entities} or one of its entities is {@literal null}. */ void deleteAll(Iterable entities); diff --git a/src/main/java/org/springframework/data/repository/reactive/ReactiveCrudRepository.java b/src/main/java/org/springframework/data/repository/reactive/ReactiveCrudRepository.java index 24772b5674..6929672f3e 100644 --- a/src/main/java/org/springframework/data/repository/reactive/ReactiveCrudRepository.java +++ b/src/main/java/org/springframework/data/repository/reactive/ReactiveCrudRepository.java @@ -50,7 +50,8 @@ public interface ReactiveCrudRepository extends Repository { * * @param entities must not be {@literal null}. * @return {@link Flux} emitting the saved entities. - * @throws IllegalArgumentException in case the given {@link Iterable} {@code entities} is {@literal null}. + * @throws IllegalArgumentException in case the given {@link Iterable entities} or one of its entities is + * {@literal null}. */ Flux saveAll(Iterable entities); @@ -59,7 +60,7 @@ public interface ReactiveCrudRepository extends Repository { * * @param entityStream must not be {@literal null}. * @return {@link Flux} emitting the saved entities. - * @throws IllegalArgumentException in case the given {@code Publisher} {@code entityStream} is {@literal null}. + * @throws IllegalArgumentException in case the given {@link Publisher entityStream} is {@literal null}. */ Flux saveAll(Publisher entityStream); @@ -77,12 +78,12 @@ public interface ReactiveCrudRepository extends Repository { * * @param id must not be {@literal null}. Uses the first emitted element to perform the find-query. * @return {@link Mono} emitting the entity with the given id or {@link Mono#empty()} if none found. - * @throws IllegalArgumentException in case the given {@link Publisher} {@code id} is {@literal null}. + * @throws IllegalArgumentException in case the given {@link Publisher id} is {@literal null}. */ Mono findById(Publisher id); /** - * Returns whether an entity with the id exists. + * Returns whether an entity with the given {@code id} exists. * * @param id must not be {@literal null}. * @return {@link Mono} emitting {@literal true} if an entity with the given id exists, {@literal false} otherwise. @@ -95,8 +96,8 @@ public interface ReactiveCrudRepository extends Repository { * element to perform the exists-query. * * @param id must not be {@literal null}. - * @return {@link Mono} emitting {@literal true} if an entity with the given id exists, {@literal false} otherwise - * @throws IllegalArgumentException in case the given {@link Publisher} {@code id} is {@literal null}. + * @return {@link Mono} emitting {@literal true} if an entity with the given id exists, {@literal false} otherwise. + * @throws IllegalArgumentException in case the given {@link Publisher id} is {@literal null}. */ Mono existsById(Publisher id); @@ -108,20 +109,29 @@ public interface ReactiveCrudRepository extends Repository { Flux findAll(); /** - * Returns all instances with the given IDs. + * Returns all instances of the type {@code T} with the given IDs. + *

+ * If some or all ids are not found, no entities are returned for these IDs. + *

+ * Note that the order of elements in the result is not guaranteed. * - * @param ids must not be {@literal null}. - * @return {@link Flux} emitting the found entities. - * @throws IllegalArgumentException in case the given {@link Iterable} {@code ids} is {@literal null}. + * @param ids must not be {@literal null} nor contain any {@literal null} values. + * @return {@link Flux} emitting the found entities. The size can be equal or less than the number of given + * {@code ids}. + * @throws IllegalArgumentException in case the given {@link Iterable ids} or one of its items is {@literal null}. */ Flux findAllById(Iterable ids); /** - * Returns all instances of the type with the given IDs supplied by a {@link Publisher}. + * Returns all instances of the type {@code T} with the given IDs supplied by a {@link Publisher}. + *

+ * If some or all ids are not found, no entities are returned for these IDs. + *

+ * Note that the order of elements in the result is not guaranteed. * * @param idStream must not be {@literal null}. * @return {@link Flux} emitting the found entities. - * @throws IllegalArgumentException in case the given {@link Publisher} {@code idStream} is {@literal null}. + * @throws IllegalArgumentException in case the given {@link Publisher idStream} is {@literal null}. */ Flux findAllById(Publisher idStream); @@ -146,7 +156,7 @@ public interface ReactiveCrudRepository extends Repository { * * @param id must not be {@literal null}. * @return {@link Mono} signaling when operation has completed. - * @throws IllegalArgumentException in case the given {@link Publisher} {@code id} is {@literal null}. + * @throws IllegalArgumentException in case the given {@link Publisher id} is {@literal null}. */ Mono deleteById(Publisher id); @@ -164,7 +174,8 @@ public interface ReactiveCrudRepository extends Repository { * * @param entities must not be {@literal null}. * @return {@link Mono} signaling when operation has completed. - * @throws IllegalArgumentException in case the given {@link Iterable} {@code entities} is {@literal null}. + * @throws IllegalArgumentException in case the given {@link Iterable entities} or one of its entities is + * {@literal null}. */ Mono deleteAll(Iterable entities); @@ -173,7 +184,7 @@ public interface ReactiveCrudRepository extends Repository { * * @param entityStream must not be {@literal null}. * @return {@link Mono} signaling when operation has completed. - * @throws IllegalArgumentException in case the given {@link Publisher} {@code entityStream} is {@literal null}. + * @throws IllegalArgumentException in case the given {@link Publisher entityStream} is {@literal null}. */ Mono deleteAll(Publisher entityStream); diff --git a/src/main/java/org/springframework/data/repository/reactive/RxJava2CrudRepository.java b/src/main/java/org/springframework/data/repository/reactive/RxJava2CrudRepository.java index 9489060424..7e005f498c 100644 --- a/src/main/java/org/springframework/data/repository/reactive/RxJava2CrudRepository.java +++ b/src/main/java/org/springframework/data/repository/reactive/RxJava2CrudRepository.java @@ -42,7 +42,8 @@ public interface RxJava2CrudRepository extends Repository { * entity instance completely. * * @param entity must not be {@literal null}. - * @return the saved entity. + * @return {@link Single} emitting the saved entity. + * @throws IllegalArgumentException in case the given {@code entity} is {@literal null}. */ Single save(S entity); @@ -50,8 +51,9 @@ public interface RxJava2CrudRepository extends Repository { * Saves all given entities. * * @param entities must not be {@literal null}. - * @return the saved entities. - * @throws IllegalArgumentException in case the given entity is {@literal null}. + * @return {@link Flowable} emitting the saved entities. + * @throws IllegalArgumentException in case the given {@link Iterable entities} or one of its entities is + * {@literal null}. */ Flowable saveAll(Iterable entities); @@ -59,8 +61,8 @@ public interface RxJava2CrudRepository extends Repository { * Saves all given entities. * * @param entityStream must not be {@literal null}. - * @return the saved entities. - * @throws IllegalArgumentException in case the given {@code Publisher} is {@literal null}. + * @return {@link Flowable} emitting the saved entities. + * @throws IllegalArgumentException in case the given {@link Flowable entityStream} is {@literal null}. */ Flowable saveAll(Flowable entityStream); @@ -68,26 +70,26 @@ public interface RxJava2CrudRepository extends Repository { * Retrieves an entity by its id. * * @param id must not be {@literal null}. - * @return the entity with the given id or {@link Maybe#empty()} if none found. - * @throws IllegalArgumentException if {@code id} is {@literal null}. + * @return {@link Maybe} emitting the entity with the given id or {@link Maybe#empty()} if none found. + * @throws IllegalArgumentException in case the given {@code id} is {@literal null}. */ Maybe findById(ID id); /** * Retrieves an entity by its id supplied by a {@link Single}. * - * @param id must not be {@literal null}. - * @return the entity with the given id or {@link Maybe#empty()} if none found. - * @throws IllegalArgumentException if {@code id} is {@literal null}. + * @param id must not be {@literal null}. Uses the first emitted element to perform the find-query. + * @return {@link Maybe} emitting the entity with the given id or {@link Maybe#empty()} if none found. + * @throws IllegalArgumentException in case the given {@link Single id} is {@literal null}. */ Maybe findById(Single id); /** - * Returns whether an entity with the given id exists. + * Returns whether an entity with the given {@code id} exists. * * @param id must not be {@literal null}. - * @return {@literal true} if an entity with the given id exists, {@literal false} otherwise. - * @throws IllegalArgumentException if {@code id} is {@literal null}. + * @return {@link Single} emitting {@literal true} if an entity with the given id exists, {@literal false} otherwise. + * @throws IllegalArgumentException in case the given {@code id} is {@literal null}. */ Single existsById(ID id); @@ -95,38 +97,49 @@ public interface RxJava2CrudRepository extends Repository { * Returns whether an entity with the given id, supplied by a {@link Single}, exists. * * @param id must not be {@literal null}. - * @return {@literal true} if an entity with the given id exists, {@literal false} otherwise. - * @throws IllegalArgumentException if {@code id} is {@literal null} + * @return {@link Single} emitting {@literal true} if an entity with the given id exists, {@literal false} otherwise. + * @throws IllegalArgumentException in case the given {@link Single id} is {@literal null}. */ Single existsById(Single id); /** * Returns all instances of the type. * - * @return all entities. + * @return {@link Flowable} emitting all entities. */ Flowable findAll(); /** - * Returns all instances of the type with the given IDs. + * Returns all instances of the type {@code T} with the given IDs. + *

+ * If some or all ids are not found, no entities are returned for these IDs. + *

+ * Note that the order of elements in the result is not guaranteed. * - * @param ids must not be {@literal null}. - * @return the found entities. + * @param ids must not be {@literal null} nor contain any {@literal null} values. + * @return {@link Flowable} emitting the found entities. The size can be equal or less than the number of given + * {@code ids}. + * @throws IllegalArgumentException in case the given {@link Iterable ids} or one of its items is {@literal null}. */ Flowable findAllById(Iterable ids); /** - * Returns all instances of the type with the given IDs. + * Returns all instances of the type {@code T} with the given IDs supplied by a {@link Flowable}. + *

+ * If some or all ids are not found, no entities are returned for these IDs. + *

+ * Note that the order of elements in the result is not guaranteed. * * @param idStream must not be {@literal null}. - * @return the found entities. + * @return {@link Flowable} emitting the found entities. + * @throws IllegalArgumentException in case the given {@link Flowable idStream} is {@literal null}. */ Flowable findAllById(Flowable idStream); /** * Returns the number of entities available. * - * @return the number of entities. + * @return {@link Single} emitting the number of entities. */ Single count(); @@ -134,6 +147,7 @@ public interface RxJava2CrudRepository extends Repository { * Deletes the entity with the given id. * * @param id must not be {@literal null}. + * @return {@link Completable} signaling when operation has completed. * @throws IllegalArgumentException in case the given {@code id} is {@literal null}. */ Completable deleteById(ID id); @@ -142,6 +156,7 @@ public interface RxJava2CrudRepository extends Repository { * Deletes a given entity. * * @param entity must not be {@literal null}. + * @return {@link Completable} signaling when operation has completed. * @throws IllegalArgumentException in case the given entity is {@literal null}. */ Completable delete(T entity); @@ -150,20 +165,25 @@ public interface RxJava2CrudRepository extends Repository { * Deletes the given entities. * * @param entities must not be {@literal null}. - * @throws IllegalArgumentException in case the given {@link Iterable} is {@literal null}. + * @return {@link Completable} signaling when operation has completed. + * @throws IllegalArgumentException in case the given {@link Iterable entities} or one of its entities is + * {@literal null}. */ Completable deleteAll(Iterable entities); /** - * Deletes the given entities. + * Deletes the given entities supplied by a {@link Flowable}. * * @param entityStream must not be {@literal null}. - * @throws IllegalArgumentException in case the given {@link Flowable} is {@literal null}. + * @return {@link Completable} signaling when operation has completed. + * @throws IllegalArgumentException in case the given {@link Flowable entityStream} is {@literal null}. */ Completable deleteAll(Flowable entityStream); /** * Deletes all entities managed by the repository. + * + * @return {@link Completable} signaling when operation has completed. */ Completable deleteAll(); }