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) {