Change Java JSON to Avaje Jsonb (#8721)

Jackson is a very heavy library; it supports loads of features that we don't need, and historically has caused issues due to long class loading times (a little over 2 seconds to load AprilTagFieldLayout). This often manifests as a help request in the form of "my robot disables when I do X, but doesn't disable when doing X in subsequent attempts until code restart." While SC has brought down Jackson loading times significantly, with AprilTagFieldLayout loads taking only 330 milliseconds, that's still a rather long delay, and while libraries should handle any JSON loading ahead of time to prevent delays in auto/teleop, it would still be good to make the worst case better to reduce user frustration. Benchmarks indicate using [Avaje Jsonb](https://github.com/avaje/avaje-jsonb) to load AprilTagFieldLayout only takes ~70 ms, a fair chunk of which isn't actually in Avaje Jsonb (~4 ms is spent on using getResourceAsStream to retrieve the JSON file, ~8 ms is spent on just loading the AprilTag class and its dependencies). Note that all times listed are end-to-end, meaning nothing else was done except for the operation being benchmarked, and doing arithmetic on them can be flawed due to some classes being loaded twice, i.e., getResourceAsStream and `new AprilTag()` likely load some of the same JDK classes and so subtracting both from the Avaje Jsonb load time is likely slightly incorrect because class loading is being double counted. For our purposes, it's likely accurate enough and is mostly just for contextualization. Benchmarks were run on a Raspberry Pi CM5 with 2 GB of RAM. Source code for the [results](https://github.com/user-attachments/files/26471452/benchmark.txt) can be found in the "Fastjson2" commit (2456d15ca8ebd17635e607cd40bf8816e77869a1). Avaje Jsonb uses code generation via annotation processors to generate the classes needed to do JSON serde and uses service providers to find them, which will require downstream changes in robot projects, as the different service providers in each library must be merged together for Avaje Jsonb to function. We will use the Gradle shadow plugin, as its already used by the installer and therefore adds zero additional dependencies.
2026-06-19 00:41:43 +00:00 · 2026-04-11 02:21:00 -04:00
parent 346cd9ed9c
commit 2102a543d1
32 changed files with 294 additions and 298 deletions
--- a/apriltag/BUILD.bazel
+++ b/apriltag/BUILD.bazel
@@ -140,6 +140,9 @@ wpilib_jni_java_library(
    maven_artifact_name = "apriltag-java",
    maven_group_id = "org.wpilib.apriltag",
    native_libs = [":apriltagjni"],
+    plugins = [
+        "//:avaje_jsonb_generator",
+    ],
    resource_strip_prefix = "apriltag/src/main/native/resources",
    resources = glob(["src/main/native/resources/**"]),
    visibility = ["//visibility:public"],
@@ -147,9 +150,8 @@ wpilib_jni_java_library(
        "//wpimath:wpimath-java",
        "//wpiutil:wpiutil-java",
        "@bzlmodrio-opencv//libraries/java/opencv",
-        "@maven//:com_fasterxml_jackson_core_jackson_annotations",
-        "@maven//:com_fasterxml_jackson_core_jackson_core",
-        "@maven//:com_fasterxml_jackson_core_jackson_databind",
+        "@maven//:io_avaje_avaje_json_core",
+        "@maven//:io_avaje_avaje_jsonb",
    ],
 )

@@ -182,7 +184,7 @@ wpilib_java_junit5_test(
        "//wpimath:wpimath-java",
        "//wpiutil:wpiutil-java",
        "@bzlmodrio-opencv//libraries/java/opencv",
-        "@maven//:com_fasterxml_jackson_core_jackson_databind",
+        "@maven//:io_avaje_avaje_jsonb",
    ],
 )

--- a/apriltag/CMakeLists.txt
+++ b/apriltag/CMakeLists.txt
@@ -39,7 +39,7 @@ if(WITH_JAVA)
    set(CMAKE_JNI_TARGET true)

    file(GLOB EJML_JARS "${WPILIB_BINARY_DIR}/wpimath/thirdparty/ejml/*.jar")
