Add contract annotations to public API.

See #3745
Original pull request: #3781

Author: christophstrobl

spring-data-jpa/src/main/java/org/springframework/data/jpa/convert/QueryByExamplePredicateBuilder.java

@@ -43,6 +43,7 @@
 import org.springframework.data.jpa.repository.query.EscapeCharacter;
 import org.springframework.data.support.ExampleMatcherAccessor;
 import org.springframework.data.util.DirectFieldAccessFallbackBeanWrapper;
+import org.springframework.lang.Contract;
 import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 import org.springframework.util.ObjectUtils;
@@ -242,7 +243,6 @@ private static class PathNode {
 
 		String name;
 		@Nullable PathNode parent;
-		List<PathNode> siblings = new ArrayList<>();
 		@Nullable Object value;
 
 		PathNode(String edge, @Nullable PathNode parent, @Nullable Object value) {
@@ -254,9 +254,7 @@ private static class PathNode {
 
 		PathNode add(String attribute, @Nullable Object value) {
 
-			PathNode node = new PathNode(attribute, this, value);
-			siblings.add(node);
-			return node;
+			return new PathNode(attribute, this, value);
 		}
 
 		boolean spansCycle() {

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

@@ -24,6 +24,7 @@
 import java.time.ZoneId;
 import java.util.Optional;
 
+import org.jspecify.annotations.NullUnmarked;
 import org.springframework.data.domain.Auditable;
 
 import org.jspecify.annotations.Nullable;
@@ -38,23 +39,19 @@
  * @param <PK> the type of the auditing type's identifier.
  */
 @MappedSuperclass
-@SuppressWarnings("NullAway")
+@SuppressWarnings("NullAway") // querydsl does not work with jspecify -> 'Did not find type @org.jspecify.annotations.Nullable...'
 public abstract class AbstractAuditable<U, PK extends Serializable> extends AbstractPersistable<PK>
 		implements Auditable<U, PK, LocalDateTime> {
 
-//	@Nullable
 	@ManyToOne //
 	private  U createdBy;
 
-//	@Nullable
 	private  Instant createdDate;
 
-//	@Nullable
 	@ManyToOne //
 	private U lastModifiedBy;
 
-//	@Nullable
-	private  Instant lastModifiedDate;
+	private Instant lastModifiedDate;
 
 	@Override
 	public Optional<U> getCreatedBy() {

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

@@ -38,16 +38,13 @@
  * @param <PK> the type of the identifier.
  */
 @MappedSuperclass
-
+@SuppressWarnings("NullAway") // querydsl does not work with jspecify -> 'Did not find type @org.jspecify.annotations.Nullable...'
 public abstract class AbstractPersistable<PK extends Serializable> implements Persistable<PK> {
 
 	@Nullable
 	@Id @GeneratedValue private PK id;
 
 	@Override
-	@SuppressWarnings("NullAway")
-	// TODO: Querydsl APT does not like @Nullable
-	// -> errors with cryptic 'Did not find type @org.jspecify.annotations.Nullable PK'
 	public PK getId() {
 		return id;
 	}

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

@@ -151,6 +151,7 @@ default DeleteSpecification<T> or(PredicateSpecification<T> other) {
 	 * @param spec can be {@literal null}.
 	 * @return guaranteed to be not {@literal null}.
 	 */
+	@Contract("_ -> new")
 	static <T> DeleteSpecification<T> not(DeleteSpecification<T> spec) {
 
 		Assert.notNull(spec, "Specification must not be null");

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

@@ -28,6 +28,8 @@
 import org.springframework.data.domain.Sort;
 
 import org.jspecify.annotations.Nullable;
+import org.springframework.lang.CheckReturnValue;
+import org.springframework.lang.Contract;
 import org.springframework.util.Assert;
 
 /**
@@ -103,6 +105,8 @@ public static JpaSort of(Direction direction, Path<?, ?>... paths) {
 	 * @param attributes must not be {@literal null}.
 	 * @return
 	 */
+	@Contract("_, _ -> new")
+	@CheckReturnValue
 	public JpaSort and(@Nullable Direction direction, Attribute<?, ?>... attributes) {
 
 		Assert.notNull(attributes, "Attributes must not be null");
@@ -117,6 +121,8 @@ public JpaSort and(@Nullable Direction direction, Attribute<?, ?>... attributes)
 	 * @param paths must not be {@literal null}.
 	 * @return
 	 */
+	@Contract("_, _ -> new")
+	@CheckReturnValue
 	public JpaSort and(@Nullable Direction direction, Path<?, ?>... paths) {
 
 		Assert.notNull(paths, "Paths must not be null");
@@ -137,6 +143,8 @@ public JpaSort and(@Nullable Direction direction, Path<?, ?>... paths) {
 	 * @param properties must not be {@literal null} or empty.
 	 * @return
 	 */
+	@Contract("_, _ -> new")
+	@CheckReturnValue
 	public JpaSort andUnsafe(@Nullable Direction direction, String... properties) {
 
 		Assert.notEmpty(properties, "Properties must not be empty");
@@ -274,6 +282,8 @@ private Path(List<? extends Attribute<?, ?>> attributes) {
 		 * @param attribute must not be {@literal null}.
 		 * @return
 		 */
+		@Contract("_ -> new")
+		@CheckReturnValue
 		public <A extends Attribute<S, U>, U> Path<S, U> dot(A attribute) {
 			return new Path<>(add(attribute));
 		}
@@ -284,6 +294,8 @@ public <A extends Attribute<S, U>, U> Path<S, U> dot(A attribute) {
 		 * @param attribute must not be {@literal null}.
 		 * @return
 		 */
+		@Contract("_ -> new")
+		@CheckReturnValue
 		public <P extends PluralAttribute<S, ?, U>, U> Path<S, U> dot(P attribute) {
 			return new Path<>(add(attribute));
 		}
@@ -371,6 +383,8 @@ public JpaOrder with(NullHandling nullHandling) {
 		 * @param properties must not be {@literal null}.
 		 * @return
 		 */
+		@Contract("_ -> new")
+		@CheckReturnValue
 		public Sort withUnsafe(String... properties) {
 
 			Assert.notEmpty(properties, "Properties must not be empty");

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

@@ -57,6 +57,7 @@
 import org.springframework.data.repository.query.ReturnedType;
 import org.springframework.data.util.Lazy;
 import org.springframework.jdbc.support.JdbcUtils;
+import org.springframework.lang.Contract;
 import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 
@@ -193,6 +194,7 @@ protected JpaQueryExecution getExecution() {
 	 * @return
 	 */
 	@SuppressWarnings("NullAway")
+	@Contract("_, _ -> param1")
 	protected <T extends Query> T applyHints(T query, JpaQueryMethod method) {
 
 		List<QueryHint> hints = method.getHints();

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

@@ -20,6 +20,7 @@
 import java.util.stream.Stream;
 
 import org.jspecify.annotations.Nullable;
+import org.springframework.lang.Contract;
 
 /**
  * A value type encapsulating an escape character for LIKE queries and the actually usage of it in escaping
@@ -49,6 +50,7 @@ public static EscapeCharacter of(char escapeCharacter) {
 	 * @param value may be {@literal null}.
 	 * @return
 	 */
+	@Contract("null -> null")
 	public @Nullable String escape(@Nullable String value) {
 
 		return value == null //

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

@@ -149,7 +149,6 @@ private static Class<?> potentiallyUnwrapReturnTypeFor(RepositoryMetadata metada
 	}
 
 	@Override
-	@SuppressWarnings({ "rawtypes", "unchecked" })
 	public JpaEntityMetadata<?> getEntityInformation() {
 		return this.entityMetadata.get();
 	}

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

@@ -33,6 +33,8 @@
 import org.jspecify.annotations.Nullable;
 import org.springframework.data.mapping.PropertyPath;
 import org.springframework.data.util.Predicates;
+import org.springframework.lang.CheckReturnValue;
+import org.springframework.lang.Contract;
 import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 import org.springframework.util.ObjectUtils;
@@ -405,16 +407,19 @@ public interface SelectStep {
 		/**
 		 * Apply {@code DISTINCT}.
 		 */
+		@CheckReturnValue
 		SelectStep distinct();
 
 		/**
 		 * Select the entity.
 		 */
+		@CheckReturnValue
 		Select entity();
 
 		/**
 		 * Select the count.
 		 */
+		@CheckReturnValue
 		Select count();
 
 		/**
@@ -425,6 +430,7 @@ public interface SelectStep {
 		 * @param paths
 		 * @return
 		 */
+		@CheckReturnValue
 		default Select instantiate(Class<?> resultType, Collection<JpqlQueryBuilder.PathExpression> paths) {
 			return instantiate(resultType.getName(), paths);
 		}
@@ -436,6 +442,7 @@ default Select instantiate(Class<?> resultType, Collection<JpqlQueryBuilder.Path
 		 * @param paths
 		 * @return
 		 */
+		@CheckReturnValue
 		Select instantiate(String resultType, Collection<JpqlQueryBuilder.PathExpression> paths);
 
 		/**
@@ -444,6 +451,7 @@ default Select instantiate(Class<?> resultType, Collection<JpqlQueryBuilder.Path
 		 * @param paths
 		 * @return
 		 */
+		@CheckReturnValue
 		Select select(Collection<JpqlQueryBuilder.PathExpression> paths);
 
 		/**
@@ -452,6 +460,7 @@ default Select instantiate(Class<?> resultType, Collection<JpqlQueryBuilder.Path
 		 * @param path
 		 * @return
 		 */
+		@CheckReturnValue
 		default Select select(JpqlQueryBuilder.PathExpression path) {
 			return select(List.of(path));
 		}
@@ -626,6 +635,8 @@ public interface Predicate {
 		 * @param other
 		 * @return a composed predicate combining this and {@code other} using the OR operator.
 		 */
+		@Contract("_ -> new")
+		@CheckReturnValue
 		default Predicate or(Predicate other) {
 			return new OrPredicate(this, other);
 		}
@@ -636,6 +647,8 @@ default Predicate or(Predicate other) {
 		 * @param other
 		 * @return a composed predicate combining this and {@code other} using the AND operator.
 		 */
+		@Contract("_ -> new")
+		@CheckReturnValue
 		default Predicate and(Predicate other) { // don't like the structuring of this and the nest() thing
 			return new AndPredicate(this, other);
 		}
@@ -645,6 +658,8 @@ default Predicate and(Predicate other) { // don't like the structuring of this a
 		 *
 		 * @return a nested variant of this predicate.
 		 */
+		@Contract("-> new")
+		@CheckReturnValue
 		default Predicate nest() {
 			return new NestedPredicate(this);
 		}
@@ -700,6 +715,7 @@ private Select(Selection selection, Entity entity) {
 		 * @param join
 		 * @return
 		 */
+		@Contract("_ -> this")
 		public Select join(Join join) {
 
 			if (join.source() instanceof Join parent) {
@@ -716,6 +732,7 @@ public Select join(Join join) {
 		 * @param orderBy
 		 * @return
 		 */
+		@Contract("_ -> this")
 		public Select orderBy(Expression orderBy) {
 			this.orderBy.add(orderBy);
 			return this;