diff --git a/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Criteria.java b/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Criteria.java index 77cbe80d1..8cbba520e 100644 --- a/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Criteria.java +++ b/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(…)}. *

* 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 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 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); diff --git a/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/CriteriaDefinition.java b/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/CriteriaDefinition.java index c09129a1b..89ce03e2f 100644 --- a/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/CriteriaDefinition.java +++ b/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 { diff --git a/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Query.java b/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Query.java index 3a8e9d72c..ef2b879e0 100644 --- a/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Query.java +++ b/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 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"); diff --git a/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Update.java b/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Update.java index ceaabf69b..4ea6a6af2 100644 --- a/spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Update.java +++ b/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); }