/lib/java/jdk-28: Purpose — translating Java source to SLeeLa, based on JDK 28
Container rule: Java is housed, never specified
Everything in this directory is Java container content. None of it is part of
the SLeeLa specification (SLEELA.syntax section 38.4): the language defines the
mechanisms (signature spelling, static access, library unit references), and the
container defines Math, Integer, Long and the rest.
- Implicit. A Java name is housed by the import that selects it
(
import java.jdk-28;). A bareMathwithout that import is not a Java reference. - Explicit. Each unit states its container in its own text (
javaType,javaModule,javaSource, and the "SLeeLa file for the Java type" header). Translators record a Java reference asjava.jdk-28:java.lang.Math. - Documents. Every mapping, example and conformance note here describes the Java container, not the language.
Purpose
jdk-28/ exists so that Java procedural source code can be translated into
SLeeLa that does the same thing, running on the SLeeLa VM with no JVM.
- Vocabulary. One SLeeLa file per public JDK 28 type (1:1, same folders as the online API) gives a translated program every class, constructor, method, field and constant it can name, with the exact Java signature.
- Behavior. Where a type is implemented (see
../JDK28-PROCEDURAL-IMPLEMENTATION.mdand../COVERAGE.md) the file carries real SLeeLa logic. Everywhere else the body throwsUnsupportedOperationException(orAbstractMethodErrorfor abstract methods), so a gap fails loudly and never silently returns a wrong answer. - Target. Same output for the same input. The yardstick is the differential
tests in
examples/java/differential/(real JDK vs SLeeLa, identical output) and the self-checking programs inexamples/java/. - Not a goal. Copying Java implementation source, or calling into a JVM. Each file names its JDK 28 API page as its Java Source; nothing is copied.
A translation is faithful when each Java construct below is either (a) supported natively by SLeeLa, (b) rewritten by a stated rule, or (c) rejected with a clear error. The tables list what must be addressed.
Status values: Native = SLeeLa does it as Java does. Rule = translate by
the stated rewrite. Gap = still to be addressed in the compiler/VM/library.
Statuses are taken from JDK28-PROCEDURAL-IMPLEMENTATION.md (2026-11-10) and
SLEELA.syntax sections 38–44 (rows 8, 9, 10, 14, 17, 18, 19, 23, 35 re-checked 2026-11-13);
re-check them there as items land.
1. Language differences
| # | Area | Java (JDK 28) | SLeeLa | Status | What we need to address |
|---|---|---|---|---|---|
| 1 | Source version | No per-file marker | File declares #sleela 3.0; real throw and Java UTF-16 String ops are gated at 3.0 | Rule | Translator emits #sleela 3.0 first in every file. |
| 2 | Package / file layout | package a.b; one public type per file | Library unit found by simple file name; jdk-28/ is a reference tier, a real unit of the same name wins | Rule | Map a.b.Type to jdk-28/<module>/a/b/Type.sleela; resolve simple-name clashes with import java.java.util; style imports. |
| 3 | Imports | import a.b.C;, import a.b.*;, import static | Package-prefix import; ambiguous when a subpackage reuses a name | Gap | Loader needs exact-package import matching (deferred item 15). Static imports need a rewrite to Class.member. |
| 4 | Nested types | Map.Entry, Character.UnicodeBlock | Files named Outer.Inner.sleela; loader resolves by simple name so does not load them yet | Gap | Loader support for dotted nested-type files (item 14). |
| 5 | Static members | Math.abs(x), Integer.MAX_VALUE | Class.member / Class.method(...) work (syntax §38.2). Math is real statics (Math.abs(x), Math.PI); StrictMath maps each static call to the Math function of the same name; other hand-written classes still expose statics as instance methods (new Integer(0).parseInt("42")) | Native, partly Rule | A static Math/StrictMath reference is mapped, not rewritten (full table in MATH-MAP.md): Math.sin(x) stays Math.sin(x), and StrictMath.sin(x) is Math.sin(x). Convert the remaining classes to real statics class by class; until then the translator emits the instance form for them. |
| 6 | Overloading | Resolved by parameter types | Resolved by argument count, assignability and exact-type score; ties go to source order (§40). Hand-written classes still use suffixed names (absInt, toStringRadix, nextIntBound) | Native, partly Rule | Convert suffixed names to true overloads; translator must map a Java overload to the right suffix meanwhile. Ranking differs from Java's most-specific rule in edge cases, so test them. |
| 7 | Constructors | Many per class; this(...), super(...) | Many allowed at 3.0 (§40). super("constructor") is lowered to the root of the lineage (SLEELA.syntax §42.5); jdk-28 stubs carry it (tools/jdk28_add_lineage.py) | Rule | Java super(args) argument passing is still not evaluated; translator inlines inherited initialization. |
| 8 | Inheritance and virtual dispatch | An override is called through a base-typed reference | Overrides are reached through a base-typed receiver and implicit this; super.m() (SLEELA.syntax 43.6 rules 6, 7) | Native | Library units written before it still compose exception messages at construction; convert them class by class. |
| 9 | Field initializers in base classes | Run for every subclass instance | Run along the extends chain, base first (43.6 rule 5) | Native | None. |
| 10 | Subtype assignment | Throwable t = ioe; | Implicit for superclasses and implemented interfaces (43.6 rule 1) | Native | A runtime cast to an interface still fails (lib/java/converter/README.md section 6). |
| 11 | Generics | Type parameters, bounds, wildcards, reified only by erasure | Signatures accept them (§38.1) and erase to Any; no type checking of arguments | Rule | Translator inserts checked casts on reads: (int) list.get(0). Java compile-time generic errors are not reproduced. |
| 12 | Interfaces, default and static interface methods | Yes | Interface/abstract types present as signatures; abstract calls throw AbstractMethodError | Native, partly Gap | Verify default-method inheritance through dispatch (depends on row 8). |
| 13 | Exceptions: throw | throw new X(...) | Real throw at 3.0 | Native | None beyond row 1. |
| 14 | Exceptions: catch | Typed, multi-catch, finally, try-with-resources | Typed and multi catch and finally (43.6 rule 11); return / break / continue through finally run it (44.5); try-with-resources not lowered | Native, partly Gap | try-with-resources. |
| 15 | Exception hierarchy | Real extends chain | 290 java.* Throwables and 208 others carry the real chain and documented constructors | Native | Keep getMessage() semantics (row 8). |
| 16 | Primitives | byte short char int long float double boolean, fixed width | VM integer is 64-bit; byte/short/char/float accepted as types on the int/double slots (§38.1) | Rule | Wrap int results to 32 bits where Java would overflow; carry byte/short/char as in-range int; round float to binary32 (fround). |
| 17 | Literals | 10L, 1.5f, 0x, 0b, _ separators, char 'a' | L / l, d / f, 0x, 0b, 0o, _ are lexed (43.6 rule 10); the character literal 'a' exists since syntax 3.1 (44.2, its value is the integer code); a subnormal double literal is rejected | Native | Java octal 017 must become 0o17; a subnormal literal must be written another way (lib/java/converter rule 5). |
| 18 | Bitwise operators | & | ^ ~ << >> >>> | Native VM operators with Java shift-count masking (opcodes 185-191) | Native | int shifts wrap only on store to int32 (STATUS.md section 10). |
| 19 | Integer arithmetic | Silent wrap on overflow, / truncates toward zero, % sign follows dividend | 64-bit VM integer; int32 wraps on store; / 0 throws ArithmeticException inside a try (SLEELA.syntax 37.5), fatal outside | Rule | lib/java/converter 0.5.0: one JavaOperands.toInt where an int value leaves int arithmetic, and JavaOperands.divInt / remInt for / and % (exact, ArithmeticException on zero), from conversion.model. |
| 20 | Floating point | IEEE 754 binary32/64, NaN, -0.0, strictfp default | Double slot; Double/Float give exact bit views and Java toString | Native, library | Use Double.toString/parseDouble from the library, never the legacy number formatter. |
| 21 | Strings | UTF-16, immutable, + concatenation, interned literals | Literals are legacy UTF-8; javaString* are VM UTF-16 strings; no UTF-16 ↔ legacy conversion; + cannot mix them; methods on String via JavaStringMethods (§41) | Gap | One VM operation for UTF-16 ↔ legacy conversion (item 8). Until then restrict to ASCII, or keep all text in one kind. Note 4,096 live UTF-16 handles cap. |
| 22 | String equality | equals by value, == by identity | == compares strings by value | Rule | Translator maps a.equals(b) to value compare; flag Java code that relies on == identity of strings (rare, usually a bug). |
| 23 | Arrays | Zero-initialized, bounds-checked, covariant | new T[n] starts at zero / false (44.3); array initializers since syntax 3.1; stores into byte[] / short[] elements do not wrap | Native, partly Gap | Element-store narrowing for byte[] / short[]. |
| 24 | Multi-dimensional arrays | new int[3][4], ragged | Array-of-array handling to be confirmed | Gap | Test and, if needed, lower to nested allocation. |
| 25 | Enums | Constants with bodies, values(), valueOf, switch | All 161 JDK enums complete (constants, name, ordinal, values, valueOf, compareTo); constant-specific methods not done | Native, partly Gap | Constant-specific bodies (for example DayOfWeek.plus). User enums need the same generated shape. |
| 26 | Records | Canonical constructor, accessors, equals/hashCode/toString | 4 JDK records complete; Java-style record keyword exists in the language | Native, partly Gap | record is reserved in SLeeLa; user identifiers named record must be renamed. |
| 27 | Reserved words | native, synchronized, volatile, … are Java keywords | record, close, native, enum, interface, struct, switch, instanceof, assert, super, this, … reserved; close collides with a runtime built-in; protected is reserved for static members | Rule | Rename conflicting identifiers (trailing _, as in generated parameter names). Java protected instance members carry @JavaProtected. |
| 28 | Lambdas, method refs, functional interfaces | x -> ..., String::length, Function, Comparator, … | SLJavaLambda (id, env) values; calls on Any dispatch at run time (SLEELA.syntax 43.7) | Rule | lib/java/converter 0.6.0 lowers lambdas (0 to 2 parameters) and method references with a known target (JConvLambda, LOWERING.md section 2); functional interface types are written Any. Not yet: 3+ parameters, array captures, references without a target. |
| 29 | Streams, Optional | java.util.stream | Optional* done; Streams need lambdas | Gap | Depends on row 28. |
| 30 | Collections | Live views, fail-fast iterators | 14 collections done; keySet/values/entrySet/subList return snapshots | Gap | Live views (item 12); fail-fast ConcurrentModificationException check. |
| 31 | Equality and hashing in collections | Uses equals/hashCode of elements | ==; objects by identity; hash matches Java for numbers, booleans, Strings | Gap | Consult user equals/hashCode (needs row 8). |
| 32 | Concurrency | Threads, synchronized, volatile, executors, java.util.concurrent | Atomics implemented on VM lock 31; no Thread semantics listed | Gap | Plan: synchronized to VM locks, Thread/Runnable, executors, memory-model statement. Out of scope for the first procedural pass. |
| 33 | Inner and anonymous classes | Capture outer this and effectively final locals | Inner classes: explicit slOuter field and slOuterArg constructor parameter | Rule (inner) / Gap (anonymous, local) | lib/java/converter 0.7.0 (JConvOuter): new Inner(..) passes the enclosing instance, Outer.this and unqualified outer members go through this.slOuter. Anonymous and local classes are still stubs (reasons 3, 14); sleelactl java-convert lowers them to generated classes. |
| 34 | Initializer blocks, static {} | Yes | Not listed | Gap | Confirm, otherwise lower into constructors / a static init method called on first use. |
| 35 | Control flow | if for while do switch break continue labeled, enhanced for, switch expressions, pattern matching, yield | Enhanced for (43.6 rule 9), labeled break / continue (44.4); switch expressions and pattern matching not in the language | Native, partly Gap | lib/java/converter lowers pattern instanceof in two exact shapes and stubs the rest. |
| 36 | var, text blocks, sealed types | Java 10+/15+/17+ | Not listed | Gap | Translator resolves var to a declared type; text blocks to a string literal; sealed is a compile-time check that can be dropped. |
| 37 | Annotations | Metadata only, no runtime effect by default | @… annotations exist with SLeeLa meanings (@modium, @loopDelay, …) | Rule | Strip or map Java annotations; avoid name clashes with SLeeLa annotations. |
| 38 | Comments | //, /* */, /** */ | //, #, < … >, << … >>; /* */ is not supported; angle comments must begin a line; an apostrophe inside a comment is a lexical error | Rule | Translator rewrites /* … */ to << … >> and drops or rewrites apostrophes. |
| 39 | Memory | GC, finalizers, weak refs | VM-owned handles reclaimed by collection; gc hint | Rule | Drop finalize; map System.gc() to the VM hint. |
| 40 | Class size | No fixed limit that matters | At most 64 named instance fields per class or struct | Rule | Pack related fields into an array field with accessor methods, or split the class. |
| 41 | Object methods | equals, hashCode, toString, getClass | A value of any type is assignable to Object | Native, partly Gap | Provide defaults on every class; getClass needs reflection (see row 43). |
| 42 | Static/instance access | Instance method via class name is an error | Same: instance method 'C::m' must be called on an instance | Native | None. |
| 43 | Reflection, ClassLoader, Proxy | Yes | Out of scope | Gap | Decide whether to support; most procedural code does not need it. |
| 44 | I/O, networking, native | java.io, java.nio, java.net, JNI | SLeeLa has OS and pipe built-ins; most JDK I/O types are signatures only | Gap | Implement per package after the core language rows; JNI is out of scope. |
| 45 | Entry point | public static void main(String[] args) | main method required in the run unit (a library class alone reports "no 'main' method found") | Rule | Translator emits a main wrapper passing args. |
| 46 | Multi-file programs | javac compiles the whole tree | run resolves library units per file and duplicates them; use one main file and let the loader pull /lib units | Gap | Fix multi-file duplication (item 13). |
1a. Decided rules: stubs, super, and the lineage list
@throwableon the method. Until a member has SLeeLa logic, its stub carries@throwable("<java exception>")on the method or constructor itself (as the generated files already do) and returns the Java default value. The annotation names what Java would throw; athrowstatement in the body is not used for stubs.super(...)goes to the backmost class. For `A extends B extends C extends D, asuper("constructor")written inA` means: set the reference toD, the root.BandCare not called by hand; they are implied by the SLeeLa language definition (the chain is walked by the language, not by translated code). The translator therefore emits one root-directedsuperper constructor and never a hand-written chain.Sleela.homeis the implied lineage structure (assumed for now). SLeeLa provides an implied static structure,Sleela.home, on every class. It is the bean setter for the lineage links. The translator never declares parent or child fields; they become available whenever a lineage keyword (extends,super) is used. The syntax definition creates the structure at the time of the static reference, at compile time and again at run time.- Reading the links. For
A extends B extends C extends D:Expression (in A)Meaning Sleela.home.parentB, the immediate parentSleela.home.childThe SLeeLa VM. The VM links to AandAlinks back to the VM, so the most-derived class is closed by the VMSleela.home.parents("-")One level up: BSleela.home.parents("--")Two levels up: CSleela.home.parents("---")Three levels up: D, the root. Each-is one levelSleela.home.parents("...")Same as "---": each.is one level, like-From
B,Sleela.home.childisA; fromD, it isC. The list is thereforeVM <-> A <-> B <-> C <-> D, walkable both ways from any member. - Constructor rule.
super("constructor")inAisSleela.home.parents("---"): it addresses the rootDdirectly.BandCare filled in by the language definition, not by translated code. - Decided answers (normative text:
SLEELA.syntaxsection 42, implemented in the source compiler andworking-binaries/sleela; tests inimpl/tests/lineage/):D'sSleela.home.parentisSleela.System, the VM, so the lineage is a cycle of references:VM -> A -> B -> C -> D -> VM.parents("")isSleela.System. More dashes than ancestors clamp to the root:parents("----")matchesparents("---")when there are three ancestors.Sleelais reserved;Sleela.VM,Sleela.SystemandSleela.OSare equivalent names for the VM reference. The VM hands it back as a HashMap-like value holding the VM reference and the nearest descendant. Its basic holder islib/java/SleelaHome.sleela, public fieldsvmandnearestDescendant. A translated Java identifier namedSleelais renamed (row 27).SleelaHomeis included statically in every class, with no import. It is inert (vmandnearestDescendantare null) until the VM loads a file or files; loading makes it live. A translator therefore emits no setup code.- During VM boot, init and start the VM-end references (
childof the most-derived class,parentof the root,parents("")) point tolib/security/Security2.sleela, which sits above the VM in colocated memory; they point to the VM once it is fully initialized (SLEELA.syntaxsection 42.6). - A link is set left to right:
B -> Sleela.home.parent.
2. Value and library conventions the translator must follow today
- Static call.
Math.abs(x)andStrictMath.abs(x)map straight to the SLeeLaMath.abs(x)(no instance form). Any other class becomesClass.method(x)when it is converted, elsenew Class().method(x). - Overload. Pick the suffixed method name that matches the Java overload (
absInt,absLong,toStringRadix). - Generics. Erase to
Anyand cast reads:(int) list.get(0). - Upcasts. Write them explicitly.
- Array elements of a user class. Bind to a typed local before calling a method on it:
Foo f = foos[i]; f.run();. Calling through the element inline loses the type at runtime. - Int overflow. Wrap to 32 bits wherever Java would.
- Imports. Add
import java.java.lang;/import java.java.util;when a simple name (Character,Vector,List,Map) also exists elsewhere in/lib. - Unsupported member. Calls to an unimplemented member throw
UnsupportedOperationException: not yet implemented in SLeeLa: <signature>. Treat this as a work item, not an error in the program.
3. How a gap is closed
- Pick a row marked Gap.
- Make the compiler or VM change, with a normative note in
SLEELA.syntax. - Remove the workaround from the generators in
../tools/implementation/and../tools/jdk28_implement_throwables.py, and re-run them. - Add a
<Name>.java/<Name>.sleelapair underexamples/java/differential/, so that real Java output and SLeeLa output are compared line for line. - Regenerate
security/sha256-manifest.json, thelib/inventory andCOVERAGE.md. - Change the row's status here in the same commit.