Introduce HGETEX command to the Spring Data Redis framework

Signed-off-by: viktoriya.kutsarova <viktoriya.kutsarova@redis.com>

Author: viktoriya-kutsarova

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

@@ -1615,6 +1615,11 @@ public List<String> hGetDel(String key, String... fields) {
         return convertAndReturn(delegate.hGetDel(serialize(key), serializeMulti(fields)), byteListToStringList);
     }
 
+    @Override
+    public List<String> hGetEx(String key, Expiration expiration, String... fields) {
+        return convertAndReturn(delegate.hGetEx(serialize(key), expiration, serializeMulti(fields)), byteListToStringList);
+    }
+
 	@Override
 	public Long incr(String key) {
 		return incr(serialize(key));
@@ -2593,6 +2598,11 @@ public List<byte[]> hGetDel(@NotNull byte[] key, @NotNull byte[]... fields) {
         return convertAndReturn(delegate.hGetDel(key, fields), Converters.identityConverter());
     }
 
+    @Override
+    public List<byte[]> hGetEx(@NotNull byte[] key, Expiration expiration, @NotNull byte[]... fields) {
+        return convertAndReturn(delegate.hGetEx(key, expiration, fields), Converters.identityConverter());
+    }
+
 	public @Nullable List<Long> applyExpiration(String key,
 			org.springframework.data.redis.core.types.Expiration expiration,
 			ExpirationOptions options, String... fields) {

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

@@ -1601,6 +1601,13 @@ default List<byte[]> hGetDel(byte[] key, byte[]... fields) {
         return hashCommands().hGetDel(key, fields);
     }
 
+    /** @deprecated in favor of {@link RedisConnection#hashCommands()}}. */
+    @Override
+    @Deprecated
+    default List<byte[]> hGetEx(byte[] key, Expiration expiration, byte[]... fields) {
+        return hashCommands().hGetEx(key, expiration, fields);
+    }
+
 	/** @deprecated in favor of {@link RedisConnection#hashCommands()}}. */
 	@Override
 	@Deprecated

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

@@ -1338,4 +1338,76 @@ default Mono<List<ByteBuffer>> hGetDel(ByteBuffer key, Collection<ByteBuffer> fi
      * @see <a href="https://redis.io/commands/hgetdel">Redis Documentation: HGETDEL</a>
      */
     Flux<MultiValueResponse<HGetDelCommand, ByteBuffer>> hGetDel(Publisher<HGetDelCommand> commands);
+
+    class HGetExCommand extends HashFieldsCommand {
+
+        private final Expiration expiration;
+
+        private HGetExCommand(@Nullable ByteBuffer key, List<ByteBuffer> fields, Expiration expiration) {
+
+            super(key, fields);
+
+            this.expiration = expiration;
+        }
+
+        /**
+         * Creates a new {@link HGetExCommand}.
+         *
+         * @param fields the {@code fields} names to apply expiration to
+         * @param expiration the {@link Expiration} to apply to the given {@literal fields}.
+         * @return new instance of {@link HGetExCommand}.
+         */
+        public static HGetExCommand expire(List<ByteBuffer> fields, Expiration expiration) {
+            return new HGetExCommand(null, fields, expiration);
+        }
+
+        /**
+         * @param key the {@literal key} from which to expire the {@literal fields} from.
+         * @return new instance of {@link HashExpireCommand}.
+         */
+        public HGetExCommand from(ByteBuffer key) {
+            return new HGetExCommand(key, getFields(), expiration);
+        }
+
+        /**
+         * Creates a new {@link HGetExCommand}.
+         *
+         * @param fields the {@code fields} names to apply expiration to
+         * @return new instance of {@link HGetExCommand}.
+         */
+        public HGetExCommand fields(Collection<ByteBuffer> fields) {
+            return new HGetExCommand(getKey(), new ArrayList<>(fields), expiration);
+        }
+
+        public Expiration getExpiration() {
+            return expiration;
+        }
+    }
+
+    /**
+     * Get the value of one or more {@literal fields} from hash at {@literal key} and optionally set expiration time or
+     * time-to-live (TTL) for given {@literal fields}.
+     *
+     * @param key must not be {@literal null}.
+     * @param fields must not be {@literal null}.
+     * @return never {@literal null}.
+     * @see <a href="https://redis.io/commands/hgetex">Redis Documentation: HGETEX</a>
+     */
+    default Mono<List<ByteBuffer>> hGetEx(ByteBuffer key, Expiration expiration, List<ByteBuffer> fields) {
+
+        Assert.notNull(key, "Key must not be null");
+        Assert.notNull(fields, "Fields must not be null");
+
+        return hGetEx(Mono.just(HGetExCommand.expire(fields, expiration).from(key))).next().map(MultiValueResponse::getOutput);
+    }
+
+    /**
+     * Get the value of one or more {@literal fields} from hash at {@literal key} and optionally set expiration time or
+     * time-to-live (TTL) for given {@literal fields}.
+     *
+     * @param commands must not be {@literal null}.
+     * @return never {@literal null}.
+     * @see <a href="https://redis.io/commands/hgetex">Redis Documentation: HGETEX</a>
+     */
+    Flux<MultiValueResponse<HGetExCommand, ByteBuffer>> hGetEx(Publisher<HGetExCommand> commands);
 }

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

@@ -25,6 +25,7 @@
 import org.jspecify.annotations.NullUnmarked;
 import org.springframework.data.redis.core.Cursor;
 import org.springframework.data.redis.core.ScanOptions;
+import org.springframework.data.redis.core.types.Expiration;
 import org.springframework.util.ObjectUtils;
 
 /**
@@ -554,4 +555,17 @@ default List<Long> hExpireAt(byte @NonNull [] key, long unixTime, byte @NonNull
      * @see <a href="https://redis.io/commands/hgetdel">Redis Documentation: HGETDEL</a>
      */
     List<byte[]> hGetDel(byte @NonNull [] key, byte @NonNull [] @NonNull... fields);
+
+    /**
+     * Get the value of one or more {@code fields} from hash at {@code key} and optionally set expiration time or
+     * time-to-live (TTL) for given {@code fields}.
+     *
+     * @param key must not be {@literal null}.
+     * @param fields must not be {@literal null}.
+     * @return empty {@link List} if key does not exist. {@literal null} when used in pipeline / transaction.
+     * @see <a href="https://redis.io/commands/hgetex">Redis Documentation: HGETEX</a>
+     */
+    List<byte[]> hGetEx(byte @NonNull [] key, Expiration expiration,
+                                byte @NonNull [] @NonNull... fields);
+
 }

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

@@ -2564,6 +2564,18 @@ List<Long> hpExpireAt(@NonNull String key, long unixTimeInMillis, ExpirationOpti
      */
     List<String> hGetDel(@NonNull String key, @NonNull String @NonNull... fields);
 
+    /**
+     * Get the value of one or more {@code fields} from hash at {@code key} and optionally set expiration time or
+     * time-to-live (TTL) for given {@code fields}.
+     *
+     * @param key must not be {@literal null}.
+     * @param fields must not be {@literal null}.
+     * @return empty {@link List} if key does not exist. {@literal null} when used in pipeline / transaction.
+     * @see <a href="https://redis.io/commands/hgetex">Redis Documentation: HGETEX</a>
+     * @see RedisHashCommands#hGetEx(byte[], Expiration, byte[]...)
+     */
+    List<String> hGetEx(@NonNull String key, Expiration expiration, @NonNull String @NonNull... fields);
+
 	// -------------------------------------------------------------------------
 	// Methods dealing with HyperLogLog
 	// -------------------------------------------------------------------------

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

@@ -15,6 +15,7 @@
  */
 package org.springframework.data.redis.connection.jedis;
 
+import org.springframework.data.redis.core.types.Expiration;
 import redis.clients.jedis.args.ExpiryOption;
 import redis.clients.jedis.params.ScanParams;
 import redis.clients.jedis.resps.ScanResult;
@@ -425,7 +426,19 @@ public List<byte[]> hGetDel(byte[] key, byte[]... fields) {
         } catch (Exception ex) {
             throw convertJedisAccessException(ex);
         }
+    }
+
+    @Override
+    public List<byte[]> hGetEx(byte[] key, Expiration expiration, byte[]... fields) {
+
+        Assert.notNull(key, "Key must not be null");
+        Assert.notNull(fields, "Fields must not be null");
 
+        try {
+            return connection.getCluster().hgetex(key, JedisConverters.toHGetExParams(expiration), fields);
+        } catch (Exception ex) {
+            throw convertJedisAccessException(ex);
+        }
     }
 
 	@Nullable

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

@@ -22,13 +22,7 @@
 import redis.clients.jedis.args.FlushMode;
 import redis.clients.jedis.args.GeoUnit;
 import redis.clients.jedis.args.ListPosition;
-import redis.clients.jedis.params.GeoRadiusParam;
-import redis.clients.jedis.params.GeoSearchParam;
-import redis.clients.jedis.params.GetExParams;
-import redis.clients.jedis.params.ScanParams;
-import redis.clients.jedis.params.SetParams;
-import redis.clients.jedis.params.SortingParams;
-import redis.clients.jedis.params.ZAddParams;
+import redis.clients.jedis.params.*;
 import redis.clients.jedis.resps.GeoRadiusResponse;
 import redis.clients.jedis.util.SafeEncoder;
 
@@ -398,6 +392,40 @@ static GetExParams toGetExParams(Expiration expiration, GetExParams params) {
 				: params.ex(expiration.getConverted(TimeUnit.SECONDS));
 	}
 
+    /**
+     * Converts a given {@link Expiration} to the according {@code HGETEX} command argument depending on
+     * {@link Expiration#isUnixTimestamp()}.
+     * <dl>
+     * <dt>{@link TimeUnit#MILLISECONDS}</dt>
+     * <dd>{@code PX|PXAT}</dd>
+     * <dt>{@link TimeUnit#SECONDS}</dt>
+     * <dd>{@code EX|EXAT}</dd>
+     * </dl>
+     *
+     * @param expiration must not be {@literal null}.
+     * @since 4.0
+     */
+    static HGetExParams toHGetExParams(Expiration expiration) {
+        return toHGetExParams(expiration, new HGetExParams());
+    }
+
+    static HGetExParams toHGetExParams(Expiration expiration, HGetExParams params) {
+
+        if (expiration.isPersistent()) {
+            return params.persist();
+        }
+
+        if (expiration.getTimeUnit() == TimeUnit.MILLISECONDS) {
+            if (expiration.isUnixTimestamp()) {
+                return params.pxAt(expiration.getExpirationTime());
+            }
+            return params.px(expiration.getExpirationTime());
+        }
+
+        return expiration.isUnixTimestamp() ? params.exAt(expiration.getConverted(TimeUnit.SECONDS))
+                : params.ex(expiration.getConverted(TimeUnit.SECONDS));
+    }
+
 	/**
 	 * Converts a given {@link SetOption} to the according {@code SET} command argument.<br />
 	 * <dl>

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

@@ -15,6 +15,7 @@
  */
 package org.springframework.data.redis.connection.jedis;
 
+import org.springframework.data.redis.core.types.Expiration;
 import redis.clients.jedis.Jedis;
 import redis.clients.jedis.args.ExpiryOption;
 import redis.clients.jedis.commands.PipelineBinaryCommands;
@@ -341,6 +342,15 @@ public List<byte[]> hGetDel(byte @NonNull [] key, byte @NonNull [] @NonNull... f
         return connection.invoke().just(Jedis::hgetdel, PipelineBinaryCommands::hgetdel, key, fields);
     }
 
+    @Override
+    public List<byte[]> hGetEx(byte @NonNull [] key, Expiration expiration, byte @NonNull [] @NonNull... fields) {
+
+        Assert.notNull(key, "Key must not be null");
+        Assert.notNull(fields, "Fields must not be null");
+
+        return connection.invoke().just(Jedis::hgetex, PipelineBinaryCommands::hgetex, key, JedisConverters.toHGetExParams(expiration), fields);
+    }
+
 	@Nullable
 	@Override
 	public Long hStrLen(byte[] key, byte[] field) {

src/main/java/org/springframework/data/redis/connection/lettuce/LettuceConnection.java

@@ -1244,8 +1244,9 @@ static class TypeHints {
 			COMMAND_OUTPUT_TYPE_MAPPING.put(ZREVRANGE, ValueListOutput.class);
 			COMMAND_OUTPUT_TYPE_MAPPING.put(ZREVRANGEBYSCORE, ValueListOutput.class);
             COMMAND_OUTPUT_TYPE_MAPPING.put(HGETDEL, ValueListOutput.class);
+            COMMAND_OUTPUT_TYPE_MAPPING.put(HGETEX, ValueListOutput.class);
 
-			// BOOLEAN
+            // BOOLEAN
 			COMMAND_OUTPUT_TYPE_MAPPING.put(EXISTS, BooleanOutput.class);
 			COMMAND_OUTPUT_TYPE_MAPPING.put(EXPIRE, BooleanOutput.class);
 			COMMAND_OUTPUT_TYPE_MAPPING.put(EXPIREAT, BooleanOutput.class);

src/main/java/org/springframework/data/redis/connection/lettuce/LettuceConverters.java

@@ -23,6 +23,8 @@
 import io.lettuce.core.cluster.models.partitions.RedisClusterNode.NodeFlag;
 
 import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.time.Instant;
 import java.util.*;
 import java.util.concurrent.TimeUnit;
 import java.util.stream.Collectors;
@@ -620,6 +622,35 @@ static GetExArgs toGetExArgs(@Nullable Expiration expiration) {
 				: args.ex(expiration.getConverted(TimeUnit.SECONDS));
 	}
 
+    /**
+     * Convert {@link Expiration} to {@link HGetExArgs}.
+     *
+     * @param expiration can be {@literal null}.
+     * @since 4.0
+     */
+    static HGetExArgs toHGetExArgs(@Nullable Expiration expiration) {
+
+        HGetExArgs args = new HGetExArgs();
+
+        if (expiration == null) {
+            return args;
+        }
+
+        if (expiration.isPersistent()) {
+            return args.persist();
+        }
+
+        if (expiration.getTimeUnit() == TimeUnit.MILLISECONDS) {
+            if (expiration.isUnixTimestamp()) {
+                return args.pxAt(Instant.ofEpochSecond(expiration.getExpirationTime()));
+            }
+            return args.px(Duration.ofMillis(expiration.getExpirationTime()));
+        }
+
+        return expiration.isUnixTimestamp() ? args.exAt(Instant.ofEpochSecond(expiration.getConverted(TimeUnit.SECONDS)))
+                : args.ex(Duration.ofSeconds(expiration.getConverted(TimeUnit.SECONDS)));
+    }
+
 	@SuppressWarnings("NullAway")
 	static Converter<List<byte[]>, Long> toTimeConverter(TimeUnit timeUnit) {