Address concerns provided in the PR feedback

src/main/asciidoc/java/parsetools.adoc

@@ -51,7 +51,7 @@ For more details, check out the `link:../../apidocs/io/vertx/core/parsetools/Rec
 
 == Json Parser
 
-You can easily parse JSON structures but that requires to provide the JSON string at once, but it
+You can easily parse JSON structures but that requires to provide the JSON content at once, but it
 may not be convenient when you need to parse very large structures.
 
 The non-blocking JSON parser is an event driven parser able to deal with very large structures.
@@ -78,7 +78,7 @@ parser.handler(event -> {
       break;
     case VALUE:
       // Handle a value
-      String field = event.field();
+      String field = event.fieldName();
       if (field != null) {
         // In an object
       } else {
@@ -94,7 +94,7 @@ parser.handler(event -> {
 });
 ----
 
-The parser is non-blocking and emitted events are driven by the input buffers
+The parser is non-blocking and emitted events are driven by the input buffers.
 
 [source, java]
 ----
@@ -122,8 +122,8 @@ parser.handle(Buffer.buffer("]"));
 parser.end();
 ----
 
-Event driven parsing provides more control but comes at the price of flexibility. The parser allows you
-to handle JSON structures as values when it is desired:
+Event driven parsing provides more control but comes at the price of dealing with fine grained events, which can be
+inconvenient sometimes. The JSON parser allows you to handle JSON structures as values when it is desired:
 
 [source, java]
 ----
@@ -150,7 +150,7 @@ parser.end();
 ----
 
 The value mode can be set and unset during the parsing allowing you to switch between fine grained
-events or JSON object/array value events.
+events or JSON object value events.
 
 [source, java]
 ----
@@ -167,7 +167,7 @@ parser.handler(event -> {
     case VALUE:
       // Handle each object
       // Get the field in which this object was parsed
-      String id = event.field();
+      String id = event.fieldName();
       System.out.println("User with id " + id + " : " + event.value());
       break;
     case END_OBJECT:
@@ -181,15 +181,45 @@ parser.handle(Buffer.buffer("{\"39877483847\":{\"firstName\":\"Bob\"},\"lastName
 parser.end();
 ----
 
+You can do the same with arrays as well
+
+[source, java]
+----
+JsonParser parser = JsonParser.newParser();
+
+parser.handler(event -> {
+  // Start the object
+
+  switch (event.type()) {
+    case START_OBJECT:
+      // Set array value mode to handle each entry, from now on the parser won't emit start array events
+      parser.arrayValueMode();
+      break;
+    case VALUE:
+      // Handle each array
+      // Get the field in which this object was parsed
+      System.out.println("Value : " + event.value());
+      break;
+    case END_OBJECT:
+      // Set the array event mode so the parser emits start/end object events again
+      parser.arrayEventMode();
+      break;
+  }
+});
+
+parser.handle(Buffer.buffer("[0,1,2,3,4,...]"));
+parser.end();
+----
+
 You can also decode POJOs
 
 [source, java]
 ----
 parser.handler(event -> {
   // Handle each object
   // Get the field in which this object was parsed
-  String id = event.field();
-  User user = event.as(User.class);
+  String id = event.fieldName();
+  User user = event.mapTo(User.class);
   System.out.println("User with id " + id + " : " + user.firstName + " " + user.lastName);
 });
 ----
@@ -198,12 +228,10 @@ Whenever the parser fails to process a buffer, an exception will be thrown unles
 
 [source, java]
 ----
-parser.handler(event -> {
-  // Handle each object
-  // Get the field in which this object was parsed
-  String id = event.field();
-  User user = event.as(User.class);
-  System.out.println("User with id " + id + " : " + user.firstName + " " + user.lastName);
+JsonParser parser = JsonParser.newParser();
+
+parser.exceptionHandler(err -> {
+  // Catch any parsing or decoding error
 });
 ----
 

src/main/java/examples/ParseToolsExamples.java

@@ -143,12 +143,40 @@ public void jsonParserExample4() {
     parser.end();
   }
 
+  public void jsonParserExample5() {
+
+    JsonParser parser = JsonParser.newParser();
+
+    parser.handler(event -> {
+      // Start the object
+
+      switch (event.type()) {
+        case START_OBJECT:
+          // Set array value mode to handle each entry, from now on the parser won't emit start array events
+          parser.arrayValueMode();
+          break;
+        case VALUE:
+          // Handle each array
+          // Get the field in which this object was parsed
+          System.out.println("Value : " + event.value());
+          break;
+        case END_OBJECT:
+          // Set the array event mode so the parser emits start/end object events again
+          parser.arrayEventMode();
+          break;
+      }
+    });
+
+    parser.handle(Buffer.buffer("[0,1,2,3,4,...]"));
+    parser.end();
+  }
+
   private static class User {
     private String firstName;
     private String lastName;
   }
 
-  public void jsonParserExample5(JsonParser parser) {
+  public void jsonParserExample6(JsonParser parser) {
     parser.handler(event -> {
       // Handle each object
       // Get the field in which this object was parsed
@@ -158,7 +186,7 @@ public void jsonParserExample5(JsonParser parser) {
     });
   }
 
-  public void jsonParserExample6() {
+  public void jsonParserExample7() {
 
     JsonParser parser = JsonParser.newParser();
 

src/main/java/io/vertx/core/parsetools/JsonEvent.java

@@ -18,6 +18,7 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import io.vertx.codegen.annotations.GenIgnore;
 import io.vertx.codegen.annotations.VertxGen;
+import io.vertx.core.buffer.Buffer;
 import io.vertx.core.json.JsonArray;
 import io.vertx.core.json.JsonObject;
 
@@ -107,7 +108,7 @@ public interface JsonEvent {
    * @throws java.lang.ClassCastException if the value is not a String
    * @throws java.lang.IllegalArgumentException if the String value is not a legal Base64 encoded value
    */
-  byte[] binaryValue();
+  Buffer binaryValue();
 
   /**
    * Return the {@code Instant} value.
@@ -120,6 +121,7 @@ public interface JsonEvent {
    * @throws java.lang.ClassCastException if the value is not a String
    * @throws java.time.format.DateTimeParseException if the String value is not a legal ISO 8601 encoded value
    */
+  @GenIgnore
   Instant instantValue();
 
   /**

src/main/java/io/vertx/core/parsetools/JsonEventType.java

@@ -38,7 +38,7 @@ public enum JsonEventType {
   START_ARRAY,
 
   /**
-   * Signals the end of a JSON object.
+   * Signals the end of a JSON array.
    */
   END_ARRAY,
 

src/main/java/io/vertx/core/parsetools/impl/JsonEventImpl.java

@@ -17,6 +17,7 @@
 
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.util.TokenBuffer;
+import io.vertx.core.buffer.Buffer;
 import io.vertx.core.json.DecodeException;
 import io.vertx.core.json.Json;
 import io.vertx.core.json.JsonArray;
@@ -184,8 +185,8 @@ public String stringValue() {
   }
 
   @Override
-  public byte[] binaryValue() {
-    return value != null ? Base64.getDecoder().decode((String) value) : null;
+  public Buffer binaryValue() {
+    return value != null ? Buffer.buffer(Base64.getDecoder().decode((String) value)) : null;
   }
 
   @Override

src/main/java/io/vertx/core/parsetools/package-info.java

@@ -57,7 +57,7 @@
  *
  * == Json Parser
  *
- * You can easily parse JSON structures but that requires to provide the JSON string at once, but it
+ * You can easily parse JSON structures but that requires to provide the JSON content at once, but it
  * may not be convenient when you need to parse very large structures.
  *
  * The non-blocking JSON parser is an event driven parser able to deal with very large structures.
@@ -68,41 +68,48 @@
  * {@link examples.ParseToolsExamples#jsonParserExample1()}
  * ----
  *
- * The parser is non-blocking and emitted events are driven by the input buffers
+ * The parser is non-blocking and emitted events are driven by the input buffers.
  *
  * [source, $lang]
  * ----
  * {@link examples.ParseToolsExamples#jsonParserExample2}
  * ----
  *
- * Event driven parsing provides more control but comes at the price of flexibility. The parser allows you
- * to handle JSON structures as values when it is desired:
+ * Event driven parsing provides more control but comes at the price of dealing with fine grained events, which can be
+ * inconvenient sometimes. The JSON parser allows you to handle JSON structures as values when it is desired:
  *
  * [source, $lang]
  * ----
  * {@link examples.ParseToolsExamples#jsonParserExample3}
  * ----
  *
  * The value mode can be set and unset during the parsing allowing you to switch between fine grained
- * events or JSON object/array value events.
+ * events or JSON object value events.
  *
  * [source, $lang]
  * ----
  * {@link examples.ParseToolsExamples#jsonParserExample4}
  * ----
  *
- * You can also decode POJOs
+ * You can do the same with arrays as well
  *
  * [source, $lang]
  * ----
  * {@link examples.ParseToolsExamples#jsonParserExample5}
  * ----
  *
+ * You can also decode POJOs
+ *
+ * [source, $lang]
+ * ----
+ * {@link examples.ParseToolsExamples#jsonParserExample6}
+ * ----
+ *
  * Whenever the parser fails to process a buffer, an exception will be thrown unless you set an exception handler:
  *
  * [source, $lang]
  * ----
- * {@link examples.ParseToolsExamples#jsonParserExample5}
+ * {@link examples.ParseToolsExamples#jsonParserExample7}
  * ----
  *
  * For more details, check out the {@link io.vertx.core.parsetools.JsonParser} class.

src/test/java/io/vertx/test/core/JsonParserTest.java

@@ -150,9 +150,15 @@ public void testParseObjectValue() {
     parser.handler(event -> {
       assertEquals(0, status.getAndIncrement());
       assertEquals(JsonEventType.VALUE, event.type());
-      assertEquals(new JsonObject().put("number", 3).put("true", true).put("false", false).put("string", "s").putNull("null"), event.value());
+      assertEquals(new JsonObject().put("number", 3)
+        .put("true", true)
+        .put("false", false)
+        .put("string", "s")
+        .put("object", new JsonObject().put("foo", "bar"))
+        .put("array", new JsonArray().add(0).add(1).add(2))
+        .putNull("null"), event.value());
     });
-    parser.handle(Buffer.buffer("{\"number\":3,\"true\":true,\"false\":false,\"string\":\"s\",\"null\":null}"));
+    parser.handle(Buffer.buffer("{\"number\":3,\"true\":true,\"false\":false,\"string\":\"s\",\"null\":null,\"object\":{\"foo\":\"bar\"},\"array\":[0,1,2]}"));
     assertEquals(1, status.get());
   }
 
@@ -162,10 +168,16 @@ public void testParseArrayValue() {
     AtomicInteger status = new AtomicInteger();
     parser.arrayValueMode();
     parser.handler(event -> {
-      assertEquals(new JsonArray().add(1).add(2).add(3), event.value());
+      assertEquals(new JsonArray().add(3)
+        .add(true)
+        .add(false)
+        .add("s")
+        .addNull()
+        .add(new JsonObject().put("foo", "bar"))
+        .add(new JsonArray().add(0).add(1).add(2)), event.value());
       assertEquals(0, status.getAndIncrement());
     });
-    parser.handle(Buffer.buffer("[1,2,3]"));
+    parser.handle(Buffer.buffer("[3,true,false,\"s\",null,{\"foo\":\"bar\"},[0,1,2]]"));
     assertEquals(1, status.get());
   }
 
@@ -246,7 +258,7 @@ public void testBinaryValue() {
       assertFalse(event.isBoolean());
       assertTrue(event.isString());
       assertEquals(encoded, event.stringValue());
-      assertTrue(Arrays.equals(value, event.binaryValue()));
+      assertEquals(Buffer.buffer(value), event.binaryValue());
       assertThrowCCE(event,
         JsonEvent::integerValue,
         JsonEvent::longValue,