Polishing.

Adding and correcting `@since` annotations. Cleaning up some JavaDoc. Tweaking some tests to make them more precise. Original pull request spring-projects#2148

Author: schauder

src/main/java/org/springframework/data/jpa/repository/JpaRepository.java

@@ -72,16 +72,17 @@ public interface JpaRepository<T, ID> extends PagingAndSortingRepository<T, ID>,
 /**
  * Saves an entity and flushes changes instantly.
  *
- * @param entity
+ * @param entity entity to be saved. Must not be {@literal null}.
  * @return the saved entity
  */
 <S extends T> S saveAndFlush(S entity);
 
 /**
  * Saves all entities and flushes changes instantly.
  *
- * @param entities
+ * @param entities entities to be deleted. Must not be {@literal null}.
  * @return the saved entities
+ * @since 2.5
  */
 <S extends T> List<S> saveAllAndFlush(Iterable<S> entities);
 
@@ -90,7 +91,7 @@ public interface JpaRepository<T, ID> extends PagingAndSortingRepository<T, ID>,
  * first level cache and the database out of sync. Consider flushing the {@link EntityManager} before calling this
  * method.
  *
- * @param entities
+ * @param entities entities to be deleted. Must not be {@literal null}.
  * @deprecated Use {@link #deleteAllInBatch(Iterable)} instead.
  */
 @Deprecated
@@ -101,8 +102,8 @@ public interface JpaRepository<T, ID> extends PagingAndSortingRepository<T, ID>,
  * first level cache and the database out of sync. Consider flushing the {@link EntityManager} before calling this
  * method.
  *
- * @param entities
- * @since 3.0
+ * @param entities entities to be deleted. Must not be {@literal null}.
+ * @since 2.5
  */
 void deleteAllInBatch(Iterable<T> entities);
 
@@ -111,8 +112,8 @@ public interface JpaRepository<T, ID> extends PagingAndSortingRepository<T, ID>,
  * Deletes the entities identified by the given ids using a single query. This kind of operation leaves JPAs first
  * level cache and the database out of sync. Consider flushing the {@link EntityManager} before calling this method.
  *
- * @param ids
- * @since 3.0
+ * @param ids the ids of the entities to be deleted. Must not be {@literal null}.
+ * @since 2.5
  */
 void deleteAllByIdInBatch(Iterable<ID> ids);
 

src/test/java/org/springframework/data/jpa/repository/UserRepositoryTests.java

@@ -46,7 +46,6 @@
 import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
-
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.dao.DataAccessException;
 import org.springframework.dao.DataIntegrityViolationException;
@@ -60,16 +59,16 @@
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Slice;
 import org.springframework.data.domain.Sort;
+import org.springframework.data.domain.ExampleMatcher.*;
 import org.springframework.data.domain.Sort.Direction;
 import org.springframework.data.domain.Sort.Order;
-import org.springframework.data.domain.ExampleMatcher.*;
 import org.springframework.data.jpa.domain.Specification;
 import org.springframework.data.jpa.domain.sample.Address;
 import org.springframework.data.jpa.domain.sample.Role;
 import org.springframework.data.jpa.domain.sample.SpecialUser;
 import org.springframework.data.jpa.domain.sample.User;
-import org.springframework.data.jpa.repository.sample.SampleEvaluationContextExtension.SampleSecurityContextHolder;
 import org.springframework.data.jpa.repository.sample.UserRepository;
+import org.springframework.data.jpa.repository.sample.SampleEvaluationContextExtension.SampleSecurityContextHolder;
 import org.springframework.data.jpa.repository.sample.UserRepository.NameOnly;
 import org.springframework.test.context.ContextConfiguration;
 import org.springframework.test.context.junit.jupiter.SpringExtension;
@@ -152,8 +151,8 @@ void findsAllByGivenIds() {
 
 flushTestUsers();
 
-assertThat(repository.findAllById(asList(firstUser.getId(), secondUser.getId()))).contains(firstUser,
-secondUser);
+assertThat(repository.findAllById(asList(firstUser.getId(), secondUser.getId()))) //
+.containsExactlyInAnyOrder(firstUser, secondUser);
 }
 
 @Test
@@ -167,23 +166,23 @@ void testReadByIdReturnsNullForNotFoundEntities() {
 @Test
 void savesCollectionCorrectly() throws Exception {
 
-assertThat(repository.saveAll(asList(firstUser, secondUser, thirdUser))).hasSize(3).contains(firstUser,
-secondUser, thirdUser);
+assertThat(repository.saveAll(asList(firstUser, secondUser, thirdUser))) //
+.containsExactlyInAnyOrder(firstUser, secondUser, thirdUser);
 }
 
-@Test // DATAJPA-1574
+@Test // gh-2148
 void savesAndFlushesCollectionCorrectly() {
 
-assertThat(repository.saveAllAndFlush(asList(firstUser, secondUser, thirdUser))).hasSize(3).contains(firstUser,
-secondUser, thirdUser);
+assertThat(repository.saveAllAndFlush(asList(firstUser, secondUser, thirdUser))) //
+.containsExactlyInAnyOrder(firstUser, secondUser, thirdUser);
 }
 
 @Test
 void savingEmptyCollectionIsNoOp() throws Exception {
 assertThat(repository.saveAll(new ArrayList<>())).isEmpty();
 }
 
-@Test // DATAJPA-1574
+@Test // gh-2148
 void savingAndFlushingEmptyCollectionIsNoOp() {
 assertThat(repository.saveAllAndFlush(new ArrayList<>())).isEmpty();
 }
@@ -1114,7 +1113,7 @@ void saveAndFlushShouldSupportReturningSubTypesOfRepositoryEntity() {
 assertThat(user.getEmailAddress()).isEqualTo(savedUser.getEmailAddress());
 }
 
-@Test // DATAJPA-1574
+@Test // gh-2148
 void saveAllAndFlushShouldSupportReturningSubTypesOfRepositoryEntity() {
 
 repository.deleteAll();