Documentation of custom commands #122

RELEASE-NOTES.md

@@ -205,6 +205,29 @@ This API is a technical preview, so your feedback is highly appreciated.
 
 Read more: https://github.com/mp911de/lettuce/wiki/Redis-Cluster-(4.0)
 
+Custom commands
+---------------
+Lettuce covers nearly all Redis commands. Redis development is an ongoing process,
+and some commands are not covered by lettuce meaning there are use cases that
+require invocation of custom commands or custom outputs.
+lettuce 4.x allows you to trigger own commands. That API is used by lettuce itself
+to dispatch commands and requires some knowledge of how commands are constructed
+and dispatched within lettuce.
+
+```java
+StatefulRedisConnection<String, String> connection = redis.getStatefulConnection();
+
+RedisCommand<String, String, String> command = new Command<>(CommandType.PING,
+                                        new StatusOutput<>(new Utf8StringCodec()));
+
+AsyncCommand<String, String, String> async = new AsyncCommand<>(command);
+connection.dispatch(async);
+
+// async instanceof CompletableFuture == true
+```
+
+Read more: https://github.com/mp911de/lettuce/wiki/Custom-commands%2C-outputs-and-command-mechanics
+
 
 Updated dependencies
 --------------------
@@ -228,7 +251,7 @@ Enhancements
 * Allow limiting the request queue size #115
 * Improve Codec API #118
 * Allow to read from master/slave/nearest node when using Redis Cluster #114
-
+* Documentation of custom commands #122
 
 Fixes
 -----

src/main/java/com/lambdaworks/redis/ReactiveCommandDispatcher.java

@@ -1,5 +1,7 @@
 package com.lambdaworks.redis;
 
+import static com.google.common.base.Preconditions.checkArgument;
+
 import java.util.Collection;
 import java.util.function.Supplier;
 
@@ -24,8 +26,8 @@ public class ReactiveCommandDispatcher<K, V, T> implements Observable.OnSubscrib
 
     /**
      * 
-     * @param staticCommand static command
-     * @param connection the connection
+     * @param staticCommand static command, must not be {@literal null}
+     * @param connection the connection, must not be {@literal null}
      * @param dissolve dissolve collections into particular elements
      */
     public ReactiveCommandDispatcher(RedisCommand<K, V, T> staticCommand, StatefulConnection<K, V> connection, boolean dissolve) {
@@ -34,12 +36,14 @@ public ReactiveCommandDispatcher(RedisCommand<K, V, T> staticCommand, StatefulCo
 
     /**
      * 
-     * @param commandSupplier command supplier
-     * @param connection the connection
+     * @param commandSupplier command supplier, must not be {@literal null}
+     * @param connection the connection, must not be {@literal null}
      * @param dissolve dissolve collections into particular elements
      */
     public ReactiveCommandDispatcher(Supplier<RedisCommand<K, V, T>> commandSupplier, StatefulConnection<K, V> connection,
             boolean dissolve) {
+        checkArgument(commandSupplier != null, "CommandSupplier must not be null");
+        checkArgument(connection != null, "StatefulConnection must not be null");
         this.commandSupplier = commandSupplier;
         this.connection = connection;
         this.dissolve = dissolve;

src/main/java/com/lambdaworks/redis/api/StatefulConnection.java

@@ -35,9 +35,10 @@ public interface StatefulConnection<K, V> extends AutoCloseable {
 
     /**
      * Dispatch a command. Write a command on the channel. The command may be changed/wrapped during write and the written
-     * instance is returned after the call.
+     * instance is returned after the call. This command does not wait until the command completes and does not guarantee
+     * whether the command is executed successfully.
      *
-     * @param command the redis command
+     * @param command the Redis command
      * @param <T> result type
      * @param <C> command type
      * @return the written redis command

src/main/java/com/lambdaworks/redis/output/CommandOutput.java

@@ -2,6 +2,8 @@
 
 package com.lambdaworks.redis.output;
 
+import static com.google.common.base.Preconditions.checkArgument;
+
 import java.nio.ByteBuffer;
 
 import com.lambdaworks.redis.codec.RedisCodec;
@@ -23,10 +25,11 @@ public abstract class CommandOutput<K, V, T> {
     /**
      * Initialize a new instance that encodes and decodes keys and values using the supplied codec.
      * 
-     * @param codec Codec used to encode/decode keys and values.
+     * @param codec Codec used to encode/decode keys and values, must not be {@literal null}.
      * @param output Initial value of output.
      */
     public CommandOutput(RedisCodec<K, V> codec, T output) {
+        checkArgument(codec != null, "RedisCodec must not be null");
         this.codec = codec;
         this.output = output;
     }

src/main/java/com/lambdaworks/redis/protocol/AsyncCommand.java

@@ -1,5 +1,7 @@
 package com.lambdaworks.redis.protocol;
 
+import static com.google.common.base.Preconditions.checkArgument;
+
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.TimeUnit;
@@ -27,7 +29,13 @@ public class AsyncCommand<K, V, T> extends CompletableFuture<T> implements Redis
     protected RedisCommand<K, V, T> command;
     protected CountDownLatch latch = new CountDownLatch(1);
 
+    /**
+     * 
+     * @param command the command, must not be {@literal null}.
+     * 
+     */
     public AsyncCommand(RedisCommand<K, V, T> command) {
+        checkArgument(command != null, "RedisCommand must not be null");
         this.command = command;
     }
 

src/main/java/com/lambdaworks/redis/protocol/Command.java

@@ -2,6 +2,8 @@
 
 package com.lambdaworks.redis.protocol;
 
+import static com.google.common.base.Preconditions.checkArgument;
+
 import com.lambdaworks.redis.output.CommandOutput;
 import io.netty.buffer.ByteBuf;
 
@@ -26,14 +28,25 @@ public class Command<K, V, T> implements RedisCommand<K, V, T> {
     protected boolean cancelled = false;
     protected boolean completed = false;
 
+    /**
+     * Create a new command with the supplied type.
+     *
+     * @param type Command type, must not be {@literal null}.
+     * @param output Command output, can be {@literal null}.
+     */
+    public Command(ProtocolKeyword type, CommandOutput<K, V, T> output) {
+        this(type, output, null);
+    }
+
     /**
      * Create a new command with the supplied type and args.
      *
-     * @param type Command type.
-     * @param output Command output.
-     * @param args Command args, if any.
+     * @param type Command type, must not be {@literal null}.
+     * @param output Command output, can be {@literal null}.
+     * @param args Command args, can be {@literal null}
      */
     public Command(ProtocolKeyword type, CommandOutput<K, V, T> output, CommandArgs<K, V> args) {
+        checkArgument(type != null, "Command type must not be null");
         this.type = type;
         this.output = output;
         this.args = args;

src/main/java/com/lambdaworks/redis/protocol/CommandArgs.java

@@ -2,6 +2,7 @@
 
 package com.lambdaworks.redis.protocol;
 
+import static com.google.common.base.Preconditions.checkArgument;
 import static java.lang.Math.max;
 
 import java.nio.BufferOverflowException;
@@ -28,12 +29,17 @@ public class CommandArgs<K, V> {
     private Long firstInteger;
     private String firstString;
 
+    /**
+     *
+     * @param codec Codec used to encode/decode keys and values, must not be {@literal null}.
+     */
     public CommandArgs(RedisCodec<K, V> codec) {
+        checkArgument(codec != null, "RedisCodec must not be null");
         this.codec = codec;
         this.buffer = ByteBuffer.allocate(32);
     }
 
-    public ByteBuffer buffer() {
+    ByteBuffer buffer() {
         buffer.flip();
         return buffer;
     }