(rontolisp) docs
← Reference

Java interop

Interop lowers to the java: surface and runs on the interpreter and the JVM only -- the wasm backends reject java: (a dependency's plain Java class is read as Clojure there instead, Deviations), and a wasm compile warns only of a call the host alone answers: an instance call or field read no value there has ((.getBytes 5 "UTF-8"), (.-s 5)) is the oracle's refusal (No matching method getBytes found taking 1 args for class java.lang.Long), and (String. x) of anything but a byte array is refused by name. Class names resolve dotted as written, through :import, or through java.lang (the oracle's default-import list: the common throwables such as IllegalStateException are there, AutoCloseable is not). A string receiver answers the mapped core operation (a Lisp string is no host object), and .toString of any value that is no host object its str spelling, on every backend. A collection, keyword, symbol, ratio or atom answers its common methods (.count, .get, .contains, .getName, .numerator, .deref, ...) through the core functions on every backend, and refuses any other method by name (.name); a var answers clojure.lang.Var's .isDynamic, .ns, .sym, .toSymbol, .isMacro, .isPublic and .isBound the same way. A clojure.java.io File, URL, URI or stream answers its class's methods on every backend and crosses into a Java member as the host object it stands for (the interpreter and the JVM); a host java.io.File, URL or URI a member answers is one to slurp, spit, the namespace's functions and a protocol extended to its class. A java.util.Date, java.sql.Timestamp or java.util.UUID construction, UUID/randomUUID, UUID/fromString and System/currentTimeMillis make the values #inst and #uuid read, on every backend; such a value crosses into a member as the host object, and a host Date or UUID a member answers is = to it. A java.math.BigDecimal or MathContext construction, BigDecimal/valueOf, RoundingMode/valueOf and the BigDecimal, RoundingMode and MathContext constants make decimals and their contexts on every backend, which answer BigDecimal's methods there (.setScale, .divide, .toPlainString ...); a BigDecimal method beyond those runs on the host's object where a host is. A BigDecimal a member answers is a decimal where the member declares one, and where it declares Object or Number in a program that makes a decimal itself. str of a host object answers its toString. Printed readably (prn, pr-str, inside a collection str spells), a Java List is a vector when it is RandomAccess (ArrayList) and a list otherwise (LinkedList), a Map a map and a Set a set, in the collection's own order, like the oracle; any other host object, and every one under println/print, shows #<java C> (the oracle's #object[...] without the hash and toString), except a class object, which prints its name. A construction of a throwable class that carries only a message and a cause is an exception, and .getMessage/.getLocalizedMessage/.getCause of an exception (a caught runtime error included) answer from it, on every backend. An exception a member throws is the host's own, which a catch takes by its class (try); an exception the program built, passed to a member, is a host exception of its class (Deviations). A fn passed where a Java interface is expected implements its abstract method, called with the method's arguments; the interface's default methods keep their bodies, an answer where the method answers an object is the value's own object and where it answers a primitive is cast as the oracle casts it, and a fn Java takes as a Runnable, Callable, Comparator or Object, inside a collection too, comes back from Java as the fn (Deviations). Java's false comes back as false. A value passed to a member reaches Java as an object Java reads as the oracle's own -- a collection a read-only java.util collection printing as Clojure prints it, a keyword, symbol or ratio an object equal, hashing and ordering like the oracle's, a deftype or reify whose body implements a Java interface (Runnable, Comparable, Iterable, a java.util collection, java.util.concurrent.ThreadFactory ...) or overrides Object's methods an implementation of those interfaces calling its methods, equals, hashCode and toString included, a record whose body implements a Java interface a java.util.Map of its entries implementing it too, a fn the Runnable, Callable and Comparator it is, any other value an object equal only to itself -- and comes back as itself (Deviations). A byte array reaches Java as the byte[] of its bytes wherever a member takes one (an Object parameter included), and what the member stores into it, then or later, the program reads; a byte[] a member answers, or a host collection holds, comes back as a byte array, and so does one Java hands a fn, a proxy or a deftype or reify method, whose stores Java reads; a byte array a fn or proxy method answers reaches Java as its byte[] (Deviations). (String. bytes ...) and .getBytes decode and encode on every backend, in UTF-8, ISO-8859-1 or US-ASCII, named by a string or by a java.nio.charset.StandardCharsets field or Charset/forName of a literal, a charset value of its own that crosses into a member as the host Charset (byte-array).

What a host form means depends on the class it names -- a static method or a field, a throwable built as an exception or as a host object, the methods an interface declares -- so the lowering reads the class. The GraalVM native binary reads it from class files, the JDK's it finds (JAVA_HOME, else the java on PATH) and the program's Java class path, and so lowers a program as the jar does. With no JDK to read it answers from the classes its own image holds: a host form naming one of the JDK classes the front end names in its own code (the throwable classes, the hostless receivers, the value methods' host kinds, the time values' kinds, the clojure.java.io API types, Object and Throwable) lowers as the jar lowers it, and the compile warns it found no JDK (warning: no JDK found). A program naming another class may lower differently.

NameExampleResult
.(. "hi" length)2
..(.. "hi" (toUpperCase) (length))2
.name / .-name(.toUpperCase "hi")HI
Class/member(Integer/parseInt "42")42
Class/member (value)(every? Character/isWhitespace " ")true
Class/.method(map String/.length ["ab" "abcd"])(2 4)
Class/new(String/new "q")q
^[types](map ^[double] Math/abs [-1 2])(1.0 2.0)
new(.length (new String "hi"))2
memfn((memfn toUpperCase) "hi")HI
proxy(.get (proxy [java.util.function.Supplier] [] (get [] "p")))p
fn as an interface(let [l (java.util.ArrayList. [3 1 2])] (.sort l (fn [a b] (compare b a))) (vec l))[3 2 1]
reify as an interface(let [ran (atom 0)] (doto (Thread. (reify Runnable (run [_] (swap! ran inc)))) .start .join) @ran)1