feat: Add API tracker to compare local and upstream JSON APIs #8

simbo1905 · 2025-07-26T06:49:05Z

Summary

Implements API tracker module to compare our backported JSON API with upstream OpenJDK
Adds daily GitHub Action to automatically track API differences
Closes Add daily API tracking between local and upstream JSON APIs #7

Implementation Details

API Tracker Module

Class Discovery: Uses reflection to find all classes in and internal packages
Upstream Fetching: Downloads source files from OpenJDK GitHub repository
API Extraction:
- Local: Uses reflection to extract public API details
- Upstream: Uses compiler parsing (JavacTask) to analyze source code
Comparison: Detailed comparison of methods, fields, constructors, modifiers, and inheritance

GitHub Action

Runs daily at 2 AM UTC via cron schedule
Can be manually triggered for testing
Creates GitHub issue if API differences are detected

Testing

Comprehensive unit tests for all components
Integration test verifying full comparison workflow
Learning test demonstrating compiler API usage

Test Results

All tests passing (12 tests total):

Class discovery
API extraction (local and upstream)
Comparison logic
Full integration test

Usage

Manual testing:

mvn exec:java -pl json-java21-api-tracker -Dexec.mainClass="io.github.simbo1905.tracker.ApiTrackerRunner"

The tracker produces a JSON report showing:

Total classes analyzed
Matching vs different APIs
Detailed differences for each class
Execution time

This will help us stay synchronized with upstream API changes and identify when our backport needs updates.

- Implement API tracker module with reflection for local classes - Add compiler parsing for upstream source analysis - Create comparison logic to identify API differences - Add GitHub Action for daily API tracking (cron: 2 AM UTC) - Include command-line runner for manual testing The tracker discovers local classes, fetches upstream sources from GitHub, extracts public APIs using both reflection and compiler parsing, then generates a detailed comparison report showing any differences. Closes #7

simbo1905 · 2025-07-26T06:50:28Z

.github/workflows/daily-api-tracker.yml

+    - name: Set up JDK 21
+      uses: actions/setup-java@v4
+      with:
+        java-version: '21'


we must be using latest JDK to run tooling this should be Java 24

simbo1905 · 2025-07-26T06:51:56Z

.github/workflows/daily-api-tracker.yml

+          -pl json-java21-api-tracker \
+          -Dexec.mainClass="io.github.simbo1905.tracker.ApiTrackerRunner" \
+          -Dexec.args="INFO" \
+          -Djava.util.logging.ConsoleHandler.level=INFO


please ensure that there is good INFO logging in the current code. especially to see timeouts and retries and 404 we expect the initial fetching to be the most runreliable part

simbo1905 · 2025-07-26T06:54:45Z

json-java21-api-tracker/src/main/java/io/github/simbo1905/tracker/ApiTracker.java

+        final var classes = new TreeSet<Class<?>>((a, b) -> a.getName().compareTo(b.getName()));
+
+        // Known public API classes
+        final var publicApiClasses = List.of(


this is a really bad idea as fragile. if more is added to the public API at a later date we need to remember to add to this list. so this is a dumb idea. these classes will be on the class path and reflection on the packages should find them all. so we only need to know the two package names that are likely to be stable and not get additions.

simbo1905 · 2025-07-26T06:54:56Z

json-java21-api-tracker/src/main/java/io/github/simbo1905/tracker/ApiTracker.java

+
+        // Known internal implementation classes
+        final var internalClasses = List.of(
+            "jdk.sandbox.internal.util.json.JsonParser",


simbo1905 · 2025-07-26T06:55:30Z

json-java21-api-tracker/src/main/java/io/github/simbo1905/tracker/ApiTracker.java

+                }
+            });
+
+        LOGGER.fine(() -> "Discovered " + classes.size() + " classes");


we need to know what the tool is doing this should be iNFO level logging.

simbo1905 · 2025-07-26T07:10:04Z

json-java21-api-tracker/src/main/java/io/github/simbo1905/tracker/ApiTrackerMain.java

