feat(json): Improve JsonStructure API and documentation

Author: PerfectSlayer

components/json/src/main/java/datadog/json/JsonStructure.java

@@ -1,19 +1,56 @@
 package datadog.json;
 
+/** The {@link JsonStructure} keeps track of JSON value being built. */
 interface JsonStructure {
+  /**
+   * Begins an object.
+   *
+   * @throws IllegalStateException if the object can not be started at this position.
+   */
   void beginObject();
 
+  /**
+   * Checks whether the current position is within an object.
+   *
+   * @return {@code true} if the current position is within an object, {@code false} otherwise.
+   */
   boolean objectStarted();
 
+  /**
+   * Ends the current object.
+   *
+   * @throws IllegalStateException if the current position is not within an object.
+   */
   void endObject();
 
+  /** Begins an array. */
   void beginArray();
 
+  /**
+   * Checks whether the current position is within an array.
+   *
+   * @return {@code true} if the current position is within an array, {@code false} otherwise.
+   */
   boolean arrayStarted();
 
+  /**
+   * Ends the current array.
+   *
+   * @throws IllegalStateException if the current position is not within an array.
+   */
   void endArray();
 
-  void checkNameAllowed();
-
-  void checkValueAllowed();
+  /**
+   * Adds a name to the current object.
+   *
+   * @throws IllegalStateException if the current position is not within an object.
+   */
+  void addName();
+
+  /**
+   * Adds a value.
+   *
+   * @throws IllegalStateException if the current position can not have a value.
+   */
+  void addValue();
 }

components/json/src/main/java/datadog/json/JsonWriter.java

@@ -9,7 +9,7 @@
 import java.io.OutputStreamWriter;
 
 /**
- * A lightweight JSON writer without dependencies. It performs minimal JSON structure check unless
+ * A lightweight JSON writer without dependencies. It performs minimal JSON structure checks unless
  * using the lenient mode.
  */
 public final class JsonWriter implements Flushable, AutoCloseable {
@@ -71,7 +71,7 @@ public JsonWriter name(String name) {
     if (name == null) {
       throw new IllegalArgumentException("name cannot be null");
     }
-    this.structure.checkNameAllowed();
+    this.structure.addName();
     injectCommaIfNeeded();
     writeStringLiteral(name);
     write(':');
@@ -84,7 +84,7 @@ public JsonWriter name(String name) {
    * @return This writer.
    */
   public JsonWriter nullValue() {
-    this.structure.checkValueAllowed();
+    this.structure.addValue();
     injectCommaIfNeeded();
     writeStringRaw("null");
     endsValue();
@@ -112,7 +112,7 @@ public JsonWriter jsonValue(String value) {
    * @return This writer.
    */
   public JsonWriter value(boolean value) {
-    this.structure.checkValueAllowed();
+    this.structure.addValue();
     injectCommaIfNeeded();
     writeStringRaw(value ? "true" : "false");
     endsValue();
@@ -129,7 +129,7 @@ public JsonWriter value(String value) {
     if (value == null) {
       return nullValue();
     }
-    this.structure.checkValueAllowed();
+    this.structure.addValue();
     injectCommaIfNeeded();
     writeStringLiteral(value);
     endsValue();
@@ -143,7 +143,7 @@ public JsonWriter value(String value) {
    * @return This writer.
    */
   public JsonWriter value(int value) {
-    this.structure.checkValueAllowed();
+    this.structure.addValue();
     injectCommaIfNeeded();
     writeStringRaw(Integer.toString(value));
     endsValue();
@@ -157,7 +157,7 @@ public JsonWriter value(int value) {
    * @return This writer.
    */
   public JsonWriter value(long value) {
-    this.structure.checkValueAllowed();
+    this.structure.addValue();
     injectCommaIfNeeded();
     writeStringRaw(Long.toString(value));
     endsValue();
@@ -174,7 +174,7 @@ public JsonWriter value(float value) {
     if (Float.isNaN(value)) {
       return nullValue();
     }
-    this.structure.checkValueAllowed();
+    this.structure.addValue();
     injectCommaIfNeeded();
     writeStringRaw(Float.toString(value));
     endsValue();
@@ -191,7 +191,7 @@ public JsonWriter value(double value) {
     if (Double.isNaN(value)) {
       return nullValue();
     }
-    this.structure.checkValueAllowed();
+    this.structure.addValue();
     injectCommaIfNeeded();
     writeStringRaw(Double.toString(value));
     endsValue();

components/json/src/main/java/datadog/json/LenientJsonStructure.java

@@ -1,5 +1,6 @@
 package datadog.json;
 
+/** A permissive {@link JsonStructure} that performs no structural checks on the built JSON. */
 class LenientJsonStructure implements JsonStructure {
   LenientJsonStructure() {}
 
@@ -26,8 +27,8 @@ public boolean arrayStarted() {
   public void endArray() {}
 
   @Override
-  public void checkNameAllowed() {}
+  public void addName() {}
 
   @Override
-  public void checkValueAllowed() {}
+  public void addValue() {}
 }

components/json/src/main/java/datadog/json/SafeJsonStructure.java

@@ -5,6 +5,10 @@
 import java.util.ArrayDeque;
 import java.util.Deque;
 
+/**
+ * This {@link JsonStructure} performs minimal structure checks to ensure the built JSON is
+ * coherent.
+ */
 class SafeJsonStructure implements JsonStructure {
   private final Deque<Boolean> structure;
   private boolean complete;
@@ -63,14 +67,14 @@ public void endArray() {
   }
 
   @Override
-  public void checkNameAllowed() {
+  public void addName() {
     if (!objectStarted()) {
       throw new IllegalStateException("Object not started");
     }
   }
 
   @Override
-  public void checkValueAllowed() {
+  public void addValue() {
     if (this.complete) {
       throw new IllegalStateException("Object is complete");
     }

components/json/src/test/java/datadog/json/JsonStructureTest.java

@@ -27,7 +27,7 @@ void lenientStructure() {
     lenientJsonStructure.beginArray();
     assertTrue(lenientJsonStructure.arrayStarted());
     lenientJsonStructure.endArray();
-    assertDoesNotThrow(lenientJsonStructure::checkNameAllowed);
-    assertDoesNotThrow(lenientJsonStructure::checkValueAllowed);
+    assertDoesNotThrow(lenientJsonStructure::addName);
+    assertDoesNotThrow(lenientJsonStructure::addValue);
   }
 }