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

@@ -39,16 +39,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;
 
 /**
@@ -104,6 +106,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");
@@ -118,6 +122,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");
@@ -138,6 +144,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");
@@ -275,6 +283,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));
 }
@@ -285,6 +295,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));
 }
@@ -372,6 +384,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

@@ -165,7 +165,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;