Polishing.

Update javadoc and format sources. See #3054.
spring-projects · Mar 5, 2025 · 06f3591 · 06f3591
1 parent c6ba95f
commit 06f3591
Show file tree

Hide file tree

Showing 15 changed files with 432 additions and 294 deletions.
diff --git a/src/main/java/org/springframework/data/redis/connection/ReactiveHashCommands.java b/src/main/java/org/springframework/data/redis/connection/ReactiveHashCommands.java
@@ -865,22 +865,52 @@ private ExpireCommand(@Nullable ByteBuffer key, List<ByteBuffer> fields, Expirat
 			this.options = options;
 		}
 
+		/**
+		 * Creates a new {@link ExpireCommand}.
+		 *
+		 * @param fields the {@code field} names to apply expiration to
+		 * @param timeout the actual timeout
+		 * @param unit the unit of measure for the {@code timeout}.
+		 * @return new instance of {@link ExpireCommand}.
+		 */
 		public static ExpireCommand expire(List<ByteBuffer> fields, long timeout, TimeUnit unit) {
 
 			Assert.notNull(fields, "Field must not be null");
 			return expire(fields, Expiration.from(timeout, unit));
 		}
 
+		/**
+		 * Creates a new {@link ExpireCommand}.
+		 *
+		 * @param fields the {@code field} names to apply expiration to.
+		 * @param ttl the actual timeout.
+		 * @return new instance of {@link ExpireCommand}.
+		 */
 		public static ExpireCommand expire(List<ByteBuffer> fields, Duration ttl) {
 
 			Assert.notNull(fields, "Field must not be null");
 			return expire(fields, Expiration.from(ttl));
 		}
 
+		/**
+		 * Creates a new {@link ExpireCommand}.
+		 *
+		 * @param fields the {@code field} names to apply expiration to
+		 * @param expiration the {@link Expiration} to apply to the given {@literal fields}.
+		 * @return new instance of {@link ExpireCommand}.
+		 */
 		public static ExpireCommand expire(List<ByteBuffer> fields, Expiration expiration) {
 			return new ExpireCommand(null, fields, expiration, FieldExpirationOptions.none());
 		}
 
