Issue #144 Sync to last java.util.json sandbox commit c1a4f80 (2026-02-05)

simbo1905 · simbo1905 · commit 698c9395cea5 · 2026-05-19T15:32:15.000+01:00
This is the final sync of the java.util.json API before upstream moved to jdk.incubator.json. Changes from upstream since our last sync: - Added JsonValue.toInt() and JsonNumber.toInt() methods - Improved Javadoc for all conversion methods with @implSpec sections - Reordered valueOrNull() to end of JsonValue interface - Minor wording improvements in error messages Local changes preserved: - JsonNumber.of(double) bug fix (delegate to of(String) for correct offsets) - Utils.powExact() polyfill (Math.powExact not available in Java 21) - StableValue.java polyfill - JsonAssertionException.java All 27 tests pass. Upstream source: openjdk/jdk-sandbox@c1a4f80 Branch: json (last commit before preview->incubator move)
diff --git a/README.md b/README.md
@@ -285,22 +285,27 @@ The test data is bundled as ZIP files and extracted automatically at runtime:
 
 ## Current Status
 
-This code (as of 2026-01-25) is derived from the OpenJDK jdk-sandbox repository "json" branch. Key API changes from the previous version include:
-- `JsonString.value()` → `JsonString.string()`
-- `JsonNumber.toNumber()` → `JsonNumber.toLong()` / `JsonNumber.toDouble()`
-- `JsonBoolean.value()` → `JsonBoolean.bool()`
-- `JsonArray.values()` → `JsonArray.elements()`
-- `Json.fromUntyped()` and `Json.toUntyped()` have been removed
-- New accessor methods on `JsonValue`: `get(String)`, `element(int)`, `getOrAbsent(String)`, `valueOrNull()`
-- Internal implementation changed from `StableValue` to `LazyConstant`
+**Final `java.util.json` sandbox-era release** (2026-05-19).
+
+This code is derived from the OpenJDK jdk-sandbox repository "json" branch at commit `c1a4f80` (2026-02-05), which was the last commit before the API was moved to `jdk.incubator.json`.
+
+### API Summary
+- `JsonValue` conversion methods: `asBoolean()`, `toInt()`, `toLong()`, `toDouble()`, `asString()`
+- `JsonValue` navigation methods: `get(String)`, `get(int)`, `getOrAbsent(String)`, `valueOrNull()`
+- `JsonArray`: `elements()`, `of(List)`
+- `JsonObject`: `members()`, `of(Map)`
+- `Json`: `parse(String)`, `parse(char[])`, `toDisplayString(JsonValue, int)`
+
+### Upstream Migration Notice
+The upstream `java.util.json` API has been promoted to `jdk.incubator.json` (commit `b956ae0`, 2026-02-05). The incubator version introduces significant API changes including method renames (`bool()`→`asBoolean()`, `string()`→`asString()`, etc.) and new methods (`asInt()`). A separate branch tracks the incubator upgrade — see issue #145.
 
 The original proposal and design rationale can be found in the included PDF: [Towards a JSON API for the JDK.pdf](Towards%20a%20JSON%20API%20for%20the%20JDK.pdf)
 
 The JSON compatibitlity tests in this repo suggest 99% conformance with a leading test suite when in "strict" mode. The two conformance expecatations that fail assume that duplicated keys in a JSON document are okay. The upstream code at this time appear to take a strict stance that it should not siliently ignore duplicate keys in a json object. 
 
 ### CI: Upstream API Tracking
 
-A daily workflow runs an API comparison against the OpenJDK sandbox and prints a JSON report. Implication: differences do not currently fail the build or auto‑open issues; check the workflow logs (or adjust the workflow to fail on diffs) if you need notifications.
+**Note**: The daily API tracker workflow currently targets the old `java.util.json` paths which no longer exist upstream. It needs to be updated to track `jdk.incubator.json` — see issue #145.
 
 ## Modifications
 
diff --git a/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonArrayImpl.java b/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonArrayImpl.java
@@ -30,7 +30,6 @@
 
 import jdk.sandbox.java.util.json.JsonArray;
 import jdk.sandbox.java.util.json.JsonValue;
-
 /**
  * JsonArray implementation class
  */
diff --git a/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonBooleanImpl.java b/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonBooleanImpl.java
@@ -26,7 +26,6 @@
 package jdk.sandbox.internal.util.json;
 
 import jdk.sandbox.java.util.json.JsonBoolean;
