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

.github/workflows/dep_build_v3.yml

@@ -15,20 +15,43 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        java_version: ['17', '21']
+        # 17, 21: all modules except Blackbird (profile-gated to JDK 25+).
+        # 25: only the Blackbird modules, which the other two leave out.
+        java_version: ['17', '21', '25']
     env:
       JAVA_OPTS: "-XX:+TieredCompilation -XX:TieredStopAtLevel=1"
     steps:
     - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       with:
         ref: 3.x
+    # Blackbird builds only on JDK 25+, but its jar must run on 17-24 too
+    # (module discovery skips it there); blackbird-tests starts those JDKs.
+    # Keep in sync with main.yml.
+    - name: Set up older JDKs for Blackbird runtime tests
+      if: ${{ matrix.java_version == '25' }}
+      uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
+      with:
+        distribution: 'temurin'
+        java-version: |
+          17
+          21
     - name: Set up JDK
       uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
       with:
         distribution: 'temurin'
         java-version: ${{ matrix.java_version }}
         cache: 'maven'
     - name: Build and test
-      run: ./mvnw -B -ff -ntp clean verify
+      run: |
+        BUILD_ARGS=""
+        if [ "${{ matrix.java_version }}" = "25" ]; then
+          if [ -z "${JAVA_HOME_17_X64:-}" ] || [ -z "${JAVA_HOME_21_X64:-}" ]; then
+            echo "::error::JDK 17/21 homes not found; Blackbird old-JDK tests would be skipped"
+            exit 1
+          fi
+          BUILD_ARGS="-pl blackbird,blackbird-tests,blackbird-jpms-tests -am"
+          BUILD_ARGS="${BUILD_ARGS} -Dblackbird.test.oldJdks=${JAVA_HOME_17_X64},${JAVA_HOME_21_X64}"
+        fi
+        ./mvnw -B -ff -ntp clean verify ${BUILD_ARGS}
 
 # No recursive rebuild (yet?)

.github/workflows/main.yml

@@ -20,12 +20,24 @@ jobs:
       matrix:
         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"
     steps:
     - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+    # Blackbird builds only on JDK 25+, but its jar must run on 17-24 too
+    # (module discovery skips it there); blackbird-tests starts those JDKs.
+    - name: Set up older JDKs for Blackbird runtime tests
+      if: ${{ matrix.java_version == '25' }}
+      uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
+      with:
+        distribution: 'temurin'
+        java-version: |
+          17
+          21
     - name: Set up JDK
       uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
       with:
@@ -39,7 +51,16 @@ jobs:
         # gpg-private-key: ${{ secrets.MAVEN_GPG_PRIVATE_KEY }} # Value of the GPG private key to import
         # gpg-passphrase: MAVEN_GPG_PASSPHRASE # env variable for GPG private key passphrase
     - name: Build
-      run: ./mvnw -B -ff -ntp clean verify
+      run: |
+        OLD_JDKS=""
+        if [ "${{ matrix.java_version }}" = "25" ]; then
+          if [ -z "${JAVA_HOME_17_X64:-}" ] || [ -z "${JAVA_HOME_21_X64:-}" ]; then
+            echo "::error::JDK 17/21 homes not found; Blackbird old-JDK tests would be skipped"
+            exit 1
+          fi
+          OLD_JDKS="-Dblackbird.test.oldJdks=${JAVA_HOME_17_X64},${JAVA_HOME_21_X64}"
+        fi
+        ./mvnw -B -ff -ntp clean verify ${OLD_JDKS}
     - name: Extract project Maven version
       id: projectVersion
       run: echo "version=$(./mvnw org.apache.maven.plugins:maven-help-plugin:3.5.1:evaluate -DforceStdout -Dexpression=project.version -q)" >> $GITHUB_OUTPUT

CLAUDE.md

@@ -10,7 +10,9 @@ Jackson modules-base is a multi-module Maven project containing 11 foundational
 
 (paranamer is not part of 3.x — it only appears commented out in the root `pom.xml`.)
 