+		/**
+		 * Creates a new {@link ExpireCommand}.
+		 *
+		 * @param fields the {@code field} names to apply expiration to
+		 * @param ttl the unix point in time when to expire the given {@literal fields}.
+		 * @param precision can be {@link TimeUnit#SECONDS} or {@link TimeUnit#MILLISECONDS}.
+		 * @return new instance of {@link ExpireCommand}.
+		 */
 		public static ExpireCommand expireAt(List<ByteBuffer> fields, Instant ttl, TimeUnit precision) {
 
 			if (precision.compareTo(TimeUnit.MILLISECONDS) > 0) {
@@ -890,10 +920,18 @@ public static ExpireCommand expireAt(List<ByteBuffer> fields, Instant ttl, TimeU
 			return expire(fields, Expiration.unixTimestamp(ttl.toEpochMilli(), TimeUnit.MILLISECONDS));
 		}
 
+		/**
+		 * @param key the {@literal key} from which to expire the {@literal fields} from.
+		 * @return new instance of {@link ExpireCommand}.
+		 */
 		public ExpireCommand from(ByteBuffer key) {
 			return new ExpireCommand(key, getFields(), expiration, options);
 		}
 
+		/**
+		 * @param options additional options to be sent along with the command.
+		 * @return new instance of {@link ExpireCommand}.
+		 */
 		public ExpireCommand withOptions(FieldExpirationOptions options) {
 			return new ExpireCommand(getKey(), getFields(), getExpiration(), options);
 		}

diff --git a/src/main/java/org/springframework/data/redis/connection/RedisHashCommands.java b/src/main/java/org/springframework/data/redis/connection/RedisHashCommands.java
@@ -255,11 +255,34 @@ public interface RedisHashCommands {
 	@Nullable
 	Long hStrLen(byte[] key, byte[] field);
 
+	/**
+	 * Apply a given {@link org.springframework.data.redis.core.types.Expiration} to the given {@literal fields}.
+	 * 
+	 * @param key must not be {@literal null}.
+	 * @param expiration the {@link org.springframework.data.redis.core.types.Expiration} to apply.
+	 * @param fields the names of the {@literal fields} to apply the {@literal expiration} to.
+	 * @return a {@link List} holding the command result for each field in order - {@code 2} indicating the specific field
+	 *         is deleted already due to expiration, or provided expiry interval is 0; {@code 1} indicating expiration
+	 *         time is set/updated; {@code 0} indicating the expiration time is not set; {@code -2} indicating there is no
+	 *         such field;
+	 * @since 3.5
+	 */
 	default @Nullable List<Long> applyExpiration(byte[] key,
 			org.springframework.data.redis.core.types.Expiration expiration, byte[]... fields) {
 		return applyExpiration(key, expiration, FieldExpirationOptions.none(), fields);
 	}
 
+	/**
+	 * @param key must not be {@literal null}.
+	 * @param expiration the {@link org.springframework.data.redis.core.types.Expiration} to apply.
+	 * @param options additional options to be sent along with the command.
+	 * @param fields the names of the {@literal fields} to apply the {@literal expiration} to.
+	 * @return a {@link List} holding the command result for each field in order - {@code 2} indicating the specific field
+	 *         is deleted already due to expiration, or provided expiry interval is 0; {@code 1} indicating expiration
+	 *         time is set/updated; {@code 0} indicating the expiration time is not set (a provided NX | XX | GT | LT
+	 *         condition is not met); {@code -2} indicating there is no such field;
+	 * @since 3.5
+	 */
 	@Nullable
 	default List<Long> applyExpiration(byte[] key, org.springframework.data.redis.core.types.Expiration expiration,
 			FieldExpirationOptions options, byte[]... fields) {
@@ -304,9 +327,8 @@ default List<Long> applyExpiration(byte[] key, org.springframework.data.redis.co
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: {@code 2} indicating the specific field is
 	 *         deleted already due to expiration, or provided expiry interval is 0; {@code 1} indicating expiration time
-	 *         is set/updated; {@code 0} indicating the expiration time is not set (a provided NX | XX | GT | LT condition
-	 *         is not met); {@code -2} indicating there is no such field; {@literal null} when used in pipeline /
-	 *         transaction.
+	 *         is set/updated; {@code 0} indicating the expiration time is not set; {@code -2} indicating there is no such
+	 *         field; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hexpire/">Redis Documentation: HEXPIRE</a>
 	 * @since 3.5
 	 */
@@ -324,9 +346,8 @@ default List<Long> hExpire(byte[] key, long seconds, byte[]... fields) {
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: {@code 2} indicating the specific field is
 	 *         deleted already due to expiration, or provided expiry interval is 0; {@code 1} indicating expiration time
-	 *         is set/updated; {@code 0} indicating the expiration time is not set (a provided NX | XX | GT | LT condition
-	 *         is not met); {@code -2} indicating there is no such field; {@literal null} when used in pipeline /
-	 *         transaction.
+	 *         is set/updated; {@code 0} indicating the expiration time is not set; {@code -2} indicating there is no such
+	 *         field; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hexpire/">Redis Documentation: HEXPIRE</a>
 	 * @since 3.5
 	 */
@@ -362,9 +383,8 @@ default List<Long> hExpire(byte[] key, Duration ttl, byte[]... fields) {
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: {@code 2} indicating the specific field is
 	 *         deleted already due to expiration, or provided expiry interval is 0; {@code 1} indicating expiration time
-	 *         is set/updated; {@code 0} indicating the expiration time is not set (a provided NX | XX | GT | LT condition
-	 *         is not met); {@code -2} indicating there is no such field; {@literal null} when used in pipeline /
-	 *         transaction.
+	 *         is set/updated; {@code 0} indicating the expiration time is not set ; {@code -2} indicating there is no
+	 *         such field; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hpexpire/">Redis Documentation: HPEXPIRE</a>
 	 * @since 3.5
 	 */
@@ -382,9 +402,8 @@ default List<Long> hpExpire(byte[] key, long millis, byte[]... fields) {
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: {@code 2} indicating the specific field is
 	 *         deleted already due to expiration, or provided expiry interval is 0; {@code 1} indicating expiration time
-	 *         is set/updated; {@code 0} indicating the expiration time is not set (a provided NX | XX | GT | LT condition
-	 *         is not met); {@code -2} indicating there is no such field; {@literal null} when used in pipeline /
-	 *         transaction.
+	 *         is set/updated; {@code 0} indicating the expiration time is not set; {@code -2} indicating there is no such
+	 *         field; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hpexpire/">Redis Documentation: HPEXPIRE</a>
 	 * @since 3.5
 	 */
@@ -420,9 +439,8 @@ default List<Long> hpExpire(byte[] key, Duration ttl, byte[]... fields) {
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: {@code 2} indicating the specific field is
 	 *         deleted already due to expiration, or provided expiry interval is in the past; {@code 1} indicating
-	 *         expiration time is set/updated; {@code 0} indicating the expiration time is not set (a provided NX | XX |
-	 *         GT | LT condition is not met); {@code -2} indicating there is no such field; {@literal null} when used in
-	 *         pipeline / transaction.
+	 *         expiration time is set/updated; {@code 0} indicating the expiration time is not set; {@code -2} indicating
+	 *         there is no such field; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hexpireat/">Redis Documentation: HEXPIREAT</a>
 	 * @since 3.5
 	 */
@@ -457,9 +475,8 @@ default List<Long> hExpireAt(byte[] key, long unixTime, byte[]... fields) {
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: {@code 2} indicating the specific field is
 	 *         deleted already due to expiration, or provided expiry interval is in the past; {@code 1} indicating
-	 *         expiration time is set/updated; {@code 0} indicating the expiration time is not set (a provided NX | XX |
-	 *         GT | LT condition is not met); {@code -2} indicating there is no such field; {@literal null} when used in
-	 *         pipeline / transaction.
+	 *         expiration time is set/updated; {@code 0} indicating the expiration time is not set; {@code -2} indicating
+	 *         there is no such field; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hpexpireat/">Redis Documentation: HPEXPIREAT</a>
 	 * @since 3.5
 	 */
@@ -531,8 +548,6 @@ List<Long> hpExpireAt(byte[] key, long unixTimeInMillis, FieldExpirationOptions.
 	 * @since 3.5
 	 */
 	@Nullable
-	// TODO: this is complete nonsense as it would jeopardize negative values
-	// TODO: this should be a List<Map.Entry<byte, Expiration>>
 	List<Long> hTtl(byte[] key, TimeUnit timeUnit, byte[]... fields);
 
 	/**

diff --git a/src/main/java/org/springframework/data/redis/connection/StringRedisConnection.java b/src/main/java/org/springframework/data/redis/connection/StringRedisConnection.java
@@ -2341,9 +2341,8 @@ Long zRangeStoreRevByScore(String dstKey, String srcKey,
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: {@code 2} indicating the specific field is
 	 *         deleted already due to expiration, or provided expiry interval is 0; {@code 1} indicating expiration time
-	 *         is set/updated; {@code 0} indicating the expiration time is not set (a provided NX | XX | GT | LT condition
-	 *         is not met); {@code -2} indicating there is no such field; {@literal null} when used in pipeline /
-	 *         transaction.
+	 *         is set/updated; {@code 0} indicating the expiration time is not set; {@code -2} indicating there is no such
+	 *         field; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hexpire/">Redis Documentation: HEXPIRE</a>
 	 * @since 3.5
 	 */
@@ -2377,9 +2376,8 @@ default List<Long> hExpire(String key, long seconds, String... fields) {
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: {@code 2} indicating the specific field is
 	 *         deleted already due to expiration, or provided expiry interval is 0; {@code 1} indicating expiration time
-	 *         is set/updated; {@code 0} indicating the expiration time is not set (a provided NX | XX | GT | LT condition
-	 *         is not met); {@code -2} indicating there is no such field; {@literal null} when used in pipeline /
-	 *         transaction.
+	 *         is set/updated; {@code 0} indicating the expiration time is not set; {@code -2} indicating there is no such
+	 *         field; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hpexpire/">Redis Documentation: HPEXPIRE</a>
 	 * @since 3.5
 	 */
@@ -2413,9 +2411,8 @@ default List<Long> hpExpire(String key, long millis, String... fields) {
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: {@code 2} indicating the specific field is
 	 *         deleted already due to expiration, or provided expiry interval is in the past; {@code 1} indicating
-	 *         expiration time is set/updated; {@code 0} indicating the expiration time is not set (a provided NX | XX |
-	 *         GT | LT condition is not met); {@code -2} indicating there is no such field; {@literal null} when used in
-	 *         pipeline / transaction.
+	 *         expiration time is set/updated; {@code 0} indicating the expiration time is not set; {@code -2} indicating
+	 *         there is no such field; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hexpireat/">Redis Documentation: HEXPIREAT</a>
 	 * @since 3.5
 	 */
@@ -2449,9 +2446,8 @@ default List<Long> hExpireAt(String key, long unixTime, String... fields) {
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: {@code 2} indicating the specific field is
 	 *         deleted already due to expiration, or provided expiry interval is in the past; {@code 1} indicating
-	 *         expiration time is set/updated; {@code 0} indicating the expiration time is not set (a provided NX | XX |
-	 *         GT | LT condition is not met); {@code -2} indicating there is no such field; {@literal null} when used in
-	 *         pipeline / transaction.
+	 *         expiration time is set/updated; {@code 0} indicating the expiration time is not set; {@code -2} indicating
+	 *         there is no such field; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hpexpireat/">Redis Documentation: HPEXPIREAT</a>
 	 * @since 3.5
 	 */