-
 /**
  * JsonBoolean implementation class
  */
diff --git a/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonNullImpl.java b/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonNullImpl.java
@@ -26,7 +26,6 @@
 package jdk.sandbox.internal.util.json;
 
 import jdk.sandbox.java.util.json.JsonNull;
-
 /**
  * JsonNull implementation class
  */
diff --git a/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonNumberImpl.java b/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonNumberImpl.java
@@ -29,8 +29,6 @@
 
 import java.util.Optional;
 import jdk.sandbox.java.util.json.JsonNumber;
-
-
 /**
  * JsonNumber implementation class
  */
@@ -43,6 +41,7 @@ public final class JsonNumberImpl implements JsonNumber, JsonValueImpl {
     private final int exponentOffset;
 
     private final LazyConstant<String> numString = LazyConstant.of(this::initNumString);
+    private final LazyConstant<Optional<Integer>> numInteger = LazyConstant.of(this::initNumInteger);
     private final LazyConstant<Optional<Long>> numLong = LazyConstant.of(this::initNumLong);
     private final LazyConstant<Optional<Double>> numDouble = LazyConstant.of(this::initNumDouble);
 
@@ -54,6 +53,12 @@ public JsonNumberImpl(char[] doc, int start, int end, int dec, int exp) {
         exponentOffset = exp;
     }
 
+    @Override
+    public int toInt() {
+        return numInteger.get().orElseThrow(() ->
+            Utils.composeError(this, this + " cannot be represented as an int."));
+    }
+
     @Override
     public long toLong() {
         return numLong.get().orElseThrow(() ->
@@ -97,6 +102,14 @@ private String initNumString() {
         return new String(doc, startOffset, endOffset - startOffset);
     }
 
+    private Optional<Integer> initNumInteger() {
+        try {
+            return numLong.get().map(Math::toIntExact);
+        } catch(ArithmeticException e) {
+            return Optional.empty();
+        }
+    }
+
     // 4 cases: Fully integral, has decimal, has exponent, has decimal and exponent
     private Optional<Long> initNumLong() {
         try {
@@ -147,7 +160,7 @@ private Optional<Long> initNumLong() {
                             startOffset, decimalOffset - startOffset), 10));
                 }
             }
-        } catch (NumberFormatException | ArithmeticException ignored) {}
+        } catch(NumberFormatException | ArithmeticException e) {}
         return Optional.empty();
     }
 
diff --git a/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonObjectImpl.java b/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonObjectImpl.java
@@ -30,7 +30,6 @@
 
 import jdk.sandbox.java.util.json.JsonObject;
 import jdk.sandbox.java.util.json.JsonValue;
-
 /**
  * JsonObject implementation class
  */
diff --git a/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonStringImpl.java b/json-java21/src/main/java/jdk/sandbox/internal/util/json/JsonStringImpl.java
@@ -26,7 +26,6 @@
 package jdk.sandbox.internal.util.json;
 
 import jdk.sandbox.java.util.json.JsonString;
-
 /**
  * JsonString implementation class
  */
diff --git a/json-java21/src/main/java/jdk/sandbox/internal/util/json/Utils.java b/json-java21/src/main/java/jdk/sandbox/internal/util/json/Utils.java
@@ -95,12 +95,12 @@ public static JsonAssertionException composeError(JsonValue jv, String message)
     // Use to compose an exception when casting to an incorrect type
     public static JsonAssertionException composeTypeError(JsonValue jv, String expected) {
         var actual = switch (jv) {
-            case JsonObject ignored -> "JsonObject";
-            case JsonArray ignored -> "JsonArray";
-            case JsonBoolean ignored -> "JsonBoolean";
-            case JsonNull ignored -> "JsonNull";
-            case JsonNumber ignored -> "JsonNumber";
-            case JsonString ignored -> "JsonString";
+            case JsonObject v -> "JsonObject";
+            case JsonArray v -> "JsonArray";
+            case JsonBoolean v -> "JsonBoolean";
+            case JsonNull v -> "JsonNull";
+            case JsonNumber v -> "JsonNumber";
+            case JsonString v -> "JsonString";
         };
         return composeError(jv, "%s is not a %s.".formatted(actual, expected));
     }
