Add @CheckReturnValue to Query and Update API.

Closes #2145

Author: mp911de

spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Criteria.java

@@ -29,12 +29,13 @@
 import org.springframework.data.relational.core.sql.IdentifierProcessing;
 import org.springframework.data.relational.core.sql.SqlIdentifier;
 import org.springframework.data.util.Pair;
+import org.springframework.lang.CheckReturnValue;
 import org.springframework.util.Assert;
 
 /**
- * Central class for creating queries. It follows a fluent API style so that you can easily chain together multiple
- * criteria. Static import of the {@code Criteria.property(…)} method will improve readability as in
- * {@code where(property(…).is(…)}.
+ * Central value class for creating criteria predicates. It follows a fluent (and immutable) API style so that you can
+ * easily chain together multiple criteria. Static import of the {@code Criteria.property(…)} method will improve
+ * readability as in {@code where(property(…).is(…)}.
  * <p>
  * The Criteria API supports composition with a {@link #empty() NULL object} and a {@link #from(List) static factory
  * method}. Example usage:
@@ -162,6 +163,7 @@ public static CriteriaStep where(String column) {
 	 * @param column Must not be {@literal null} or empty.
 	 * @return a new {@link CriteriaStep} object to complete the next {@link Criteria}.
 	 */
+	@CheckReturnValue
 	public CriteriaStep and(String column) {
 
 		Assert.hasText(column, "Column name must not be null or empty");
@@ -182,6 +184,7 @@ protected Criteria createCriteria(Comparator comparator, @Nullable Object value)
 	 * @return a new {@link Criteria} object.
 	 * @since 1.1
 	 */
+	@CheckReturnValue
 	public Criteria and(CriteriaDefinition criteria) {
 
 		Assert.notNull(criteria, "Criteria must not be null");
@@ -196,6 +199,7 @@ public Criteria and(CriteriaDefinition criteria) {
 	 * @return a new {@link Criteria} object.
 	 */
 	@SuppressWarnings("unchecked")
+	@CheckReturnValue
 	public Criteria and(List<? extends CriteriaDefinition> criteria) {
 
 		Assert.notNull(criteria, "Criteria must not be null");
@@ -209,6 +213,7 @@ public Criteria and(List<? extends CriteriaDefinition> criteria) {
 	 * @param column Must not be {@literal null} or empty.
 	 * @return a new {@link CriteriaStep} object to complete the next {@link Criteria}.
 	 */
+	@CheckReturnValue
 	public CriteriaStep or(String column) {
 
 		Assert.hasText(column, "Column name must not be null or empty");
@@ -229,6 +234,7 @@ protected Criteria createCriteria(Comparator comparator, @Nullable Object value)
 	 * @return a new {@link Criteria} object.
 	 * @since 1.1
 	 */
+	@CheckReturnValue
 	public Criteria or(CriteriaDefinition criteria) {
 
 		Assert.notNull(criteria, "Criteria must not be null");
@@ -244,6 +250,7 @@ public Criteria or(CriteriaDefinition criteria) {
 	 * @since 1.1
 	 */
 	@SuppressWarnings("unchecked")
+	@CheckReturnValue
 	public Criteria or(List<? extends CriteriaDefinition> criteria) {
 
 		Assert.notNull(criteria, "Criteria must not be null");
@@ -257,6 +264,7 @@ public Criteria or(List<? extends CriteriaDefinition> criteria) {
 	 * @param ignoreCase {@literal true} if comparison should be done in case-insensitive way
 	 * @return a new {@link Criteria} object
 	 */
+	@CheckReturnValue
 	public Criteria ignoreCase(boolean ignoreCase) {
 		if (this.ignoreCase != ignoreCase) {
 			return new Criteria(previous, combinator, group, column, comparator, value, ignoreCase);

spring-data-relational/src/main/java/org/springframework/data/relational/core/query/CriteriaDefinition.java

@@ -29,6 +29,7 @@
  * @author Mark Paluch
  * @author Jens Schauder
  * @since 2.0
+ * @see Criteria
  */
 public interface CriteriaDefinition {
 

spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Query.java

@@ -27,11 +27,12 @@
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.relational.core.sql.SqlIdentifier;
+import org.springframework.lang.CheckReturnValue;
 import org.springframework.util.Assert;
 
 /**
- * Query object representing {@link Criteria}, columns, {@link Sort}, and limit/offset for a SQL query. {@link Query} is
- * created with a fluent API creating immutable objects.
+ * Query object representing {@link Criteria}, columns, {@link Sort}, and limit/offset for a SQL query. Methods on this
+ * class are designed to be used in a fluent style creating immutable objects.
  *
  * @author Mark Paluch
  * @since 2.0
@@ -94,6 +95,7 @@ public static Query empty() {
 	 * @param columns
 	 * @return a new {@link Query} object containing the former settings with {@code columns} applied.
 	 */
+	@CheckReturnValue
 	public Query columns(String... columns) {
 
 		Assert.notNull(columns, "Columns must not be null");
@@ -107,6 +109,7 @@ public Query columns(String... columns) {
 	 * @param columns
 	 * @return a new {@link Query} object containing the former settings with {@code columns} applied.
 	 */
+	@CheckReturnValue
 	public Query columns(Collection<String> columns) {
 
 		Assert.notNull(columns, "Columns must not be null");
@@ -121,6 +124,7 @@ public Query columns(Collection<String> columns) {
 	 * @return a new {@link Query} object containing the former settings with {@code columns} applied.
 	 * @since 1.1
 	 */
+	@CheckReturnValue
 	public Query columns(SqlIdentifier... columns) {
 
 		Assert.notNull(columns, "Columns must not be null");
@@ -149,6 +153,7 @@ private Query withColumns(Collection<SqlIdentifier> columns) {
 	 * @param offset
 	 * @return a new {@link Query} object containing the former settings with {@code offset} applied.
 	 */
+	@CheckReturnValue
 	public Query offset(long offset) {
 		return new Query(this.criteria, this.columns, this.sort, this.limit, offset);
 	}
@@ -159,6 +164,7 @@ public Query offset(long offset) {
 	 * @param limit
 	 * @return a new {@link Query} object containing the former settings with {@code limit} applied.
 	 */
+	@CheckReturnValue
 	public Query limit(int limit) {
 		return new Query(this.criteria, this.columns, this.sort, limit, this.offset);
 	}
@@ -170,6 +176,7 @@ public Query limit(int limit) {
 	 * @param pageable
 	 * @return a new {@link Query} object containing the former settings with {@link Pageable} applied.
 	 */
+	@CheckReturnValue
 	public Query with(Pageable pageable) {
 
 		assertNoCaseSort(pageable.getSort());
@@ -188,6 +195,7 @@ public Query with(Pageable pageable) {
 	 * @param sort
 	 * @return a new {@link Query} object containing the former settings with {@link Sort} applied.
 	 */
+	@CheckReturnValue
 	public Query sort(Sort sort) {
 
 		Assert.notNull(sort, "Sort must not be null");

spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Update.java

@@ -23,10 +23,12 @@
 import org.jspecify.annotations.Nullable;
 import org.springframework.data.relational.core.sql.IdentifierProcessing;
 import org.springframework.data.relational.core.sql.SqlIdentifier;
+import org.springframework.lang.CheckReturnValue;
 import org.springframework.util.Assert;
 
 /**
- * Class to easily construct SQL update assignments.
+ * Class to easily construct SQL update assignments. Methods on this class are designed to be used in a fluent style
+ * creating immutable objects.
  *
  * @author Mark Paluch
  * @author Oliver Drotbohm
@@ -70,6 +72,7 @@ public static Update update(String column, @Nullable Object value) {
 	 * @param value can be {@literal null}.
 	 * @return
 	 */
+	@CheckReturnValue
 	public Update set(String column, @Nullable Object value) {
 
 		Assert.hasText(column, "Column for update must not be null or blank");
@@ -85,6 +88,7 @@ public Update set(String column, @Nullable Object value) {
 	 * @return
 	 * @since 1.1
 	 */
+	@CheckReturnValue
 	public Update set(SqlIdentifier column, @Nullable Object value) {
 		return addMultiFieldOperation(column, value);
 	}