Start 3.0.0 API Changes and Improvements.

Author: scottf

build.gradle

@@ -11,7 +11,7 @@ plugins {
     id 'signing'
 }
 
-def jarVersion = "2.21.0"
+def jarVersion = "3.0.0"
 group = 'io.nats'
 
 def isMerge = System.getenv("BUILD_EVENT") == "push"

src/main/java/io/nats/json/ArrayBuilder.java

@@ -0,0 +1,52 @@
+// Copyright 2025 The NATS Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at:
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package io.nats.json;
+
+import java.util.ArrayList;
+import java.util.Collection;
+
+public class ArrayBuilder implements JsonSerializable {
+
+    public final JsonValue jv = new JsonValue(new ArrayList<>());
+
+    public static ArrayBuilder instance() {
+        return new ArrayBuilder();
+    }
+
+    public ArrayBuilder add(Object o) {
+        //noinspection DataFlowIssue // NO ISSUE, WE KNOW jv.array is NOT NULL
+        jv.array.add(JsonValue.instance(o));
+        return this;
+    }
+
+    public ArrayBuilder addItems(Collection<?> c) {
+        if (c != null) {
+            for (Object o : c) {
+                //noinspection DataFlowIssue // NO ISSUE, WE KNOW jv.array is NOT NULL
+                jv.array.add(JsonValue.instance(o));
+            }
+        }
+        return this;
+    }
+
+    @Override
+    public String toJson() {
+        return jv.toJson();
+    }
+
+    @Override
+    public JsonValue toJsonValue() {
+        return jv;
+    }
+}

src/main/java/io/nats/json/DateTimeUtils.java

@@ -1,4 +1,4 @@
-// Copyright 2020-2024 The NATS Authors
+// Copyright 2020-2025 The NATS Authors
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at:

src/main/java/io/nats/json/Encoding.java

@@ -1,4 +1,4 @@
-// Copyright 2020-2024 The NATS Authors
+// Copyright 2020-2025 The NATS Authors
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at:
@@ -13,11 +13,12 @@
 
 package io.nats.json;
 
+import org.apache.commons.codec.binary.Base64;
+
 import java.net.URLDecoder;
+import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 
-import org.apache.commons.codec.binary.Base64;
-
 /**
  * Utilities for encoding, i.e., Base64, URI and JSON
  */
@@ -52,6 +53,16 @@ public static String base64BasicEncodeToString(String input) {
         return Base64.encodeBase64String(input.getBytes(StandardCharsets.UTF_8));
     }
 
+    /**
+     * base64 url encode a byte array to a byte array
+     * @param input the input byte array to encode
+     * @param charset the charset of the input string
+     * @return the encoded byte array
+     */
+    public static String base64BasicEncodeToString(String input, Charset charset) {
+        return Base64.encodeBase64String(input.getBytes(charset));
+    }
+
     /**
      * base64 url encode a byte array to a byte array
      * @param input the input byte array to encode
@@ -79,6 +90,16 @@ public static String base64UrlEncodeToString(String input) {
         return Base64.encodeBase64URLSafeString(input.getBytes(StandardCharsets.UTF_8));
     }
 
+    /**
+     * base64 url encode a byte array to a byte array
+     * @param input the input byte array to encode
+     * @param charset the charset of the input string
+     * @return the encoded byte array
+     */
+    public static String base64UrlEncodeToString(String input, Charset charset) {
+        return Base64.encodeBase64URLSafeString(input.getBytes(charset));
+    }
+
     /**
      * base64 decode a byte array
      * @param input the input byte array to decode
@@ -103,7 +124,17 @@ public static byte[] base64BasicDecode(String input) {
      * @return the decoded string
      */
     public static String base64BasicDecodeToString(String input) {
-        return new String(Base64.decodeBase64(input));
+        return new String(Base64.decodeBase64(input), StandardCharsets.UTF_8);
+    }
+
+    /**
+     * base64 decode a base64 encoded string
+     * @param input the input string to decode
+     * @param charset the charset to use when decoding the decoded bytes to string
+     * @return the decoded string
+     */
+    public static String base64BasicDecodeToString(String input, Charset charset) {
+        return new String(Base64.decodeBase64(input), charset);
     }
 
     /**
@@ -115,6 +146,15 @@ public static byte[] base64UrlDecode(byte[] input) {
         return Base64.decodeBase64(input);
     }
 
+    /**
+     * base64 url decode a byte array
+     * @param input the input byte array to decode
+     * @return the decoded byte array
+     */
+    public static String base64UrlDecodeToString(byte[] input) {
+        return new String(Base64.decodeBase64(input));
+    }
+
     /**
      * base64 url decode a base64 url encoded string
      * @param input the input string to decode

src/main/java/io/nats/json/JsonParser.java

@@ -1,4 +1,4 @@
-// Copyright 2023-2024 The NATS Authors
+// Copyright 2023-2025 The NATS Authors
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at:
@@ -135,14 +135,7 @@ public JsonParser(char[] json, Option... options) {
     public JsonParser(char[] json, int startIndex, Option... options) {
         this.json = json;
 
-        boolean kn = false;
-        for (Option o : options) {
-            if (o == Option.KEEP_NULLS) {
-                kn = true;
-                break; // b/c only option currently
-            }
-        }
-        keepNulls = kn;
+        keepNulls = options != null && options.length > 0; // KEEP_NULLS is currently the only option
 
         len = json == null ? 0 : json.length;
         idx = startIndex;
@@ -311,7 +304,7 @@ private char peekToken() {
         return next;
     }
 
-    // next string assumes you have already seen the starting quote
+    // nextString() assumes you have already seen the starting quote
     private String nextString() throws JsonParseException {
         StringBuilder sb = new StringBuilder();
         while (true) {

src/main/java/io/nats/json/JsonSerializable.java

@@ -1,4 +1,4 @@
-// Copyright 2021-2024 The NATS Authors
+// Copyright 2021-2025 The NATS Authors
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at:
@@ -15,13 +15,32 @@
 
 import java.nio.charset.StandardCharsets;
 
+/**
+ * Interface for objects that can automatically render as JSON
+ */
 public interface JsonSerializable {
+
+    /**
+     * Get the String version of the JSON object
+     * @return the string
+     */
     String toJson();
 
+    /**
+     * Get the byte[] version of the JSON object
+     * The built-in default implementation uses the toJson() and converts it to a string.
+     * @return the byte array
+     */
     default byte[] serialize() {
         return toJson().getBytes(StandardCharsets.UTF_8);
     }
 
+    /**
+     * Get the JsonValue version of the JSON object
+     * The built-in default implementation uses the toJson() and parse it to a JsonValue.
+     * It assumes that you have valid JSON
+     * @return the JsonValue
+     */
     default JsonValue toJsonValue() {
         return JsonParser.parseUnchecked(toJson());
     }