Introduce dedicated objects for time to live and status changes.

This commit introduces several value objects capturing keys and their respective time to live/status change values.

Author: christophstrobl

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

@@ -2596,6 +2596,11 @@ public List<Long> hTtl(byte[] key, byte[]... fields) {
 		return this.delegate.hTtl(key, fields);
 	}
 
+	@Override
+	public List<Long> hpTtl(byte[] key, byte[]... fields) {
+		return this.delegate.hpTtl(key, fields);
+	}
+
 	@Override
 	public List<Long> hTtl(byte[] key, TimeUnit timeUnit, byte[]... fields) {
 		return this.delegate.hTtl(key, timeUnit, fields);
@@ -2636,6 +2641,11 @@ public List<Long> hTtl(String key, TimeUnit timeUnit, String... fields) {
 		return hTtl(serialize(key), timeUnit, serializeMulti(fields));
 	}
 
+	@Override
+	public List<Long> hpTtl(String key, String... fields) {
+		return hTtl(serialize(key), serializeMulti(fields));
+	}
+
 	@Override
 	public void setClientName(byte[] name) {
 		this.delegate.setClientName(name);

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

@@ -1520,6 +1520,13 @@ default List<Long> hTtl(byte[] key, TimeUnit timeUnit, byte[]... fields) {
 		return hashCommands().hTtl(key, timeUnit, fields);
 	}
 
+	/** @deprecated in favor of {@link RedisConnection#hashCommands()}}. */
+	@Override
+	@Deprecated
+	default List<Long> hpTtl(byte[] key, byte[]... fields) {
+		return hashCommands().hpTtl(key, fields);
+	}
+
 	// GEO COMMANDS
 
 	/** @deprecated in favor of {@link RedisConnection#geoCommands()}}. */

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

@@ -15,6 +15,7 @@
  */
 package org.springframework.data.redis.connection;
 
+import java.time.Duration;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -253,37 +254,73 @@ public interface RedisHashCommands {
 	Long hStrLen(byte[] key, byte[] field);
 
 	/**
-	 * Set time to live for given {@code field} in seconds.
+	 * Set time to live for given {@code fields} in seconds.
 	 *
 	 * @param key must not be {@literal null}.
-	 * @param seconds the amount of time after which the key will be expired in seconds, must not be {@literal null}.
+	 * @param seconds the amount of time after which the fields will be expired in seconds, must not be {@literal null}.
 	 * @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.
 	 * @see <a href="https://redis.io/docs/latest/commands/hexpire/">Redis Documentation: HEXPIRE</a>
-	 * @since 3.4
+	 * @since 3.5
 	 */
 	@Nullable
 	List<Long> hExpire(byte[] key, long seconds, byte[]... fields);
 
 	/**
-	 * Set time to live for given {@code field} in milliseconds.
+	 * Set time to live for given {@code fields}.
 	 *
 	 * @param key must not be {@literal null}.
-	 * @param millis the amount of time after which the key will be expired in milliseconds, must not be {@literal null}.
+	 * @param ttl the amount of time after which the fields will be expired in {@link Duration#toSeconds() seconds} precision, must not be {@literal null}.
+	 * @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.
+	 * @see <a href="https://redis.io/docs/latest/commands/hexpire/">Redis Documentation: HEXPIRE</a>
+	 * @since 3.5
+	 */
+	@Nullable
+	default List<Long> hExpire(byte[] key, Duration ttl, byte[]... fields) {
+		return hExpire(key, ttl.toSeconds(), fields);
+	}
+
+	/**
+	 * Set time to live for given {@code fields} in milliseconds.
+	 *
+	 * @param key must not be {@literal null}.
+	 * @param millis the amount of time after which the fields will be expired in milliseconds, must not be {@literal null}.
 	 * @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.
 	 * @see <a href="https://redis.io/docs/latest/commands/hpexpire/">Redis Documentation: HPEXPIRE</a>
-	 * @since 3.4
+	 * @since 3.5
 	 */
 	@Nullable
 	List<Long> hpExpire(byte[] key, long millis, byte[]... fields);
 
+	/**
+	 * Set time to live for given {@code fields} in milliseconds.
+	 *
+	 * @param key must not be {@literal null}.
+	 * @param ttl the amount of time after which the fields will be expired in {@link Duration#toMillis() milliseconds} precision, must not be {@literal null}.
+	 * @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.
+	 * @see <a href="https://redis.io/docs/latest/commands/hpexpire/">Redis Documentation: HPEXPIRE</a>
+	 * @since 3.5
+	 */
+	@Nullable
+	default List<Long> hpExpire(byte[] key, Duration ttl, byte[]... fields) {
+		return hpExpire(key, ttl.toMillis(), fields);
+	}
+
 	/**
 	 * Set the expiration for given {@code field} as a {@literal UNIX} timestamp.
 	 *
@@ -295,7 +332,7 @@ public interface RedisHashCommands {
 	 * 	       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.
 	 * @see <a href="https://redis.io/docs/latest/commands/hexpireat/">Redis Documentation: HEXPIREAT</a>
-	 * @since 3.4
+	 * @since 3.5
 	 */
 	@Nullable
 	List<Long> hExpireAt(byte[] key, long unixTime, byte[]... fields);
@@ -311,7 +348,7 @@ public interface RedisHashCommands {
 	 * 	       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.
 	 * @see <a href="https://redis.io/docs/latest/commands/hpexpireat/">Redis Documentation: HPEXPIREAT</a>
-	 * @since 3.4
+	 * @since 3.5
 	 */
 	@Nullable
 	List<Long> hpExpireAt(byte[] key, long unixTimeInMillis, byte[]... fields);
@@ -325,27 +362,27 @@ public interface RedisHashCommands {
 	 * 	       {@code -1} field has no expiration time to be removed; {@code -2} indicating there is no such field;
 	 * 	       {@literal null} when used in pipeline / transaction.{@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hpersist/">Redis Documentation: HPERSIST</a>
-	 * @since 3.4
+	 * @since 3.5
 	 */
 	@Nullable
 	List<Long> hPersist(byte[] key, byte[]... fields);
 
 	/**
-	 * Get the time to live for {@code field} in seconds.
+	 * Get the time to live for {@code fields} in seconds.
 	 *
 	 * @param key must not be {@literal null}.
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: the time to live in seconds; or a negative value
-	 *         to signal an error. The command returns {@code -1} if the key exists but has no associated expiration time.
-	 * 	       The command returns {@code -2} if the key does not exist; {@literal null} when used in pipeline / transaction.
+	 *         to signal an error. The command returns {@code -1} if the field exists but has no associated expiration time.
+	 * 	       The command returns {@code -2} if the field does not exist; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hexpire/">Redis Documentation: HTTL</a>
-	 * @since 3.4
+	 * @since 3.5
 	 */
 	@Nullable
 	List<Long> hTtl(byte[] key, byte[]... fields);
 
 	/**
-	 * Get the time to live for {@code field} in and convert it to the given {@link TimeUnit}.
+	 * Get the time to live for {@code fields} in and convert it to the given {@link TimeUnit}.
 	 *
 	 * @param key must not be {@literal null}.
 	 * @param timeUnit must not be {@literal null}.
@@ -354,8 +391,24 @@ public interface RedisHashCommands {
 	 *         to signal an error. The command returns {@code -1} if the key exists but has no associated expiration time.
 	 * 	       The command returns {@code -2} if the key does not exist; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hexpire/">Redis Documentation: HTTL</a>
-	 * @since 3.4
+	 * @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);
+
+	/**
+	 * Get the time to live for {@code fields} in milliseconds.
+	 *
+	 * @param key must not be {@literal null}.
+	 * @param fields must not be {@literal null}.
+	 * @return a list of {@link Long} values for each of the fields provided: the time to live in seconds; or a negative value
+	 *         to signal an error. The command returns {@code -1} if the key exists but has no associated expiration time.
+	 * 	       The command returns {@code -2} if the key does not exist; {@literal null} when used in pipeline / transaction.
+	 * @see <a href="https://redis.io/docs/latest/commands/hexpire/">Redis Documentation: HTTL</a>
+	 * @since 3.5
+	 */
+	@Nullable
+	List<Long> hpTtl(byte[] key, byte[]... fields);
 }

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

@@ -16,6 +16,7 @@
 package org.springframework.data.redis.connection;
 
 import java.time.Duration;
+import java.time.Instant;
 import java.util.List;
 import java.util.Set;
 import java.util.concurrent.TimeUnit;
@@ -191,6 +192,20 @@ default Cursor<byte[]> scan(KeyScanOptions options) {
 	@Nullable
 	Boolean expire(byte[] key, long seconds);
 
+	/**
+	 * Set time to live for given {@code key} using {@link Duration#toSeconds() seconds} precision.
+	 *
+	 * @param key must not be {@literal null}.
+	 * @param duration
+	 * @return {@literal null} when used in pipeline / transaction.
+	 * @see <a href="https://redis.io/commands/expire">Redis Documentation: EXPIRE</a>
+	 * @since 3.5
+	 */
+	@Nullable
+	default Boolean expire(byte[] key, Duration duration) {
+		return expire(key, duration.toSeconds());
+	}
+
 	/**
 	 * Set time to live for given {@code key} in milliseconds.
 	 *
@@ -202,6 +217,20 @@ default Cursor<byte[]> scan(KeyScanOptions options) {
 	@Nullable
 	Boolean pExpire(byte[] key, long millis);
 
+	/**
+	 * Set time to live for given {@code key} using {@link Duration#toMillis() milliseconds} precision.
+	 *
+	 * @param key must not be {@literal null}.
+	 * @param duration
+	 * @return {@literal null} when used in pipeline / transaction.
+	 * @see <a href="https://redis.io/commands/pexpire">Redis Documentation: PEXPIRE</a>
+	 * @since 3.5
+	 */
+	@Nullable
+	default Boolean pExpire(byte[] key, Duration duration) {
+		return pExpire(key, duration.toMillis());
+	}
+
 	/**
 	 * Set the expiration for given {@code key} as a {@literal UNIX} timestamp.
 	 *
@@ -213,6 +242,21 @@ default Cursor<byte[]> scan(KeyScanOptions options) {
 	@Nullable
 	Boolean expireAt(byte[] key, long unixTime);
 
+	/**
+	 * Set the expiration for given {@code key} as a {@literal UNIX} timestamp in {@link Instant#getEpochSecond() seconds}
+	 * precision.
+	 *
+	 * @param key must not be {@literal null}.
+	 * @param unixTime
+	 * @return {@literal null} when used in pipeline / transaction.
+	 * @see <a href="https://redis.io/commands/expireat">Redis Documentation: EXPIREAT</a>
+	 * @since 3.5
+	 */
+	@Nullable
+	default Boolean expireAt(byte[] key, Instant unixTime) {
+		return expireAt(key, unixTime.getEpochSecond());
+	}
+
 	/**
 	 * Set the expiration for given {@code key} as a {@literal UNIX} timestamp in milliseconds.
 	 *
@@ -224,6 +268,21 @@ default Cursor<byte[]> scan(KeyScanOptions options) {
 	@Nullable
 	Boolean pExpireAt(byte[] key, long unixTimeInMillis);
 
+	/**
+	 * Set the expiration for given {@code key} as a {@literal UNIX} timestamp in {@link Instant#toEpochMilli()
+	 * milliseconds} precision.
+	 *
+	 * @param key must not be {@literal null}.
+	 * @param unixTime
+	 * @return {@literal null} when used in pipeline / transaction.
+	 * @see <a href="https://redis.io/commands/pexpireat">Redis Documentation: PEXPIREAT</a>
+	 * @since 3.5
+	 */
+	@Nullable
+	default Boolean pExpireAt(byte[] key, Instant unixTime) {
+		return pExpireAt(key, unixTime.toEpochMilli());
+	}
+
 	/**
 	 * Remove the expiration from given {@code key}.
 	 *

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

@@ -2333,6 +2333,7 @@ Long zRangeStoreRevByScore(String dstKey, String srcKey,
 	@Nullable
 	Long hStrLen(String key, String field);
 
+	// TODO: why why whay is this such a shitty api that there's missing all the NX, XX, GT Options
 	/**
 	 * Set time to live for given {@code field} in seconds.
 	 *
@@ -2412,21 +2413,21 @@ Long zRangeStoreRevByScore(String dstKey, String srcKey,
 	List<Long> hPersist(String key, String... fields);
 
 	/**
-	 * Get the time to live for {@code field} in seconds.
+	 * Get the time to live for {@code fields} in seconds.
 	 *
 	 * @param key must not be {@literal null}.
 	 * @param fields must not be {@literal null}.
 	 * @return a list of {@link Long} values for each of the fields provided: the time to live in milliseconds; or a negative value
 	 * 	       to signal an error. The command returns {@code -1} if the key exists but has no associated expiration time.
 	 * 	       The command returns {@code -2} if the key does not exist; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hexpire/">Redis Documentation: HTTL</a>
-	 * @since 3.4
+	 * @since 3.5
 	 */
 	@Nullable
 	List<Long> hTtl(String key, String... fields);
 
 	/**
-	 * Get the time to live for {@code field} in and convert it to the given {@link TimeUnit}.
+	 * Get the time to live for {@code fields} in and convert it to the given {@link TimeUnit}.
 	 *
 	 * @param key must not be {@literal null}.
 	 * @param timeUnit must not be {@literal null}.
@@ -2435,11 +2436,25 @@ Long zRangeStoreRevByScore(String dstKey, String srcKey,
 	 *         to signal an error. The command returns {@code -1} if the key exists but has no associated expiration time.
 	 * 	       The command returns {@code -2} if the key does not exist; {@literal null} when used in pipeline / transaction.
 	 * @see <a href="https://redis.io/docs/latest/commands/hexpire/">Redis Documentation: HTTL</a>
-	 * @since 3.4
+	 * @since 3.5
 	 */
 	@Nullable
 	List<Long> hTtl(String key, TimeUnit timeUnit, String... fields);
 
+	/**
+	 * Get the time to live for {@code fields} in seconds.
+	 *
+	 * @param key must not be {@literal null}.
+	 * @param fields must not be {@literal null}.
+	 * @return a list of {@link Long} values for each of the fields provided: the time to live in milliseconds; or a negative value
+	 * 	       to signal an error. The command returns {@code -1} if the key exists but has no associated expiration time.
+	 * 	       The command returns {@code -2} if the key does not exist; {@literal null} when used in pipeline / transaction.
+	 * @see <a href="https://redis.io/docs/latest/commands/hexpire/">Redis Documentation: HTTL</a>
+	 * @since 3.5
+	 */
+	@Nullable
+	List<Long> hpTtl(String key, String... fields);
+
 	// -------------------------------------------------------------------------
 	// Methods dealing with HyperLogLog
 	// -------------------------------------------------------------------------

src/main/java/org/springframework/data/redis/connection/jedis/JedisClusterHashCommands.java

@@ -375,6 +375,18 @@ public List<Long> hTtl(byte[] key, TimeUnit timeUnit, byte[]... fields) {
 		}
 	}
 
+	@Override
+	public List<Long> hpTtl(byte[] key, byte[]... fields) {
+		Assert.notNull(key, "Key must not be null");
+		Assert.notNull(fields, "Fields must not be null");
+
+		try {
+			return connection.getCluster().hpttl(key, fields);
+		} catch (Exception ex) {
+			throw convertJedisAccessException(ex);
+		}
+	}
+
 	@Nullable
 	@Override
 	public Long hStrLen(byte[] key, byte[] field) {

src/main/java/org/springframework/data/redis/connection/jedis/JedisHashCommands.java

@@ -288,6 +288,11 @@ public List<Long> hTtl(byte[] key, TimeUnit timeUnit, byte[]... fields) {
 				.toList(Converters.secondsToTimeUnit(timeUnit));
 	}
 
+	@Override
+	public List<Long> hpTtl(byte[] key, byte[]... fields) {
+		return connection.invoke().just(Jedis::hpttl, PipelineBinaryCommands::hpttl, key, fields);
+	}
+
 	@Nullable
 	@Override
 	public Long hStrLen(byte[] key, byte[] field) {