Add `@CheckReturnValue` to `Query` and `Update` API.

Closes #2145

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

@@ -27,13 +27,14 @@ import org.springframework.dao.InvalidDataAccessApiUsageException;
 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.lang.Nullable;
 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:
@@ -161,6 +162,7 @@ public class Criteria implements CriteriaDefinition {
 	 * @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");
@@ -181,6 +183,7 @@ public class Criteria implements CriteriaDefinition {
 	 * @return a new {@link Criteria} object.
 	 * @since 1.1
 	 */
+	@CheckReturnValue
 	public Criteria and(CriteriaDefinition criteria) {
 
 		Assert.notNull(criteria, "Criteria must not be null");
@@ -195,6 +198,7 @@ public class Criteria implements CriteriaDefinition {
 	 * @return a new {@link Criteria} object.
 	 */
 	@SuppressWarnings("unchecked")
+	@CheckReturnValue
 	public Criteria and(List<? extends CriteriaDefinition> criteria) {
 
 		Assert.notNull(criteria, "Criteria must not be null");
@@ -208,6 +212,7 @@ public class Criteria implements CriteriaDefinition {
 	 * @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");
@@ -228,6 +233,7 @@ public class Criteria implements CriteriaDefinition {
 	 * @return a new {@link Criteria} object.
 	 * @since 1.1
 	 */
+	@CheckReturnValue
 	public Criteria or(CriteriaDefinition criteria) {
 
 		Assert.notNull(criteria, "Criteria must not be null");
@@ -243,6 +249,7 @@ public class Criteria implements CriteriaDefinition {
 	 * @since 1.1
 	 */
 	@SuppressWarnings("unchecked")
+	@CheckReturnValue
 	public Criteria or(List<? extends CriteriaDefinition> criteria) {
 
 		Assert.notNull(criteria, "Criteria must not be null");
@@ -256,6 +263,7 @@ public class Criteria implements CriteriaDefinition {
 	 * @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 @@ import org.springframework.util.Assert;
  * @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

@@ -26,12 +26,13 @@ import java.util.stream.Collectors;
 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.lang.Nullable;
 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
@@ -93,6 +94,7 @@ public class Query {
 	 * @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");
@@ -106,6 +108,7 @@ public class Query {
 	 * @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");
@@ -120,6 +123,7 @@ public class Query {
 	 * @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");
@@ -148,6 +152,7 @@ public class Query {
 	 * @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);
 	}
@@ -158,6 +163,7 @@ public class Query {
 	 * @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);
 	}
@@ -169,6 +175,7 @@ public class Query {
 	 * @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());
@@ -187,6 +194,7 @@ public class Query {
 	 * @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

@@ -22,11 +22,13 @@ import java.util.StringJoiner;
 
 import org.springframework.data.relational.core.sql.IdentifierProcessing;
 import org.springframework.data.relational.core.sql.SqlIdentifier;
+import org.springframework.lang.CheckReturnValue;
 import org.springframework.lang.Nullable;
 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 class Update {
 	 * @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 class Update {
 	 * @return
 	 * @since 1.1
 	 */
+	@CheckReturnValue
 	public Update set(SqlIdentifier column, @Nullable Object value) {
 		return addMultiFieldOperation(column, value);
 	}