Add Contract annotations.

Original Pull Request: #3578
spring-projects · Jan 14, 2025 · 28a52e0 · 28a52e0
1 parent 5fafaa4
commit 28a52e0
Show file tree

Hide file tree

Showing 5 changed files with 52 additions and 9 deletions.
diff --git a/spring-data-jpa/src/main/java/org/springframework/data/jpa/domain/DeleteSpecification.java b/spring-data-jpa/src/main/java/org/springframework/data/jpa/domain/DeleteSpecification.java
@@ -24,14 +24,16 @@
 import java.util.Arrays;
 import java.util.stream.StreamSupport;
 
+import org.springframework.lang.CheckReturnValue;
+import org.springframework.lang.Contract;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
  * Specification in the sense of Domain Driven Design to handle Criteria Deletes.
  *
  * @author Mark Paluch
- * @since xxx
+ * @since 4.0
  */
 @FunctionalInterface
 public interface DeleteSpecification<T> extends Serializable {
@@ -81,6 +83,8 @@ static <T> DeleteSpecification<T> where(PredicateSpecification<T> spec) {
 	 * @param other the other {@link DeleteSpecification}.
 	 * @return the conjunction of the specifications.
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default DeleteSpecification<T> and(DeleteSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");
@@ -94,6 +98,8 @@ default DeleteSpecification<T> and(DeleteSpecification<T> other) {
 	 * @param other the other {@link PredicateSpecification}.
 	 * @return the conjunction of the specifications.
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default DeleteSpecification<T> and(PredicateSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");
@@ -107,6 +113,8 @@ default DeleteSpecification<T> and(PredicateSpecification<T> other) {
 	 * @param other the other {@link DeleteSpecification}.
 	 * @return the disjunction of the specifications.
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default DeleteSpecification<T> or(DeleteSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");
@@ -120,6 +128,8 @@ default DeleteSpecification<T> or(DeleteSpecification<T> other) {
 	 * @param other the other {@link PredicateSpecification}.
 	 * @return the disjunction of the specifications.
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default DeleteSpecification<T> or(PredicateSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");

diff --git a/...ng-data-jpa/src/main/java/org/springframework/data/jpa/domain/PredicateSpecification.java b/...ng-data-jpa/src/main/java/org/springframework/data/jpa/domain/PredicateSpecification.java
@@ -23,14 +23,16 @@
 import java.util.Arrays;
 import java.util.stream.StreamSupport;
 
+import org.springframework.lang.CheckReturnValue;
+import org.springframework.lang.Contract;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
  * Specification in the sense of Domain Driven Design.
  *
  * @author Mark Paluch
- * @since xxx
+ * @since 4.0
  */
 public interface PredicateSpecification<T> extends Serializable {
 
@@ -54,7 +56,7 @@ static <T> PredicateSpecification<T> all() {
 	 */
 	static <T> PredicateSpecification<T> where(PredicateSpecification<T> spec) {
 
-		Assert.notNull(spec, "DeleteSpecification must not be null");
+		Assert.notNull(spec, "PredicateSpecification must not be null");
 
 		return spec;
 	}
@@ -65,6 +67,8 @@ static <T> PredicateSpecification<T> where(PredicateSpecification<T> spec) {
 	 * @param other the other {@link PredicateSpecification}.
 	 * @return the conjunction of the specifications.
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default PredicateSpecification<T> and(PredicateSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");
@@ -78,6 +82,8 @@ default PredicateSpecification<T> and(PredicateSpecification<T> other) {
 	 * @param other the other {@link PredicateSpecification}.
 	 * @return the disjunction of the specifications.
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default PredicateSpecification<T> or(PredicateSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");

diff --git a/spring-data-jpa/src/main/java/org/springframework/data/jpa/domain/Specification.java b/spring-data-jpa/src/main/java/org/springframework/data/jpa/domain/Specification.java
@@ -25,6 +25,8 @@
 import java.util.Arrays;
 import java.util.stream.StreamSupport;
 
+import org.springframework.lang.CheckReturnValue;
+import org.springframework.lang.Contract;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
@@ -75,6 +77,8 @@ static <T> Specification<T> where(PredicateSpecification<T> spec) {
 	 * @return the conjunction of the specifications.
 	 * @since 2.0
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default Specification<T> and(Specification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");
@@ -89,6 +93,8 @@ default Specification<T> and(Specification<T> other) {
 	 * @return the conjunction of the specifications.
 	 * @since 2.0
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default Specification<T> and(PredicateSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");
@@ -103,6 +109,8 @@ default Specification<T> and(PredicateSpecification<T> other) {
 	 * @return the disjunction of the specifications
 	 * @since 2.0
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default Specification<T> or(Specification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");
@@ -117,6 +125,8 @@ default Specification<T> or(Specification<T> other) {
 	 * @return the disjunction of the specifications
 	 * @since 2.0
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default Specification<T> or(PredicateSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");

diff --git a/spring-data-jpa/src/main/java/org/springframework/data/jpa/domain/UpdateSpecification.java b/spring-data-jpa/src/main/java/org/springframework/data/jpa/domain/UpdateSpecification.java
@@ -24,14 +24,16 @@
 import java.util.Arrays;
 import java.util.stream.StreamSupport;
 
+import org.springframework.lang.CheckReturnValue;
+import org.springframework.lang.Contract;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
  * Specification in the sense of Domain Driven Design to handle Criteria Updates.
  *
  * @author Mark Paluch
- * @since xxx
+ * @since 4.0
  */
 @FunctionalInterface
 public interface UpdateSpecification<T> extends Serializable {
@@ -103,6 +105,8 @@ static <T> UpdateSpecification<T> where(PredicateSpecification<T> spec) {
 	 * @param other the other {@link UpdateSpecification}.
 	 * @return the conjunction of the specifications.
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default UpdateSpecification<T> and(UpdateSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");
@@ -116,6 +120,8 @@ default UpdateSpecification<T> and(UpdateSpecification<T> other) {
 	 * @param other the other {@link PredicateSpecification}.
 	 * @return the conjunction of the specifications.
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default UpdateSpecification<T> and(PredicateSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");
@@ -129,6 +135,8 @@ default UpdateSpecification<T> and(PredicateSpecification<T> other) {
 	 * @param other the other {@link UpdateSpecification}.
 	 * @return the disjunction of the specifications.
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default UpdateSpecification<T> or(UpdateSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");
@@ -142,6 +150,8 @@ default UpdateSpecification<T> or(UpdateSpecification<T> other) {
 	 * @param other the other {@link PredicateSpecification}.
 	 * @return the disjunction of the specifications.
 	 */
+	@Contract("_ -> new")
+	@CheckReturnValue
 	default UpdateSpecification<T> or(PredicateSpecification<T> other) {
 
 		Assert.notNull(other, "Other specification must not be null");
@@ -256,6 +266,8 @@ interface UpdateOperation<T> {
 		 * @param other the other {@link UpdateOperation}.
 		 * @return the conjunction of the specifications.
 		 */
+		@Contract("_ -> new")
+		@CheckReturnValue
 		default UpdateOperation<T> and(UpdateOperation<T> other) {
 
 			Assert.notNull(other, "Other UpdateOperation must not be null");
@@ -272,6 +284,8 @@ default UpdateOperation<T> and(UpdateOperation<T> other) {
 		 * @param specification the {@link PredicateSpecification}.
 		 * @return the conjunction of the specifications.
 		 */
+		@Contract("_ -> new")
+		@CheckReturnValue
 		default UpdateSpecification<T> where(PredicateSpecification<T> specification) {
 
 			Assert.notNull(specification, "PredicateSpecification must not be null");
@@ -288,6 +302,8 @@ default UpdateSpecification<T> where(PredicateSpecification<T> specification) {
 		 * @param specification the {@link UpdateSpecification}.
 		 * @return the conjunction of the specifications.
 		 */
+		@Contract("_ -> new")
+		@CheckReturnValue
 		default UpdateSpecification<T> where(UpdateSpecification<T> specification) {
 
 			Assert.notNull(specification, "UpdateSpecification must not be null");
@@ -306,6 +322,7 @@ default UpdateSpecification<T> where(UpdateSpecification<T> specification) {
 		 * @param criteriaBuilder must not be {@literal null}.
 		 */
 		void apply(Root<T> root, CriteriaUpdate<T> update, CriteriaBuilder criteriaBuilder);
+
 	}
 
 }
diff --git a/...pa/src/main/java/org/springframework/data/jpa/repository/support/SimpleJpaRepository.java b/...pa/src/main/java/org/springframework/data/jpa/repository/support/SimpleJpaRepository.java
@@ -260,7 +260,7 @@ public void deleteAllByIdInBatch(Iterable<ID> ids) {
 			/*
 			 * Some JPA providers require {@code ids} to be a {@link Collection} so we must convert if it's not already.
 			 */
-			Collection<ID> idCollection = toCollection(ids);
+						Collection<ID> idCollection = toCollection(ids);
 			query.setParameter("ids", idCollection);
 
 			applyQueryHints(query);
@@ -732,8 +732,7 @@ protected TypedQuery<T> getQuery(Specification<T> spec, Pageable pageable) {
 	 * @param domainClass must not be {@literal null}.
 	 * @param pageable must not be {@literal null}.
 	 */
-	protected <S extends T> TypedQuery<S> getQuery(Specification<S> spec, Class<S> domainClass,
-			Pageable pageable) {
+	protected <S extends T> TypedQuery<S> getQuery(Specification<S> spec, Class<S> domainClass, Pageable pageable) {
 
 		return getQuery(spec, domainClass, pageable.getSort());
 	}
@@ -1074,7 +1073,7 @@ private static long executeCountQuery(TypedQuery<Long> query) {
 	@SuppressWarnings("rawtypes")
 	private static final class ByIdsSpecification<T> implements Specification<T> {
 
-		@Serial private static final long serialVersionUID = 1L;
+		@Serial private static final @Serial long serialVersionUID = 1L;
 
 		private final JpaEntityInformation<T, ?> entityInformation;
 
@@ -1085,6 +1084,7 @@ private static final class ByIdsSpecification<T> implements Specification<T> {
 		}
 
 		@Override
+		@SuppressWarnings("unchecked")
 		public Predicate toPredicate(Root<T> root, CriteriaQuery<?> query, CriteriaBuilder cb) {
 
 			Path<?> path = root.get(entityInformation.getIdAttribute());
@@ -1103,7 +1103,7 @@ public Predicate toPredicate(Root<T> root, CriteriaQuery<?> query, CriteriaBuild
 	 */
 	private static class ExampleSpecification<T> implements Specification<T> {
 
-		@Serial private static final long serialVersionUID = 1L;
+		@Serial private static final @Serial long serialVersionUID = 1L;
 
 		private final Example<T> example;
 		private final EscapeCharacter escapeCharacter;