Blackbird: ClassFile generation of unrolled codec class, optimize record / builder / field

.github/workflows/main.yml

@@ -18,9 +18,11 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        java_version: ['17', '21', '24']
+        java_version: ['17', '21', '24', '25']
         include:
-          - java_version: '17'
+          # Release/deploy runs on 25 so the blackbird module (profile-gated
+          # to JDK 25+) is part of the deployed reactor.
+          - java_version: '25'
             release_build: 'R'
     env:
       JAVA_OPTS: "-XX:+TieredCompilation -XX:TieredStopAtLevel=1"

blackbird-jpms-tests/pom.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>tools.jackson.module</groupId>
+    <artifactId>jackson-modules-base</artifactId>
+    <version>3.3.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>jackson-module-blackbird-jpms-tests</artifactId>
+  <name>Jackson module: Blackbird JPMS integration tests</name>
+  <packaging>jar</packaging>
+  <description>Module-path integration tests: a foreign named module that
+requires blackbird, exercising codec generation for its own non-public
+classes. Not published.</description>
+
+  <properties>
+    <maven.compiler.release>25</maven.compiler.release>
+    <javac.src.version>25</javac.src.version>
+    <javac.target.version>25</javac.target.version>
+    <!-- test-only module -->
+    <maven.deploy.skip>true</maven.deploy.skip>
+    <gpg.skip>true</gpg.skip>
+  </properties>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <configuration>
+          <!-- These tests assert module-path semantics (what a named module
+               can and cannot reach); the reactor-wide classpath toggle
+               (-Dsurefire.useModulePath=false) must not apply here. -->
+          <useModulePath>true</useModulePath>
+          <!-- The tests assert codec engagement through the generation trace. -->
+          <systemPropertyVariables>
+            <blackbird.debug.codegen>true</blackbird.debug.codegen>
+          </systemPropertyVariables>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+
+  <dependencies>
+    <dependency>
+      <groupId>tools.jackson.module</groupId>
+      <artifactId>jackson-module-blackbird</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+</project>

blackbird-jpms-tests/src/main/java/blackbird/jpms/test/beans/Beans.java

@@ -0,0 +1,16 @@
+package blackbird.jpms.test.beans;
+
+import java.lang.invoke.MethodHandles;
+
+/** Hands tests this module's lookup and its non-public bean type. */
+public final class Beans {
+    private Beans() {}
+
+    public static MethodHandles.Lookup lookup() {
+        return MethodHandles.lookup();
+    }
+
+    public static Class<?> pkgBeanClass() {
+        return PkgBean.class;
+    }
+}

blackbird-jpms-tests/src/main/java/blackbird/jpms/test/beans/PkgBean.java

@@ -0,0 +1,14 @@
+package blackbird.jpms.test.beans;
+
+// Deliberately package-private: the codec for this bean must be defined in
+// this module's package context, which only works when the generated class
+// can resolve its supertype from here.
+class PkgBean {
+    private int count;
+    private String name;
+
+    public int getCount() { return count; }
+    public void setCount(int v) { count = v; }
+    public String getName() { return name; }
+    public void setName(String v) { name = v; }
+}

blackbird-jpms-tests/src/main/java/module-info.java

@@ -0,0 +1,15 @@
+// A foreign named module from Blackbird's point of view: it requires the
+// blackbird module and holds non-public beans plus a lookup of its own, the
+// exact arrangement a modular application has.
+module blackbird.jpms.test
+{
+    requires tools.jackson.databind;
+    requires tools.jackson.module.blackbird;
+
+    exports blackbird.jpms.test.beans;
+    // What a modular application must do for stock databind to construct
+    // non-public beans reflectively - and the ONLY requirement blackbird
+    // adds: none. Deliberately NOT opened to blackbird: the accelerated path
+    // rides databind's fixAccess through unreflected constant handles.
+    opens blackbird.jpms.test.beans to tools.jackson.databind;
+}

blackbird-jpms-tests/src/test/java/blackbird/jpms/test/beans/JpmsPackagePrivateTest.java

@@ -0,0 +1,93 @@
+package blackbird.jpms.test.beans;
+
+import java.io.ByteArrayOutputStream;
+import java.io.PrintStream;
+import java.lang.invoke.MethodHandles;
+import java.nio.charset.StandardCharsets;
+import java.util.function.Supplier;
+
+import org.junit.jupiter.api.Test;
+
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.json.JsonMapper;
+import tools.jackson.module.blackbird.BlackbirdModule;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Runs on the module path as the named module blackbird.jpms.test, which
+ * requires blackbird: the arrangement a modular application has. A
+ * package-private bean of this module accelerates with no user lookup at all:
+ * the only JPMS requirement is the {@code opens ... to tools.jackson.databind}
+ * that stock databind already needs. Databind's fixAccess marks the members
+ * accessible, the codec reaches them through unreflected constant handles,
+ * and the generated class defines in blackbird's own module context. The
+ * lookup-supplying constructor remains a supported (now redundant) API.
+ *
+ * Engagement is asserted through the blackbird.debug.codegen diagnostic
+ * stream: byte-identical output makes generated and stock otherwise
+ * indistinguishable from out here.
+ */
+public class JpmsPackagePrivateTest
+{
+    private static final String DOC = "{\"count\":7,\"name\":\"x\"}";
+
+    // The lookup API is a released contract and must keep working even though
+    // acceleration no longer needs it.
+    @Test
+    public void packagePrivateBeanAcceleratesWithModuleLookup() throws Exception {
+        ObjectMapper mapper = JsonMapper.builder()
+                .addModule(new BlackbirdModule() {
+                    private static final long serialVersionUID = 1L;
+                    @Override
+                    protected Supplier<MethodHandles.Lookup> findLookupSupplier() {
+                        return Beans::lookup;
+                    }
+                })
+                .build();
+        String err = captureErr(() -> {
+            PkgBean bean = mapper.readValue(DOC, PkgBean.class);
+            assertEquals(7, bean.getCount());
+            assertEquals("x", bean.getName());
+        });
+        assertTrue(err.contains("BBReader_PkgBean"),
+                "expected a generated codec for PkgBean; diagnostics:\n" + err);
+        assertFalse(err.contains("null (gated)"),
+                "PkgBean was gated instead of accelerated; diagnostics:\n" + err);
+    }
+
+    @Test
+    public void acceleratesWithoutUserLookup() throws Exception {
+        // Widened from a demotion pin: no lookup is required any more. The
+        // opens-to-databind that stock needs is the whole contract.
+        ObjectMapper mapper = JsonMapper.builder()
+                .addModule(new BlackbirdModule())
+                .build();
+        String err = captureErr(() -> {
+            PkgBean bean = mapper.readValue(DOC, PkgBean.class);
+            assertEquals(7, bean.getCount());
+            assertEquals("x", bean.getName());
+        });
+        assertTrue(err.contains("BBReader_PkgBean"),
+                "expected a generated codec for PkgBean with no user lookup; diagnostics:\n"
+                        + err);
+        assertFalse(err.contains("null (gated)"),
+                "PkgBean was gated instead of accelerated; diagnostics:\n" + err);
+    }
+
+    private interface Body {
+        void run() throws Exception;
+    }
+
+    private static synchronized String captureErr(Body body) throws Exception {
+        PrintStream original = System.err;
+        ByteArrayOutputStream buffer = new ByteArrayOutputStream();
+        System.setErr(new PrintStream(buffer, true, StandardCharsets.UTF_8));
+        try {
+            body.run();
+        } finally {
+            System.setErr(original);
+        }
+        return buffer.toString(StandardCharsets.UTF_8);
+    }
+}

blackbird-tests/src/test/java/tools/jackson/module/blackbird/inject/BlackbirdInjectionTestBase.java

@@ -1,8 +1,5 @@
 package tools.jackson.module.blackbird.inject;
 
-import java.lang.reflect.Field;
-import java.util.ArrayList;
-import java.util.List;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 
@@ -11,25 +8,30 @@
 import tools.jackson.databind.SerializationConfig;
 import tools.jackson.databind.ValueDeserializer;
 import tools.jackson.databind.ValueSerializer;
-import tools.jackson.databind.deser.SettableBeanProperty;
 import tools.jackson.databind.deser.ValueDeserializerModifier;
-import tools.jackson.databind.deser.bean.BeanDeserializer;
 import tools.jackson.databind.json.JsonMapper;
 import tools.jackson.databind.module.SimpleModule;
-import tools.jackson.databind.ser.BeanPropertyWriter;
 import tools.jackson.databind.ser.ValueSerializerModifier;
 import tools.jackson.module.blackbird.BlackbirdModule;
 
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 
-// Test utilities for verifying that Blackbird's lambda-based injection pipeline
-// actually ran on a given POJO. Because Blackbird's optimized property and writer
-// classes (SettableIntProperty, etc.; IntPropertyWriter, etc.) are package-private
-// inside the blackbird module, these checks rely on reflection and simple-name
-// matching rather than compile-time type references. Mirrors the afterburner-tests
-// harness; see that module's README for the broader rationale.
+// Test utilities for verifying that Blackbird's codec generation engaged for a
+// given POJO loaded from the unnamed module (classpath). Blackbird installs a
+// per-bean placeholder (BBReaderPlaceholder / BBWriterPlaceholder) that
+// resolves to a generated hidden-class codec; the placeholder types are
+// package-private inside the blackbird module, so these checks match by simple
+// name and package rather than compile-time type references. Mirrors the
+// afterburner-tests harness; see that module's README for the broader
+// rationale.
 abstract class BlackbirdInjectionTestBase
 {
+    static {
+        // Strict mode: a codec-generation failure fails the test instead of
+        // demoting to the stock path (see CodegenFallbacks).
+        System.setProperty("tools.jackson.module.blackbird.failOnCodegenError", "true");
+    }
+
     protected static Harness newHarness() {
         return new Harness();
     }
@@ -67,9 +69,11 @@ public ValueSerializer<?> modifySerializer(
                     });
                 }
             };
