Adding some JavaDoc

redis · Aug 2, 2024 · c4dc288 · c4dc288
1 parent 5edb922
commit c4dc288
Show file tree

Hide file tree

Showing 10 changed files with 176 additions and 47 deletions.
diff --git a/src/main/java/io/lettuce/core/json/DefaultJsonParser.java b/src/main/java/io/lettuce/core/json/DefaultJsonParser.java
@@ -23,7 +23,6 @@
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.lettuce.core.codec.RedisCodec;
-import io.lettuce.core.codec.StringCodec;
 
 import java.io.IOException;
 import java.nio.ByteBuffer;
@@ -48,12 +47,12 @@ public JsonValue<K, V> createJsonValue(V value) {
 
     @Override
     public JsonObject<K, V> createEmptyJsonObject() {
-        return new DefaultJsonObject<K, V>(codec);
+        return new DelegateJsonObject<K, V>(codec);
     }
 
     @Override
     public JsonArray<K, V> createEmptyJsonArray() {
-        return new DefaultJsonArray<K, V>(codec);
+        return new DelegateJsonArray<K, V>(codec);
     }
 
     protected JsonValue<K, V> parse(V value) {
@@ -72,11 +71,11 @@ private JsonValue<K, V> parse(String value) {
             JsonNode root = mapper.readTree(value);
 
             if (root.isObject()) {
-                return new DefaultJsonObject<>(root, codec);
+                return new DelegateJsonObject<>(root, codec);
             } else if (root.isArray()) {
-                return new DefaultJsonArray<>(root, codec);
+                return new DelegateJsonArray<>(root, codec);
             }
-            return new DefaultJsonValue<>(root, codec);
+            return new DelegateJsonValue<>(root, codec);
         } catch (IOException e) {
             throw new RuntimeException(e);
         }
@@ -91,11 +90,11 @@ public JsonValue<K, V> parse(ByteBuffer byteBuffer) {
             JsonNode root = mapper.readTree(bytes);
 
             if (root.isObject()) {
-                return new DefaultJsonObject<>(root, codec);
+                return new DelegateJsonObject<>(root, codec);
             } else if (root.isArray()) {
-                return new DefaultJsonArray<>(root, codec);
+                return new DelegateJsonArray<>(root, codec);
             }
-            return new DefaultJsonValue<>(root, codec);
+            return new DelegateJsonValue<>(root, codec);
         } catch (IOException e) {
             throw new RuntimeException(e);
         }

diff --git a/...o/lettuce/core/json/DefaultJsonArray.java → .../lettuce/core/json/DelegateJsonArray.java b/...o/lettuce/core/json/DefaultJsonArray.java → .../lettuce/core/json/DelegateJsonArray.java
@@ -23,33 +23,41 @@
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.node.ArrayNode;
 import com.fasterxml.jackson.databind.node.JsonNodeFactory;
+import com.fasterxml.jackson.databind.node.ObjectNode;
 import io.lettuce.core.codec.RedisCodec;
 
 import java.util.ArrayList;
 import java.util.Iterator;
 import java.util.List;
 
-class DefaultJsonArray<K, V> extends DefaultJsonValue<K, V> implements JsonArray<K, V> {
+/**
+ * Implementation of the {@link DelegateJsonArray} that delegates most of it's dunctionality to the Jackson {@link ArrayNode}.
+ *
+ * @param <K> Key type.
+ * @param <V> Value type.
+ * @author Tihomir Mateev
+ */
+class DelegateJsonArray<K, V> extends DelegateJsonValue<K, V> implements JsonArray<K, V> {
 
-    DefaultJsonArray(RedisCodec<K, V> codec) {
+    DelegateJsonArray(RedisCodec<K, V> codec) {
         super(new ArrayNode(JsonNodeFactory.instance), codec);
     }
 
-    DefaultJsonArray(JsonNode node, RedisCodec<K, V> codec) {
+    DelegateJsonArray(JsonNode node, RedisCodec<K, V> codec) {
         super(node, codec);
     }
 
     @Override
     public JsonArray<K, V> add(JsonValue<K, V> element) {
-        JsonNode newNode = ((DefaultJsonValue<K, V>) element).getNode();
+        JsonNode newNode = ((DelegateJsonValue<K, V>) element).getNode();
         ((ArrayNode) node).add(newNode);
 
         return this;
     }
 
     @Override
     public void addAll(JsonArray<K, V> element) {
-        ArrayNode otherArray = (ArrayNode) ((DefaultJsonValue<K, V>) element).getNode();
+        ArrayNode otherArray = (ArrayNode) ((DelegateJsonValue<K, V>) element).getNode();
         ((ArrayNode) node).addAll(otherArray);
     }
 
@@ -58,7 +66,7 @@ public List<JsonValue<K, V>> asList() {
         List<JsonValue<K, V>> result = new ArrayList<>();
 
         for (JsonNode jsonNode : node) {
-            result.add(new DefaultJsonValue<>(jsonNode, codec));
+            result.add(new DelegateJsonValue<>(jsonNode, codec));
         }
 
         return result;
@@ -68,7 +76,7 @@ public List<JsonValue<K, V>> asList() {
     public JsonValue<K, V> get(int index) {
         JsonNode jsonNode = node.get(index);
 
-        return new DefaultJsonValue<>(jsonNode, codec);
+        return new DelegateJsonValue<>(jsonNode, codec);
     }
 
     @Override
@@ -81,7 +89,7 @@ public Iterator<JsonValue<K, V>> iterator() {
         List<JsonValue<K, V>> result = new ArrayList<>();
         while (node.iterator().hasNext()) {
             JsonNode jsonNode = node.iterator().next();
-            result.add(new DefaultJsonValue<>(jsonNode, codec));
+            result.add(new DelegateJsonValue<>(jsonNode, codec));
         }
 
         return result.iterator();
@@ -91,15 +99,15 @@ public Iterator<JsonValue<K, V>> iterator() {
     public JsonValue<K, V> remove(int index) {
         JsonNode jsonNode = ((ArrayNode) node).remove(index);
 
-        return new DefaultJsonValue<>(jsonNode, codec);
+        return new DelegateJsonValue<>(jsonNode, codec);
     }
 
     @Override
     public JsonValue<K, V> replace(int index, JsonValue<K, V> newElement) {
-        JsonNode replaceWith = ((DefaultJsonValue<K, V>) newElement).getNode();
+        JsonNode replaceWith = ((DelegateJsonValue<K, V>) newElement).getNode();
         JsonNode replaced = ((ArrayNode) node).set(index, replaceWith);
 
-        return new DefaultJsonValue<>(replaced, codec);
+        return new DelegateJsonValue<>(replaced, codec);
     }
 
     @Override

diff --git a/.../lettuce/core/json/DefaultJsonObject.java → ...lettuce/core/json/DelegateJsonObject.java b/.../lettuce/core/json/DefaultJsonObject.java → ...lettuce/core/json/DelegateJsonObject.java
@@ -25,20 +25,27 @@
 import com.fasterxml.jackson.databind.node.ObjectNode;
 import io.lettuce.core.codec.RedisCodec;
 
-class DefaultJsonObject<K, V> extends DefaultJsonValue<K, V> implements JsonObject<K, V> {
+/**
+ * Implementation of the {@link DelegateJsonObject} that delegates most of it's dunctionality to the Jackson {@link ObjectNode}.
+ *
+ * @param <K> Key type.
+ * @param <V> Value type.
+ * @author Tihomir Mateev
+ */
+class DelegateJsonObject<K, V> extends DelegateJsonValue<K, V> implements JsonObject<K, V> {
 
-    DefaultJsonObject(RedisCodec<K, V> codec) {
+    DelegateJsonObject(RedisCodec<K, V> codec) {
         super(new ObjectNode(JsonNodeFactory.instance), codec);
     }
 
-    DefaultJsonObject(JsonNode node, RedisCodec<K, V> codec) {
+    DelegateJsonObject(JsonNode node, RedisCodec<K, V> codec) {
         super(node, codec);
     }
 
     @Override
-    public JsonObject<K, V> add(K key, JsonValue<K, V> element) {
+    public JsonObject<K, V> put(K key, JsonValue<K, V> element) {
         String keyString = getStringValue(key);
-        JsonNode newNode = ((DefaultJsonValue<K, V>) element).getNode();
+        JsonNode newNode = ((DelegateJsonValue<K, V>) element).getNode();
 
         ((ObjectNode) node).replace(keyString, newNode);
         return this;
@@ -49,15 +56,15 @@ public JsonValue<K, V> get(K key) {
         String keyString = getStringValue(key);
         JsonNode value = node.get(keyString);
 
-        return new DefaultJsonValue<>(value, codec);
+        return new DelegateJsonValue<>(value, codec);
     }
 
     @Override
     public JsonValue<K, V> remove(K key) {
         String keyString = getStringValue(key);
         JsonNode value = ((ObjectNode) node).remove(keyString);
 
-        return new DefaultJsonValue<>(value, codec);
+        return new DelegateJsonValue<>(value, codec);
     }
 
     @Override

diff --git a/...o/lettuce/core/json/DefaultJsonValue.java → .../lettuce/core/json/DelegateJsonValue.java b/...o/lettuce/core/json/DefaultJsonValue.java → .../lettuce/core/json/DelegateJsonValue.java
@@ -26,13 +26,20 @@
 
 import java.nio.ByteBuffer;
 
-class DefaultJsonValue<K, V> implements JsonValue<K, V> {
+/**
+ * Implementation of the {@link JsonValue} that delegates most of it's dunctionality to the Jackson {@link JsonNode}.
+ *
+ * @param <K> Key type.
+ * @param <V> Value type.
+ * @author Tihomir Mateev
+ */
+class DelegateJsonValue<K, V> implements JsonValue<K, V> {
 
     protected final RedisCodec<K, V> codec;
 
     protected JsonNode node;
 
-    DefaultJsonValue(JsonNode node, RedisCodec<K, V> codec) {
+    DelegateJsonValue(JsonNode node, RedisCodec<K, V> codec) {
         this.codec = codec;
         this.node = node;
     }
@@ -75,9 +82,7 @@ public boolean isString() {
     }
 
     @Override
-    public String asString() {
-        return node.asText();
-    }
+    public String asString() { return node.asText(); }
 
     @Override
     public boolean isNumber() {
@@ -91,7 +96,6 @@ public Number asNumber() {
         } else if (node.isLong()) {
             return node.asLong();
         }
-
         return node.asDouble();
     }
 

diff --git a/src/main/java/io/lettuce/core/json/JsonArray.java b/src/main/java/io/lettuce/core/json/JsonArray.java
@@ -23,24 +23,84 @@
 import java.util.Iterator;
 import java.util.List;
 
+/**
+ * Representation of a JSON array as per <a href="https://datatracker.ietf.org/doc/html/rfc8259#section-5"> </a>RFC 8259 - The
+ * JavaScript Object Notation (JSON) Data Interchange Format, Section 5. Arrays</a>
+ * <p>
+ *
+ *
+ * @param <K> Key type based on the {@link io.lettuce.core.codec.RedisCodec} used.
+ * @param <V> Value type based on the {@link io.lettuce.core.codec.RedisCodec} used.
+ * @see JsonValue
+ * @author Tihomir Mateev
+ * @since 6.5
+ */
 public interface JsonArray<K, V> extends JsonValue<K, V> {
 
+    /**
+     * Add a new {@link JsonValue} to the array. Supports chaining of calls.
+     *
+     * @param element the value to add
+     * @return the updated {@link JsonArray} to allow call chaining
+     */
     JsonArray<K, V> add(JsonValue<K, V> element);
 
+    /**
+     * Add all elements from the provided {@link JsonArray} to this array.
+     *
+     * @param element the array to add all elements from
+     */
     void addAll(JsonArray<K, V> element);
 
+    /**
+     * Get all the {@link JsonValue}s in the array as a {@link List}.
+     *
+     * @return the {@link List} of {@link JsonValue}s in the array
+     */
     List<JsonValue<K, V>> asList();
 
+    /**
+     * Get the {@link JsonValue} at the provided index.
+     *
+     * @param index the index to get the value for
+     * @return the {@link JsonValue} at the provided index or {@code null} if no value is found
+     */
     JsonValue<K, V> get(int index);
 
+    /**
+     * Get the first {@link JsonValue} in the array.
+     *
+     * @return the first {@link JsonValue} in the array or {@code null} if the array is empty
+     */
     JsonValue<K, V> getFirst();
 
+    /**
+     * Get an {@link Iterator} allowing access to all the  {@link JsonValue}s in the array.
+     *
+     * @return the last {@link JsonValue} in the array or {@code null} if the array is empty
+     */
     Iterator<JsonValue<K, V>> iterator();
 
+    /**
+     * Remove the {@link JsonValue} at the provided index.
+     *
+     * @param index the index to remove the value for
+     * @return the removed {@link JsonValue} or {@code null} if no value is found
+     */
     JsonValue<K, V> remove(int index);
 
+    /**
+     * Replace the {@link JsonValue} at the provided index with the provided new {@link JsonValue}.
+     *
+     * @param index the index to replace the value for
+     * @param newElement the new value to replace the old one with
+     * @return the updated {@link JsonArray} to allow call chaining
+     */
     JsonValue<K, V> replace(int index, JsonValue<K, V> newElement);
 
+    /**
+     * @return the number of elements in this {@link JsonArray}
+     */
     int size();
 
 }
diff --git a/src/main/java/io/lettuce/core/json/JsonObject.java b/src/main/java/io/lettuce/core/json/JsonObject.java
@@ -20,8 +20,6 @@
 
 package io.lettuce.core.json;
 
-import java.util.Map;
-
 /**
  * Representation of a JSON object as per <a href="https://datatracker.ietf.org/doc/html/rfc8259#section-4"> </a>RFC 8259 - The
  * JavaScript Object Notation (JSON) Data Interchange Format, Section 4. Objects</a>
@@ -31,16 +29,40 @@
  * @param <K> Key type based on the {@link io.lettuce.core.codec.RedisCodec} used.
  * @param <V> Value type based on the {@link io.lettuce.core.codec.RedisCodec} used.
  * @see JsonValue
+ * @author Tihomir Mateev
  * @since 6.5
  */
 public interface JsonObject<K, V> extends JsonValue<K, V> {
 
-    JsonObject<K, V> add(K key, JsonValue<K, V> element);
+    /**
+     * Add (if there is no value with the same key already) or replace (if there is) a new {@link JsonValue} to the object
+     * under the provided key. Supports chaining of calls.
+     *
+     * @param key the key of the {@link JsonValue} to add or replace
+     * @param element the value to add or replace
+     * @return the updated {@link JsonObject} to allow call chaining
+     */
+    JsonObject<K, V> put(K key, JsonValue<K, V> element);
 
+    /**
+     * Get the {@link JsonValue} under the provided key.
+     *
+     * @param key the key to get the value for
+     * @return the {@link JsonValue} under the provided key or {@code null} if no value is found
+     */
     JsonValue<K, V> get(K key);
 
+    /**
+     * Remove the {@link JsonValue} under the provided key.
+     *
+     * @param key the key to remove the value for
+     * @return the removed {@link JsonValue} or {@code null} if no value is found
+     */
     JsonValue<K, V> remove(K key);
 
+    /**
+     * @return the number of key-value pairs in this {@link JsonObject}
+     */
     int size();
 
 }
diff --git a/src/main/java/io/lettuce/core/json/JsonValue.java b/src/main/java/io/lettuce/core/json/JsonValue.java
@@ -38,6 +38,8 @@
  * @see io.lettuce.core.codec.RedisCodec
  * @see <a href="https://datatracker.ietf.org/doc/html/rfc8259">RFC 8259 - The JavaScript Object Notation (JSON) Data
  *      Interchange Format</a>
+ * @author Tihomir Mateev
+ * @since 6.5
  */
 public interface JsonValue<K, V> {