+    }
+
+    public static void main(String[] args) {
+        LOGGER.info("Starting API Tracker v0.1-SNAPSHOT");


there should be no hardcoding of a version that will change.

simbo1905 · 2025-07-26T07:10:50Z

json-java21-api-tracker/src/main/java/io/github/simbo1905/tracker/ApiTrackerMain.java

+     * Validates that the JSON backport is working correctly.
+     * Tests various JSON structures to ensure compatibility.
+     */
+    private static boolean validateJsonBackport() {


this should not be here as we have unit tests.

simbo1905 · 2025-07-26T07:11:16Z

json-java21-api-tracker/src/main/java/io/github/simbo1905/tracker/ApiTrackerMain.java

+    /**
+     * Tests edge cases for JSON parsing.
+     */
+    private static void testEdgeCases() throws JsonParseException {


this should not be here as we have unit tests.

json-java21-api-tracker/src/main/java/io/github/simbo1905/tracker/ApiTrackerRunner.java

simbo1905 · 2025-07-26T07:12:41Z

json-java21-api-tracker/src/test/java/io/github/simbo1905/tracker/CompilerApiLearningTest.java

+import java.util.logging.Logger;
+import java.util.logging.Level;
+
+public class CompilerApiLearningTest {


delete this scaffolding test.

- Remove duplicate ApiTrackerMain class (keep only ApiTrackerRunner) - Replace hardcoded class list with dynamic classpath scanning - Change logging from FINE to INFO for key operations - Remove hardcoded version references The API tracker now dynamically discovers classes in the JSON API packages by scanning both directories and JAR files on the classpath. This makes it more robust and eliminates the need to manually update class lists.

- Update both GitHub workflows to use Java 24 instead of matrix build - Add comprehensive INFO logging for HTTP operations and class discovery - Remove scaffolding test and fix compilation warnings - Maintain Java 21 compatibility for main library while using Java 24 for tooling 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

- Remove internal package scanning (jdk.sandbox.internal.util.json) - Track only public API classes (jdk.sandbox.java.util.json) - Eliminate false positive 404 errors for removed internal classes like StableValue - Reduce tracked classes from 19 to 10 (public API only) - Improve performance and focus on meaningful API drift detection - Update tests to verify no internal classes are tracked Results: 0 missing upstream, 10 public API classes, faster execution 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

* refactor: Convert to multi-module Maven project * build: Enforce stricter compiler settings and fix warnings * feat: Add API tracker to compare local and upstream JSON APIs - Implement API tracker module with reflection for local classes - Add compiler parsing for upstream source analysis - Create comparison logic to identify API differences - Add GitHub Action for daily API tracking (cron: 2 AM UTC) - Include command-line runner for manual testing The tracker discovers local classes, fetches upstream sources from GitHub, extracts public APIs using both reflection and compiler parsing, then generates a detailed comparison report showing any differences. Closes #7 * fix: Address PR review comments - Remove duplicate ApiTrackerMain class (keep only ApiTrackerRunner) - Replace hardcoded class list with dynamic classpath scanning - Change logging from FINE to INFO for key operations - Remove hardcoded version references The API tracker now dynamically discovers classes in the JSON API packages by scanning both directories and JAR files on the classpath. This makes it more robust and eliminates the need to manually update class lists. * fix: Address PR review comments - Update both GitHub workflows to use Java 24 instead of matrix build - Add comprehensive INFO logging for HTTP operations and class discovery - Remove scaffolding test and fix compilation warnings - Maintain Java 21 compatibility for main library while using Java 24 for tooling 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix: Focus API tracker on public API only, eliminate false positives - Remove internal package scanning (jdk.sandbox.internal.util.json) - Track only public API classes (jdk.sandbox.java.util.json) - Eliminate false positive 404 errors for removed internal classes like StableValue - Reduce tracked classes from 19 to 10 (public API only) - Improve performance and focus on meaningful API drift detection - Update tests to verify no internal classes are tracked Results: 0 missing upstream, 10 public API classes, faster execution 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: Claude <[email protected]>

simbo1905 added 3 commits July 25, 2025 22:36

refactor: Convert to multi-module Maven project

218e2da

build: Enforce stricter compiler settings and fix warnings

96729c2

simbo1905 commented Jul 26, 2025

View reviewed changes

simbo1905 and others added 3 commits July 26, 2025 08:24

simbo1905 merged commit 0cb586c into main Jul 27, 2025
1 check passed

simbo1905 deleted the jdk-sandbox-api-tracker branch July 27, 2025 16:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add API tracker to compare local and upstream JSON APIs #8

feat: Add API tracker to compare local and upstream JSON APIs #8

Uh oh!

simbo1905 commented Jul 26, 2025

Uh oh!

simbo1905 Jul 26, 2025

Uh oh!

simbo1905 Jul 26, 2025

Uh oh!

simbo1905 Jul 26, 2025

Uh oh!

simbo1905 Jul 26, 2025

Uh oh!

simbo1905 Jul 26, 2025

Uh oh!

simbo1905 Jul 26, 2025

Uh oh!

simbo1905 Jul 26, 2025

Uh oh!

simbo1905 Jul 26, 2025

Uh oh!

Uh oh!

simbo1905 Jul 26, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: Add API tracker to compare local and upstream JSON APIs #8

feat: Add API tracker to compare local and upstream JSON APIs #8

Uh oh!

Conversation

simbo1905 commented Jul 26, 2025

Summary

Implementation Details

API Tracker Module

GitHub Action

Testing

Test Results

Usage

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants