Constistent unrestricted() behaviour for all *Specification types.

Closes #4023
Original pull request: #4024

Signed-off-by: Peter Aisher <[email protected]>

Author: peteraisher

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

@@ -29,6 +29,13 @@
 
 /**
  * Specification in the sense of Domain Driven Design.
+ * <p>
+ * Specifications can be composed into higher order functions from other specifications using
+ * {@link #and(Specification)}, {@link #or(Specification)} or factory methods such as {@link #allOf(Iterable)}.
+ * <p>
+ * Composition considers whether one or more specifications contribute to the overall predicate by returning a
+ * {@link Predicate} or {@literal null}. Specifications returning {@literal null}, such as {@link #unrestricted()}, are
+ * considered to not contribute to the overall predicate, and their result is not considered in the final predicate.
  *
  * @author Oliver Gierke
  * @author Thomas Darimont
@@ -38,6 +45,7 @@
  * @author Jens Schauder
  * @author Daniel Shuy
  * @author Sergey Rukin
+ * @author Peter Aisher
  */
 @FunctionalInterface
 public interface Specification<T> extends Serializable {
@@ -65,7 +73,16 @@ static <T> Specification<T> not(@Nullable Specification<T> spec) {
 	}
 
 	/**
-	 * Simple static factory method to create a specification matching all objects.
+	 * Simple static factory method to create a specification which does not participate in matching. The specification
+	 * returned is {@code null}-like, and is elided in all operations.
+	 *
+	 * <pre>
+	 * {@code
+	 * unrestricted().and(other) // consider only `other`
+	 * unrestricted().or(other) // consider only `other`
+	 * not(unrestricted()) // equivalent to `unrestricted()`
+	 * }
+	 * </pre>
 	 *
 	 * @param <T> the type of the {@link Root} the resulting {@literal Specification} operates on.
 	 * @return guaranteed to be not {@literal null}.

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

@@ -45,6 +45,7 @@
  * @author Jens Schauder
  * @author Mark Paluch
  * @author Daniel Shuy
+ * @author Peter Aisher
  */
 @SuppressWarnings({ "unchecked", "deprecation", "removal" })
 @ExtendWith(MockitoExtension.class)
@@ -209,15 +210,13 @@ void orCombinesSpecificationsInOrder() {
 		verify(builder).or(firstPredicate, secondPredicate);
 	}
 
-	@Test // GH-3849
+	@Test // GH-3849, GH-4023
 	void notWithNullPredicate() {
 
-		when(builder.disjunction()).thenReturn(mock(Predicate.class));
+		Specification<Object> notSpec = Specification.not(Specification.unrestricted());
 
-		Specification<Object> notSpec = Specification.not((r, q, cb) -> null);
-
-		assertThat(notSpec.toPredicate(root, query, builder)).isNotNull();
-		verify(builder).disjunction();
+		assertThat(notSpec.toPredicate(root, query, builder)).isNull();
+		verifyNoInteractions(builder);
 	}
 
 	static class SerializableSpecification implements Serializable, Specification<Object> {