Home /Modules/java/PURPOSE.md

PURPOSE.md

lib/java/jdk-28/PURPOSE.md · 178 line(s) · markdown

/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.

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.

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

#AreaJava (JDK 28)SLeeLaStatusWhat we need to address
1Source versionNo per-file markerFile declares #sleela 3.0; real throw and Java UTF-16 String ops are gated at 3.0RuleTranslator emits #sleela 3.0 first in every file.
2Package / file layoutpackage a.b; one public type per fileLibrary unit found by simple file name; jdk-28/ is a reference tier, a real unit of the same name winsRuleMap a.b.Type to jdk-28/<module>/a/b/Type.sleela; resolve simple-name clashes with import java.java.util; style imports.
3Importsimport a.b.C;, import a.b.*;, import staticPackage-prefix import; ambiguous when a subpackage reuses a nameGapLoader needs exact-package import matching (deferred item 15). Static imports need a rewrite to Class.member.
4Nested typesMap.Entry, Character.UnicodeBlockFiles named Outer.Inner.sleela; loader resolves by simple name so does not load them yetGapLoader support for dotted nested-type files (item 14).
5Static membersMath.abs(x), Integer.MAX_VALUEClass.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 RuleA 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.
6OverloadingResolved by parameter typesResolved 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 RuleConvert 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.
7ConstructorsMany 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)RuleJava super(args) argument passing is still not evaluated; translator inlines inherited initialization.
8Inheritance and virtual dispatchAn override is called through a base-typed referenceOverrides are reached through a base-typed receiver and implicit this; super.m() (SLEELA.syntax 43.6 rules 6, 7)NativeLibrary units written before it still compose exception messages at construction; convert them class by class.
9Field initializers in base classesRun for every subclass instanceRun along the extends chain, base first (43.6 rule 5)NativeNone.
10Subtype assignmentThrowable t = ioe;Implicit for superclasses and implemented interfaces (43.6 rule 1)NativeA runtime cast to an interface still fails (lib/java/converter/README.md section 6).
11GenericsType parameters, bounds, wildcards, reified only by erasureSignatures accept them (§38.1) and erase to Any; no type checking of argumentsRuleTranslator inserts checked casts on reads: (int) list.get(0). Java compile-time generic errors are not reproduced.
12Interfaces, default and static interface methodsYesInterface/abstract types present as signatures; abstract calls throw AbstractMethodErrorNative, partly GapVerify default-method inheritance through dispatch (depends on row 8).
13Exceptions: throwthrow new X(...)Real throw at 3.0NativeNone beyond row 1.
14Exceptions: catchTyped, multi-catch, finally, try-with-resourcesTyped and multi catch and finally (43.6 rule 11); return / break / continue through finally run it (44.5); try-with-resources not loweredNative, partly Gaptry-with-resources.
15Exception hierarchyReal extends chain290 java.* Throwables and 208 others carry the real chain and documented constructorsNativeKeep getMessage() semantics (row 8).
16Primitivesbyte short char int long float double boolean, fixed widthVM integer is 64-bit; byte/short/char/float accepted as types on the int/double slots (§38.1)RuleWrap int results to 32 bits where Java would overflow; carry byte/short/char as in-range int; round float to binary32 (fround).
17Literals10L, 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 rejectedNativeJava octal 017 must become 0o17; a subnormal literal must be written another way (lib/java/converter rule 5).
18Bitwise operators& | ^ ~ << >> >>>Native VM operators with Java shift-count masking (opcodes 185-191)Nativeint shifts wrap only on store to int32 (STATUS.md section 10).
19Integer arithmeticSilent wrap on overflow, / truncates toward zero, % sign follows dividend64-bit VM integer; int32 wraps on store; / 0 throws ArithmeticException inside a try (SLEELA.syntax 37.5), fatal outsideRulelib/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.
20Floating pointIEEE 754 binary32/64, NaN, -0.0, strictfp defaultDouble slot; Double/Float give exact bit views and Java toStringNative, libraryUse Double.toString/parseDouble from the library, never the legacy number formatter.
21StringsUTF-16, immutable, + concatenation, interned literalsLiterals are legacy UTF-8; javaString* are VM UTF-16 strings; no UTF-16 ↔ legacy conversion; + cannot mix them; methods on String via JavaStringMethods (§41)GapOne 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.
22String equalityequals by value, == by identity== compares strings by valueRuleTranslator maps a.equals(b) to value compare; flag Java code that relies on == identity of strings (rare, usually a bug).
23ArraysZero-initialized, bounds-checked, covariantnew T[n] starts at zero / false (44.3); array initializers since syntax 3.1; stores into byte[] / short[] elements do not wrapNative, partly GapElement-store narrowing for byte[] / short[].
24Multi-dimensional arraysnew int[3][4], raggedArray-of-array handling to be confirmedGapTest and, if needed, lower to nested allocation.
25EnumsConstants with bodies, values(), valueOf, switchAll 161 JDK enums complete (constants, name, ordinal, values, valueOf, compareTo); constant-specific methods not doneNative, partly GapConstant-specific bodies (for example DayOfWeek.plus). User enums need the same generated shape.
26RecordsCanonical constructor, accessors, equals/hashCode/toString4 JDK records complete; Java-style record keyword exists in the languageNative, partly Gaprecord is reserved in SLeeLa; user identifiers named record must be renamed.
27Reserved wordsnative, synchronized, volatile, … are Java keywordsrecord, close, native, enum, interface, struct, switch, instanceof, assert, super, this, … reserved; close collides with a runtime built-in; protected is reserved for static membersRuleRename conflicting identifiers (trailing _, as in generated parameter names). Java protected instance members carry @JavaProtected.
28Lambdas, method refs, functional interfacesx -> ..., String::length, Function, Comparator, …SLJavaLambda (id, env) values; calls on Any dispatch at run time (SLEELA.syntax 43.7)Rulelib/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.
29Streams, Optionaljava.util.streamOptional* done; Streams need lambdasGapDepends on row 28.
30CollectionsLive views, fail-fast iterators14 collections done; keySet/values/entrySet/subList return snapshotsGapLive views (item 12); fail-fast ConcurrentModificationException check.
31Equality and hashing in collectionsUses equals/hashCode of elements==; objects by identity; hash matches Java for numbers, booleans, StringsGapConsult user equals/hashCode (needs row 8).
32ConcurrencyThreads, synchronized, volatile, executors, java.util.concurrentAtomics implemented on VM lock 31; no Thread semantics listedGapPlan: synchronized to VM locks, Thread/Runnable, executors, memory-model statement. Out of scope for the first procedural pass.
33Inner and anonymous classesCapture outer this and effectively final localsInner classes: explicit slOuter field and slOuterArg constructor parameterRule (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.
34Initializer blocks, static {}YesNot listedGapConfirm, otherwise lower into constructors / a static init method called on first use.
35Control flowif for while do switch break continue labeled, enhanced for, switch expressions, pattern matching, yieldEnhanced for (43.6 rule 9), labeled break / continue (44.4); switch expressions and pattern matching not in the languageNative, partly Gaplib/java/converter lowers pattern instanceof in two exact shapes and stubs the rest.
36var, text blocks, sealed typesJava 10+/15+/17+Not listedGapTranslator resolves var to a declared type; text blocks to a string literal; sealed is a compile-time check that can be dropped.
37AnnotationsMetadata only, no runtime effect by default@… annotations exist with SLeeLa meanings (@modium, @loopDelay, …)RuleStrip or map Java annotations; avoid name clashes with SLeeLa annotations.
38Comments//, /* */, /** *///, #, < … >, << … >>; /* */ is not supported; angle comments must begin a line; an apostrophe inside a comment is a lexical errorRuleTranslator rewrites /* … */ to << … >> and drops or rewrites apostrophes.
39MemoryGC, finalizers, weak refsVM-owned handles reclaimed by collection; gc hintRuleDrop finalize; map System.gc() to the VM hint.
40Class sizeNo fixed limit that mattersAt most 64 named instance fields per class or structRulePack related fields into an array field with accessor methods, or split the class.
41Object methodsequals, hashCode, toString, getClassA value of any type is assignable to ObjectNative, partly GapProvide defaults on every class; getClass needs reflection (see row 43).
42Static/instance accessInstance method via class name is an errorSame: instance method 'C::m' must be called on an instanceNativeNone.
43Reflection, ClassLoader, ProxyYesOut of scopeGapDecide whether to support; most procedural code does not need it.
44I/O, networking, nativejava.io, java.nio, java.net, JNISLeeLa has OS and pipe built-ins; most JDK I/O types are signatures onlyGapImplement per package after the core language rows; JNI is out of scope.
45Entry pointpublic static void main(String[] args)main method required in the run unit (a library class alone reports "no 'main' method found")RuleTranslator emits a main wrapper passing args.
46Multi-file programsjavac compiles the whole treerun resolves library units per file and duplicates them; use one main file and let the loader pull /lib unitsGapFix multi-file duplication (item 13).

1a. Decided rules: stubs, super, and the lineage list

  1. @throwable on 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; a throw statement in the body is not used for stubs.
  2. super(...) goes to the backmost class. For `A extends B extends C extends D, asuper("constructor")written inA` means: set the reference to D, the root. B and C are 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-directed super per constructor and never a hand-written chain.
  3. Sleela.home is 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.
  4. Reading the links. For A extends B extends C extends D:
    Expression (in A)Meaning
    Sleela.home.parentB, the immediate parent
    Sleela.home.childThe SLeeLa VM. The VM links to A and A links back to the VM, so the most-derived class is closed by the VM
    Sleela.home.parents("-")One level up: B
    Sleela.home.parents("--")Two levels up: C
    Sleela.home.parents("---")Three levels up: D, the root. Each - is one level
    Sleela.home.parents("...")Same as "---": each . is one level, like -

    From B, Sleela.home.child is A; from D, it is C. The list is therefore VM <-> A <-> B <-> C <-> D, walkable both ways from any member.

  5. Constructor rule. super("constructor") in A is Sleela.home.parents("---"): it addresses the root D directly. B and C are filled in by the language definition, not by translated code.
  6. Decided answers (normative text: SLEELA.syntax section 42, implemented in the source compiler and working-binaries/sleela; tests in impl/tests/lineage/):
    • D's Sleela.home.parent is Sleela.System, the VM, so the lineage is a cycle of references: VM -> A -> B -> C -> D -> VM.
    • parents("") is Sleela.System. More dashes than ancestors clamp to the root: parents("----") matches parents("---") when there are three ancestors.
    • Sleela is reserved; Sleela.VM, Sleela.System and Sleela.OS are 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 is lib/java/SleelaHome.sleela, public fields vm and nearestDescendant. A translated Java identifier named Sleela is renamed (row 27).
    • SleelaHome is included statically in every class, with no import. It is inert (vm and nearestDescendant are 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 (child of the most-derived class, parent of the root, parents("")) point to lib/security/Security2.sleela, which sits above the VM in colocated memory; they point to the VM once it is fully initialized (SLEELA.syntax section 42.6).
    • A link is set left to right: B -> Sleela.home.parent.

2. Value and library conventions the translator must follow today

  1. Static call. Math.abs(x) and StrictMath.abs(x) map straight to the SLeeLa Math.abs(x) (no instance form). Any other class becomes Class.method(x) when it is converted, else new Class().method(x).
  2. Overload. Pick the suffixed method name that matches the Java overload (absInt, absLong, toStringRadix).
  3. Generics. Erase to Any and cast reads: (int) list.get(0).
  4. Upcasts. Write them explicitly.
  5. 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.
  6. Int overflow. Wrap to 32 bits wherever Java would.
  7. Imports. Add import java.java.lang; / import java.java.util; when a simple name (Character, Vector, List, Map) also exists elsewhere in /lib.
  8. 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

  1. Pick a row marked Gap.
  2. Make the compiler or VM change, with a normative note in SLEELA.syntax.
  3. Remove the workaround from the generators in ../tools/implementation/ and ../tools/jdk28_implement_throwables.py, and re-run them.
  4. Add a <Name>.java / <Name>.sleela pair under examples/java/differential/, so that real Java output and SLeeLa output are compared line for line.
  5. Regenerate security/sha256-manifest.json, the lib/ inventory and COVERAGE.md.
  6. Change the row's status here in the same commit.