+            // Modifiers run in reverse registration order, so the capture
+            // module registers first to observe what Blackbird installed.
             this.mapper = JsonMapper.builder()
-                    .addModule(new BlackbirdModule())
                     .addModule(capture)
+                    .addModule(new BlackbirdModule())
                     .build();
         }
 
@@ -86,86 +90,20 @@ ValueSerializer<?> serFor(Class<?> cls) {
         }
     }
 
-    /** Returns the `_propsByIndex` array from a bean deserializer. */
-    protected static SettableBeanProperty[] propsOf(ValueDeserializer<?> deser) {
-        if (!(deser instanceof BeanDeserializer)) {
-            throw new AssertionError("not a BeanDeserializer: " + deser.getClass().getName());
-        }
-        return (SettableBeanProperty[]) reflectField(deser, "_propsByIndex");
+    /** True if Blackbird installed its deserializer codec for the captured value. */
+    protected static boolean isBlackbirdReader(ValueDeserializer<?> deser) {
+        return blackbirdClassChainIncludes(deser.getClass(), "BBReaderPlaceholder");
     }
 
-    /** Returns the BeanPropertyWriter[] from a bean serializer, as a list. */
-    protected static List<BeanPropertyWriter> writersOf(ValueSerializer<?> ser) {
-        BeanPropertyWriter[] arr = (BeanPropertyWriter[]) reflectField(ser, "_props");
-        List<BeanPropertyWriter> out = new ArrayList<>(arr.length);
-        for (BeanPropertyWriter w : arr) {
-            out.add(w);
-        }
-        return out;
-    }
-
-    /** Walks the class chain of {@code instance} looking for a declared field
-     *  named {@code fieldName}. Picks the error message hypothesis based on the
-     *  class's package — databind/blackbird fields usually mean a rename,
-     *  anything else means the caller passed the wrong receiver. */
-    protected static Object reflectField(Object instance, String fieldName) {
-        Class<?> origClass = instance.getClass();
-        Class<?> c = origClass;
-        while (c != null) {
-            try {
-                Field f = c.getDeclaredField(fieldName);
-                f.setAccessible(true);
-                return f.get(instance);
-            } catch (NoSuchFieldException ignore) {
-                c = c.getSuperclass();
-            } catch (IllegalAccessException e) {
-                throw new AssertionError("cannot read field '" + fieldName + "' on "
-                        + origClass.getName(), e);
-            }
-        }
-        String pkg = origClass.getPackageName();
-        String hint;
-        if (pkg.startsWith("tools.jackson.databind")
-                || pkg.startsWith("tools.jackson.module.blackbird")) {
-            hint = "databind or blackbird may have renamed or removed it;"
-                    + " update " + BlackbirdInjectionTestBase.class.getSimpleName()
-                    + " to match.";
-        } else {
-            hint = "this looks like the wrong receiver type — '" + fieldName
-                    + "' is an internal Jackson field and the caller passed an"
-                    + " instance of " + origClass.getName() + ".";
-        }
-        throw new AssertionError("field '" + fieldName + "' not found on "
-                + origClass.getName() + " (walked up full class chain) — " + hint);
-    }
-
-    /** True if `prop`'s class chain contains Blackbird's OptimizedSettableBeanProperty. */
-    protected static boolean isOptimizedProperty(SettableBeanProperty prop) {
-        return blackbirdClassChainIncludes(prop.getClass(), "OptimizedSettableBeanProperty");
-    }
-
-    /** True if `writer`'s class chain contains Blackbird's OptimizedBeanPropertyWriter. */
-    protected static boolean isOptimizedWriter(BeanPropertyWriter writer) {
-        return blackbirdClassChainIncludes(writer.getClass(), "OptimizedBeanPropertyWriter");
-    }
-
-    /** Walks the superclass chain of {@code cls} looking for a class whose simple
-     *  name is {@code simpleName}. Used to recognize Blackbird's package-private
-     *  optimized types without importing them. */
-    protected static boolean classChainIncludes(Class<?> cls, String simpleName) {
-        Class<?> c = cls;
-        while (c != null) {
-            if (simpleName.equals(c.getSimpleName())) {
-                return true;
-            }
-            c = c.getSuperclass();
-        }
-        return false;
+    /** True if Blackbird installed its serializer codec for the captured value. */
+    protected static boolean isBlackbirdWriter(ValueSerializer<?> ser) {
+        return blackbirdClassChainIncludes(ser.getClass(), "BBWriterPlaceholder");
     }
 
-    /** Like {@link #classChainIncludes} but additionally requires the matched
-     *  class to live inside a blackbird package. Guards against false positives
-     *  from unrelated classes that happen to share a simple name. */
+    /** Walks the superclass chain of {@code cls} looking for a class whose
+     *  simple name is {@code simpleName} and that lives inside a blackbird
+     *  package. Recognizes Blackbird's package-private types without importing
+     *  them, and guards against unrelated classes sharing a simple name. */
     protected static boolean blackbirdClassChainIncludes(Class<?> cls, String simpleName) {
         Class<?> c = cls;
         while (c != null) {