Polishing.

Update Kotlin, Reactive and List repository variant documentation.

See #2651
Original pull request: #2673.

Author: mp911de

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

@@ -36,9 +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.
+	 * @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 extends T> S save(S entity);
 
@@ -50,9 +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.
+	 * @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.
 	 */
 	<S extends T> Iterable<S> saveAll(Iterable<S> entities);
 
@@ -105,8 +105,7 @@ 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>
+	 * 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<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.
+	 * @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.
 	 * <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>
+	 * 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<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.
+	 * @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<? extends T> entities);
 

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

@@ -17,6 +17,8 @@
 
 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<T, ID> extends CrudRepository<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 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.
 	 */
 	<S extends T> List<S> saveAll(Iterable<S> entities);
 

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

@@ -19,6 +19,8 @@
 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<T, ID> extends Repository<T, ID> {
 	 * @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.
 	 */
 	<S extends T> Mono<S> save(S entity);
 
@@ -62,6 +67,9 @@ public interface ReactiveCrudRepository<T, ID> extends Repository<T, ID> {
 	 * @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.
 	 */
 	<S extends T> Flux<S> saveAll(Iterable<S> entities);
 
@@ -71,6 +79,9 @@ public interface ReactiveCrudRepository<T, ID> extends Repository<T, ID> {
 	 * @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.
 	 */
 	<S extends T> Flux<S> saveAll(Publisher<S> entityStream);
 
@@ -154,6 +165,8 @@ public interface ReactiveCrudRepository<T, ID> extends Repository<T, ID> {
 
 	/**
 	 * Deletes the entity with the given id.
+	 * <p>
+	 * 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<T, ID> extends Repository<T, ID> {
 
 	/**
 	 * Deletes the entity with the given id supplied by a {@link Publisher}.
+	 * <p>
+	 * 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<T, ID> extends Repository<T, ID> {
 	 * @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<Void> delete(T entity);
 
 	/**
 	 * Deletes all instances of the type {@code T} with the given IDs.
+	 * <p>
+	 * 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<T, ID> extends Repository<T, ID> {
 	 * @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<Void> deleteAll(Iterable<? extends T> entities);
 
@@ -206,6 +229,9 @@ public interface ReactiveCrudRepository<T, ID> extends Repository<T, ID> {
 	 * @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<Void> deleteAll(Publisher<? extends T> entityStream);
 

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

@@ -20,17 +20,21 @@
 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;
 
 /**
  * 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.
+ * 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.
+ * 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
@@ -50,6 +54,9 @@ public interface RxJava3CrudRepository<T, ID> extends Repository<T, ID> {
 	 * @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.
 	 */
 	<S extends T> Single<S> save(S entity);
 
@@ -60,6 +67,9 @@ public interface RxJava3CrudRepository<T, ID> extends Repository<T, ID> {
 	 * @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.
 	 */
 	<S extends T> Flowable<S> saveAll(Iterable<S> entities);
 
@@ -69,6 +79,9 @@ public interface RxJava3CrudRepository<T, ID> extends Repository<T, ID> {
 	 * @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.
 	 */
 	<S extends T> Flowable<S> saveAll(Flowable<S> entityStream);
 
@@ -151,6 +164,8 @@ public interface RxJava3CrudRepository<T, ID> extends Repository<T, ID> {
 
 	/**
 	 * Deletes the entity with the given id.
+	 * <p>
+	 * 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<T, ID> extends Repository<T, ID> {
 	 * @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.
+	 * <p>
+	 * 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<T, ID> extends Repository<T, ID> {
 	 * @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<? extends T> entities);
 
@@ -194,6 +217,9 @@ public interface RxJava3CrudRepository<T, ID> extends Repository<T, ID> {
 	 * @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<? extends T> entityStream);