diff --git a/json-java21/src/main/java/jdk/sandbox/java/util/json/Json.java b/json-java21/src/main/java/jdk/sandbox/java/util/json/Json.java
@@ -32,7 +32,6 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.stream.Collectors;
-
 import jdk.sandbox.internal.util.json.JsonParser;
 import jdk.sandbox.internal.util.json.Utils;
 
diff --git a/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonArray.java b/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonArray.java
@@ -31,7 +31,6 @@
 import java.util.stream.Collectors;
 
 import jdk.sandbox.internal.util.json.JsonArrayImpl;
-
 /**
  * The interface that represents JSON array.
  * <p>
@@ -45,12 +44,22 @@
 public non-sealed interface JsonArray extends JsonValue {
 
     /**
-     * {@return an unmodifiable list of the {@code JsonValue} elements in
-     * this {@code JsonArray}}
+     * {@inheritDoc}
      */
     @Override
     List<JsonValue> elements();
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param index {@inheritDoc}
+     * @throws JsonAssertionException if the given index is out of bounds
+     */
+    default JsonValue element(int index) {
+        // Overridden to specify
+        return JsonValue.super.element(index);
+    }
+
     /**
      * {@return the {@code JsonArray} created from the given
      * list of {@code JsonValue}s}
diff --git a/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonBoolean.java b/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonBoolean.java
@@ -24,7 +24,6 @@
  */
 
 package jdk.sandbox.java.util.json;
-
 import jdk.sandbox.internal.util.json.JsonBooleanImpl;
 
 /**
@@ -41,8 +40,7 @@
 public non-sealed interface JsonBoolean extends JsonValue {
 
     /**
-     * {@return the {@code boolean} value represented by this
-     * {@code JsonBoolean}}
+     * {@inheritDoc}
      */
     @Override
     boolean bool();
diff --git a/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonNull.java b/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonNull.java
@@ -24,7 +24,6 @@
  */
 
 package jdk.sandbox.java.util.json;
-
 import jdk.sandbox.internal.util.json.JsonNullImpl;
 
 /**
diff --git a/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonNumber.java b/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonNumber.java
@@ -24,7 +24,6 @@
  */
 
 package jdk.sandbox.java.util.json;
