Clarify behaviour of when save or delete operations result in a NOOP.

Behaviour of implementing modules need to adapt to the new clarification.

Closes #2651
Original pull request #2673

Author: schauder

src/main/java/org/springframework/data/repository/CrudRepository.java

@@ -17,6 +17,8 @@
 
 import java.util.Optional;
 
+import org.springframework.dao.OptimisticLockingFailureException;
+
 /**
  * Interface for generic CRUD operations on a repository for a specific type.
  *
@@ -34,6 +36,9 @@ public interface CrudRepository<T, ID> extends Repository<T, ID> {
 	 * @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.
 	 */
 	<S extends T> S save(S entity);
 
@@ -45,6 +50,9 @@ public interface CrudRepository<T, ID> extends Repository<T, ID> {
 	 *         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.
 	 */
 	<S extends T> Iterable<S> saveAll(Iterable<S> entities);
 
@@ -96,6 +104,9 @@ public interface CrudRepository<T, ID> extends Repository<T, ID> {
 
 	/**
 	 * Deletes the entity with the given id.
+	 * <p>
+	 * When no entity with the given id is available, <b>no</b> exception will be thrown.
+	 * </p>
 	 *
 	 * @param id must not be {@literal null}.
 	 * @throws IllegalArgumentException in case the given {@literal id} is {@literal null}
@@ -107,11 +118,18 @@ public interface CrudRepository<T, ID> extends Repository<T, ID> {
 	 *
 	 * @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.
 	 */
 	void delete(T entity);
 
 	/**
 	 * Deletes all instances of the type {@code T} with the given IDs.
+	 * <p>
+	 * When some or all of the ids aren't found in the persistence store this is silently ignored and <b>no</b> exception
+	 * is thrown.
+	 * </p>
 	 *
 	 * @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}.
@@ -124,6 +142,9 @@ public interface CrudRepository<T, ID> extends Repository<T, ID> {
 	 *
 	 * @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.
 	 */
 	void deleteAll(Iterable<? extends T> entities);
 

src/main/java/org/springframework/data/repository/reactive/ReactiveCrudRepository.java

@@ -25,6 +25,15 @@
 /**
  * Interface for generic CRUD operations on a repository for a specific type. This repository follows reactive paradigms
  * and uses Project Reactor types which are built on top of Reactive Streams.
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
  *
  * @author Mark Paluch
  * @author Christph Strobl

src/main/java/org/springframework/data/repository/reactive/RxJava3CrudRepository.java

@@ -26,6 +26,12 @@
 /**
  * Interface for generic CRUD operations on a repository for a specific type. This repository follows reactive paradigms
  * and uses RxJava 3 types.
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
  *
  * @author Mark Paluch
  * @since 2.4

src/main/kotlin/org/springframework/data/repository/kotlin/CoroutineCrudRepository.kt

@@ -22,6 +22,13 @@ import reactor.core.publisher.Mono
 
 /**
  * Interface for generic CRUD operations using Kotlin Coroutines on a repository for a specific type.
+ * <p>
+ * Save and delete operations with entities that have a version attribute throw 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.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+
  *
  * @author Mark Paluch
  * @author Christoph Strobl
@@ -86,7 +93,7 @@ interface CoroutineCrudRepository<T, ID> : Repository<T, ID> {
 	fun findAll(): Flow<T>
 
 	/**
-	 * Returns all instances of the type `T` 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.
 	 *
@@ -98,7 +105,7 @@ interface CoroutineCrudRepository<T, ID> : Repository<T, ID> {
 	fun findAllById(ids: Iterable<ID>): Flow<T>
 
 	/**
-	 * Returns all instances of the type `T` 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.
 	 *
@@ -133,7 +140,7 @@ interface CoroutineCrudRepository<T, ID> : Repository<T, ID> {
 	suspend fun delete(entity: T)
 
 	/**
-	 * Deletes all instances of the type `T` with the given IDs.
+	 * Deletes all instances of the type {@code T} with the given IDs.
 	 *
 	 * @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.