# JDK 28 procedural implementation in SLeeLa **Premise.** `/lib/java` covers the Java procedural language in SLeeLa. Each Java type under `lib/java/java/` gets the fields, constructors, methods, return values and imports of the JDK 28 API (Java SE 28, Java 25+ for reference), written in SLeeLa and running on the SLeeLa VM. It does not call into a JVM. This first phase builds the **body of the work**. Java keywords and semantics the compiler cannot express yet were worked around and are listed in [Deferred keywords and semantics](#deferred-keywords-and-semantics). The next phase addresses them. ## Measured coverage [`COVERAGE.md`](COVERAGE.md) is regenerated by `tools/jdk_api_coverage.py`. It measures against the reflected public API of a real JDK (`api/jdk-api.jsonl`, written by `tools/ApiDump.java` on OpenJDK 25.0.2): **4,801 types and 51,554 members** (constructors, methods, fields and enum constants). Two numbers are reported: - **Covered.** Members that exist in SLeeLa with their Java meaning. This includes the API-declared part below plus hand-implemented behavior. Currently **44.5%**. - **Behavior.** Only hand-written method bodies. Currently **8.9%**. ### Exact Java signatures (`tools/jdk_api_signatures.py`) Every public method of every JDK type that SLeeLa does not implement yet is written with its **exact Java signature**. That is 33,978 methods: 9,732 abstract and 24,246 awaiting logic. The modifiers, type parameters and generic types come from `api/jdk-signatures.jsonl`, which `tools/ApiSignatures.java` writes from reflection on a real JDK, with parameter names read from the JDK source declarations. For example: ``` class ArrayList extends AbstractList { public T[] toArray(T[] a) { throw new UnsupportedOperationException("not yet implemented in SLeeLa: java.util.ArrayList.toArray(T[])"); } public static java.util.List asList(T... a) { ... } public abstract E get(int index) { throw new AbstractMethodError("java.util.AbstractList.get(int)"); } ``` Generic classes carry their Java type parameters (`class HashMap`). The SLeeLa front end reads this Java surface (SLEELA.syntax section 38). Static members are reached through the class name, as in Java: `DayOfWeek.MONDAY`, `DayOfWeek.valueOf("FRIDAY")`, `Integer.MAX_VALUE`. Bodies that are not yet SLeeLa logic throw. An abstract method throws `AbstractMethodError`, which is what the JVM does; abstract methods count as covered. Any other method throws `UnsupportedOperationException` naming the Java signature; those stubs are not counted as coverage. Two adaptations are named in the source: - a Java *protected instance* member carries `@JavaProtected`, because SLeeLa reserves `protected` for static members; - a parameter whose Java name is a SLeeLa reserved word gets a trailing `_`. Not written: - methods whose name the type, or a SLeeLa ancestor with an implementation block, already implements (calls resolve by name until overload resolution lands); - constructors (one per class); - `java.lang.String`. When a method gets real logic, write it in an implementation block and re-run `jdk_api_signatures.py`. ### API-declared part (`tools/jdk_api_declare.py`) These are the parts of each type whose Java meaning comes entirely from the API, with no behavior to invent. They are generated into a `BEGIN/END java declarations` block in every type: - **Constants.** Every public/protected static final primitive or String field, with its real JDK value. Reading one from another class needs cross-class static access (deferred item 1). - **Fields.** The remaining public/protected fields. - **Abstract methods.** Every abstract method of an interface, abstract class or annotation type. A direct call throws `java.lang.AbstractMethodError`, as the JVM does. - **Enums.** All 161 are complete: one static final instance per constant (`==` holds), `name`, `ordinal`, `toString`, `values`, `valueOf` (with the Java exceptions), `compareTo`, `equals`, `hashCode`. Get a handle with `new DayOfWeek(null, -1)`, then `valueOf("MONDAY")` or `values()`. Constant-specific methods such as `DayOfWeek.plus` are still behavior work. - **Records.** All 4 are complete: canonical constructor, accessors, and `equals`/`hashCode`/`toString`. - **Missing types.** The 1,235 types missing from the tree were created from the JDK 28 index envelopes, so every public type now has a file. ## Status (2026-11-10) | Area | Types | What is implemented | |---|---|---| | `java.lang.Throwable` hierarchy | 290 (every `java.*` exception and error) | The real JDK 28 superclass of each type via `extends` (resolved inheritance). Throwable state: detail message, cause, `initCause`, suppressed list, stack-trace slot, `toString`, `printStackTrace`. Each type has its documented constructor. Class-specific state is included, for example `ParseException.getErrorOffset`, `URISyntaxException`/`InvalidPathException` input/reason/index, `PatternSyntaxException` caret message, `FileSystemException` file/other/reason, `SQLException` SQLState/error code/next-exception chain, the `java.util` format-exception messages, and charset exceptions. | | `java.lang.Math`, `StrictMath` | 2 | Constants, plus abs/min/max/signum/copySign/clamp, floor/ceil/rint/round, sqrt/cbrt/hypot, exp/expm1/log/log10/log1p/pow, trig, inverse trig and hyperbolics, toRadians/toDegrees, floorDiv/floorMod/ceilDiv/ceilMod, `*Exact` (throws `ArithmeticException`), `powExact`, the `unsigned*` multiply/pow family, fma, scalb. All pure SLeeLa, with relative error around 1e-15. `StrictMath` has no algorithms of its own: each static maps to the `Math` function of the same name. | | `Integer`, `Long`, `Short`, `Byte` | 4 | MIN/MAX/SIZE/BYTES, two's-complement wrapping, parse/valueOf/decode (throwing `NumberFormatException` with the Java messages), toString in any radix, hex/octal/binary/unsigned strings, compare/compareUnsigned, divide/remainderUnsigned, bitCount, leading/trailing zeros, highest/lowestOneBit, rotate, reverse, reverseBytes, hashCode, equals, compareTo, Number views. | | `Double`, `Float` | 2 | Exact IEEE 754 bit views (`doubleToLongBits`, `longBitsToDouble`, `floatToIntBits`, `intBitsToFloat`). `toString` uses the Java layout with shortest round-trip digits, computed with double-double arithmetic. `parseDouble`/`parseFloat` round to nearest. `toHexString`, compare (with -0.0/NaN order), hashCode, min/max, Number views. Float is exact binary32 through `fround`. | | `Character`, `Boolean` | 2 | Surrogates and code points, toChars, isWhitespace/isSpaceChar/isISOControl (exact). Letter/digit/case predicates and simple case maps are table-driven from Unicode 14.0 data for the covered blocks. digit/forDigit/getNumericValue. Boolean.parseBoolean and the logical helpers. | | `java.util` collections | 14 | `ArrayList`, `LinkedList`, `ArrayDeque`, `Vector`, `Stack`, `HashMap`, `LinkedHashMap`, `HashSet`, `LinkedHashSet`, `TreeMap`, `TreeSet`, `PriorityQueue`, `Iterator`, `KeyValueHolder` (Map.Entry). Covers the List/Deque/Queue/SequencedCollection API, the Map API with navigation (floor/ceiling/higher/lower, head/tail/sub maps), set algebra (addAll/retainAll/removeAll/containsAll), and Java `hashCode`/`equals`/`toString` formulas. | | `java.util` utilities | 7 | `Arrays` (int/double/Object sort, binarySearch, fill, copyOf/copyOfRange, equals, hashCode, toString, mismatch, asList). `Collections` (sort, reverse, swap, fill, rotate, shuffle, max, min, frequency, disjoint, binarySearch, indexOfSubList, nCopies, empty and singleton factories). `Objects`. `Optional`, `OptionalInt`, `OptionalLong`, `OptionalDouble`. `Random`, the Java 48-bit LCG bit for bit. | | Concurrency, checksums, bits | 17 | `java.util.concurrent.atomic`: `AtomicInteger`, `AtomicLong`, `AtomicBoolean`, `AtomicReference`, the three atomic arrays, `LongAdder`, `DoubleAdder`. All use VM lock 31, which is reserved for atomics. `Int`/`Long`/`DoubleSummaryStatistics`, including Java's Kahan summation and `%f` output. `java.util.zip` `CRC32`, `CRC32C`, `Adler32`. `java.util.BitSet`, including the Java long-word layout for `hashCode`, `toLongArray` and `valueOf`. `java.lang.StackTraceElement`. | | `java.time` core | 11 | `LocalDate`, `LocalTime`, `LocalDateTime`, `Instant`, `Duration`, `Period`, `Year`, `YearMonth`, `MonthDay`, and the `DayOfWeek`/`Month` behavior. Uses the java.time epoch-day algorithm over 400-year cycles, month arithmetic, carrying between date and time, ISO `toString`/`parse`, Java `hashCode`s, and 128-bit `Duration` multiply/divide. `Math`/`StrictMath` gain `add`/`subtract`/`multiply`/`negateExactLong`. | | Throwables outside `java.*` | 208 | Every public `javax.*`, `jdk.*`, `com.sun.*` and `org.*` exception and error, generated from the reflected API (`jdk28_implement_throwables.py`, API-driven pass). Each gets its real superclass, its documented constructor, inherited state initialized from the `java.*` ancestors, and package imports where a superclass name is ambiguous. | That is 558 implemented types with about 1,560 constructors and methods, roughly 9,800 lines of SLeeLa. ## Conformance ### Differential tests (real JDK vs SLeeLa) [`examples/java/differential/`](../../examples/java/differential/) holds pairs of `.java` and `.sleela` that make the same calls and print the same lines. `run-differential.sh` compiles and runs the Java side on a real JDK, runs the SLeeLa side on the VM, and requires identical output. Nothing is transcribed by hand; the expected values come from Java itself. ```sh examples/java/differential/run-differential.sh ``` ### Self-checking programs [`examples/java/`](../../examples/java/README.md) holds eight conformance programs. They compare against values the Java SE API returns for the same calls (for example `new Random(42).nextInt() == -1170105035`, `Double.toString(0.1 + 0.2) == "0.30000000000000004"`, `"Hello".hashCode() == 69609650`). There is also a 1,348-value `Double.toString`/`parseDouble` round trip. Run them all: ```sh examples/java/run-conformance.sh ``` All eight pass with the source-built compiler (`impl/build/sleela`). Programs must declare `#sleela 3.0`, because real `throw` and Java UTF-16 String operations are gated at 3.0. ## Conventions used in this phase 1. **Static members are instance methods (except `Math` and `StrictMath`).** `Math.abs(x)`, `Math.PI` and `StrictMath.abs(x)` work as written; every `StrictMath` static call is mapped to the `Math` function of the same name. SLeeLa does not yet resolve `Integer.MAX_VALUE` across classes. Create an instance and call through it: `new Math().abs(x)`, `new Integer(0).parseInt("42")`, `new Integer(0).maxValue()`. `static final` constants are still declared, so the Java names are in the source. 2. **Overloads get a role or type suffix.** Calls resolve by name only: - Math: `absInt`, `absLong`, `maxLong`. - Integer: `toStringOf(int)` versus `toString()`, `toStringRadix`, `parseIntRadix`. - Collections: `addAt(int, E)`, `removeObject(Object)`, `addAllAt`. - Arrays: `sortDoubles` and `sortObjects`. - Random: `nextIntBound(bound)`. - Map: `replaceValue(k, old, new)` and `removeMapping(k, v)`. The plain name is always the most common Java form. 3. **Generics are erased to `Any`.** Collections hold `Any`. Read a value back with a checked cast: `(int) list.get(0)`, `(Box) map.get("k")`. 4. **Primitive mapping.** The VM integer is 64-bit, and `byte`, `short`, `char` and `float` do not exist. `int` results are wrapped to 32 bits wherever Java would overflow. byte/short/char are carried as `int` in range. float is carried as a `double` rounded to binary32. 5. **Value semantics.** Element and key equality is SLeeLa `==`: strings and numbers compare by value, objects by identity. Hashing matches the Java `hashCode` for numbers, booleans and Strings. Natural ordering compares numbers numerically and anything else by Java `String.compareTo` of its text. 6. **Upcasts are explicit.** Write `t.initCause((Throwable) ioe)`. Implicit subtype assignment is not implemented yet. 7. **Selecting the package.** Some simple names also exist elsewhere in `/lib`: `Character`, `Vector`, `List`, `Map`, `CertificateException`, …. A program that uses them adds `import java.java.lang;` and/or `import java.java.util;`. The `java.util` units carry `import java.java.util;` themselves. ## Deferred keywords and semantics > **Status 2026-11-13.** Items 3 to 7 (virtual dispatch, base-class field > initializers, `super(...)`, implicit subtype assignment, typed and multiple > `catch` with `finally`) are now done in the compiler (SLEELA.syntax 43.6; > regression `impl/tests/java_references/oop/`). Item 10 is done for the > bitwise operators, `L` / `f` suffixes and the `byte` / `short` / `char` / > `int32` widths (`STATUS.md` section 10); `char` literals are still open. The > workarounds in the generated classes remain until those classes are > regenerated. Item 9 is done too: `new T[n]` starts at zero / `false` > (SLEELA.syntax 44.3), and `char` literals exist since syntax 3.1 (44.2). The > current list of differences is `STATUS.md` section 6. Each of these is a compiler or VM change. Each workaround above maps to one item here. When an item lands, its workaround can be removed by editing the generators in [`tools/implementation/`](tools/implementation/) and [`tools/jdk28_implement_throwables.py`](tools/jdk28_implement_throwables.py) and re-running them. 1. **Static member access across classes.** *Done:* `Class.member` and `Class.method(...)` now work (SLEELA.syntax section 38). The hand-implemented classes still expose their static API as instance methods; they are converted class by class. 2. **Overload resolution** by parameter types, and more than one constructor per class. *Done* (SLEELA.syntax section 40); the hand-implemented classes still carry their earlier suffixed names. 3. **Virtual dispatch.** An override is not reached through a base-typed receiver or an implicit-`this` call. That is why exceptions compose their message into `detailMessage` at construction instead of overriding `getMessage()`, and why a user `equals`/`compareTo` is not consulted by the collections. 4. **Base-class field initializers do not run for subclass instances.** Every generated constructor first initializes the inherited state. 5. **`super(...)` constructor calls are not lowered.** 6. **Implicit subtype assignability** (`Throwable t = ioe;`). 7. **Typed `catch` and multiple catch clauses.** Only `catch (Any e)` exists today, and `finally` is not lowered. 8. **The String bridge.** Literals are legacy UTF-8 strings. `javaString*` values are Java UTF-16 strings. There is no UTF-16-to-legacy conversion, and `+` cannot mix the two. `java.lang.String`, `StringBuilder` and `Character.toString` of non-ASCII therefore wait for one VM operation. UTF-16 handles are also capped at 4,096 live strings and are reclaimed only by a collection, so the collections issue a periodic `gc` hint. 9. **New `int[]`/`boolean[]` elements read as `null`**, not 0/false. The implementation clears them explicitly. 10. **`byte`, `short`, `char`, `float` primitives** (*now accepted* as types, on the int / double slots), `L`/`f` literal suffixes, and the bitwise operators `& | ^ ~ << >> >>>`. Bit operations are implemented arithmetically. 11. **Lambdas and functional interfaces.** `Comparator`, `Function`, `Consumer`, … So comparator sorting, `compute`/`merge`, `forEach` and streams are not provided yet. 12. **Live collection views.** `keySet`, `values`, `entrySet` and `subList` return snapshots. 13. **Multi-file `run` resolves library units per file** and duplicates them. Use a single main file and let the loader pull in `/lib` units. 14. **Nested types** (`Map.Entry`, `Character.UnicodeBlock`, …) live in `Outer.Inner.sleela` files. The loader resolves units by simple file name, so it never loads them yet. 15. **Package-prefix imports are ambiguous** when a subpackage reuses a name. For example, `import java.java.security;` still matches both `security/Certificate` and `security/cert/Certificate`. The loader needs exact-package import matching. ## Regenerating ```sh # refresh the reflected API (needs a JDK), then the declarations and the report javac -d /tmp/apid lib/java/tools/ApiDump.java && java -cp /tmp/apid ApiDump > lib/java/api/jdk-api.jsonl python3 lib/java/tools/jdk_api_declare.py # constants, fields, abstract methods, enums, records javac -d /tmp/sigs lib/java/tools/ApiSignatures.java && java -cp /tmp/sigs ApiSignatures > lib/java/api/jdk-signatures.jsonl python3 lib/java/tools/jdk_api_signatures.py # exact Java signatures (run last) python3 lib/java/tools/jdk_api_coverage.py --markdown lib/java/COVERAGE.md python3 lib/java/tools/jdk28_implement_throwables.py # 290 Throwable types cd lib/java/tools/implementation python3 gen_integral.py # Integer Long Short Byte python3 gen_floating.py # Double Float python3 gen_character.py # Character (Unicode tables from Python unicodedata) python3 gen_collections.py # java.util collections python3 gen_util2.py # Arrays Collections Optional* Random ``` The generators are idempotent. `Math`, `StrictMath`, `Boolean` and `Objects` are maintained directly in their `.sleela` files, between the `BEGIN/END java implementation` markers. After any change, regenerate `security/sha256-manifest.json` (`python3 tools/generate-sha256-manifest.py --root . --output security/sha256-manifest.json`).