-
 import jdk.sandbox.internal.util.json.JsonNumberImpl;
 
 /**
@@ -38,10 +37,10 @@
  * syntax</a>.
  * Alternatively, {@link #of(double)}, {@link #of(long)}, or {@link #of(String)}
  * can be used to obtain a {@code JsonNumber}.
- * The value of the {@code JsonNumber} can be retrieved as a {@code long}
- * with {@link #toLong()} or as a {@code double} with {@link #toDouble()}.
- * {@link #toString()} can be used to return the string representation of
- * the JSON number.
+ * The value of the {@code JsonNumber} can be retrieved as an {@code int} with
+ * {@link #toInt()}, as a {@code long} with {@link #toLong()}, or as a
+ * {@code double} with {@link #toDouble()}. {@link #toString()} can be used to
+ * return the string representation of the JSON number.
  *
  * @apiNote
  * To avoid precision loss when converting JSON numbers to Java types, or when
@@ -63,14 +62,16 @@
 public non-sealed interface JsonNumber extends JsonValue {
 
     /**
-     * {@return a {@code long} if it can be translated from the string
-     * representation of this {@code JsonNumber}} That is, it can be expressed
-     * as a whole number and is within the range of {@link Long#MIN_VALUE} and
-     * {@link Long#MAX_VALUE}. This occurs, even if the string contains an
-     * exponent or a fractional part consisting of only zero digits. For example,
-     * both the JSON number "123.0" and "1.23e2" produce a {@code long} value of
-     * "123". A {@code JsonAssertionException} is thrown when the numeric value
-     * cannot be represented as a {@code long}; for example, the value "5.5".
+     * {@inheritDoc}
+     *
+     * @throws JsonAssertionException if this {@code JsonNumber} cannot
+     *      be represented as an {@code int}.
+     */
+    @Override
+    int toInt();
+
+    /**
+     * {@inheritDoc}
      *
      * @throws JsonAssertionException if this {@code JsonNumber} cannot
      *      be represented as a {@code long}.
@@ -79,14 +80,9 @@ public non-sealed interface JsonNumber extends JsonValue {
     long toLong();
 
     /**
-     * {@return a finite {@code double} if it can be translated from the string
-     * representation of this {@code JsonNumber}} If the string representation
-     * is outside the range of {@link Double#MAX_VALUE -Double.MAX_VALUE} and
-     * {@link Double#MAX_VALUE}, a {@code JsonAssertionException} is thrown.
+     * {@inheritDoc}
      *
-     * @apiNote Callers of this method should be aware of the potential loss in
-     * precision when the string representation of the JSON number is translated
-     * to a {@code double}.
+     * @apiNote {@inheritDoc}
      * @implNote The JDK reference implementation uses {@link
      * Double#parseDouble(String)} to perform the conversion from string to
      * finite double.
@@ -113,11 +109,22 @@ static JsonNumber of(double num) {
         if (!Double.isFinite(num)) {
             throw new IllegalArgumentException("Not a valid JSON number");
         }
-        // LOCAL FIX for upstream bug: The original code hardcoded decimalOffset=0
-        // and exponentOffset=0, which breaks toLong() for integral doubles like 123.0.
-        // Delegating to of(String) ensures correct offset computation via Json.parse().
-        // See: https://github.com/simbo1905/java.util.json.Java21/issues/118
-        return JsonNumber.of(Double.toString(num));
+        // Delegate to of(String) which correctly computes offsets via Json.parse()
+        // Upstream bug: hardcoded decimalOffset=0 and exponentOffset=0
+        return of(Double.toString(num));
+    }
+
+    /**
+     * Creates a JSON number from the given {@code int} value.
+     * The string representation of the JSON number created is produced by applying
+     * {@link Integer#toString(int)} on {@code num}.
+     *
+     * @param num the given {@code int} value.
+     * @return a JSON number created from the {@code int} value
+     */
+    static JsonNumber of(int num) {
+        var str = Integer.toString(num);
+        return new JsonNumberImpl(str.toCharArray(), 0, str.length(), -1, -1);
     }
 
     /**
@@ -155,7 +162,7 @@ static JsonNumber of(String num) {
             if (Json.parse(num) instanceof JsonNumber jn) {
                 return jn;
             }
-        } catch (JsonParseException ignored) {}
+        } catch(JsonParseException e) {}
         throw new IllegalArgumentException("Not a JSON number");
     }
 
diff --git a/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonObject.java b/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonObject.java
@@ -28,8 +28,8 @@
 import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Optional;
 import java.util.stream.Collectors;
-
 import jdk.sandbox.internal.util.json.JsonObjectImpl;
 
 /**
@@ -48,12 +48,36 @@
 public non-sealed interface JsonObject extends JsonValue {
 
     /**
-     * {@return an unmodifiable map of the {@code String} to {@code JsonValue}
-     * members in this {@code JsonObject}}
+     * {@inheritDoc}
      */
     @Override
     Map<String, JsonValue> members();
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param name {@inheritDoc}
+     * @throws JsonAssertionException if there is no association with the member name
+     * @throws NullPointerException {@inheritDoc}
+     */
+    @Override
+    default JsonValue get(String name) {
+        // Overridden to specify
+        return JsonValue.super.get(name);
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @param name {@inheritDoc}
+     * @throws NullPointerException {@inheritDoc}
+     */
+    @Override
+    default Optional<JsonValue> getOrAbsent(String name) {
+        // Overridden to specify
+        return JsonValue.super.getOrAbsent(name);
+    }
+
     /**
      * {@return the {@code JsonObject} created from the given
      * map of {@code String} to {@code JsonValue}s}
@@ -70,7 +94,7 @@ static JsonObject of(Map<String, ? extends JsonValue> map) {
                 .stream()
                 .collect(Collectors.toMap(
                         e -> Objects.requireNonNull(e.getKey()), Map.Entry::getValue, // Implicit NPE on val
-                        (ignored, v) -> v, LinkedHashMap::new)));
+                        (k, v) -> v, LinkedHashMap::new)));
     }
 
     /**
diff --git a/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonParseException.java b/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonParseException.java
@@ -24,8 +24,6 @@
  */
 
 package jdk.sandbox.java.util.json;
-
-
 import java.io.Serial;
 
 /**
diff --git a/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonString.java b/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonString.java
diff --git a/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonValue.java b/json-java21/src/main/java/jdk/sandbox/java/util/json/JsonValue.java
diff --git a/json-java21/src/main/java/jdk/sandbox/java/util/json/package-info.java b/json-java21/src/main/java/jdk/sandbox/java/util/json/package-info.java
