Added examples in documentation. Minor format RedisClientTest.

Bit-Quill · Feb 23, 2024 · d562038 · d562038
1 parent 0f74bd4
commit d562038
Show file tree

Hide file tree

Showing 2 changed files with 73 additions and 0 deletions.
diff --git a/java/client/src/main/java/glide/api/commands/GenericBaseCommands.java b/java/client/src/main/java/glide/api/commands/GenericBaseCommands.java
@@ -67,6 +67,11 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
+     * @example
+     *     <pre>
+     * Boolean isSet = client.expire("my_key", 60).get()
+     * assert isSet //Indicates that a timeout of 60 seconds has been set for "my_key."
+     * </pre>
      */
     CompletableFuture<Boolean> expire(String key, long seconds);
 
@@ -84,6 +89,11 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
+     * @example
+     *     <pre>
+     * Boolean isSet = client.expire("my_key", 60, ExpireOptions.HAS_NO_EXPIRY).get()
+     * assert isSet //Indicates that a timeout of 60 seconds has been set for "my_key."
+     * </pre>
      */
     CompletableFuture<Boolean> expire(String key, long seconds, ExpireOptions expireOptions);
 
@@ -101,6 +111,11 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
+     * @example
+     *     <pre>
+     * Boolean isSet = client.expireAt("my_key", 1672531200).get()
+     * assert isSet
+     * </pre>
      */
     CompletableFuture<Boolean> expireAt(String key, long unixSeconds);
 
@@ -119,6 +134,11 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
+     * @example
+     *     <pre>
+     * Boolean isSet = client.expireAt("my_key", 1672531200, ExpireOptions.HasNoExpiry).get()
+     * assert isSet
+     * </pre>
      */
     CompletableFuture<Boolean> expireAt(String key, long unixSeconds, ExpireOptions expireOptions);
 
@@ -135,6 +155,11 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
+     * @example
+     *     <pre>
+     * Boolean isSet = client.pexpire("my_key", 60000).get()
+     * assert isSet
+     * </pre>
      */
     CompletableFuture<Boolean> pexpire(String key, long milliseconds);
 
@@ -152,6 +177,11 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
+     * @example
+     *     <pre>
+     * Boolean isSet = client.pexpire("my_key", 60000, ExpireOptions.HasNoExpiry).get()
+     * assert isSet
+     * </pre>
      */
     CompletableFuture<Boolean> pexpire(String key, long milliseconds, ExpireOptions expireOptions);
 
@@ -169,6 +199,11 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
+     * @example
+     *     <pre>
+     * Boolean isSet = client.pexpireAt("my_key", 1672531200000).get()
+     * assert isSet
+     * </pre>
      */
     CompletableFuture<Boolean> pexpireAt(String key, long unixMilliseconds);
 
@@ -187,6 +222,11 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
+     * @example
+     *     <pre>
+     * Boolean isSet = client.pexpireAt("my_key", 1672531200000, ExpireOptions.HasNoExpiry).get()
+     * assert isSet
+     * </pre>
      */
     CompletableFuture<Boolean> pexpireAt(
         String key, long unixMilliseconds, ExpireOptions expireOptions);
@@ -198,6 +238,13 @@ CompletableFuture<Boolean> pexpireAt(
      * @param key The <code>key</code> to return its timeout.
      * @return TTL in seconds, -2 if <code>key</code> does not exist, or -1 if <code>key</code> exists
      *     but has no associated expire.
+     * @example
+     *     <pre>
+     * Long timeRemaining = client.ttl("my_key").get()
+     * assert timeRemaining == 3600L //Indicates that "my_key" has a remaining time to live of 3600 seconds.
+     * Long timeRemaining = client.ttl("nonexistent_key").get()
+     * assert timeRemaining == -2L //Returns -2 for a non-existing key.
+     * </pre>
      */
     CompletableFuture<Long> ttl(String key);
 }
