Nullability annotations, javadoc and test coverage

Author: scottf

build.gradle

@@ -33,6 +33,7 @@ repositories {
 }
 
 dependencies {
+    implementation 'org.jetbrains:annotations:26.0.2'
     implementation 'commons-codec:commons-codec:1.18.0'
 
     testImplementation 'org.junit.jupiter:junit-jupiter:5.7.1'

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

@@ -13,24 +13,58 @@
 
 package io.nats.json;
 
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
 import java.util.ArrayList;
 import java.util.Collection;
 
+/**
+ * Utility class to build a JsonValue for an array
+ */
 public class ArrayBuilder implements JsonSerializable {
 
-    public final JsonValue jv = new JsonValue(new ArrayList<>());
+    /**
+     * The JsonValue backing this ArrayBuilder
+     */
+    @NotNull
+    public final JsonValue jv;
+
+    /**
+     * Get a new instance of ArrayBuilder
+     */
+    public ArrayBuilder() {
+        jv = new JsonValue(new ArrayList<>());
+    }
 
+    /**
+     * Get an instance of ArrayBuilder
+     * @return an ArrayBuilder instance
+     */
+    @NotNull
     public static ArrayBuilder instance() {
         return new ArrayBuilder();
     }
 
-    public ArrayBuilder add(Object o) {
+    /**
+     * Add an object to the array. The object is converted to a JsonValue if it isn't one already.
+     * @param o the object
+     * @return the builder
+     */
+    @NotNull
+    public ArrayBuilder add(@Nullable 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) {
+    /**
+     * Add all items in the collection to the array, unless an item is null;
+     * @param c the collection
+     * @return the builder
+     */
+    @NotNull
+    public ArrayBuilder addItems(@Nullable Collection<?> c) {
         if (c != null) {
             for (Object o : c) {
                 //noinspection DataFlowIssue // NO ISSUE, WE KNOW jv.array is NOT NULL
@@ -40,12 +74,20 @@ public ArrayBuilder addItems(Collection<?> c) {
         return this;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
+    @NotNull
     public String toJson() {
         return jv.toJson();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
+    @NotNull
     public JsonValue toJsonValue() {
         return jv;
     }

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

@@ -13,6 +13,9 @@
 
 package io.nats.json;
 
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
 import java.time.Duration;
 import java.time.Instant;
 import java.time.ZoneId;
@@ -29,31 +32,36 @@ private DateTimeUtils() {}  /* ensures cannot be constructed */
     /**
      * The ZoneId for GMT
      */
+    @NotNull
     public static final ZoneId ZONE_ID_GMT = ZoneId.of("GMT");
 
     /**
      * The ZoneDateTime uses as a default, can be used instead of null
      */
+    @NotNull
     public static final ZonedDateTime DEFAULT_TIME = ZonedDateTime.of(1, 1, 1, 0, 0, 0, 0, ZONE_ID_GMT);
 
     /**
      * The formatter to crate RFC 3339 strings from dates.
      */
+    @NotNull
     public static final DateTimeFormatter RFC3339_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.nnnnnnnnn'Z'");
 
     /**
      * Convert a ZoneDateTime to a GMT version of the ZoneDateTime
      * @param zonedDateTime the input
      * @return the output
      */
-    public static ZonedDateTime toGmt(ZonedDateTime zonedDateTime) {
+    @NotNull
+    public static ZonedDateTime toGmt(@NotNull ZonedDateTime zonedDateTime) {
         return zonedDateTime.withZoneSameInstant(ZONE_ID_GMT);
     }
 
     /**
      * Get an instance of ZonedDateTime.now(), but for the GMT timezone
      * @return the current date-time using the system clock in GMT
      */
+    @NotNull
     public static ZonedDateTime gmtNow() {
         return ZonedDateTime.now().withZoneSameInstant(ZONE_ID_GMT);
     }
@@ -64,7 +72,7 @@ public static ZonedDateTime gmtNow() {
      * @param zdt2 the second ZonedDateTime
      * @return true if they are equal
      */
-    public static boolean equals(ZonedDateTime zdt1, ZonedDateTime zdt2) {
+    public static boolean equals(@Nullable ZonedDateTime zdt1, @Nullable ZonedDateTime zdt2) {
         if (zdt1 == zdt2) return true;
         if (zdt1 == null || zdt2 == null) return false;
         return zdt1.withZoneSameInstant(ZONE_ID_GMT).equals(zdt2.withZoneSameInstant(ZONE_ID_GMT));
@@ -75,7 +83,8 @@ public static boolean equals(ZonedDateTime zdt1, ZonedDateTime zdt2) {
      * @param zonedDateTime the input
      * @return the formatted string
      */
-    public static String toRfc3339(ZonedDateTime zonedDateTime) {
+    @NotNull
+    public static String toRfc3339(@NotNull ZonedDateTime zonedDateTime) {
         return RFC3339_FORMATTER.format(toGmt(zonedDateTime));
     }
 
@@ -84,7 +93,8 @@ public static String toRfc3339(ZonedDateTime zonedDateTime) {
      * @param dateTime - date time from the server.
      * @return a Zoned Date time.
      */
-    public static ZonedDateTime parseDateTime(String dateTime) {
+    @NotNull
+    public static ZonedDateTime parseDateTime(@NotNull String dateTime) {
         return parseDateTime(dateTime, DEFAULT_TIME);
     }
 
@@ -94,7 +104,8 @@ public static ZonedDateTime parseDateTime(String dateTime) {
      * @param dflt - the default ZoneDateTime to use if the input string exceptions while parsing
      * @return a ZonedDateTime.
      */
-    public static ZonedDateTime parseDateTime(String dateTime, ZonedDateTime dflt) {
+    @NotNull
+    public static ZonedDateTime parseDateTime(@NotNull String dateTime, @NotNull ZonedDateTime dflt) {
         try {
             return toGmt(ZonedDateTime.parse(dateTime));
         }
@@ -108,7 +119,8 @@ public static ZonedDateTime parseDateTime(String dateTime, ZonedDateTime dflt) {
      * @param dateTime - date time from the server.
      * @return a ZonedDateTime.
      */
-    public static ZonedDateTime parseDateTimeThrowParseError(String dateTime) {
+    @NotNull
+    public static ZonedDateTime parseDateTimeThrowParseError(@NotNull String dateTime) {
         return toGmt(ZonedDateTime.parse(dateTime));
     }
 
@@ -117,6 +129,7 @@ public static ZonedDateTime parseDateTimeThrowParseError(String dateTime) {
      * @param millis the millis from now value
      * @return a ZonedDateTime.
      */
+    @NotNull
     public static ZonedDateTime fromNow(long millis) {
         return ZonedDateTime.ofInstant(Instant.now().plusMillis(millis), ZONE_ID_GMT);
     }
@@ -126,7 +139,8 @@ public static ZonedDateTime fromNow(long millis) {
      * @param dur the duration to use the millis for from now
      * @return a ZonedDateTime.
      */
-    public static ZonedDateTime fromNow(Duration dur) {
+    @NotNull
+    public static ZonedDateTime fromNow(@NotNull Duration dur) {
         return ZonedDateTime.ofInstant(Instant.now().plusMillis(dur.toMillis()), ZONE_ID_GMT);
     }
 }