Document conditional set return values.

Closes #3414

Author: mhalbritter

src/main/java/org/springframework/data/redis/connection/ReactiveStringCommands.java

@@ -172,7 +172,7 @@ default Mono<Boolean> set(ByteBuffer key, ByteBuffer value) {
 	 * @param expiration must not be {@literal null}. Use {@link Expiration#persistent()} for no expiration time or
 	 *          {@link Expiration#keepTtl()} to keep the existing.
 	 * @param option must not be {@literal null}.
-	 * @return
+	 * @return {@literal true} if the value was set, {@literal false} if {@literal option} was not met.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 */
 	default Mono<Boolean> set(ByteBuffer key, ByteBuffer value, Expiration expiration, SetOption option) {
@@ -188,7 +188,8 @@ default Mono<Boolean> set(ByteBuffer key, ByteBuffer value, Expiration expiratio
 	 * Set each and every item separately by invoking {@link SetCommand}.
 	 *
 	 * @param commands must not be {@literal null}.
-	 * @return {@link Flux} of {@link BooleanResponse} holding the {@link SetCommand} along with the command result.
+	 * @return {@link Flux} of {@link BooleanResponse} holding the {@link SetCommand} along with {@literal true} if the
+	 *         value was set, {@literal false} if the command's condition was not met.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 */
 	Flux<BooleanResponse<SetCommand>> set(Publisher<SetCommand> commands);
@@ -412,7 +413,7 @@ default Mono<List<ByteBuffer>> mGet(List<ByteBuffer> keys) {
 	 *
 	 * @param key must not be {@literal null}.
 	 * @param value must not be {@literal null}.
-	 * @return
+	 * @return {@literal true} if the value was set, {@literal false} if {@literal key} already exists.
 	 * @see <a href="https://redis.io/commands/setnx">Redis Documentation: SETNX</a>
 	 */
 	default Mono<Boolean> setNX(ByteBuffer key, ByteBuffer value) {
@@ -427,7 +428,8 @@ default Mono<Boolean> setNX(ByteBuffer key, ByteBuffer value) {
 	 * Set {@literal key value} pairs, only if {@literal key} does not exist.
 	 *
 	 * @param values must not be {@literal null}.
-	 * @return
+	 * @return {@link Flux} of {@link BooleanResponse} holding the {@link SetCommand} along with {@literal true} if the
+	 *         value was set, {@literal false} if {@literal key} already exists.
 	 * @see <a href="https://redis.io/commands/setnx">Redis Documentation: SETNX</a>
 	 */
 	Flux<BooleanResponse<SetCommand>> setNX(Publisher<SetCommand> values);
@@ -556,7 +558,8 @@ default Mono<Boolean> mSet(Map<ByteBuffer, ByteBuffer> keyValuePairs) {
 	 * provided key does not exist.
 	 *
 	 * @param keyValuePairs must not be {@literal null}.
-	 * @return
+	 * @return {@literal true} if all keys were set, {@literal false} if at least one key already exists, in which case
+	 *         no key is set.
 	 * @see <a href="https://redis.io/commands/msetnx">Redis Documentation: MSETNX</a>
 	 */
 	default Mono<Boolean> mSetNX(Map<ByteBuffer, ByteBuffer> keyValuePairs) {
@@ -571,7 +574,8 @@ default Mono<Boolean> mSetNX(Map<ByteBuffer, ByteBuffer> keyValuePairs) {
 	 * does not exist.
 	 *
 	 * @param source must not be {@literal null}.
-	 * @return
+	 * @return {@link Flux} of {@link BooleanResponse} holding the {@link MSetCommand} along with {@literal true} if all
+	 *         keys were set, {@literal false} if at least one key already exists, in which case no key is set.
 	 * @see <a href="https://redis.io/commands/msetnx">Redis Documentation: MSETNX</a>
 	 */
 	Flux<BooleanResponse<MSetCommand>> mSetNX(Publisher<MSetCommand> source);

src/main/java/org/springframework/data/redis/connection/RedisStringCommands.java

@@ -114,7 +114,8 @@ enum BitOperation {
 	 * @param expiration must not be {@literal null}. Use {@link Expiration#persistent()} to not set any ttl or
 	 *          {@link Expiration#keepTtl()} to keep the existing expiration.
 	 * @param option must not be {@literal null}. Use {@link SetOption#upsert()} to add non existing.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if the value was set, {@literal false} if {@code option} was not met. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @since 1.7
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 */
@@ -141,7 +142,8 @@ byte[] setGet(byte @NonNull [] key, byte @NonNull [] value, @NonNull Expiration
 	 *
 	 * @param key must not be {@literal null}.
 	 * @param value must not be {@literal null}.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} already exists. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/commands/setnx">Redis Documentation: SETNX</a>
 	 */
 	Boolean setNX(byte @NonNull [] key, byte @NonNull [] value);
@@ -183,7 +185,8 @@ byte[] setGet(byte @NonNull [] key, byte @NonNull [] value, @NonNull Expiration
 	 * not exist.
 	 *
 	 * @param tuple must not be {@literal null}.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if all keys were set, {@literal false} if at least one key already exists, in which case
+	 *         no key is set. {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/commands/msetnx">Redis Documentation: MSETNX</a>
 	 */
 	Boolean mSetNX(@NonNull Map<byte @NonNull [], byte @NonNull []> tuple);

src/main/java/org/springframework/data/redis/connection/StringRedisConnection.java

@@ -526,6 +526,8 @@ default Boolean pExpireAt(@NonNull String key, long unixTimeInMillis) {
 	 * @param expiration can be {@literal null}. Defaulted to {@link Expiration#persistent()}. Use
 	 *          {@link Expiration#keepTtl()} to keep the existing expiration.
 	 * @param option can be {@literal null}. Defaulted to {@link SetOption#UPSERT}.
+	 * @return {@literal true} if the value was set, {@literal false} if {@code option} was not met. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @since 1.7
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 * @see RedisStringCommands#set(byte[], byte[], Expiration, SetOption)
@@ -537,7 +539,8 @@ default Boolean pExpireAt(@NonNull String key, long unixTimeInMillis) {
 	 *
 	 * @param key must not be {@literal null}.
 	 * @param value must not be {@literal null}.
-	 * @return
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} already exists. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/commands/setnx">Redis Documentation: SETNX</a>
 	 * @see RedisStringCommands#setNX(byte[], byte[])
 	 */
@@ -580,6 +583,8 @@ default Boolean pExpireAt(@NonNull String key, long unixTimeInMillis) {
 	 * not exist.
 	 *
 	 * @param tuple must not be {@literal null}.
+	 * @return {@literal true} if all keys were set, {@literal false} if at least one key already exists, in which case
+	 *         no key is set. {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/commands/msetnx">Redis Documentation: MSETNX</a>
 	 * @see RedisStringCommands#mSetNX(Map)
 	 */

src/main/java/org/springframework/data/redis/core/BoundValueOperations.java

@@ -104,7 +104,8 @@ default void set(@NonNull V value, @NonNull Duration timeout) {
 	 * Set the bound key to hold the string {@code value} if the bound key is absent.
 	 *
 	 * @param value must not be {@literal null}.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if the value was set, {@literal false} if the bound key already exists. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/commands/setnx">Redis Documentation: SETNX</a>
 	 */
 	Boolean setIfAbsent(@NonNull V value);
@@ -115,7 +116,8 @@ default void set(@NonNull V value, @NonNull Duration timeout) {
 	 * @param value must not be {@literal null}.
 	 * @param timeout
 	 * @param unit must not be {@literal null}.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if the value was set, {@literal false} if the bound key already exists. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @since 2.1
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 */
@@ -126,7 +128,8 @@ default void set(@NonNull V value, @NonNull Duration timeout) {
 	 *
 	 * @param value must not be {@literal null}.
 	 * @param timeout must not be {@literal null}.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if the value was set, {@literal false} if the bound key already exists. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @throws IllegalArgumentException if either {@code value} or {@code timeout} is not present.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 * @since 2.1
@@ -146,7 +149,8 @@ default Boolean setIfAbsent(@NonNull V value, @NonNull Duration timeout) {
 	 * Set the bound key to hold the string {@code value} if the bound key is present.
 	 *
 	 * @param value must not be {@literal null}.
-	 * @return command result indicating if the key has been set.
+	 * @return {@literal true} if the value was set, {@literal false} if the bound key does not exist. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @throws IllegalArgumentException if {@code value} is not present.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 * @since 2.1
@@ -159,7 +163,8 @@ default Boolean setIfAbsent(@NonNull V value, @NonNull Duration timeout) {
 	 * @param value must not be {@literal null}.
 	 * @param timeout the key expiration timeout.
 	 * @param unit must not be {@literal null}.
-	 * @return command result indicating if the key has been set.
+	 * @return {@literal true} if the value was set, {@literal false} if the bound key does not exist. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @throws IllegalArgumentException if either {@code value} or {@code timeout} is not present.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 * @since 2.1
@@ -171,7 +176,8 @@ default Boolean setIfAbsent(@NonNull V value, @NonNull Duration timeout) {
 	 *
 	 * @param value must not be {@literal null}.
 	 * @param timeout must not be {@literal null}.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if the value was set, {@literal false} if the bound key does not exist. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @throws IllegalArgumentException if either {@code value} or {@code timeout} is not present.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 * @since 2.1

src/main/java/org/springframework/data/redis/core/ReactiveValueOperations.java

@@ -76,6 +76,7 @@ public interface ReactiveValueOperations<K, V> {
 	 *
 	 * @param key must not be {@literal null}.
 	 * @param value
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} already exists.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 */
 	Mono<Boolean> setIfAbsent(K key, V value);
@@ -86,6 +87,7 @@ public interface ReactiveValueOperations<K, V> {
 	 * @param key must not be {@literal null}.
 	 * @param value
 	 * @param timeout must not be {@literal null}.
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} already exists.
 	 * @since 2.1
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 */
@@ -96,6 +98,7 @@ public interface ReactiveValueOperations<K, V> {
 	 *
 	 * @param key must not be {@literal null}.
 	 * @param value
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} does not exist.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 */
 	Mono<Boolean> setIfPresent(K key, V value);
@@ -106,6 +109,7 @@ public interface ReactiveValueOperations<K, V> {
 	 * @param key must not be {@literal null}.
 	 * @param value
 	 * @param timeout must not be {@literal null}.
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} does not exist.
 	 * @since 2.1
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 */
@@ -124,6 +128,8 @@ public interface ReactiveValueOperations<K, V> {
 	 * not exist.
 	 *
 	 * @param map must not be {@literal null}.
+	 * @return {@literal true} if all keys were set, {@literal false} if at least one key already exists, in which case
+	 *         no key is set.
 	 * @see <a href="https://redis.io/commands/msetnx">Redis Documentation: MSETNX</a>
 	 */
 	Mono<Boolean> multiSetIfAbsent(Map<? extends K, ? extends V> map);

src/main/java/org/springframework/data/redis/core/ValueOperations.java

@@ -118,7 +118,8 @@ default void set(@NonNull K key, @NonNull V value, @NonNull Duration timeout) {
 	 *
 	 * @param key must not be {@literal null}.
 	 * @param value must not be {@literal null}.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} already exists. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 */
 	Boolean setIfAbsent(@NonNull K key, @NonNull V value);
@@ -130,7 +131,8 @@ default void set(@NonNull K key, @NonNull V value, @NonNull Duration timeout) {
 	 * @param value must not be {@literal null}.
 	 * @param timeout the key expiration timeout.
 	 * @param unit must not be {@literal null}.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} already exists. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @since 2.1
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 */
@@ -142,7 +144,8 @@ default void set(@NonNull K key, @NonNull V value, @NonNull Duration timeout) {
 	 * @param key must not be {@literal null}.
 	 * @param value must not be {@literal null}.
 	 * @param timeout must not be {@literal null}.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} already exists. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @throws IllegalArgumentException if either {@code key}, {@code value} or {@code timeout} is not present.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 * @since 2.1
@@ -163,7 +166,8 @@ default Boolean setIfAbsent(@NonNull K key, @NonNull V value, @NonNull Duration
 	 *
 	 * @param key must not be {@literal null}.
 	 * @param value must not be {@literal null}.
-	 * @return command result indicating if the key has been set.
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} does not exist. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @throws IllegalArgumentException if either {@code key} or {@code value} is not present.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 * @since 2.1
@@ -177,7 +181,8 @@ default Boolean setIfAbsent(@NonNull K key, @NonNull V value, @NonNull Duration
 	 * @param value must not be {@literal null}.
 	 * @param timeout the key expiration timeout.
 	 * @param unit must not be {@literal null}.
-	 * @return command result indicating if the key has been set.
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} does not exist. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @throws IllegalArgumentException if either {@code key}, {@code value} or {@code timeout} is not present.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 * @since 2.1
@@ -190,7 +195,8 @@ default Boolean setIfAbsent(@NonNull K key, @NonNull V value, @NonNull Duration
 	 * @param key must not be {@literal null}.
 	 * @param value must not be {@literal null}.
 	 * @param timeout must not be {@literal null}.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if the value was set, {@literal false} if {@code key} does not exist. {@literal null}
+	 *         when used in pipeline / transaction.
 	 * @throws IllegalArgumentException if either {@code key}, {@code value} or {@code timeout} is not present.
 	 * @see <a href="https://redis.io/commands/set">Redis Documentation: SET</a>
 	 * @since 2.1
@@ -219,7 +225,8 @@ default Boolean setIfPresent(@NonNull K key, @NonNull V value, @NonNull Duration
 	 * not exist.
 	 *
 	 * @param map must not be {@literal null}.
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @return {@literal true} if all keys were set, {@literal false} if at least one key already exists, in which case
+	 *         no key is set. {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/commands/msetnx">Redis Documentation: MSETNX</a>
 	 */
 	Boolean multiSetIfAbsent(Map<? extends @NonNull K, ? extends @NonNull V> map);