diff --git a/java/client/src/test/java/glide/api/RedisClientTest.java b/java/client/src/test/java/glide/api/RedisClientTest.java
@@ -306,8 +306,11 @@ public void expire_returns_success() {
         String key = "testKey";
         long seconds = 10L;
         String[] arguments = new String[] {key, Long.toString(seconds)};
+
         CompletableFuture<Boolean> testResponse = mock(CompletableFuture.class);
         when(testResponse.get()).thenReturn(true);
+
+        // match on protobuf request
         when(commandManager.<Boolean>submitNewCommand(eq(Expire), eq(arguments), any()))
                 .thenReturn(testResponse);
 
@@ -326,8 +329,11 @@ public void expire_with_expireOptions_returns_success() {
         String key = "testKey";
         long seconds = 10L;
         String[] arguments = new String[] {key, Long.toString(seconds), "NX"};
+
         CompletableFuture<Boolean> testResponse = mock(CompletableFuture.class);
         when(testResponse.get()).thenReturn(false);
+
+        // match on protobuf request
         when(commandManager.<Boolean>submitNewCommand(eq(Expire), eq(arguments), any()))
                 .thenReturn(testResponse);
 
@@ -346,8 +352,11 @@ public void expireAt_returns_success() {
         String key = "testKey";
         long unixSeconds = 100000L;
         String[] arguments = new String[] {key, Long.toString(unixSeconds)};
+
         CompletableFuture<Boolean> testResponse = mock(CompletableFuture.class);
         when(testResponse.get()).thenReturn(true);
+
+        // match on protobuf request
         when(commandManager.<Boolean>submitNewCommand(eq(ExpireAt), eq(arguments), any()))
                 .thenReturn(testResponse);
 
@@ -366,8 +375,11 @@ public void expireAt_with_expireOptions_returns_success() {
         String key = "testKey";
         long unixSeconds = 100000L;
         String[] arguments = new String[] {key, Long.toString(unixSeconds), "XX"};
+
         CompletableFuture<Boolean> testResponse = mock(CompletableFuture.class);
         when(testResponse.get()).thenReturn(false);
+
+        // match on protobuf request
         when(commandManager.<Boolean>submitNewCommand(eq(ExpireAt), eq(arguments), any()))
                 .thenReturn(testResponse);
 
@@ -387,8 +399,11 @@ public void pexpire_returns_success() {
         String key = "testKey";
         long milliseconds = 5L;
         String[] arguments = new String[] {key, Long.toString(milliseconds)};
+
         CompletableFuture<Boolean> testResponse = mock(CompletableFuture.class);
         when(testResponse.get()).thenReturn(true);
+
+        // match on protobuf request
         when(commandManager.<Boolean>submitNewCommand(eq(PExpire), eq(arguments), any()))
                 .thenReturn(testResponse);
 
@@ -407,8 +422,11 @@ public void pexpire_with_expireOptions_returns_success() {
         String key = "testKey";
         long milliseconds = 5L;
         String[] arguments = new String[] {key, Long.toString(milliseconds), "LT"};
+
         CompletableFuture<Boolean> testResponse = mock(CompletableFuture.class);
         when(testResponse.get()).thenReturn(false);
+
+        // match on protobuf request
         when(commandManager.<Boolean>submitNewCommand(eq(PExpire), eq(arguments), any()))
                 .thenReturn(testResponse);
 
@@ -428,8 +446,11 @@ public void pexpireAt_returns_success() {
         String key = "testKey";
         long unixMilliseconds = 999999L;
         String[] arguments = new String[] {key, Long.toString(unixMilliseconds)};
+
         CompletableFuture<Boolean> testResponse = mock(CompletableFuture.class);
         when(testResponse.get()).thenReturn(true);
+
+        // match on protobuf request
         when(commandManager.<Boolean>submitNewCommand(eq(PExpireAt), eq(arguments), any()))
                 .thenReturn(testResponse);
 
@@ -448,8 +469,11 @@ public void pexpireAt_with_expireOptions_returns_success() {
         String key = "testKey";
         long unixMilliseconds = 999999L;
         String[] arguments = new String[] {key, Long.toString(unixMilliseconds), "GT"};
+
         CompletableFuture<Boolean> testResponse = mock(CompletableFuture.class);
         when(testResponse.get()).thenReturn(false);
+
+        // match on protobuf request
         when(commandManager.<Boolean>submitNewCommand(eq(PExpireAt), eq(arguments), any()))
                 .thenReturn(testResponse);
 
@@ -471,6 +495,8 @@ public void ttl_returns_success() {
 
         CompletableFuture<Long> testResponse = mock(CompletableFuture.class);
         when(testResponse.get()).thenReturn(ttl);
+
+        // match on protobuf request
         when(commandManager.<Long>submitNewCommand(eq(TTL), eq(new String[] {key}), any()))
                 .thenReturn(testResponse);