diff --git a/src/main/java/org/springframework/data/repository/CrudRepository.java b/src/main/java/org/springframework/data/repository/CrudRepository.java index e6b6e776c..d7ccd1f40 100644 --- a/src/main/java/org/springframework/data/repository/CrudRepository.java +++ b/src/main/java/org/springframework/data/repository/CrudRepository.java @@ -36,9 +36,9 @@ 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 {@literal entity} is {@literal null}. - * @throws OptimisticLockingFailureException when the entity has a version attribute with a different value from that - * found in the persistence store. This also occurs when the entity which has a version attribute does no - * longer exist in the database. + * @throws OptimisticLockingFailureException when the entity uses optimistic locking and has a version attribute with + * a different value from that found in the persistence store. Also thrown if the entity is assumed to be + * present but does not exist in the database. */ S save(S entity); @@ -50,9 +50,9 @@ public interface CrudRepository extends Repository { * as the {@literal Iterable} passed as an argument. * @throws IllegalArgumentException in case the given {@link Iterable entities} or one of its entities is * {@literal null}. - * @throws OptimisticLockingFailureException when at least one entity has a version attribute with a different value from that - * found in the persistence store. This also occurs when the entity which has a version attribute does no - * longer exist in the database. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version + * attribute with a different value from that found in the persistence store. Also thrown if at least one + * entity is assumed to be present but does not exist in the database. */ Iterable saveAll(Iterable entities); @@ -105,8 +105,7 @@ public interface CrudRepository extends Repository { /** * Deletes the entity with the given id. *

- * When no entity with the given id is available, no exception will be thrown. - *

+ * If the entity is not found in the persistence store it is silently ignored. * * @param id must not be {@literal null}. * @throws IllegalArgumentException in case the given {@literal id} is {@literal null} @@ -118,18 +117,16 @@ public interface CrudRepository extends Repository { * * @param entity must not be {@literal null}. * @throws IllegalArgumentException in case the given entity is {@literal null}. - * @throws OptimisticLockingFailureException when the entity has a version attribute with a different value from that - * found in the persistence store. This also occurs when the entity which has a version attribute does no - * longer exist in the database. + * @throws OptimisticLockingFailureException when the entity uses optimistic locking and has a version attribute with + * a different value from that found in the persistence store. Also thrown if the entity is assumed to be + * present but does not exist in the database. */ void delete(T entity); /** * Deletes all instances of the type {@code T} with the given IDs. *

- * When some or all of the ids aren't found in the persistence store this is silently ignored and no exception - * is thrown. - *

+ * Entities that aren't found in the persistence store are silently ignored. * * @param ids must not be {@literal null}. Must not contain {@literal null} elements. * @throws IllegalArgumentException in case the given {@literal ids} or one of its elements is {@literal null}. @@ -142,9 +139,9 @@ public interface CrudRepository extends Repository { * * @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}. - * @throws OptimisticLockingFailureException when at least one of the entities has a version attribute with a - * different value from that found in the persistence store. This also occurs when the entity which has a - * version attribute does no longer exist in the database. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version + * attribute with a different value from that found in the persistence store. Also thrown if at least one + * entity is assumed to be present but does not exist in the database. */ void deleteAll(Iterable entities); diff --git a/src/main/java/org/springframework/data/repository/ListCrudRepository.java b/src/main/java/org/springframework/data/repository/ListCrudRepository.java index 676d0afe7..00a7fe684 100644 --- a/src/main/java/org/springframework/data/repository/ListCrudRepository.java +++ b/src/main/java/org/springframework/data/repository/ListCrudRepository.java @@ -17,6 +17,8 @@ package org.springframework.data.repository; import java.util.List; +import org.springframework.dao.OptimisticLockingFailureException; + /** * Interface for generic CRUD operations on a repository for a specific type. This an extension to * {@link CrudRepository} returning {@link List} instead of {@link Iterable} where applicable. @@ -36,6 +38,9 @@ public interface ListCrudRepository extends CrudRepository { * as the {@literal Iterable} passed as an argument. * @throws IllegalArgumentException in case the given {@link Iterable entities} or one of its entities is * {@literal null}. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version + * attribute with a different value from that found in the persistence store. Also thrown if at least one + * entity is assumed to be present but does not exist in the database. */ List saveAll(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 68d74ab03..461582398 100644 --- a/src/main/java/org/springframework/data/repository/reactive/ReactiveCrudRepository.java +++ b/src/main/java/org/springframework/data/repository/reactive/ReactiveCrudRepository.java @@ -19,6 +19,8 @@ import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; import org.reactivestreams.Publisher; + +import org.springframework.dao.OptimisticLockingFailureException; import org.springframework.data.repository.NoRepositoryBean; import org.springframework.data.repository.Repository; @@ -52,6 +54,9 @@ public interface ReactiveCrudRepository extends Repository { * @param entity must not be {@literal null}. * @return {@link Mono} emitting the saved entity. * @throws IllegalArgumentException in case the given {@literal entity} is {@literal null}. + * @throws OptimisticLockingFailureException when the entity uses optimistic locking and has a version attribute with + * a different value from that found in the persistence store. Also thrown if the entity is assumed to be + * present but does not exist in the database. */ Mono save(S entity); @@ -62,6 +67,9 @@ public interface ReactiveCrudRepository extends Repository { * @return {@link Flux} emitting the saved entities. * @throws IllegalArgumentException in case the given {@link Iterable entities} or one of its entities is * {@literal null}. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version + * attribute with a different value from that found in the persistence store. Also thrown if at least one + * entity is assumed to be present but does not exist in the database. */ Flux saveAll(Iterable entities); @@ -71,6 +79,9 @@ 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 {@link Publisher entityStream} is {@literal null}. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version + * attribute with a different value from that found in the persistence store. Also thrown if at least one + * entity is assumed to be present but does not exist in the database. */ Flux saveAll(Publisher entityStream); @@ -154,6 +165,8 @@ public interface ReactiveCrudRepository extends Repository { /** * Deletes the entity with the given id. + *

+ * If the entity is not found in the persistence store it is silently ignored. * * @param id must not be {@literal null}. * @return {@link Mono} signaling when operation has completed. @@ -163,6 +176,8 @@ public interface ReactiveCrudRepository extends Repository { /** * Deletes the entity with the given id supplied by a {@link Publisher}. + *

+ * If the entity is not found in the persistence store it is silently ignored. * * @param id must not be {@literal null}. * @return {@link Mono} signaling when operation has completed. @@ -176,11 +191,16 @@ public interface ReactiveCrudRepository extends Repository { * @param entity must not be {@literal null}. * @return {@link Mono} signaling when operation has completed. * @throws IllegalArgumentException in case the given entity is {@literal null}. + * @throws OptimisticLockingFailureException when the entity uses optimistic locking and has a version attribute with + * a different value from that found in the persistence store. Also thrown if the entity is assumed to be + * present but does not exist in the database. */ Mono delete(T entity); /** * Deletes all instances of the type {@code T} with the given IDs. + *

+ * Entities that aren't found in the persistence store are silently ignored. * * @param ids must not be {@literal null}. * @return {@link Mono} signaling when operation has completed. @@ -197,6 +217,9 @@ public interface ReactiveCrudRepository extends Repository { * @return {@link Mono} signaling when operation has completed. * @throws IllegalArgumentException in case the given {@link Iterable entities} or one of its entities is * {@literal null}. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version + * attribute with a different value from that found in the persistence store. Also thrown if at least one + * entity is assumed to be present but does not exist in the database. */ Mono deleteAll(Iterable entities); @@ -206,6 +229,9 @@ 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 entityStream} is {@literal null}. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version + * attribute with a different value from that found in the persistence store. Also thrown if at least one + * entity is assumed to be present but does not exist in the database. */ Mono deleteAll(Publisher entityStream); diff --git a/src/main/java/org/springframework/data/repository/reactive/RxJava3CrudRepository.java b/src/main/java/org/springframework/data/repository/reactive/RxJava3CrudRepository.java index f5ac523be..3b80db743 100644 --- a/src/main/java/org/springframework/data/repository/reactive/RxJava3CrudRepository.java +++ b/src/main/java/org/springframework/data/repository/reactive/RxJava3CrudRepository.java @@ -20,6 +20,7 @@ import io.reactivex.rxjava3.core.Flowable; import io.reactivex.rxjava3.core.Maybe; import io.reactivex.rxjava3.core.Single; +import org.springframework.dao.OptimisticLockingFailureException; import org.springframework.data.repository.NoRepositoryBean; import org.springframework.data.repository.Repository; @@ -27,10 +28,13 @@ import org.springframework.data.repository.Repository; * Interface for generic CRUD operations on a repository for a specific type. This repository follows reactive paradigms * and uses RxJava 3 types. *

- * Save and delete operations with entities that have a version attribute trigger an {@code onError} with a {@link org.springframework.dao.OptimisticLockingFailureException} when they encounter a different version value in the persistence store than in the entity passed as an argument. + * Save and delete operations with entities that have a version attribute trigger an {@code onError} with a + * {@link org.springframework.dao.OptimisticLockingFailureException} when they encounter a different version value in + * the persistence store than in the entity passed as an argument. *

*

- * Other delete operations that only receive ids or entities without version attribute do not trigger an error when no matching data is found in the persistence store. + * Other delete operations that only receive ids or entities without version attribute do not trigger an error when no + * matching data is found in the persistence store. *

* * @author Mark Paluch @@ -50,6 +54,9 @@ public interface RxJava3CrudRepository extends Repository { * @param entity must not be {@literal null}. * @return {@link Single} emitting the saved entity. * @throws IllegalArgumentException in case the given {@literal entity} is {@literal null}. + * @throws OptimisticLockingFailureException when the entity uses optimistic locking and has a version attribute with + * a different value from that found in the persistence store. Also thrown if the entity is assumed to be + * present but does not exist in the database. */ Single save(S entity); @@ -60,6 +67,9 @@ public interface RxJava3CrudRepository extends Repository { * @return {@link Flowable} emitting the saved entities. * @throws IllegalArgumentException in case the given {@link Iterable entities} or one of its entities is * {@literal null}. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version + * attribute with a different value from that found in the persistence store. Also thrown if at least one + * entity is assumed to be present but does not exist in the database. */ Flowable saveAll(Iterable entities); @@ -69,6 +79,9 @@ public interface RxJava3CrudRepository extends Repository { * @param entityStream must not be {@literal null}. * @return {@link Flowable} emitting the saved entities. * @throws IllegalArgumentException in case the given {@link Flowable entityStream} is {@literal null}. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version + * attribute with a different value from that found in the persistence store. Also thrown if at least one + * entity is assumed to be present but does not exist in the database. */ Flowable saveAll(Flowable entityStream); @@ -151,6 +164,8 @@ public interface RxJava3CrudRepository extends Repository { /** * Deletes the entity with the given id. + *

+ * If the entity is not found in the persistence store it is silently ignored. * * @param id must not be {@literal null}. * @return {@link Completable} signaling when operation has completed. @@ -164,11 +179,16 @@ public interface RxJava3CrudRepository extends Repository { * @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}. + * @throws OptimisticLockingFailureException when the entity uses optimistic locking and has a version attribute with + * a different value from that found in the persistence store. Also thrown if the entity is assumed to be + * present but does not exist in the database. */ Completable delete(T entity); /** * Deletes all instances of the type {@code T} with the given IDs. + *

+ * Entities that aren't found in the persistence store are silently ignored. * * @param ids must not be {@literal null}. * @return {@link Completable} signaling when operation has completed. @@ -185,6 +205,9 @@ public interface RxJava3CrudRepository extends Repository { * @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}. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version + * attribute with a different value from that found in the persistence store. Also thrown if at least one + * entity is assumed to be present but does not exist in the database. */ Completable deleteAll(Iterable entities); @@ -194,6 +217,9 @@ public interface RxJava3CrudRepository extends Repository { * @param entityStream must not be {@literal null}. * @return {@link Completable} signaling when operation has completed. * @throws IllegalArgumentException in case the given {@link Flowable entityStream} is {@literal null}. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version + * attribute with a different value from that found in the persistence store. Also thrown if at least one + * entity is assumed to be present but does not exist in the database. */ Completable deleteAll(Flowable entityStream); diff --git a/src/main/kotlin/org/springframework/data/repository/kotlin/CoroutineCrudRepository.kt b/src/main/kotlin/org/springframework/data/repository/kotlin/CoroutineCrudRepository.kt index 0b86a557a..50a3547ad 100644 --- a/src/main/kotlin/org/springframework/data/repository/kotlin/CoroutineCrudRepository.kt +++ b/src/main/kotlin/org/springframework/data/repository/kotlin/CoroutineCrudRepository.kt @@ -16,6 +16,7 @@ package org.springframework.data.repository.kotlin import kotlinx.coroutines.flow.Flow +import org.springframework.dao.OptimisticLockingFailureException import org.springframework.data.repository.NoRepositoryBean import org.springframework.data.repository.Repository import reactor.core.publisher.Mono @@ -44,7 +45,9 @@ interface CoroutineCrudRepository : Repository { * * @param entity must not be null. * @return the saved entity. - * @throws IllegalArgumentException in case the given entity is null. + * @throws IllegalArgumentException in case the given entity is `null`. + * @throws OptimisticLockingFailureException when the entity uses optimistic locking and has a version attribute with a different value from that + * found in the persistence store. Also thrown if the entity is assumed to be present but does not exist in the database. */ suspend fun save(entity: S): T @@ -54,7 +57,9 @@ interface CoroutineCrudRepository : Repository { * @param entities must not be null. * @return [Flow] emitting the saved entities. * @throws IllegalArgumentException in case the given [entities][Flow] or one of its entities is - * null. + * `null`. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version attribute with a different value from that + * found in the persistence store. Also thrown if at least one entity is assumed to be present but does not exist in the database. */ fun saveAll(entities: Iterable): Flow @@ -63,25 +68,25 @@ interface CoroutineCrudRepository : Repository { * * @param entityStream must not be null. * @return [Flow] emitting the saved entities. - * @throws IllegalArgumentException in case the given [entityStream][Flow] is null. + * @throws IllegalArgumentException in case the given [entityStream][Flow] is `null`. */ fun saveAll(entityStream: Flow): Flow /** * Retrieves an entity by its id. * - * @param id must not be null. + * @param id must not be `null`. * @return [Mono] emitting the entity with the given id or empty if none found. - * @throws IllegalArgumentException in case the given id is null. + * @throws IllegalArgumentException in case the given id is `null`. */ suspend fun findById(id: ID): T? /** * Returns whether an entity with the given id exists. * - * @param id must not be null. + * @param id must not be `null`. * @return true if an entity with the given id exists, false otherwise. - * @throws IllegalArgumentException in case the given id is null. + * @throws IllegalArgumentException in case the given id is `null`. */ suspend fun existsById(id: ID): Boolean @@ -97,10 +102,10 @@ interface CoroutineCrudRepository : Repository { * 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 null nor contain any null values. + * @param ids must not be `null` nor contain any `null` values. * @return [Flow] emitting the found entities. The size can be equal or less than the number of given * ids. - * @throws IllegalArgumentException in case the given [ids][Iterable] or one of its items is null. + * @throws IllegalArgumentException in case the given [ids][Iterable] or one of its items is `null`. */ fun findAllById(ids: Iterable): Flow @@ -109,41 +114,47 @@ interface CoroutineCrudRepository : Repository { * 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 null nor contain any null values. + * @param ids must not be `null` nor contain any `null` values. * @return [Flow] emitting the found entities. The size can be equal or less than the number of given * ids. - * @throws IllegalArgumentException in case the given [ids][Iterable] or one of its items is null. + * @throws IllegalArgumentException in case the given [ids][Iterable] or one of its items is `null`. */ fun findAllById(ids: Flow): Flow /** * Returns the number of entities available. * - * @return number of entities. + * @return number of entities. */ suspend fun count(): Long /** * Deletes the entity with the given id. + *

+ * If the entity is not found in the persistence store it is silently ignored. * - * @param id must not be null. - * @throws IllegalArgumentException in case the given id is null. + * @param id must not be `null`. + * @throws IllegalArgumentException in case the given id is `null`. */ suspend fun deleteById(id: ID) /** * Deletes a given entity. * - * @param entity must not be null. - * @throws IllegalArgumentException in case the given entity is null. + * @param entity must not be `null`. + * @throws IllegalArgumentException in case the given entity is `null`. + * @throws OptimisticLockingFailureException when the entity uses optimistic locking and has a version attribute with a different value from that + * found in the persistence store. Also thrown if the entity is assumed to be present but does not exist in the database. */ suspend fun delete(entity: T) /** * Deletes all instances of the type {@code T} with the given IDs. + *

+ * Entities that aren't found in the persistence store are silently ignored. * - * @param ids must not be null nor contain any null values. - * @throws IllegalArgumentException in case the given [ids][Iterable] or one of its items is null. + * @param ids must not be `null` nor contain any `null` values. + * @throws IllegalArgumentException in case the given [ids][Iterable] or one of its items is `null`. * @since 2.5 */ suspend fun deleteAllById(ids: Iterable) @@ -151,9 +162,9 @@ interface CoroutineCrudRepository : Repository { /** * Deletes the given entities. * - * @param entities must not be null. + * @param entities must not be `null`. * @throws IllegalArgumentException in case the given [entities][Iterable] or one of its entities is - * null. + * `null`. */ suspend fun deleteAll(entities: Iterable) @@ -161,7 +172,9 @@ interface CoroutineCrudRepository : Repository { * Deletes all given entities. * * @param entityStream must not be null. - * @throws IllegalArgumentException in case the given [entityStream][Flow] is null. + * @throws IllegalArgumentException in case the given [entityStream][Flow] is `null`. + * @throws OptimisticLockingFailureException when at least one entity uses optimistic locking and has a version attribute with a different value from that + * found in the persistence store. Also thrown if at least one entity is assumed to be present but does not exist in the database. */ suspend fun deleteAll(entityStream: Flow)