-There are also two test-only, never-published modules: `afterburner-tests` and `blackbird-tests`. They have no `module-info.java`, so their test POJOs live in the unnamed module and exercise the bytecode-generation paths that are disabled for beans in named JPMS modules (see each module's `README.md`).
+There are also three test-only, never-published modules: `afterburner-tests` and `blackbird-tests` have no `module-info.java`, so their test POJOs live in the unnamed module, as in most applications (see each module's `README.md`). For Afterburner this covers the bytecode-generation paths it disables for beans in named JPMS modules; Blackbird's in-tree tests run inside Blackbird's own named module, and `blackbird-tests` also holds the tests that need the packaged jar or other JDKs; `blackbird-jpms-tests` is a foreign named module that requires blackbird and runs on the module path.
+
+**Blackbird builds only on JDK 25+:** `blackbird`, `blackbird-tests` and `blackbird-jpms-tests` are in the root pom's `blackbird-jdk25` profile (activated on JDK 25+). On an older JDK the full build silently leaves them out, and `-pl blackbird` fails with "Could not find the selected project in the reactor"; use a JDK 25 (`JAVA_HOME=... ./mvnw ...`) for Blackbird work.
 
 Maven coordinates: groupId `tools.jackson.module`, parent `tools.jackson:jackson-base`; depends on `tools.jackson.core:jackson-databind`.
 
@@ -27,7 +29,10 @@ Maven coordinates: groupId `tools.jackson.module`, parent `tools.jackson:jackson
 ./mvnw -B -ff -ntp test
 
 # Run tests for a single module
-./mvnw -B -ff -ntp test -pl blackbird
+./mvnw -B -ff -ntp test -pl mrbean
+
+# Blackbird modules need JDK 25+ (not in the reactor on older JDKs)
+JAVA_HOME=/path/to/jdk25 ./mvnw -B -ff -ntp test -pl blackbird
 
 # Run a single test class
 ./mvnw -B -ff -ntp test -pl afterburner -Dtest=TestSimpleSerialize
@@ -36,20 +41,20 @@ Maven coordinates: groupId `tools.jackson.module`, parent `tools.jackson:jackson
 ./mvnw -B -ff -ntp test -pl afterburner -Dtest=BasicDeserializeTest#testIntMethod
 ```
 
-Java 17 is the minimum (`javac.src.version` 17); CI tests against 17, 21, 24, 25. osgi and afterburner-tests add `--add-opens java.base/java.lang=ALL-UNNAMED` to their test `argLine`.
+Java 17 is the minimum (`javac.src.version` 17); CI (`main.yml`) tests against 17, 21, 24, 25; Blackbird builds only in the 25 job, which also runs its runtime tests on 17 and 21 through `-Dblackbird.test.oldJdks`. The databind-push rebuild (`dep_build_v3.yml`) builds all other modules on 17 and 21 and only the Blackbird modules on 25, with the same old-JDK tests; keep the old-JDK wiring of the two workflows in sync. osgi and afterburner-tests add `--add-opens java.base/java.lang=ALL-UNNAMED` to their test `argLine`.
 
 ## Architecture
 
 Every module follows the same pattern:
 - A `*Module` class (e.g., `AfterburnerModule`, `BlackbirdModule`) extends Jackson's `tools.jackson.databind.JacksonModule`, registered on a mapper builder (e.g., `JsonMapper.builder().addModule(...)`)
 - Package: `tools.jackson.module.<name>` (hyphens dropped or turned into sub-packages: `androidrecord`, `noctordeser`, `spisubtypes`, `jakarta.xmlbind`)
 - `PackageVersion.java` is generated from `PackageVersion.java.in` by the replacer Maven plugin — do not edit manually
-- JPMS module descriptors are real sources: `<module>/src/main/java/module-info.java` (and `src/test/java/module-info.java` for tests). Moditect is no longer used; stray `src/moditect/` dirs in blackbird and android-record are leftovers
+- JPMS module descriptors are real sources: `<module>/src/main/java/module-info.java` (and `src/test/java/module-info.java` for tests). Moditect is no longer used; the stray `src/moditect/` dir in android-record is a leftover
 - SPI registration: `src/main/resources/META-INF/services/tools.jackson.databind.JacksonModule` (all modules except guice, guice7, osgi)
 
 ### Key module categories
 
-- **Performance (bytecode generation):** afterburner (Byte Buddy-based), blackbird (LambdaMetafactory-based, modern replacement) — both disable themselves automatically in GraalVM native images via `NativeImageUtil.isInNativeImage()` check in `setupModule`
+- **Performance (bytecode generation):** afterburner (Byte Buddy-based), blackbird (generated per-bean codecs through the JDK ClassFile API; a multi-release jar that builds on JDK 25+ and is active only on 25+; on Java 17-24 module discovery skips it and explicit `addModule` throws `IllegalStateException`, see `blackbird/README.md`) — both disable themselves automatically in GraalVM native images via `NativeImageUtil.isInNativeImage()` check in `setupModule`
 - **DI integration:** guice (javax.inject), guice7 (jakarta.inject) — note: guice's `ObjectMapperModule` implements Guice's `com.google.inject.Module`, not Jackson's `JacksonModule`
 - **Type materialization:** mrbean (generates implementations for interfaces/abstract classes, Byte Buddy-based)
 - **Annotation support:** jaxb (javax.xml.bind), jakarta-xmlbind (jakarta.xml.bind)

blackbird-jpms-tests/pom.xml

@@ -0,0 +1,177 @@
+<?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>
+  </properties>
+
+  <build>
+    <plugins>
+      <!-- This module is test-only and must never produce a publishable artifact.
+           Packaging stays `jar` so the compile + test lifecycle runs normally,
+           but every artifact-producing / artifact-publishing plugin inherited
+           from the parent chain is unbound here.
+
+           Verified via `mvn help:effective-pom -pl blackbird-jpms-tests`: every
+           execution listed below appears in the merged model at phase=none or
+           with skip=true. If you rename an execution here, re-verify with that
+           command — a typo turns into silent dead config and stale artifacts
+           in target/ rather than a build error. See afterburner-tests/pom.xml
+           for the same pattern with more detailed comments. -->
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jar-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>default-jar</id>
+            <phase>none</phase>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-install-plugin</artifactId>
+        <configuration>
+          <skip>true</skip>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-deploy-plugin</artifactId>
+        <configuration>
+          <skip>true</skip>
+        </configuration>
+      </plugin>
+      <!-- See afterburner-tests/pom.xml for why this is required in addition
+           to skipping maven-deploy-plugin. -->
+      <plugin>
+        <groupId>org.sonatype.central</groupId>
+        <artifactId>central-publishing-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>injected-central-publishing</id>
+            <phase>none</phase>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.felix</groupId>
+        <artifactId>maven-bundle-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>bundle-manifest</id>
+            <phase>none</phase>
+          </execution>
+          <execution>
+            <id>default-install</id>
+            <phase>none</phase>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.cyclonedx</groupId>
+        <artifactId>cyclonedx-maven-plugin</artifactId>
+        <configuration>
+          <skip>true</skip>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.gradlex</groupId>
+        <artifactId>gradle-module-metadata-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>default</id>
+            <phase>none</phase>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.jacoco</groupId>
+        <artifactId>jacoco-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>report</id>
+            <phase>none</phase>
+          </execution>
+        </executions>
+      </plugin>
+      <!-- The `release` profile (inherited from oss-parent, activated by the
+           `-Prelease` argument that maven-release-plugin passes to its
+           `clean verify` preparation build) binds maven-source-plugin,
+           maven-javadoc-plugin and maven-gpg-plugin. All three assume a main
+           artifact exists, but `default-jar` is unbound above, so GPG signing
+           fails with "project artifact has not been assigned a file" and the
+           whole `release:prepare` aborts. These plugins only run under
+           `-Prelease`, so skipping them here has no effect on normal builds.
+           See afterburner-tests/pom.xml for the same pattern. -->
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-source-plugin</artifactId>
+        <configuration>
+          <skipSource>true</skipSource>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <configuration>
+          <skip>true</skip>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-gpg-plugin</artifactId>
+        <configuration>
+          <skip>true</skip>
+        </configuration>
+      </plugin>
+      <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>
+            <!-- Strict mode for every test class, whatever loads first: a
+                 codec-generation failure fails the test instead of demoting
+                 to the stock path (see CodegenFallbacks). -->
+            <tools.jackson.module.blackbird.failOnCodegenError>true</tools.jackson.module.blackbird.failOnCodegenError>
+          </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,15 @@
+package blackbird.jpms.test.beans;
+
+// Deliberately package-private, in a foreign named module: the codec
+// defines in blackbird's own module context and reaches the members only
+// through handles databind's fixAccess made accessible (see
+// JpmsPackagePrivateTest).
+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;
+}