Redis is a data store supporting over 190 documented commands and over 450 command permutations. The community supports actively Redis development; each major Redis release comes with new commands. This year Redis was opened up for 3rd party vendors to develop modules that extend Redis functionality. Command growth and keeping track with upcoming modules are challenging for client developers and Redis users.<\/p>\n
Command growth in Redis is a challenging business for client libraries. Several clients expose a typed API that declares a method (function) signature for each Redis API call. Static declarations are beneficial for use but the amount of Redis commands pollutes clients with tons of method signatures. Some commands can be executed in different ways that affects the response type ( redis-rb<\/strong><\/p>\n jedis<\/strong><\/p>\n lettuce<\/strong><\/p>\n Declared methods provide type safety and documentation to developers, but they are static at the same time. As soon as a Redis introduces a new command, the client vendor has to change the API otherwise new commands are not usable. Most Redis clients expose a client call API to execute custom commands to address this issue:<\/p>\n redis-rb<\/strong><\/p>\n jedis<\/strong><\/p>\n lettuce<\/strong><\/p>\n Jedipus<\/strong><\/p>\n Other clients, like Constructing a Redis command requires knowledge about its request and response structure. This knowledge is written down at a location inside of the calling code. This is handy because you put it in the place where you need the code, but it comes with a few downsides. Because custom commands are run from inside a method, custom commands require additional effort to be reusable. The typical method signature as found on many clients is not required. This approach makes introspection more challenging, if not following an API component approach. This is, because all custom commands call the same method with just different arguments.<\/p>\n The nature of static method declarations with a fixed parameter list is limited to accept the provided parameters only. Contextual controls to method calls cannot be applied through that method. Lettuce for example provides a synchronous API that allows controlling the command timeout for all commands but not on command invocation level.<\/p>\n Let\u2019s approach Redis with a dynamic API.<\/p>\n Dynamic APIs are programming interfaces that give a certain amount of flexibility because they follow conventions. Dynamic APIs might be known from Resteasy Client Proxies<\/a> or Spring Data\u2019s Query Derivation<\/a>. Both are interfaces that live in userland code. Resteasy\/Spring Data inspect the interfaces and implement those by providing Java proxies. Method calls on these interfaces (proxies) are intercepted, inspected and translated into the according call. Let\u2019s see how this could work for Java and Redis: A simple command interface<\/em><\/p>\n The interface from above declares one method: The command from above called would look like:<\/p>\n and translated to a Redis Command:<\/p>\n The declaration on an interface comes with two interesting properties:<\/p>\n Multiple execution models<\/strong><\/p>\n A dynamic API allows variance in return types. Let\u2019s see how this affects the things we could derive from their return types.<\/p>\n Command structure<\/strong><\/p>\n Java requires methods to vary in name or parameter types. Variance in just the return type is supported at bytecode level but not when writing methods in your code. What if you want to declare one synchronously executed method and one that asynchronously executed taking the same parameters? You need to specify a different name. But doesn\u2019t this clash with the previously explained name derivation? It does.<\/p>\n Applying a dynamic API to Redis shifts the view to a new perspective. It can provide a simplified custom command approach to users without sacrificing reusability. The nature of method declaration creates a place for documentation and introspection regarding its callers.<\/p>\n A dynamic API is beneficial also to other applications using RESP such as Disque<\/a> or Tile38<\/a>.<\/p>\n An experimental implementation is available with lettuce<\/a> from Sonatype\u2019s OSS Snapshot repository https:\/\/oss.sonatype.org\/content\/repositories\/snapshots\/<\/a>:<\/p>\n Using RedisCommandFactory<\/em><\/p>\nZREVRANGE<\/code>, ZREVRANGE \u2026 WITHSCORES<\/code>) that require additional signatures. Let\u2019s take a closer look on some method signatures:<\/p>\n# Get the values of all the given hash fields.\r\n# \r\n# @example\r\n# redis.hmget(\"hash\", \"f1\", \"f2\")\r\n def hmget(key, *fields, &blk)<\/pre>\n
public List<String> hmget(final String key, final String... fields)<\/pre>\n
List<V>\r\npublic List<K> hmget(K key, K... fields)<\/pre>\n
client.call([:hmget, key] + fields)<\/pre>\n
final byte[][] params = \u2026;\r\njedis.sendCommand(HMGET, params);<\/pre>\n
lettuce.dispatch(CommandType.HMGET, new ValueListOutput<>(codec),\r\nnew CommandArgs<>(codec)\r\n .addKey(key)\r\n .addKey(field));<\/pre>\n
rce.accept(client -> client.sendCmd(Cmds.HMGET, \"hash\", \"field1\", \"field2\", \u2026));<\/pre>\n
node_redis<\/code> create function prototypes based on Redis commands. This is an improvement to static APIs because it enables a certain flexibility in the API.<\/p>\nDynamic API<\/h2>\n
public interface MyRedisCommands {\r\n\r\n List<String> hmget(String key, String... values);\r\n\r\n}<\/pre>\nList<String > hmget(String key, String... fields)<\/code>. We can derive from that declaration certain things:<\/p>\n\n
List<\/code> of String<\/code>s \u2013 that tells us about the command result expectation, so we expect a Redis array and convert each item into a string<\/li>\nhmget<\/code>. As that\u2019s the only detail available, we assume the command is named hmget<\/code>.<\/li>\nString key<\/code> and String... values<\/code>. This tells us about the order of parameters and their types. Although Redis does not take any other parameter types than bulk strings, we still can apply a transformation to the parameters \u2013 we can conclude their serialization from the declared type.<\/li>\n<\/ul>\ncommands.hmget(\"key\", \"field1\", \"field2\");<\/pre>\n
HMGET key field1 field2<\/pre>\n
\n
public interface MyRedisCommands {\r\n\r\n List<String> hmget(Timeout timeout, String key, String... values);\r\n\r\n RedisFuture<List<String>> mget(String... keys);\r\n\r\n Flux<String> smembers(String key);\r\n\r\n}<\/pre>\n\n
hmget<\/code> is executed in a blocking way. But wait, what\u2019s that Timeout<\/code> parameter? This is an own parameter type to declare a timeout on invocation level. The underlying execution applies timeouts from the parameter and no longer the defaults set on connection level.<\/li>\nmget<\/code> declares a RedisFuture<\/code> return type wrapping a List<\/code> of String<\/code>. RedisFuture<\/code> is a wrapper type for asynchronous execution and returns a handle to perform synchronization or method chaining in a later stage. This method could be executed asynchronously.<\/li>\nsmembers<\/code> uses Flux<\/code> of String<\/code>. Based on the return type we can expect two properties: Flux<\/code> is a reactive execution wrapper that delay execution until a subscriber subscribes to the Flux<\/code>. The List<\/code> type is gone because a Flux<\/code> can emit 0..N<\/code> items so we can decide for a streaming reactive execution.<\/li>\n<\/ul>\npublic interface MyRedisCommands {\r\n\r\n List<String> mget(String... keys);\r\n\r\n @Command(\"MGET\")\r\n RedisFuture<List<String>> mgetAsync(String... keys);\r\n\r\n @CommandNaming(strategy = DOT)\r\n double nrRun(String key, int... indexes)\r\n\r\n @Command(\"NR.OBSERVE ?0 ?1 -> ?2 TRAIN\")\r\n List<Integer> nrObserve(String key, int[] in, int... out)\r\n}<\/pre>\n\n
mget<\/code> and mgetAsync<\/code>. Both methods are intended to execute the MGET<\/code> command \u2013 synchronously and asynchronously. mgetAsync<\/code> is annotated with @Command<\/code> that provides the command name to the command and overrides the assumption that the method would be named MGETASYNC<\/code> otherwise.<\/li>\nnrRun<\/code> with @CommandNaming(strategy = DOT)<\/code>. Camel humps (changes in letter casing) are expressed by placing a dot between individual command segments and we\u2019re good to run NR.RUN<\/code> from Neural Redis<\/a>.<\/li>\nNR.OBSERVE<\/code>. It has three static parts with parameters in between. That command structure is expressed in a command-like language. NR.OBSERVE ?0 ?1 -> ?2 TRAIN<\/code> describes the command as string and puts in index references for arguments. All string parts in the command are constants and parameter references are replaces with the actual parameters.<\/li>\n<\/ul>\nConclusion<\/h2>\n
<dependency>\r\n <groupId>biz.paluch.redis<\/groupId>\r\n <artifactId>lettuce<\/artifactId>\r\n <version>5.0.0-dynamic-api-SNAPSHOT<\/version>\r\n<\/dependency><\/pre>\n
RedisCommandFactory factory = new RedisCommandFactory(connection);\r\n\r\nTestInterface api = factory.getCommands(TestInterface.class);\r\nString value = api.get(\"key\");\r\n\r\npublic interface TestInterface {\r\n\r\n String get(String key);\r\n\r\n @Command(\"GET\")\r\n byte[] getAsBytes(String key);\r\n}<\/pre>\nReference<\/h2>\n
\n
@Command<\/code>: Command annotation specifying a command name or the whole command structure by using a command-like language.<\/li>\n@CommandNaming<\/code>: Annotation to specify the command naming strategy.<\/li>\nTimeout<\/code>: Value object containing a timeout.<\/li>\nRedisFuture<\/code>: A Future result handle.<\/li>\nFlux<\/code>: Project Reactor<\/a> publisher for reactive execution that emits 0..N<\/code> items.<\/li>\n<\/ul>\n