Polishing.

Reinstate original Javadoc, add note about nullability.

Fix contract annotation, refine tests.

See #3992
Original pull request: #3998

Author: mp911de

spring-data-jpa/src/main/java/org/springframework/data/jpa/domain/Specification.java

@@ -65,33 +65,35 @@ static <T> Specification<T> unrestricted() {
 	}
 
 	/**
-	 * Simple static factory method to add some syntactic sugar translating {@link PredicateSpecification} to
-	 * {@link Specification}.
+	 * Simple static factory method to add some syntactic sugar around a {@link Specification}.
 	 *
+	 * @implNote does not accept {@literal null} values since 4.0, use {@link #unrestricted()} instead of passing
+	 *           {@literal null} values.
 	 * @param <T> the type of the {@link Root} the resulting {@literal Specification} operates on.
-	 * @param spec the {@link PredicateSpecification} to wrap.
+	 * @param spec can be {@literal null}.
 	 * @return guaranteed to be not {@literal null}.
+	 * @since 2.0
 	 */
-	static <T> Specification<T> where(PredicateSpecification<T> spec) {
+	static <T> Specification<T> where(Specification<T> spec) {
 
-		Assert.notNull(spec, "PredicateSpecification must not be null");
+		Assert.notNull(spec, "Specification must not be null");
 
-		return (root, update, criteriaBuilder) -> spec.toPredicate(root, criteriaBuilder);
+		return spec;
 	}
 
 	/**
-	 * Creates a {@link Specification} from the given {@link Specification}. This is a factory method for fluent composition.
+	 * Simple static factory method to add some syntactic sugar translating {@link PredicateSpecification} to
+	 * {@link Specification}.
 	 *
 	 * @param <T> the type of the {@link Root} the resulting {@literal Specification} operates on.
-	 * @param spec must not be {@literal null}.
-	 * @return the given specification.
-	 * @since 4.1
+	 * @param spec the {@link PredicateSpecification} to wrap.
+	 * @return guaranteed to be not {@literal null}.
 	 */
-	static <T> Specification<T> where(Specification<T> spec) {
+	static <T> Specification<T> where(PredicateSpecification<T> spec) {
 
-		Assert.notNull(spec, "Specification must not be null");
+		Assert.notNull(spec, "PredicateSpecification must not be null");
 
-		return spec;
+		return (root, update, criteriaBuilder) -> spec.toPredicate(root, criteriaBuilder);
 	}
 
 	/**

spring-data-jpa/src/main/java/org/springframework/data/jpa/repository/query/ParameterBinding.java

@@ -291,7 +291,7 @@ public JpqlQueryTemplates getTemplates() {
 
 
 		@SuppressWarnings("unchecked")
-		@Contract("false, _ -> param2; _, null -> null; true, !null -> new)")
+		@Contract("false, _ -> param2; _, null -> null; true, !null -> new")
 		private @Nullable Collection<?> potentiallyIgnoreCase(boolean ignoreCase, @Nullable Collection<?> collection) {
 
 			if (!ignoreCase || CollectionUtils.isEmpty(collection)) {

spring-data-jpa/src/test/java/org/springframework/data/jpa/domain/SpecificationUnitTests.java

@@ -162,10 +162,7 @@ void whereWithSpecificationSupportsFluentComposition() {
 
 	@Test // GH-3992
 	void whereWithNullSpecificationThrowsException() {
-
-		assertThatThrownBy(() -> Specification.where((Specification<Object>) null))
-				.isInstanceOf(IllegalArgumentException.class)
-				.hasMessage("Specification must not be null");
+		assertThatIllegalArgumentException().isThrownBy(() -> Specification.where((Specification<Object>) null));
 	}
 
 	static class SerializableSpecification implements Serializable, Specification<Object> {