-    file(GLOB JACKSON_JARS "${WPILIB_BINARY_DIR}/wpiutil/thirdparty/jackson/*.jar")
+    file(GLOB AVAJE_JARS "${WPILIB_BINARY_DIR}/wpiutil/thirdparty/avaje/*.jar")
    find_file(
        OPENCV_JAR_FILE
        NAMES opencv-${OpenCV_VERSION_MAJOR}${OpenCV_VERSION_MINOR}${OpenCV_VERSION_PATCH}.jar
@@ -69,7 +69,7 @@ if(WITH_JAVA)
            wpiutil_jar
            ${EJML_JARS}
            ${OPENCV_JAR_FILE}
-            ${JACKSON_JARS}
+            ${AVAJE_JARS}
        OUTPUT_NAME apriltag
        OUTPUT_DIR ${WPILIB_BINARY_DIR}/${java_lib_dest}
        GENERATE_NATIVE_HEADERS apriltag_jni_headers
--- a/apriltag/build.gradle
+++ b/apriltag/build.gradle
@@ -46,6 +46,7 @@ apply from: "${rootDir}/shared/opencv.gradle"

 dependencies {
    implementation project(':wpimath')
+    annotationProcessor libs.avaje.jsonb.generator
 }

 sourceSets {
--- a/apriltag/src/main/java/org/wpilib/vision/apriltag/AprilTag.java
+++ b/apriltag/src/main/java/org/wpilib/vision/apriltag/AprilTag.java
@@ -4,8 +4,7 @@

 package org.wpilib.vision.apriltag;

-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonProperty;
+import io.avaje.jsonb.Json;
 import java.util.Objects;
 import org.wpilib.math.geometry.Pose3d;
 import org.wpilib.util.RawFrame;
@@ -13,13 +12,14 @@ import org.wpilib.vision.apriltag.jni.AprilTagJNI;

 /** Represents an AprilTag's metadata. */
@SuppressWarnings("MemberName")
+@Json
 public class AprilTag {
  /** The tag's ID. */
-  @JsonProperty(value = "ID")
+  @Json.Property("ID")
  public int ID;

  /** The tag's pose. */
-  @JsonProperty(value = "pose")
+  @Json.Property("pose")
  public Pose3d pose;

  /**
@@ -29,10 +29,8 @@ public class AprilTag {
   * @param pose The tag's pose.
   */
  @SuppressWarnings("ParameterName")
-  @JsonCreator
-  public AprilTag(
-      @JsonProperty(required = true, value = "ID") int ID,
-      @JsonProperty(required = true, value = "pose") Pose3d pose) {
+  @Json.Creator
+  public AprilTag(int ID, Pose3d pose) {
    this.ID = ID;
    this.pose = pose;
  }
--- a/apriltag/src/main/java/org/wpilib/vision/apriltag/AprilTagFieldLayout.java
+++ b/apriltag/src/main/java/org/wpilib/vision/apriltag/AprilTagFieldLayout.java
@@ -4,17 +4,12 @@

 package org.wpilib.vision.apriltag;

-import com.fasterxml.jackson.annotation.JsonAutoDetect;
-import com.fasterxml.jackson.annotation.JsonCreator;
-import com.fasterxml.jackson.annotation.JsonIgnore;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.avaje.jsonb.Json;
+import io.avaje.jsonb.Jsonb;
 import java.io.IOException;
 import java.io.InputStream;
-import java.io.InputStreamReader;
 import java.io.UncheckedIOException;
-import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -43,8 +38,7 @@ import org.wpilib.math.geometry.Translation3d;
 * <p>Tag poses represent the center of the tag, with a zero rotation representing a tag that is
 * upright and facing away from the (blue) alliance wall (that is, towards the opposing alliance).
 */
-@JsonIgnoreProperties(ignoreUnknown = true)
-@JsonAutoDetect(getterVisibility = JsonAutoDetect.Visibility.NONE)
+@Json
 public class AprilTagFieldLayout {
  /** Common origin positions for the AprilTag coordinate system. */
  public enum OriginPosition {
@@ -54,12 +48,12 @@ public class AprilTagFieldLayout {
    kRedAllianceWallRightSide,
  }

-  private final Map<Integer, AprilTag> m_apriltags = new HashMap<>();
+  @Json.Ignore private final Map<Integer, AprilTag> m_apriltags = new HashMap<>();

-  @JsonProperty(value = "field")
-  private FieldDimensions m_fieldDimensions;
+  @Json.Property("field")
+  FieldDimensions m_fieldDimensions;

-  private Pose3d m_origin;
+  @Json.Ignore private Pose3d m_origin;

  /**
   * Construct a new AprilTagFieldLayout with values imported from a JSON file.
@@ -79,7 +73,7 @@ public class AprilTagFieldLayout {
   */
  public AprilTagFieldLayout(Path path) throws IOException {
    AprilTagFieldLayout layout =
-        new ObjectMapper().readValue(path.toFile(), AprilTagFieldLayout.class);
+        Jsonb.instance().type(AprilTagFieldLayout.class).fromJson(Files.newBufferedReader(path));
    m_apriltags.putAll(layout.m_apriltags);
    m_fieldDimensions = layout.m_fieldDimensions;
    setOrigin(OriginPosition.kBlueAllianceWallRightSide);
@@ -96,10 +90,10 @@ public class AprilTagFieldLayout {
    this(apriltags, new FieldDimensions(fieldLength, fieldWidth));
  }

-  @JsonCreator
-  private AprilTagFieldLayout(
-      @JsonProperty(required = true, value = "tags") List<AprilTag> apriltags,
-      @JsonProperty(required = true, value = "field") FieldDimensions fieldDimensions) {
+  @Json.Creator
+  AprilTagFieldLayout(
+      @Json.Alias("tags") List<AprilTag> apriltags,
+      @Json.Alias("field") FieldDimensions fieldDimensions) {
    // To ensure the underlying semantics don't change with what kind of list is passed in
    for (AprilTag tag : apriltags) {
      m_apriltags.put(tag.ID, tag);
@@ -113,7 +107,7 @@ public class AprilTagFieldLayout {
   *
   * @return The {@link AprilTag AprilTags} used in this layout.
   */
-  @JsonProperty("tags")
+  @Json.Property("tags")
  public List<AprilTag> getTags() {
    return new ArrayList<>(m_apriltags.values());
  }
@@ -123,7 +117,6 @@ public class AprilTagFieldLayout {
   *
   * @return length, in meters
   */
-  @JsonIgnore
  public double getFieldLength() {
    return m_fieldDimensions.fieldLength;
  }
@@ -133,7 +126,6 @@ public class AprilTagFieldLayout {
   *
   * @return width, in meters
   */
-  @JsonIgnore
  public double getFieldWidth() {
    return m_fieldDimensions.fieldWidth;
  }
@@ -147,7 +139,6 @@ public class AprilTagFieldLayout {
   *
   * @param origin The predefined origin
   */
-  @JsonIgnore
  public final void setOrigin(OriginPosition origin) {
    var pose =
        switch (origin) {
@@ -168,7 +159,6 @@ public class AprilTagFieldLayout {
   *
   * @param origin The new origin for tag transformations
   */
-  @JsonIgnore
  public final void setOrigin(Pose3d origin) {
    m_origin = origin;
  }
@@ -178,7 +168,6 @@ public class AprilTagFieldLayout {
   *
   * @return the origin
   */
-  @JsonIgnore
  public Pose3d getOrigin() {
    return m_origin;
  }
@@ -216,7 +205,7 @@ public class AprilTagFieldLayout {
   * @throws IOException If writing to the file fails.
   */
  public void serialize(Path path) throws IOException {
-    new ObjectMapper().writeValue(path.toFile(), this);
+    Jsonb.instance().type(AprilTagFieldLayout.class).toJson(this, Files.newBufferedWriter(path));
  }

  /**
@@ -253,16 +242,12 @@ public class AprilTagFieldLayout {
   * @throws IOException If the resource could not be loaded
   */
  public static AprilTagFieldLayout loadFromResource(String resourcePath) throws IOException {
-    InputStream stream = AprilTagFieldLayout.class.getResourceAsStream(resourcePath);
-    if (stream == null) {
-      // Class.getResourceAsStream() returns null if the resource does not exist.
-      throw new IOException("Could not locate resource: " + resourcePath);
-    }
-    InputStreamReader reader = new InputStreamReader(stream, StandardCharsets.UTF_8);
-    try {
-      return new ObjectMapper().readerFor(AprilTagFieldLayout.class).readValue(reader);
-    } catch (IOException e) {
-      throw new IOException("Failed to load AprilTagFieldLayout: " + resourcePath);
+    try (InputStream stream = AprilTagFieldLayout.class.getResourceAsStream(resourcePath)) {
+      if (stream == null) {
+        // Class.getResourceAsStream() returns null if the resource does not exist.
+        throw new IOException("Could not locate resource: " + resourcePath);
+      }
+      return Jsonb.instance().type(AprilTagFieldLayout.class).fromJson(stream);
    }
  }

@@ -278,21 +263,19 @@ public class AprilTagFieldLayout {
    return Objects.hash(m_apriltags, m_origin);
  }

-  @JsonIgnoreProperties(ignoreUnknown = true)
-  @JsonAutoDetect(getterVisibility = JsonAutoDetect.Visibility.NONE)
-  private static class FieldDimensions {
+  static class FieldDimensions {
    @SuppressWarnings("MemberName")
-    @JsonProperty(value = "length")
+    @Json.Property(value = "length")
    public final double fieldLength;

    @SuppressWarnings("MemberName")
-    @JsonProperty(value = "width")
+    @Json.Property(value = "width")
    public final double fieldWidth;

-    @JsonCreator()
+    @Json.Creator()
    FieldDimensions(
-        @JsonProperty(required = true, value = "length") double fieldLength,
-        @JsonProperty(required = true, value = "width") double fieldWidth) {
+        @Json.Alias(value = "length") double fieldLength,
+        @Json.Alias(value = "width") double fieldWidth) {
      this.fieldLength = fieldLength;
      this.fieldWidth = fieldWidth;
    }
--- a/apriltag/src/test/java/org/wpilib/vision/apriltag/AprilTagSerializationTest.java
+++ b/apriltag/src/test/java/org/wpilib/vision/apriltag/AprilTagSerializationTest.java
@@ -7,7 +7,7 @@ package org.wpilib.vision.apriltag;
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertEquals;

-import com.fasterxml.jackson.databind.ObjectMapper;
+import io.avaje.jsonb.Jsonb;
 import java.util.List;
 import org.junit.jupiter.api.Test;
 import org.wpilib.math.geometry.Pose3d;
@@ -25,13 +25,9 @@ class AprilTagSerializationTest {
            Units.feetToMeters(54.0),
            Units.feetToMeters(27.0));

-    var objectMapper = new ObjectMapper();
+    var layoutType = Jsonb.instance().type(AprilTagFieldLayout.class);

-    var deserialized =
-        assertDoesNotThrow(
-            () ->
-                objectMapper.readValue(
-                    objectMapper.writeValueAsString(layout), AprilTagFieldLayout.class));
+    var deserialized = assertDoesNotThrow(() -> layoutType.fromJson(layoutType.toJson(layout)));

    assertEquals(layout, deserialized);
  }